Payouts API

Use the Payouts API to make PayPal payments to multiple PayPal accounts in a single API call. You can specify the recipients by using their PayPal email addresses, phone numbers, or encrypted PayPal account numbers.

The Payouts API is a fast, convenient way to send commissions, rebates, rewards, and general disbursements. Payouts appear as Mass Payments in the sender's PayPal account and are provided with the Mass Payment reports.

Important: To use the Payouts API, request access through My Account. Alternatively, contact your account manager or PayPal Customer Support. You must have a PayPal business account.

The Payouts API uses the ISO 8601 Internet date and time format.

For more information about the Payouts API, see Payouts.

Payouts (resource group)

Use the /payouts resource to create payouts and show payout details.

Create payouts

POST /v1/payments/payouts

Creates a 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 PayPal accounts.

By default, a Payouts API call is asynchronous, which lets you show payout details at a later time. See Payouts.

If you submit a single payout, you can make a synchronous payout call, which immediately returns the results of the payout. In a synchronous payout call, the response is similar to the show payout status response.

To make a synchronous payout, include sync_mode=true in the URI:

/v1/payments/payouts?sync_mode=true

In asynchronous payout mode, sync_mode=false, you can specify a maximum of 1500 individual payouts in one API call. Exceeding 1500 payouts in one call returns the HTTP 400 Bad Request status code. The default is asynchronous payout mode.

All items in a payout must specify the same currency.

Note: PayPal prevents duplicate payouts from being processed. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request and returns an error message that indicates 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. In any case, the API completes a payment only once for a sender_batch_id that is used within 30 days.

Note: The Payouts API does not currently 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 request a BN code or to learn more about these codes, contact your partner manager or see PayPal Partner Program.

Parameters

sync_mode

query_string boolean

Deprecated. Indicates whether to return an immediate and synchronous response or an asynchronous response in the background. Set to true to return an immediate and synchronous response. Default is false.

Request

sender_batch_header

object

required

The sender-provided payout header for a payout request.
items

object (contains the payout_item object)

required

An array of individual payout items.

Minimum length: 1.

Maximum length: 15000.

SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payouts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "sender_batch_header": {
    "sender_batch_id": "2014021801",
    "email_subject": "You have a payout!",
    "email_message": "You have received a payout! Thanks for using our service!"
  },
  "items": [
    {
      "recipient_type": "EMAIL",
      "amount": {
        "value": "9.87",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "sender_item_id": "201403140001",
      "receiver": "receiver@example.com"
    },
    {
      "recipient_type": "PHONE",
      "amount": {
        "value": "112.34",
        "currency": "EUR"
      },
      "note": "Thanks for your support!",
      "sender_item_id": "201403140002",
      "receiver": "91-734-234-1234"
    },
    {
      "recipient_type": "PHONE",
      "amount": {
        "value": "5.32",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "sender_item_id": "201403140003",
      "receiver": "408-234-1234"
    },
    {
      "recipient_type": "PHONE",
      "amount": {
        "value": "5.32",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "sender_item_id": "201403140004",
      "receiver": "408-234-1234"
    }
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that contains an ID for a newly created payout and payout details. To show payout status, use the payout_batch_id value that appears the response.

If the initial scan that checks for syntax errors, missing or duplicated keywords, and more succeeds, the batch_status is PENDING. The API does not immediately validate some payout item values, such as the receiver phone numbers, before the API provides a call response.

For information about the response to a synchronous Payout request, see Create a single payout.

batch_header

object

The payout header.
errors

object

The error details.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

Sample Response

{
  "batch_header": {
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a payout!"
    },
    "payout_batch_id": "12345678",
    "batch_status": "PENDING"
  }
}

Show payout details

GET /v1/payments/payouts/payout_batch_id

Periodically shows the latest status of a payout along with the transaction status and other data for individual items.

Also, returns IDs for the individual payout items. You can use these item IDs in other calls. For example, specify the ID of a payout item to Show payout item details.

The payout status is one of these values:

Status	Description
`ACKNOWLEDGED`	The payout is acknowledged and will be processed. This status does not apply to the REST API but applies to only Web upload.
`DENIED`	No payout items are processed.
`PENDING`	The payout is waiting to be processed.
`PROCESSING`	The payout is being processed.
`SUCCESS`	The payout was successfully processed. Note that some payout items might not be completely processed because, for example, they are unclaimed or on hold.
`NEW`	The payout is delayed due to PayPal internal updates.
`CANCELED`	This status cannot occur if the sender uses the API to only send payouts. This status is an edge-case if a sender uses both the MassPay web upload and the Payouts API, cancels the web upload, and then uses the API to find the payout or payout items. Then, the `CANCELED` status is possible.

The item transaction status is one of these values:

Status	Description
`BLOCKED`	The payout item is blocked.
`DENIED`	The payout item was denied payment.
`FAILED`	Processing for the payout item failed.
`NEW`	The payment processing is delayed due to PayPal internal updates.
`ONHOLD`	The payout item is on hold.
`PENDING`	The payout item is awaiting payment.
`REFUNDED`	The payment for the payout item was successfully refunded.
`RETURNED`	The payout item is returned. If the recipient does not claim it in 30 days, the funds are returned.
`SUCCESS`	The payout item was successfully processed.
`UNCLAIMED`	The payout item is unclaimed. If it is not claimed within 30 days, the funds are returned to the sender.

Parameters

payout_batch_id

path string

The ID of the payout for which to show details.
fields

query_string string

Optional. Shows details for only the specified fields.
page

query_string integer

Optional. A non-zero integer representing the page of the results.

Default: 1.

Minimum length: 1.
page_size

query_string integer

Optional. The maximum number of results to return at one time. Value is a non-negative, non-zero integer. If the user chooses pagination, the maximum page size is 500.

Maximum length: 500.
total_required

query_string boolean

Indicates whether to show the total items and total pages count in the response.

Default: false.

SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payouts/12345678?fields=batch_header \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows payout details including the payout status.

total_items

see description

The total number of items in the full result list.
Possible types: integer
total_pages

see description

The total number of pages.
Possible types: integer
batch_header

object

A payout header. Includes the generated payout status.
items

object (contains the payout_item_response object)

An array of items in a payout.
errors

object

The error details.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

Sample Response

{
  "batch_header": {
    "payout_batch_id": "12345678",
    "batch_status": "ACKNOWLEDGED",
    "time_created": "2014-01-27T10:17:00Z",
    "time_completed": "2014-01-27T11:17:39.00Z",
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a payout!"
    },
    "amount": {
      "value": "435.85",
      "currency": "USD"
    }
  }
}

Payout item (resource group)

Use the /payouts-item resource to show details for a payout item an cancel an unclaimed payout item.

Deprecation notice: Synchronous mode will soon be deprecated. It is no longer available for new integrations but continues to be supported for existing integrations. A synchronous mode payout immediately returns the results of the payout.

Show payout item details

GET /v1/payments/payouts-item/payout_item_id

Shows the details for a payout item. Use this call to review the current status of a previously unclaimed, or pending, payout item.

For the supported status values, see the transaction status table in show payout details.

Parameters

Specify a payout item ID. The show payout details call shows payout item IDs in payout_item_id fields.

payout_item_id

path string

required

The ID of the payout item for which to show details.

SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 200 OK status code and a JSON response body with a payout_item_details object, which contains data about a payout item including the transaction status.

A payout_item_id helps you identify denied payments. If a payment is denied, you can use the payout_item_id to identify the payment even if it lacks a transaction_id.

payout_item_id

string

The ID for the payout item. Visible when you show details for a payout.

Maximum length: 30.
transaction_id

string

The PayPal-generated ID for the transaction.

Maximum length: 30.
transaction_status

object

The transaction status.
payout_item_fee

object

The estimate for the applicable payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
payout_batch_id

string

The PayPal-generated ID for the payout.

Maximum length: 30.
sender_batch_id

string

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

Maximum length: 30.
payout_item

object

The sender-provided information for the payout item.
time_processed

string

The date and time when this item was last processed, in Internet date and time format.
errors

object

The error information.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

Sample Response

{
  "payout_item_id": "1421342",
  "transaction_id": "4345",
  "transaction_status": "SUCCESS",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "20140724",
  "payout_item": {
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "recipient_type": "EMAIL",
    "note": "Thanks for your patronage!",
    "receiver": "receiver@example.com",
    "sender_item_id": "14Feb_234"
  },
  "time_processed": "2014-01-27T10:17:41Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342",
      "method": "GET"
    },
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342/cancel",
      "method": "POST"
    },
    {
      "href": "https://localhost:12380/v1/payments/payouts/NEYJ9G3JNQV78",
      "rel": "batch",
      "method": "GET"
    }
  ]
}

Cancel unclaimed payout item

POST /v1/payments/payouts-item/payout_item_id/cancel

Cancels an unclaimed transaction. If no one claims the unclaimed item within 30 days, the funds are automatically returned to the sender. Use this call to cancel the unclaimed item before the automatic 30-day refund.

A successful request returns the HTTP 200 OK status code and a JSON response body with the payout_item_details object that shows canceled payout details including a RETURNED transaction status.

Parameters

Specify a payout item ID followed by the /cancel action in the URI. The show payout details call shows payout item IDs in payout_item_id fields.

You can cancel only payout items with a transaction_status of UNCLAIMED.

payout_item_id

path string

required

The ID of the payout item to cancel.

SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

payout_item_id

string

The ID for the payout item. Visible when you show details for a payout.

Maximum length: 30.
transaction_id

string

The PayPal-generated ID for the transaction.

Maximum length: 30.
transaction_status

object

The transaction status.
payout_item_fee

object

The estimate for the applicable payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
payout_batch_id

string

The PayPal-generated ID for the payout.

Maximum length: 30.
sender_batch_id

string

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

Maximum length: 30.
payout_item

object

The sender-provided information for the payout item.
time_processed

string

The date and time when this item was last processed, in Internet date and time format.
errors

object

The error information.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

Sample Response

{
  "payout_item_id": "1421342",
  "transaction_id": "4345",
  "transaction_status": "RETURNED",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "20140724",
  "sender_batch_id": "2014021801",
  "payout_item": {
    "recipient_type": "EMAIL",
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "receiver": "receiver@example.com",
    "sender_item_id": "14Feb_234"
  },
  "time_processed": "2014-01-27T10:17:41Z",
  "errors": {
    "name": "RECEIVER_UNREGISTERED",
    "message": "Receiver is unregistered",
    "debug_id": "12341234",
    "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch#errors"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342",
      "method": "GET"
    },
    {
      "rel": "batch",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts/20140724",
      "method": "GET"
    }
  ]
}

Common object definitions

create_payout_request

sender_batch_header

object

The sender-provided payout header for a payout request.
items

object (contains the payout_item object)

An array of individual payout items.

Minimum length: 1.

Maximum length: 15000.

currency

currency

string

The three-character ISO-4217 currency code.
value

string
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.

error

name

string

The human-readable and unique name of the error.

Read only.
debug_id

string

The PayPal internal ID. Used for correlation purposes.

Read only.
message

string

The message that describes the error.

Read only.
information_link

string

The URI to use to get developer details for this error.

Read only.
details

object (contains the error_details object)

An array of additional details about the error.

Read only.

error_details

field

string

The name of the field that caused the error. Required for client-side errors.
issue

string

The reason that the error occurred.

link

href

string

The URL of the related HATEOAS link that you can use for subsequent calls.
rel

string

The link relationship. Describes how this link relates to the previous call. For example, use a self link to show details for the current call. Use a parent_payment link to show details for the parent payment. The rel value can also be a related call, such as execute or refund.
method

string

The HTTP method required to make the related call.

link_description

href

string

The complete target URL, or link, to use in combination with the method to make the related call, as defined by RFC 6570 - URI Template, with the addition of the $, (, and ) characters for pre-processing. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel

string

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. For possible values, see Link Relationship Types.
title

string

The link title.
targetSchema

object

The schema that describes the link target.
mediaType

string

The RFC 2046-defined media type that describes the link target.
method

string

The method to use to request the link target. For example, for HTTP, this might be GET or DELETE.
encType

string

The media type with which to submit data with the request.

Default: application/json.
schema

object

The schema that describes the request data.

payout

batch_header

object

The payout header.
errors

object

The error details.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

payout_enumerations

batch_enum

enum
The payouts status. Value is:
- ACKNOWLEDGED. The payout is acknowledged and will be processed. This status does not apply to the REST API but applies to only Web upload.
- DENIED. No payout items are processed.
- PENDING. The payout is waiting to be processed.
- PROCESSING. The payout is being processed.
- SUCCESS. The payout was successfully processed. Note that some payout items might not be completely processed because, for example, they are unclaimed or on hold.
- NEW. The payout is delayed due to PayPal internal updates.
- CANCELED. This status cannot occur if the sender uses the API to only send payouts. This status is an edge-case if a sender uses both the MassPay web upload and the Payouts API, cancels the web upload, and then uses the API to find the payout or payout items. Then, the CANCELED status is possible.
Possible values: ACKNOWLEDGED, DENIED, PENDING, PROCESSING, SUCCESS, NEW, CANCELED.
transaction_enum

enum
The item transaction status. Value is:
- NEW. The payment processing is delayed due to PayPal internal updates.
- SUCCESS. The payout item was successfully processed.
- DENIED. The payout item was denied payment.
- PENDING. The payout item is waiting to be processed.
- FAILED. Processing for the payout item failed.
- UNCLAIMED. The payout item is unclaimed. If it is not claimed within 30 days, the funds are returned to the sender.
- RETURNED. The payout item is returned. If the recipient does not claim it in 30 days, the funds are returned.
- ONHOLD. The payout item is on hold.
- BLOCKED. The payout item is blocked.
- REFUNDED. The payment for the payout item was successfully refunded.
Possible values: NEW, SUCCESS, DENIED, PENDING, FAILED, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, REFUNDED, REVERSED.
recipient_enum

enum
The ID type that identifies the payment receiver. Value is:
- PHONE. Unencrypted phone number.
- PAYPAL_ID. Encrypted PayPal account number.
These rules apply to the recipient_type:
- If the sender_batch_header includes a recipient_type value, any payout items without a recipient_type value use the recipient_type value in the sender_batch_header.
- If the sender_batch_header omits the recipient_type value, each payout item must include its own recipient_type value.
Possible values: EMAIL, PHONE, PAYPAL_ID.
funding_enum

enum

The funding instrument.

Possible values: BALANCE.

payout_error

name

string

The human-readable and unique name of the error.

Read only.
debug_id

string

The PayPal internal ID, which is used for correlation purposes.

Read only.
message

string

The message that describes the error.

Read only.
information_link

string

The URI for detailed information related to this error for the developer.

Read only.
payout_error_details

object (contains the payout_error_details object)

An array of additional error details.

Read only.

payout_error_details

field

string

The name of the field that caused the error.
issue

string

The reason for the error.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

payout_header

payout_batch_id

string

The PayPal-generated ID for a payout.

Maximum length: 30.
batch_status

object

The PayPal-generated payout status. If the payout passes preliminary checks, the status is PENDING.
time_created

string

The date and time when processing for the payout began, in Internet date and time format.
sender_batch_header

object

The original payout header, as provided by the payment sender.
errors

object

The error information.

payout_header_response

payout_batch_id

string

The PayPal-generated ID for a payout.

Maximum length: 30.
batch_status

object

The PayPal-generated payout status. If the payout passes preliminary checks, the status is PENDING.
time_created

string

The date and time when processing for the payout began, in Internet date and time format.
time_completed

string

The date and time when processing for the payout completed, in Internet date and time format.
sender_batch_header

object

The original payout header, as provided by the payment sender.
amount

object

The total amount, in U.S. dollars, requested for the payouts.
fees

object

The currency and amount of the total estimate for the applicable payouts fees. Initially, the fee is 0. The fee is populated after the payout moves to the PROCESSING state.
errors

object

The error information.

payout_item

payout_item_id

string

The ID for the payout item. Visible when you show details for a payout.

Maximum length: 30.
transaction_id

string

The PayPal-generated ID for the transaction.

Maximum length: 30.
transaction_status

object

The transaction status.
payout_item_fee

object

The estimate for the applicable payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
payout_batch_id

string

The PayPal-generated ID for the payout.

Maximum length: 30.
sender_batch_id

string

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

Maximum length: 30.
payout_item

object

The sender-provided information for the payout item.
time_processed

string

The date and time when this item was last processed, in Internet date and time format.
errors

object

The error information.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

payout_item

recipient_type

string
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.
If the sender_batch_header includes the recipient_type attribute, any payout item without its own recipient_type attribute uses the recipient_type value from sender_batch_header. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type value.
Maximum length: 13.
amount

object

The currency and amount to pay the receiver.
note

string

Optional. A sender-specified note for notifications.

Maximum length: 4000.
receiver

string

The receiver of the payment. Corresponds to the recipient_type value in the request.

Maximum length: 127.
sender_item_id

string

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

Maximum length: 63.

payout_item_detail

recipient_type

object
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.
If the sender_batch_header includes the recipient_type attribute, any payout item without its own recipient_type attribute uses the recipient_type value from sender_batch_header. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type value.
amount

object

The currency and amount of payout item. Might be an integer for currencies like JPY that are not typically fractional or 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.
note

string

Optional. A sender-specified note for notifications.

Maximum length: 4000.
receiver

string

The receiver of the payment. Corresponds to the recipient_type value in the request.

Maximum length: 127.
sender_item_id

string

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

Maximum length: 30.

payout_item_response

payout_item_id

string

The ID for the payout item. Viewable when you show details for a payout.

Maximum length: 30.
transaction_id

string

The PayPal-generated ID for the transaction.

Maximum length: 30.
transaction_status

object

The transaction status.
payout_item_fee

object

The fee, in U.S. dollars.
payout_batch_id

string

The PayPal-generated ID for the payout.

Maximum length: 30.
payout_item

object

The sender-provided information for the payout item.
time_processed

string

The date and time when this item was last processed, in Internet date and time format.
errors

object

The error information.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

payout_sender_header

sender_batch_id

string

The sender-specified ID number. Tracks the payout in an accounting system.
Note: PayPal prevents duplicate payouts from being processed. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request and returns an error message that identifies 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. In any case, the API completes a payment only once for a specific sender_batch_id that is used within 30 days.

Maximum length: 30.
recipient_type

object

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

string

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 with a maximum length of 255 single-byte characters.

Maximum length: 255.

payout_sync_batch_response

total_items

see description

The total number of items in the full result list.
Possible types: integer
total_pages

see description

The total number of pages.
Possible types: integer
batch_header

object

A payout header. Includes the generated payout status.
items

object (contains the payout_item_response object)

An array of items in a payout.
errors

object

The error details.
links

array (contains the link object)

HATEOAS links related to this call.

Read only.

sender_payout_header

sender_batch_id

string

A sender-specified ID number. Tracks the payout in an accounting system.
Note: PayPal prevents duplicate payouts from being processed. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request and returns an error message that indicates 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 specific sender_batch_id that is used within 30 days.

Maximum length: 30.
recipient_type

string

The ID type that is used to identify the recipient of the payment. For example, EMAIL.

Maximum length: 13.
email_subject

string

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.

Maximum length: 255.
email_message

string

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

Maximum length: 1000.
note

string

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

Maximum length: 1000.

Error messages

In addition to common HTTP status codes that the REST APIs return, the Payouts API can return the following errors.

ACCOUNT_RESTRICTED

Your account has been limited. You'll need to remove these limitations to send a payout.
ACCOUNT_UNCONFIRMED_EMAIL

Your account may not have a confirmed email and a confirmed bank account or credit card. Sender may not have account status verified.
AUTHORIZATION_ERROR

An authorization error occurred.
BATCH_NOT_COMPLETED

payout is not complete.
CLOSED_MARKET

The recipient account is in a country that's not eligible to receive a payout.
CURRENCY_COMPLIANCE

Currency compliance.
CURRENCY_NOT_SUPPORTED_FOR_RECEIVER

The transaction currency is not supported for the receiver. You can send the payout in a different currency.
DUPLICATE_ITEM

This is a duplicate item as the SENDER_ITEM_ID matches with another item in the payout. The SENDER_ITEM_ID should be unique for each payout.
GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK

Please check the country of residence. Payments to this country is not allowed.
GAMER_FAILED_FUNDING_SOURCE_CHECK

The funding source for this gamer is ineligible to make payments.
GAMING_INVALID_PAYMENT_FLOW

This payment flow is not valid for gaming.
INSUFFICIENT_FUNDS

You have insufficient funds in your PayPal balance. You'll need to add funds to your account to complete the payout.
INTERNAL_ERROR

An internal error has occurred. For item level errors, we'll try resending the payout thrice. If we are unable to complete the requests, you'll need to resubmit the payout after 24 hours. For payout level errors, we'll not retry the payout.
ITEM_ALREADY_CANCELLED

This item has already been canceled.
ITEM_CANCELLATION_FAILED

The cancellation request for this item failed due to an internal error.
ITEM_INCORRECT_STATUS

You can cancel items only with unclaimed status.
MALFORMED_REQUEST_ERROR

JSON request is malformed.
NEGATIVE_BALANCE

The payout can't be completed as your PayPal account has a negative balance. You'll need to correct this before you send a payout.
NON_HOLDING_CURRENCY

As your PayPal balance is not held in this currency, you’ll not be able to send payouts.
PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE

The payment is pending as the recipient has set a preference to not allow auto credits to the balance in a non-holding currency.
POS_LIMIT_EXCEEDED

You've exceeded the POS cumulative sending limit.
RATE_LIMIT_VALIDATION_FAILURES

Sorry, we've blocked this request due to multiple invalid requests submitted previously. Please retry the payout after some time.
RECEIVER_ACCOUNT_LOCKED

The receiver's account is locked or inactive. Any payment made to this account will appear as FAILED. You can contact the recipient to request them to activate their account.
RECEIVER_COUNTRY_NOT_ALLOWED

As the recipient's country can't receive payments, this transaction is not allowed.
RECEIVER_STATE_RESTRICTED

As the recipient's address is in a restricted state, payments can't be received.
RECEIVER_UNCONFIRMED

The receiver's email is unconfirmed. Any payment made to this account will appear as UNCLAIMED until the receiver's account is confirmed. Payments will be returned if they are not claimed within 30 days.
RECEIVER_UNREGISTERED

This receiver is not registered. You'll need to request them to sign up with PayPal to receive the payment.
RECEIVER_YOUTH_ACCOUNT

Since the recipient is a Youth account, they can't receive payments. You can send the payment to an alternate account.
RECEIVING_LIMIT_EXCEEDED

The recipient has exceeded the receiving limit.
REFUSED_ACCESS_DENIED

Access has been denied as the send money option is not allowed for this merchant.
RECEIVER_REFUSED

This payment has been refused by the recipient.
REGULATORY_BLOCKED

This transaction is blocked due to regulatory compliance reasons.
REGULATORY_PENDING

This transaction is pending completion of required regulatory and compliance checks.
REQUIRED_SCOPE_MISSING

The access token doesn't have the required scope. You'll need to use the access token with the correct scope to send a payout.
RISK_DECLINE

This transaction was declined due to risk concerns.
SELF_PAY_NOT_ALLOWED

Payment to self is not allowed.
SENDER_ACCOUNT_LOCKED

Your account is locked or inactive. You'll have to contact the customer service team to activate your account.
SENDER_ACCOUNT_UNVERIFIED

The payment hasn’t been processed as this sender account is not set up or verified by PayPal. Please contact us to resolve this issue.
SENDER_STATE_RESTRICTED

As your address is in a restricted state, payments can't be sent.
SPENDING_LIMIT_EXCEEDED

You've exceeded the spending limit.
TRANSACTION_DECLINED_BY_TRAVEL_RULE

This transaction has been declined as it hasn't complied with the Travel Rule Regulation.
TRANSACTION_LIMIT_EXCEEDED

You or the recipient has exceeded the transaction limit.
UNDEFINED

Sorry, an error has occurred. For help, please contact your account manager or our Customer Service team. You can also try sending the Payout after sometime.
UNVERIFIED_RECIPIENT_NOT_SUPPORTED

Sender supports payments to email verified recipients only.
USER_BUSINESS_ERROR

User business error has occurred.
USER_COUNTRY_NOT_ALLOWED

User's country is not allowed.
USER_FUNDING_SOURCE_INELIGIBLE

Your funding source is not eligible to make a payout.
ZERO_AMOUNT

The payout can't be done without any amount. You must enter a valid amount that's greater than zero.

sync_mode

sender_batch_header

items

Sample Request

batch_header

errors

links

Sample Response

payout_batch_id

fields

page

page_size

total_required

Sample Request

total_items

total_pages

batch_header

items

errors

links

Sample Response

payout_item_id

Sample Request

payout_item_id

transaction_id

transaction_status

payout_item_fee

payout_batch_id

sender_batch_id

payout_item

time_processed

errors

links

Sample Response

payout_item_id

Sample Request

payout_item_id

transaction_id

transaction_status

payout_item_fee

payout_batch_id

sender_batch_id

payout_item

time_processed

errors

links

Sample Response

sender_batch_header

items

currency

value

name

debug_id

message

information_link

details

field

issue

href

rel

method

href

rel

title

targetSchema

mediaType

method

encType

schema

batch_header

errors

links

batch_enum

transaction_enum

recipient_enum

funding_enum

name

debug_id

message

information_link

`sync_mode`

`sender_batch_header`

`items`

`batch_header`

`errors`

`links`

`payout_batch_id`

`fields`

`page`

`page_size`

`total_required`

`total_items`

`total_pages`

`batch_header`

`items`

`errors`

`links`

`payout_item_id`

`payout_item_id`

`transaction_id`

`transaction_status`

`payout_item_fee`

`payout_batch_id`

`sender_batch_id`

`payout_item`

`time_processed`

`errors`

`links`

`payout_item_id`

`payout_item_id`

`transaction_id`

`transaction_status`

`payout_item_fee`

`payout_batch_id`

`sender_batch_id`

`payout_item`

`time_processed`

`errors`

`links`

`sender_batch_header`

`items`

`currency`

`value`

`name`

`debug_id`

`message`

`information_link`

`details`

`field`

`issue`

`href`

`rel`

`method`

`href`

`rel`

`title`

`targetSchema`

`mediaType`

`method`

`encType`

`schema`

`batch_header`

`errors`

`links`

`batch_enum`

`transaction_enum`

`recipient_enum`

`funding_enum`

`name`

`debug_id`

`message`

`information_link`

`payout_error_details`

`field`

`issue`

`links`

`payout_batch_id`

`batch_status`

`time_created`

`sender_batch_header`