Sections

Business Platforms and marketplaces Enterprise

Help

FAQs Account help Technical support API Status

APIs & SDKs

JavaScript SDK React SDK REST API Server SDKs Codes Webhook events iOS Android

Create Payout Request

The create payout request.

sender_batch_headerobject<sender_batch_header>Required

The sender-provided payout header for a payout request.

sender_batch_header properties

5 properties

sender_batch_idstringOptional

A sender-specified ID number. Tracks the payout in an accounting system.

Note:
PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.
If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

Match^.*$Length0 <= length <= 256

recipient_typestringOptional

The ID type that identifies the recipient of the payment. For example, EMAIL.

Match^.*$Length0 <= length <= 13

email_subjectstringOptional

The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.

Match^.*$Length0 <= length <= 255

email_messagestringOptional

The email message that PayPal sends when the payout item completes. The message is the same for all recipients.

Match^.*$Length0 <= length <= 1000

notestringOptional

The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.

Match^.*$Length0 <= length <= 1000

itemsobject<payout_item_request>[]Required

An array of individual payout items.

Items1 <= length <= 15000

payout_item_request properties

10 properties

recipient_typestringOptional

The recipient type. Value is:

EMAIL. The unencrypted email. Value is a string of up to 127 single-byte characters.
PHONE. The unencrypted phone number.
Note: The PayPal sandbox does not support the PHONE recipient type.
PAYPAL_ID. The encrypted PayPal account number.
USER_HANDLE. User handle (or) Username associated with Venmo account.

If the sender_batch_header includes the recipient_type attribute, payout items use the recipient_type of the sender_batch_header, unless a payout item has its own recipient_type attribute. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type value.

Match^.*$Length0 <= length <= 13

amountobject<currency>Required

The currency and amount to pay the receiver.

currency properties

2 properties

currencystringRequired

The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/).

valuestringRequired

The value, which might be:

An integer for currencies like `JPY` that are not typically fractional.
A decimal fraction for currencies like `TND` that are subdivided into thousandths.

For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).

notestringOptional

The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.

Match^.*$Length0 <= length <= 4000

receiverstringRequired

The receiver of the payment. Corresponds to the `recipient_type` value in the request. Max value of up to 127 single-byte characters.

Match^.*$Length0 <= length <= 127

sender_item_idstringOptional

The sender-specified ID number. Tracks the payout in an accounting system.

Match^.*$Length0 <= length <= 63

recipient_walletstringOptional

The recipient wallet.

Default"PAYPAL"Match^.*$Length0 <= length <= 36

alternate_notification_methodobject<alternate_notification_method>Optional

Captures additional notification modes to reach out to the receiver regarding this payment.

alternate_notification_method properties

1 property

phoneobject<phone>Optional

The mobile phone number of the receiver.

phone properties

3 properties

country_codestringRequired

The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

Match^[0-9]{1,3}?$Length1 <= length <= 3

national_numberstringRequired

The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

Match^[0-9]{1,14}?$Length1 <= length <= 14

extension_numberstringOptional

The extension number.

Match^[0-9]{1,15}?$Length1 <= length <= 15

notification_languagestring<language>Optional

The language in which to show the payout recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language or provide invalid language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account.

Match^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$Formatppaas_common_language_v3Length2 <= length <= 10

application_contextobject<application_context>Optional

Metadata for accepting additional information from merchants to Venmo.

application_context properties

3 properties

social_feed_privacystringOptional

This attribute controls the privacy of a payout transaction in recipient’s feed. PUBLIC, FRIENDS_ONLY & PRIVATE are the values that can be used. PUBLIC - The payment displays on the recipient's public Venmo feed. FRIENDS_ONLY - The payment displays only to the recipient's Venmo friends. PRIVATE - The payment displays only on the recipient's personal feed. Defaults to `PRIVATE` if left blank.

Default"PRIVATE"Match^.*$Length1 <= length <= 15

holler_urlstringOptionalDeprecated

Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151.

FormaturiLength1 <= length <= 1000

logo_urlstringOptional

Link to a logo that displays as the sender's profile image in the recipient's Venmo feed. Used to add or update the business profile image. Max image size: 1024 x 1024 pixels. The image should be square and maximum URL length is 2000.

FormaturiLength0 <= length <= 1000

purposeenum<purpose_enum>Optional

The purpose of the transaction.

Match^[A-Z0-9_]+$Length1 <= length <= 40

Allowed values

"AWARDS"
"PRIZES"
"DONATIONS"
"GOODS"
"SERVICES"
"REBATES"
"CASHBACK"
"DISCOUNTS"
"NON_GOODS_OR_SERVICES"

Back to top

Create Payout Request

The create payout request.

sender_batch_headerobject<sender_batch_header>Required

The sender-provided payout header for a payout request.

sender_batch_header properties

5 properties

sender_batch_idstringOptional

A sender-specified ID number. Tracks the payout in an accounting system.

Note:
PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.
If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

Match^.*$Length0 <= length <= 256

recipient_typestringOptional

The ID type that identifies the recipient of the payment. For example, EMAIL.

Match^.*$Length0 <= length <= 13

email_subjectstringOptional

The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.

Match^.*$Length0 <= length <= 255

email_messagestringOptional

The email message that PayPal sends when the payout item completes. The message is the same for all recipients.

Match^.*$Length0 <= length <= 1000

notestringOptional

The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.

Match^.*$Length0 <= length <= 1000

itemsobject<payout_item_request>[]Required

An array of individual payout items.

Items1 <= length <= 15000

payout_item_request properties

10 properties

recipient_typestringOptional

The recipient type. Value is:

EMAIL. The unencrypted email. Value is a string of up to 127 single-byte characters.
PHONE. The unencrypted phone number.
Note: The PayPal sandbox does not support the PHONE recipient type.
PAYPAL_ID. The encrypted PayPal account number.
USER_HANDLE. User handle (or) Username associated with Venmo account.

If the sender_batch_header includes the recipient_type attribute, payout items use the recipient_type of the sender_batch_header, unless a payout item has its own recipient_type attribute. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type value.

Match^.*$Length0 <= length <= 13

amountobject<currency>Required

The currency and amount to pay the receiver.

currency properties

2 properties

currencystringRequired

The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/).

valuestringRequired

The value, which might be:

An integer for currencies like `JPY` that are not typically fractional.
A decimal fraction for currencies like `TND` that are subdivided into thousandths.

For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).

notestringOptional

The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.

Match^.*$Length0 <= length <= 4000

receiverstringRequired

The receiver of the payment. Corresponds to the `recipient_type` value in the request. Max value of up to 127 single-byte characters.

Match^.*$Length0 <= length <= 127

sender_item_idstringOptional

The sender-specified ID number. Tracks the payout in an accounting system.

Match^.*$Length0 <= length <= 63

recipient_walletstringOptional

The recipient wallet.

Default"PAYPAL"Match^.*$Length0 <= length <= 36

alternate_notification_methodobject<alternate_notification_method>Optional

Captures additional notification modes to reach out to the receiver regarding this payment.

alternate_notification_method properties

1 property

phoneobject<phone>Optional

The mobile phone number of the receiver.

phone properties

3 properties

country_codestringRequired

The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

Match^[0-9]{1,3}?$Length1 <= length <= 3

national_numberstringRequired

The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

Match^[0-9]{1,14}?$Length1 <= length <= 14

extension_numberstringOptional

The extension number.

Match^[0-9]{1,15}?$Length1 <= length <= 15

notification_languagestring<language>Optional

The language in which to show the payout recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language or provide invalid language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account.

Match^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$Formatppaas_common_language_v3Length2 <= length <= 10

application_contextobject<application_context>Optional

Metadata for accepting additional information from merchants to Venmo.

application_context properties

3 properties

social_feed_privacystringOptional

This attribute controls the privacy of a payout transaction in recipient’s feed. PUBLIC, FRIENDS_ONLY & PRIVATE are the values that can be used. PUBLIC - The payment displays on the recipient's public Venmo feed. FRIENDS_ONLY - The payment displays only to the recipient's Venmo friends. PRIVATE - The payment displays only on the recipient's personal feed. Defaults to `PRIVATE` if left blank.

Default"PRIVATE"Match^.*$Length1 <= length <= 15

holler_urlstringOptionalDeprecated

Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151.

FormaturiLength1 <= length <= 1000

logo_urlstringOptional

Link to a logo that displays as the sender's profile image in the recipient's Venmo feed. Used to add or update the business profile image. Max image size: 1024 x 1024 pixels. The image should be square and maximum URL length is 2000.

FormaturiLength0 <= length <= 1000

purposeenum<purpose_enum>Optional

The purpose of the transaction.

Match^[A-Z0-9_]+$Length1 <= length <= 40

Allowed values

"AWARDS"
"PRIZES"
"DONATIONS"
"GOODS"
"SERVICES"
"REBATES"
"CASHBACK"
"DISCOUNTS"
"NON_GOODS_OR_SERVICES"

Create Payout Request

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

Back to top

On this page

On this page

Create Payout Request

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

Back to top

On this page

Create Payout Request

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

Back to top

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create Payout Request

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

Back to top

On this page