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

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.

  • 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

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

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:
      EMAIL. Unencrypted email. Value is a string of up to 127 single-byte characters.
    • 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.

Additional API information

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.

Feedback

Have feedback?

Let us know.