Referenced Payouts (1)

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.

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.

SecurityOauth2
Request
header Parameters
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
PayPal-Request-Id
string

The server stores keys for three days.

Request Body schema: application/json
Array of objects (referenced_payouts_item) <= 1000 items

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.

object (payout_directive)

The funding instrument that receives the payout.

Responses
202

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.

Request samples
application/json
{
  • "referenced_payouts": [
    • {
      • "reference_id": "2KP03934U4415543C",
      • "reference_type": "TRANSACTION_ID"
      },
    • {
      • "reference_id": "8TA4226978212399L",
      • "reference_type": "TRANSACTION_ID"
      }
    ]
}
Response samples
application/json
{}

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.

SecurityOauth2
Request
path Parameters
payouts_batch_id
required
string

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

Responses
200

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.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts/KHbwO28lWlXwi2IlToJ2IYNG4juFv6kpbFx4J9oQ5Hb24RSp96Dk5FudVHd6v4E= \
-H 'Content-Type: application/json' \
-H 'Content-Encoding: gzip'
Response samples
application/json
{}

Create referenced payout item

post/v1/payments/referenced-payouts-items

Creates a referenced payout item.

SecurityOauth2
Request
header Parameters
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
PayPal-Request-Id
string

The server stores keys forever.

Request Body schema: application/json
item_id
string

The ID for the payout item request.

object (processing_state)

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
string (reference_type)

The reference type.

Enum: Description
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 reference ID for the request on the partner side. This is an external reference ID and means nothing in PayPal's system. The value is associated with any object created by the call and is included any time the object's data is returned. For example, in webhooks, GET operations, and the POST response.

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.

payee_email
string <ppaas_common_email_address_v2> (common_components-v2-schema-json-openapi-2.0-email_address.json) [ 3 .. 254 ] characters ^.+@[^"\-].+$

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.

object (Money)

The amount to be paid to merchant.

Responses
202

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.

Request samples
application/json
{
  • "reference_id": "CAPTURETXNID",
  • "reference_type": "TRANSACTION_ID"
}
Response samples
application/json
{}

Show referenced payout item details

get/v1/payments/referenced-payouts-items/{payouts_item_id}

Shows details for a referenced payout item, by ID.

SecurityOauth2
Request
path Parameters
payouts_item_id
required
string

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

header Parameters
PayPal-Partner-Attribution-Id
string
Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts-items/CDZEC5MJ8R5HY \
-H 'Content-Type: application/json' \
-H 'Content-Encoding: gzip' \
-H 'PayPal-Partner-Attribution-Id: bn1234'
Response samples
application/json
{
  • "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": []
}

Errors

AUTHENTICATION_FAILURE

Message:
Authentication failed due to invalid authentication credentials.

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

Message:
An internal server error has occurred.

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

Message:
Request is not well-formed, syntactically incorrect, or violates schema.

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

Message:
Authorization failed due to insufficient permissions.

Description: 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.

ONGOING_ACTIVITY_ON_REFERENCE

Message:
The server is already processing a previous request on this reference, please try after some time.

Description: The server is already processing a previous request on this reference, please try after some time.

RESOURCE_NOT_FOUND

Message:
The specified resource does not exist.

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

Message:
Service Unavailable.

Description: The server cannot handle the request for a service due to temporary maintenance.

Definitions

common_components-v2-schema-json-openapi-2.0-email_address.json

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.

string <ppaas_common_email_address_v2> (common_components-v2-schema-json-openapi-2.0-email_address.json) [ 3 .. 254 ] characters ^.+@[^"\-].+$

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.

"string"

common_components-v3-schema-json-openapi-2.0-currency_code.json

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

string <ppaas_common_currency_code_v2> (common_components-v3-schema-json-openapi-2.0-currency_code.json) = 3 characters

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

"str"

Error

The error information.

name
required
string

The human-readable, unique name of the error.

message
required
string

The message that describes the error.

debug_id
required
string

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.

Array of objects (Error Details)

An array of additional details about the error.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}

Error Details

The error details. Required for client-side 4XX errors.

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
Default: "body"

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

issue
required
string

The reason for the error.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string"
}

item_status

The item status.

string (item_status)

The item status.

Enum: Description
PROCESSING

The item is processing.

SUCCESS

The item succeeded.

FAILED

The item failed.

PAYOUT_FAILED

The payout failed for the item.

"PROCESSING"

Money

The currency and amount for a financial transaction, such as a balance or payment due.

currency_code
required
string <ppaas_common_currency_code_v2> (common_components-v3-schema-json-openapi-2.0-currency_code.json) = 3 characters

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

value
required
string <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

{
  • "currency_code": "str",
  • "value": "string"
}

Patch

The JSON patch object to apply partial updates to resources.

op
required
string

The operation.

Enum: Description
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.

(Patch Value (number or null)) or (Patch Value (integer or null)) or (Patch Value (string or null)) or (Patch Value (boolean or null)) or (Array of Patch Value (any or null)) or (Patch Value (object or null)) (Patch Value)

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.

{
  • "op": "add",
  • "path": "string",
  • "value": 0,
  • "from": "string"
}

payout_directive

The funding instrument that receives the payout.

destination
required
string [ 1 .. 255 ] characters

The destination can be one of the specified directive type that receives the payout.

type
required
string (payout_directive_type)

The directive type.

Enum: Description
FINANCIAL_INSTRUMENT_ID

The paypal provided ID of the financial instrument that receives the payout.

EMAIL

The valid paypal email address of an account that receives the payout.

ACCOUNT_ID

The payer id of a valid paypal account that receives the payout.

{
  • "destination": "string",
  • "type": "FINANCIAL_INSTRUMENT_ID"
}

payout_directive_type

The directive type.

string (payout_directive_type)

The directive type.

Enum: Description
FINANCIAL_INSTRUMENT_ID

The paypal provided ID of the financial instrument that receives the payout.

EMAIL

The valid paypal email address of an account that receives the payout.

ACCOUNT_ID

The payer id of a valid paypal account that receives the payout.

"FINANCIAL_INSTRUMENT_ID"

processing_state

The processing state of the reference payout.

status
string (item_status)

The item status.

Enum: Description
PROCESSING

The item is processing.

SUCCESS

The item succeeded.

FAILED

The item failed.

PAYOUT_FAILED

The payout failed for the item.

reason
string (reason_code)

The reason code.

Enum: Description
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_ON_HOLD

A payout cannot be done for this transaction at this time because the underlying transaction is currently on hold.

TRANSACTION_NOT_VALID

The transaction is not valid.

UNSUPPORTED_CURRENCY

The currency is not supported.

PAYOUT_INITIATED

The payout was already initiated.

PAYOUT_ALREADY_COMPLETED_FOR_REFERENCE

The payout was already completed.

ONGOING_ACTIVITY_ON_REFERENCE

The server is already processing a previous request on this reference, please try after some time.

INSUFFICIENT_AMOUNT

Requested Payout Amount More Than Available Amount.

INVALID_PARAMETERS

Invalid Parameters.

TRANSACTION_ALREADY_REVERSED

Referenced Transaction Already Reversed.

TRANSACTION_DENIED

Referenced Transaction Already Reversed Denied.

TRANSACTION_PENDING_FROM_RECEIPIENT

Referenced Transaction Pending From Merchant.

{
  • "status": "PROCESSING",
  • "reason": "INTERNAL_ERROR"
}

reason_code

The reason code.

string (reason_code)

The reason code.

Enum: Description
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_ON_HOLD

A payout cannot be done for this transaction at this time because the underlying transaction is currently on hold.

TRANSACTION_NOT_VALID

The transaction is not valid.

UNSUPPORTED_CURRENCY

The currency is not supported.

PAYOUT_INITIATED

The payout was already initiated.

PAYOUT_ALREADY_COMPLETED_FOR_REFERENCE

The payout was already completed.

ONGOING_ACTIVITY_ON_REFERENCE

The server is already processing a previous request on this reference, please try after some time.

INSUFFICIENT_AMOUNT

Requested Payout Amount More Than Available Amount.

INVALID_PARAMETERS

Invalid Parameters.

TRANSACTION_ALREADY_REVERSED

Referenced Transaction Already Reversed.

TRANSACTION_DENIED

Referenced Transaction Already Reversed Denied.

TRANSACTION_PENDING_FROM_RECEIPIENT

Referenced Transaction Pending From Merchant.

"INTERNAL_ERROR"

reference_type

The reference type.

string (reference_type)

The reference type.

Enum: Description
TRANSACTION_ID

The reference type is a transaction ID.

OTHERS

The reference type is other.

"TRANSACTION_ID"

referenced_payouts

An array of referenced payout batch items.

Array of objects (referenced_payouts_item) <= 1000 items

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.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (payout_directive)

The funding instrument that receives the payout.

{
  • "referenced_payouts": [
    • {
      • "item_id": "string",
      • "processing_state": {
        • "status": "PROCESSING",
        • "reason": "INTERNAL_ERROR"
        },
      • "reference_id": "string",
      • "reference_type": "TRANSACTION_ID",
      • "payout_transaction_id": "string",
      • "disbursement_transaction_id": "string",
      • "external_merchant_id": "string",
      • "external_reference_id": "string",
      • "payout_destination": "string",
      • "invoice_id": "string",
      • "custom": "string",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "payee_email": "string",
      • "payout_amount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "payout_directive": {
    • "destination": "string",
    • "type": "FINANCIAL_INSTRUMENT_ID"
    }
}

referenced_payouts_item

The referenced payouts item.

item_id
string

The ID for the payout item request.

object (processing_state)

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
string (reference_type)

The reference type.

Enum: Description
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.

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 reference ID for the request on the partner side. This is an external reference ID and means nothing in PayPal's system. The value is associated with any object created by the call and is included any time the object's data is returned. For example, in webhooks, GET operations, and the POST response.

payout_destination
string

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

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.

Array of objects (Link Description)

An array of request-related HATEOAS links.

payee_email
string <ppaas_common_email_address_v2> (common_components-v2-schema-json-openapi-2.0-email_address.json) [ 3 .. 254 ] characters ^.+@[^"\-].+$

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.

object (Money)

The amount to be paid to merchant.

{
  • "item_id": "string",
  • "processing_state": {
    • "status": "PROCESSING",
    • "reason": "INTERNAL_ERROR"
    },
  • "reference_id": "string",
  • "reference_type": "TRANSACTION_ID",
  • "payout_transaction_id": "string",
  • "disbursement_transaction_id": "string",
  • "external_merchant_id": "string",
  • "external_reference_id": "string",
  • "payout_destination": "string",
  • "invoice_id": "string",
  • "custom": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "payee_email": "string",
  • "payout_amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}