Create batch payout

Creates a batch payout. In the JSON request body, pass a `sender_batch_header` and an `items` array. The `sender_batch_header` defines how to handle the payout. The `items` array defines the payout items.
You can make payouts to one or more recipients.

Notes:
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 Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the PayPal-Partner-Attribution-Id request header.
For information about the PayPal-Partner-Attribution-Id header, see HTTP request headers. To learn about or request a BN code, contact your partner manager or see PayPal Partner Program.

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Payout to a list of recipients.https://uri.paypal.com/payments/payouts

Header Parameters

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

sender_batch_headerobject<sender_batch_header>Required

The sender-provided payout header for a payout request.

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.

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.

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.

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"

Response Body

`application/json`

curl -X POST "https://example.com/v1/payments/payouts" \  -H "Content-Type: application/json" \  -d '{    "sender_batch_header": {},    "items": [      {        "amount": {          "currency": "string",          "value": "string"        },        "receiver": "string"      }    ]  }'

{  "batch_header": {    "payout_batch_id": "string",    "batch_status": "DENIED",    "time_created": "2019-08-24T14:15:22Z",    "sender_batch_header": {      "sender_batch_id": "string",      "recipient_type": "EMAIL",      "email_subject": "string",      "email_message": "string"    }  },  "links": [    {      "href": "string",      "rel": "string",      "method": "GET"    }  ]}

Notes:
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 Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the PayPal-Partner-Attribution-Id request header.
For information about the PayPal-Partner-Attribution-Id header, see HTTP request headers. To learn about or request a BN code, contact your partner manager or see PayPal Partner Program.

Header Parameters

Request Body

application/json

curl -X POST "https://example.com/v1/payments/payouts" \ -H "Content-Type: application/json" \ -d '{ "sender_batch_header": {}, "items": [ { "amount": { "currency": "string", "value": "string" }, "receiver": "string" } ] }'

{ "batch_header": { "payout_batch_id": "string", "batch_status": "DENIED", "time_created": "2019-08-24T14:15:22Z", "sender_batch_header": { "sender_batch_id": "string", "recipient_type": "EMAIL", "email_subject": "string", "email_message": "string" } }, "links": [ { "href": "string", "rel": "string", "method": "GET" } ]}

Authorization

Header Parameters

Request Body

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

On this page

On this page

On this page

Create batch payout

Authorization

Header Parameters

Request Body

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

On this page

On this page

Create batch payout

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

201application/json

400application/json

403application/json

500application/json

defaultapplication/json

On this page

On this page

On this page

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.

Create batch payout

sender_batch_header properties

payout_item_request properties

currency properties

alternate_notification_method properties

phone properties

application_context properties

201application/json

400application/json

403application/json

500application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`