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

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

    Optional. Indicates that you are a PayPal partner. To receive revenue attribution, specify a unique build notation (BN) code. BN codes provide tracking on all transactions that originate or are associated with a particular partner. To learn more or to request a BN code, contact your partner manager or visit the PayPal Partner Portal. For more information about PayPal-Partner-Attribution-Id, see PayPal-Partner-Attribution-Id.
  • PayPal-Request-Id

    string

    Optional. Contains a unique user-generated ID that you can use to enforce idempotency.
    Note: If you omit this header, the risk of duplicate transactions increases.
    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 item.
  • reference_id

    string

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

    enum

    The type of the passed reference. For example, transaction_id.

    Allowed values: TRANSACTION_ID, OTHERS.

  • payout_transaction_id

    string

    The encrypted PayPal transaction ID for the payout when the item_status is success.
  • 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

    object

    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 that received the payout. Can be different than the account related to payee_email, based on partner and merchant grants and permissions.
  • 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.

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

    string

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

    enum

    The type of the passed reference. For example, transaction_id.

    Possible values: TRANSACTION_ID, OTHERS.

  • payout_transaction_id

    string

    The encrypted PayPal transaction ID for the payout when the item_status is success.
  • 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

    object

    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 that received the payout. Can be different than the account related to payee_email, based on partner and merchant grants and permissions.
  • 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.

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.
  • PayPal-Partner-Attribution-Id

    string

    Optional. Indicates that you are a PayPal partner. To receive revenue attribution, specify a unique build notation (BN) code. BN codes provide tracking on all transactions that originate or are associated with a particular partner. To learn more or to request a BN code, contact your partner manager or visit the PayPal Partner Portal. For more information about PayPal-Partner-Attribution-Id, see PayPal-Partner-Attribution-Id.

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

    string

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

    enum

    The type of the passed reference. For example, transaction_id.

    Possible values: TRANSACTION_ID, OTHERS.

  • payout_transaction_id

    string

    The encrypted PayPal transaction ID for the payout when the item_status is success.
  • 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

    object

    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 that received the payout. Can be different than the account related to payee_email, based on partner and merchant grants and permissions.
  • 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.

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

batch_header

  • sender_batch_id

    string

    required

    The ID of the batch from the request file.
  • partner_account_email

    string

    required

    The partner account email.

batch_item_collections

  • batch_header

    object

    required

    The status of the requested batch.
  • batch_items

    array (contains the referenced_payouts_item object)

    required

    An array of batch items.

batch_request

  • sender_batch_header

    object

    required

    The batch header as sent in the batch creation.
  • batch_items

    array (contains the referenced_payouts_item object)

    required

    An array of batch items.

batch_response

  • batch_status_details

    object

    The status of the requested batch payout with item details.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

batch_response_header

  • batch_id

    string

    required

    The ID for the batch.
  • batch_status

    enum

    required

    The generated batch status. If the batch passes the elementary checks, the status is PENDING.

    Possible values: DENIED, PENDING, PROCESSING, FAILED, SUCCESS.

  • sender_batch_header

    object

    required

    The original batch header as provided by the payment sender.

batch_status_enum

  • batch_status_enum

    enum

    The batch status.

    Possible values: DENIED, PENDING, PROCESSING, FAILED, SUCCESS.

currency_code

email_address

  • email_address

    string

    A valid 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

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

    string

    required

    A message that describes the error.
  • debug_id

    string

    required

    The PayPal internal ID that is used for correlation purposes.
  • information_link

    string

    An information link, or URI, that shows detailed information about this error for the developer.
  • 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.

error_details

  • field

    string

    The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. 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. A valid value is body, path, or query. Default is body.
  • issue

    string

    required

    The reason for the error.

item_status_enum

  • item_status_enum

    enum

    The item status.

    Possible values: PENDING, PROCESSING, SUCCESS, FAILED.

money

  • currency_code

    string

    required

    The three-character ISO-4217 currency code.

    Minimum length: 3.

    Maximum length: 3.

  • value

    string

    required

    The currency value. For currencies like JPY that are not typically fractional, might be an integer. For currencies like TND that are subdivided into thousandths, might be a decimal fraction. For the required number of decimal places for a currency code, see ISO 4217.

    Maximum length: 32.

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

patch

  • op

    enum

    required

    The operation to complete.

    Possible values: add, remove, replace, move, copy, test.

  • path

    string

    A JSON pointer. References a location in the target document where the operation is completed.
  • value

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

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

    string

    A JSON pointer. References the location in the target document 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.

processing_state

  • status

    enum

    The status of the item.

    Possible values: PENDING, PROCESSING, SUCCESS, FAILED.

  • reason

    enum

    The qualifying reason for the current status. Provides more information for failures.

    Possible values: INTERNAL_ERROR, NOT_ENOUGH_BALANCE, AMOUNT_CHECK_FAILED, MERCHANT_PARTNER_PERMISSIONS_ISSUE, MERCHANT_RESTRICTIONS, TRANSACTION_UNDER_DISPUTE, TRANSACTION_NOT_VALID, UNSUPPORTED_CURRENCY.

reason_code

  • reason_code

    enum

    The reason code.

    Possible values: INTERNAL_ERROR, NOT_ENOUGH_BALANCE, AMOUNT_CHECK_FAILED, MERCHANT_PARTNER_PERMISSIONS_ISSUE, MERCHANT_RESTRICTIONS, TRANSACTION_UNDER_DISPUTE, TRANSACTION_NOT_VALID, UNSUPPORTED_CURRENCY.

reference_type

  • reference_type

    enum

    The reference type.

    Possible values: TRANSACTION_ID, OTHERS.

referenced_payouts_item

  • item_id

    string

    The ID for the payout item request.
  • processing_state

    object

    The processing state of the item.
  • reference_id

    string

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

    enum

    The type of the passed reference. For example, transaction_id.

    Possible values: TRANSACTION_ID, OTHERS.

  • payout_transaction_id

    string

    The encrypted PayPal transaction ID for the payout when the item_status is success.
  • 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

    object

    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 that received the payout. Can be different than the account related to payee_email, based on partner and merchant grants and permissions.
  • 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.

referenced_payouts_items

Additional API information

Error messages

In addition to 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 Authentication 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.

Feedback

Have feedback?

Let us know.