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.
Creates a referenced batch payout for asynchronous, offline processing. Include a sender_batch_header
object and an items
array in the request URI.
Array of objects (referenced_payouts_item) <= 1000 items An array of referenced payouts items. For synchronous execution, the maximum number of items is | |
object (payout_directive) The funding instrument that receives the payout. |
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": [
- {
- "reference_id": "2KP03934U4415543C",
- "reference_type": "TRANSACTION_ID"
}, - {
- "reference_id": "8TA4226978212399L",
- "reference_type": "TRANSACTION_ID"
}
]
}
{- "links": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
Lists the payout items in a referenced batch payout, by ID. Each item in the list includes payout item details.
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.
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts/KHbwO28lWlXwi2IlToJ2IYNG4juFv6kpbFx4J9oQ5Hb24RSp96Dk5FudVHd6v4E= \ -H 'Content-Type: application/json' \ -H 'Content-Encoding: gzip'
{- "referenced_payouts": [
- {
- "item_id": "dVeQhMc5Ck5WPw2gWYDLzh3qM2Dp1XbRlZb9fDouzLzDhx1eMYYTFe3syHEKKx4=",
- "processing_state": {
- "status": "SUCCESS"
}, - "reference_id": "2KP03934U4415543C",
- "reference_type": "TRANSACTION_ID",
- "payout_amount": {
- "currency_code": "USD",
- "value": "1.0"
}, - "payout_destination": "KJDHGANDJ4DPZ",
- "payout_transaction_id": "3KP03934U4415543D",
- "disbursement_transaction_id": "4KP03934U4415543E",
- "links": [
- {
- "rel": "self",
- "method": "GET"
}
]
}, - {
- "item_id": "spK0ggOfijUiOUtbXBepp3h5tolruRWTl4aED-_6yz25POeNFABpkewSIxIXh4A=",
- "processing_state": {
- "status": "SUCCESS"
}, - "reference_id": "8TA4226978212399L",
- "reference_type": "TRANSACTION_ID",
- "payout_amount": {
- "currency_code": "USD",
- "value": "1.0"
}, - "payout_destination": "KJDHGANDJ4DPZ",
- "payout_transaction_id": "4KP03934U4415543D",
- "disbursement_transaction_id": "5KP03934U4415543E",
- "links": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
], - "payout_directive": {
- "destination": "CC-CDZEC5MJ8R5HY",
- "type": "FINANCIAL_INSTRUMENT_ID"
}, - "links": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
Creates a referenced payout item.
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.
{- "reference_id": "CAPTURETXNID",
- "reference_type": "TRANSACTION_ID"
}
{- "item_id": "SOMEITEMID",
- "links": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
Shows details for a referenced payout item, by ID.
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows payout item details.
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'
{- "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": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
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.
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.
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:
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.
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.
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.
Message:
Service Unavailable.
Description: The server cannot handle the request for a service due to temporary maintenance.
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.
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"
The three-character ISO-4217 currency code that identifies the currency.
The three-character ISO-4217 currency code that identifies the currency.
"str"
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"
}
]
}
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 |
issue required | string The reason for the error. |
{- "field": "string",
- "value": "string",
- "location": "body",
- "issue": "string"
}
The 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"
The request-related HATEOAS link information.
href required | string The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the |
rel required | string The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations. |
method | string The HTTP method required to make the related call. |
{- "href": "string",
- "rel": "string",
- "method": "GET"
}
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:
|
{- "currency_code": "str",
- "value": "string"
}
The JSON patch object to apply partial updates to resources.
op required | string The operation.
| ||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||
from | string The JSON Pointer to the target document location from which to move the value. Required for the |
{- "op": "add",
- "path": "string",
- "value": 0,
- "from": "string"
}
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.
|
{- "destination": "string",
- "type": "FINANCIAL_INSTRUMENT_ID"
}
The directive type.
The directive type.
Enum: | Description |
---|---|
FINANCIAL_INSTRUMENT_ID | The paypal provided ID of the financial instrument that receives the payout. |
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"
The processing state of the reference payout.
status | string (item_status) The item status.
| ||||||||||||||||||||||||||||||||||||
reason | string (reason_code) The reason code.
|
{- "status": "PROCESSING",
- "reason": "INTERNAL_ERROR"
}
The 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"
The reference type.
The reference type.
Enum: | Description |
---|---|
TRANSACTION_ID | The reference type is a transaction ID. |
OTHERS | The reference type is other. |
"TRANSACTION_ID"
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 | |
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"
}
}
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 | string (reference_type) The reference type.
| ||||||
payout_transaction_id | string The encrypted PayPal transaction ID for the payout when the | ||||||
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"
}
}