Referenced Payouts API

The Referenced Payouts API enables partner merchants and developers to process individual referenced payouts to recipients. To use this API, you must request a build notation (BN) code. To learn more or to request a BN code, contact your partner manager or visit the PayPal Partner Portal.

Referenced payouts (resource group)

Enables you to create a referenced batch payout and list all items, with details, in a referenced batch payout.

Create referenced batch payout

POST /v1/payments/referenced-payouts
Creates a referenced batch payout for asynchronous, offline processing. Include a sender_batch_header object and an items array in the request URI.

Header parameters

For more information about HTTP request headers, see HTTP request headers.
  • Prefer

    string

    Indicates how the client expects the server to process this request. To process the request asynchronously, set this header to respond-async. If you omit this header, the API processes the request synchronously. For synchronous processing the application may levy additional checks on the number of supported items in the request and may fail the request if those limits are breached.
  • PayPal-Partner-Attribution-Id

    string

    For more information about PayPal-Partner-Attribution-Id, see PayPal-Partner-Attribution-Id.
  • PayPal-Request-Id

    string

    The server stores keys for three days. For more information about PayPal-Request-Id, see PayPal-Request-Id.

Request body

  • referenced_payouts

    array (contains the referenced_payouts_item object)

    An array of referenced payouts items. For synchronous execution, the maximum number of items is 10. If you include more than 10 items, the request is processed asynchronously no matter what the partner defined in the Prefer request header.
  • payout_directive

    object

    The payout directive. Defines how the payout is made following the referenced payouts, if required. If you include this directive, all items in the request must be for the same original receiver. Otherwise, the request fails. You can override the payout directive at the item level to a different funding instrument, if required.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/referenced-payouts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Partner-Attribution-Id: bn1234" \
-H "PayPal-Request-Id: idempotent1234" \
-d '{
  "referenced_payouts": [
    {
      "reference_id": "2KP03934U4415543C",
      "reference_type": "TRANSACTION_ID"
    },
    {
      "reference_id": "8TA4226978212399L",
      "reference_type": "TRANSACTION_ID"
    }
  ]
}'

Response

A successful request returns the HTTP 202 Accepted status code and a JSON response body that includes a HATEOAS link to the ID for the batch payout.
  • referenced_payouts

    array (contains the referenced_payouts_item object)

    An array of referenced payouts items. For synchronous execution, the maximum number of items is 10. If you include more than 10 items, the request is processed asynchronously no matter what the partner defined in the Prefer request header.
  • payout_directive

    object

    The payout directive. Defines how the payout is made following the referenced payouts, if required. If you include this directive, all items in the request must be for the same original receiver. Otherwise, the request fails. You can override the payout directive at the item level to a different funding instrument, if required.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts/CDZEC5MJ8R5HY",
      "rel": "self",
      "method": "GET"
    }
  ]
}

List items in referenced batch payout

GET /v1/payments/referenced-payouts/{payouts_batch_id}
Lists the payout items in a referenced batch payout, by ID. Each item in the list includes payout item details.

Path parameters

  • payouts_batch_id

    string

    required

    The ID of the reference batch payout for which to list items.

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/referenced-payouts/CDZEC5MJ8R5HY \
-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 lists all items, with details, in the referenced batch payout.
  • referenced_payouts

    array (contains the referenced_payouts_item object)

    An array of referenced payouts items. For synchronous execution, the maximum number of items is 10. If you include more than 10 items, the request is processed asynchronously no matter what the partner defined in the Prefer request header.
  • payout_directive

    object

    The payout directive. Defines how the payout is made following the referenced payouts, if required. If you include this directive, all items in the request must be for the same original receiver. Otherwise, the request fails. You can override the payout directive at the item level to a different funding instrument, if required.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "referenced_payouts": [
    {
      "item_id": "8TA4226978212353L",
      "processing_state": {
        "status": "PAYOUT_INITIATED"
      },
      "reference_id": "2KP03934U4415543C",
      "reference_type": "TRANSACTION_ID",
      "payout_amount": {
        "currency_code": "USD",
        "value": "1.0"
      },
      "payout_destination": "CC-CDZEC5MJ8R5HY",
      "payout_transaction_id": "3KP03934U4415543D",
      "disbursement_transaction_id": "4KP03934U4415543E",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items/8TA4226978212353L",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "item_id": "9TA4226978212353M",
      "processing_state": {
        "status": "PAYOUT_INITIATED"
      },
      "reference_id": "8TA4226978212399L",
      "reference_type": "TRANSACTION_ID",
      "payout_amount": {
        "currency_code": "USD",
        "value": "1.0"
      },
      "payout_destination": "CC-CDZEC5MJ8R5HY",
      "payout_transaction_id": "4KP03934U4415543D",
      "disbursement_transaction_id": "5KP03934U4415543E",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items/9TA4226978212353M",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "payout_directive": {
    "financial_instrument_id": "CC-CDZEC5MJ8R5HY"
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts/CDZEC5MJ8R5HY",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Referenced payouts items (resource group)

Enables you to create a referenced payout item and show details for a payout item, by ID.

Create referenced payout item

POST /v1/payments/referenced-payouts-items
Creates a referenced payout item.

Header parameters

For more information about HTTP request headers, see HTTP request headers.
  • Prefer

    string

    Indicates how the client expects the server to process this request. To process the request asynchronously, set this header to respond-async. If you omit this header, the API processes the request synchronously.
  • PayPal-Partner-Attribution-Id

    string

    For more information about PayPal-Partner-Attribution-Id, see PayPal-Partner-Attribution-Id.
  • PayPal-Request-Id

    string

    The server stores keys forever. For more information about PayPal-Request-Id, see PayPal-Request-Id.

Request body

  • item_id

    string

    The ID for the payout item request.
  • processing_state

    object

    The processing state of the reference payout.
  • reference_id

    string

    The original reference ID, based on reference_type, based on the type payout.
  • reference_type

    enum

    The reference type. The allowed values are:
    • TRANSACTION_ID. The reference type is a transaction ID.
    • OTHERS. The reference type is other.
  • disbursement_transaction_id

    string

    The encrypted PayPal transaction ID for the disbursement when the money is moved from settlement hold to receiver.
  • external_merchant_id

    string

    The unique ID for the merchant on the partner side. Can be used to retrieve the PayPal account linked to this ID for the payout.
  • external_reference_id

    string

    The unique ID for the request on the partner side to enable idempotency. If this parameter is not available, idempotency is enabled for this item.
  • payee_email

    string

    The PayPal merchant account email that receives the payout. Can be used to override the default behavior where the payout receiver is derived from the reference that is passed.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

  • payout_amount

    object

    The amount to be paid to merchant.
  • invoice_id

    string

    The partner invoice ID for this referenced-payouts item. Used for reporting purposes only.
  • custom

    string

    The partner custom data for this referenced-payouts item. Used for reporting purposes only.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Partner-Attribution-Id: bn1234" \
-H "PayPal-Request-Id: some-idempotency-data" \
-d '{
  "reference_id": "CAPTURETXNID",
  "reference_type": "TRANSACTION_ID"
}'

Response

If the Prefer request header is respond-async and the API successfully queued the request for processing, a successful request returns the HTTP 202 Accepted status code and the API proceeds to process the request asynchronously.
  • item_id

    string

    The ID for the payout item request.
  • processing_state

    object

    The processing state of the reference payout.
  • reference_id

    string

    The original reference ID, based on reference_type, based on the type payout.
  • reference_type

    enum

    The reference type. The possible values are:
    • TRANSACTION_ID. The reference type is a transaction ID.
    • OTHERS. The reference type is other.
  • payout_transaction_id

    string

    The encrypted PayPal transaction ID for the payout when the item_status is success.

    Read only.

  • disbursement_transaction_id

    string

    The encrypted PayPal transaction ID for the disbursement when the money is moved from settlement hold to receiver.
  • external_merchant_id

    string

    The unique ID for the merchant on the partner side. Can be used to retrieve the PayPal account linked to this ID for the payout.
  • external_reference_id

    string

    The unique ID for the request on the partner side to enable idempotency. If this parameter is not available, idempotency is enabled for this item.
  • payee_email

    string

    The PayPal merchant account email that receives the payout. Can be used to override the default behavior where the payout receiver is derived from the reference that is passed.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

  • payout_amount

    object

    The amount to be paid to merchant.
  • payout_destination

    string

    The encrypted PayPal account number or the ID of the financial instrument that received the payout.

    Read only.

  • invoice_id

    string

    The partner invoice ID for this referenced-payouts item. Used for reporting purposes only.
  • custom

    string

    The partner custom data for this referenced-payouts item. Used for reporting purposes only.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "item_id": "SOMEITEMID",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items/SOMEITEMID",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Show referenced payout item details

GET /v1/payments/referenced-payouts-items/{payouts_item_id}
Shows details for a referenced payout item, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Path parameters

  • payouts_item_id

    string

    required

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

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items/CDZEC5MJ8R5HY \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Partner-Attribution-Id: bn1234"

Response

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

    string

    The ID for the payout item request.
  • processing_state

    object

    The processing state of the reference payout.
  • reference_id

    string

    The original reference ID, based on reference_type, based on the type payout.
  • reference_type

    enum

    The reference type. The possible values are:
    • TRANSACTION_ID. The reference type is a transaction ID.
    • OTHERS. The reference type is other.
  • payout_transaction_id

    string

    The encrypted PayPal transaction ID for the payout when the item_status is success.

    Read only.

  • disbursement_transaction_id

    string

    The encrypted PayPal transaction ID for the disbursement when the money is moved from settlement hold to receiver.
  • external_merchant_id

    string

    The unique ID for the merchant on the partner side. Can be used to retrieve the PayPal account linked to this ID for the payout.
  • external_reference_id

    string

    The unique ID for the request on the partner side to enable idempotency. If this parameter is not available, idempotency is enabled for this item.
  • payee_email

    string

    The PayPal merchant account email that receives the payout. Can be used to override the default behavior where the payout receiver is derived from the reference that is passed.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

  • payout_amount

    object

    The amount to be paid to merchant.
  • payout_destination

    string

    The encrypted PayPal account number or the ID of the financial instrument that received the payout.

    Read only.

  • invoice_id

    string

    The partner invoice ID for this referenced-payouts item. Used for reporting purposes only.
  • custom

    string

    The partner custom data for this referenced-payouts item. Used for reporting purposes only.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "item_id": "SOMEITEMID",
  "processing_state": {
    "status": "PROCESSING"
  },
  "reference_id": "CAPTURETXNID",
  "reference_type": "TRANSACTION_ID",
  "payout_amount": {
    "currency_code": "USD",
    "value": "2.0"
  },
  "payout_destination": "PAYERED",
  "payout_transaction_id": "PAYOUTTXNID",
  "links": [
    {
      "href": "https://api.paypal.com/v1/payments/referenced-payouts-items/SOMEITEMID",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Common object definitions

currency_code

email_address

  • email_address

    string

    The internationalized email address.
    Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

error

  • name

    string

    required

    The human-readable, unique name of the error.
  • message

    string

    required

    The message that describes the error.
  • debug_id

    string

    required

    The PayPal internal ID. Used for correlation purposes.
  • information_link

    string

    The information link, or URI, that shows detailed information about this error for the developer.

    Read only.

  • details

    array (contains the error_details object)

    An array of additional details about the error.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

error_details

  • field

    string

    The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
  • value

    string

    The value of the field that caused the error.
  • location

    string

    The location of the field that caused the error. Value is body, path, or query.

    Default: body.

  • issue

    string

    required

    The reason for the error.

item_status

  • item_status

    enum

    The item status. The possible values are:
    • PENDING. The item is pending.
    • PROCESSING. The item is processing.
    • SUCCESS. The item succeeded.
    • FAILED. The item failed.
    • PAYOUT_FAILED. The payout failed for the item.

money

  • currency_code

    string

    required

    The three-character ISO-4217 currency code that identifies the currency.

    Minimum length: 3.

    Maximum length: 3.

  • value

    string

    required

    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.

    Maximum length: 32.

    Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

patch

  • op

    enum

    required

    The operation. The possible values are:
    • add. Depending on the target location reference, completes one of these functions:
      • The target location is an array index. Inserts a new value into the array at the specified index.
      • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
      • The target location is an object parameter that does exist. Replaces that parameter's value.
      The value parameter defines the value to add. For more information, see 4.1. add.
    • remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
    • replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
    • move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
    • copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.
    • test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
      TypeConsidered equal if both values
      stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
      numbersAre numerically equal.
      arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
      objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
      literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
      For more information, see 4.6. test.
  • path

    string

    The JSON Pointer to the target document location at which to complete the operation.
  • value

    number,integer,string,boolean,null,array,object

    The value to apply. The remove operation does not require a value.
  • from

    string

    The JSON Pointer to the target document location from which to move the value. Required for the move operation.

patch_request

  • patch_request

    array (contains the patch object)

    An array of JSON patch objects to apply partial updates to resources.

payout_directive

  • financial_instrument_id

    string

    required

    The PayPal-provided ID of the financial instrument that receives the payout. If you omit this value, the payout is made to the receiver's balance by default. If you include payee_email to override the original receiver on the individual item or items, the API ignores this field.

    Minimum length: 1.

    Maximum length: 255.

processing_state

  • status

    enum

    The item status. The possible values are:
    • PENDING. The item is pending.
    • PROCESSING. The item is processing.
    • SUCCESS. The item succeeded.
    • FAILED. The item failed.
    • PAYOUT_FAILED. The payout failed for the item.
  • reason

    enum

    The reason code. The possible values are:
    • INTERNAL_ERROR. An internal error occurred.
    • NOT_ENOUGH_BALANCE. The balance is not enough.
    • AMOUNT_CHECK_FAILED. The amount check failed.
    • MERCHANT_PARTNER_PERMISSIONS_ISSUE. A merchant-partner permissions issue occurred.
    • MERCHANT_RESTRICTIONS. The merchant has restrictions.
    • TRANSACTION_UNDER_DISPUTE. The transaction is under dispute.
    • TRANSACTION_NOT_VALID. The transaction is not valie.
    • UNSUPPORTED_CURRENCY. The currency is not supported.
    • PAYOUT_INITIATED. The payout was already initiated.
    • PAYOUT_ALREADY_COMPLETED_FOR_REFERENCE. The payout was already completed.

reason_code

  • reason_code

    enum

    The reason code. The possible values are:
    • INTERNAL_ERROR. An internal error occurred.
    • NOT_ENOUGH_BALANCE. The balance is not enough.
    • AMOUNT_CHECK_FAILED. The amount check failed.
    • MERCHANT_PARTNER_PERMISSIONS_ISSUE. A merchant-partner permissions issue occurred.
    • MERCHANT_RESTRICTIONS. The merchant has restrictions.
    • TRANSACTION_UNDER_DISPUTE. The transaction is under dispute.
    • TRANSACTION_NOT_VALID. The transaction is not valie.
    • UNSUPPORTED_CURRENCY. The currency is not supported.
    • PAYOUT_INITIATED. The payout was already initiated.
    • PAYOUT_ALREADY_COMPLETED_FOR_REFERENCE. The payout was already completed.

reference_type

  • reference_type

    enum

    The reference type. The possible values are:
    • TRANSACTION_ID. The reference type is a transaction ID.
    • OTHERS. The reference type is other.

referenced_payouts

  • referenced_payouts

    array (contains the referenced_payouts_item object)

    An array of referenced payouts items. For synchronous execution, the maximum number of items is 10. If you include more than 10 items, the request is processed asynchronously no matter what the partner defined in the Prefer request header.
  • payout_directive

    object

    The payout directive. Defines how the payout is made following the referenced payouts, if required. If you include this directive, all items in the request must be for the same original receiver. Otherwise, the request fails. You can override the payout directive at the item level to a different funding instrument, if required.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

referenced_payouts_item

  • item_id

    string

    The ID for the payout item request.
  • processing_state

    object

    The processing state of the reference payout.
  • reference_id

    string

    The original reference ID, based on reference_type, based on the type payout.
  • reference_type

    enum

    The reference type. The possible values are:
    • TRANSACTION_ID. The reference type is a transaction ID.
    • OTHERS. The reference type is other.
  • payout_transaction_id

    string

    The encrypted PayPal transaction ID for the payout when the item_status is success.

    Read only.

  • disbursement_transaction_id

    string

    The encrypted PayPal transaction ID for the disbursement when the money is moved from settlement hold to receiver.
  • external_merchant_id

    string

    The unique ID for the merchant on the partner side. Can be used to retrieve the PayPal account linked to this ID for the payout.
  • external_reference_id

    string

    The unique ID for the request on the partner side to enable idempotency. If this parameter is not available, idempotency is enabled for this item.
  • payee_email

    string

    The PayPal merchant account email that receives the payout. Can be used to override the default behavior where the payout receiver is derived from the reference that is passed.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

  • payout_amount

    object

    The amount to be paid to merchant.
  • payout_destination

    string

    The encrypted PayPal account number or the ID of the financial instrument that received the payout.

    Read only.

  • invoice_id

    string

    The partner invoice ID for this referenced-payouts item. Used for reporting purposes only.
  • custom

    string

    The partner custom data for this referenced-payouts item. Used for reporting purposes only.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

referenced_payouts_items

Additional API information

Error messages

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

  • AUTHENTICATION_FAILURE

    Authentication failed due to invalid authentication credentials. See Authorization errors. The request requires authentication and none was provided. Note the difference between this error and the 403 Forbidden error.

  • INTERNAL_SERVER_ERROR

    An internal server error has occurred. A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. This error indicates a server-side software defect or site outage.

  • INVALID_REQUEST

    Request is not well-formed, syntactically incorrect, or violates schema. See Validation errors. The server could not understand the request. This status code indicates one of these conditions:

    • The data as part of the payload cannot be converted to the underlying data type.
    • The data is not in the expected data format.
    • Required field is not available.
    • A simple data validation error occurred.

  • NOT_AUTHORIZED

    Authorization failed due to insufficient permissions. The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct OAuth2 scope. Additionally, a business-level authorization error might have occurred. For example, the account holder does not have sufficient funds.

  • RESOURCE_NOT_FOUND

    The specified resource does not exist. The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key.

  • SERVICE_UNAVAILABLE

    Service Unavailable. The server cannot handle the request for a service due to temporary maintenance.

Popular Search Queries
PayPal Help
FAQ's

FAQ's
Forum

Tech Support Community
PayPal Community