Referenced Payouts API
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
sender_batch_header
object and an items
array in the request URI.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
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 thePrefer
request header.payout_directive
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.
Sample Request
curl -v -X POST https://api-m.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
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 thePrefer
request header.payout_directive
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.
Sample Response
{
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts/CDZEC5MJ8R5HY",
"rel": "self",
"method": "GET"
}
]
}
List items in referenced batch payout
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-m.sandbox.paypal.com/v1/payments/referenced-payouts/KHbwO28lWlXwi2IlToJ2IYNG4juFv6kpbFx4J9oQ5Hb24RSp96Dk5FudVHd6v4E= \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
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 thePrefer
request header.payout_directive
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.
Sample Response
{
"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": [
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts-items/dVeQhMc5Ck5WPw2gWYDLzh3qM2Dp1XbRlZb9fDouzLzDhx1eMYYTFe3syHEKKx4=",
"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": [
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts-items/spK0ggOfijUiOUtbXBepp3h5tolruRWTl4aED-_6yz25POeNFABpkewSIxIXh4A=",
"rel": "self",
"method": "GET"
}
]
}
],
"payout_directive": {
"destination": "CC-CDZEC5MJ8R5HY",
"type": "FINANCIAL_INSTRUMENT_ID"
},
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts/KHbwO28lWlXwi2IlToJ2IYNG4juFv6kpbFx4J9oQ5Hb24RSp96Dk5FudVHd6v4E=",
"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
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
item_id
string
The ID for the payout item request.
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
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
issuccess
.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.
payee_email
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.
payout_amount
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.
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-m.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
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
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
issuccess
.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.
payee_email
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.
payout_amount
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.
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-m.sandbox.paypal.com/v1/payments/referenced-payouts-items/SOMEITEMID",
"rel": "self",
"method": "GET"
}
]
}
Show referenced payout item details
Header parameters
PayPal-Partner-Attribution-Id
string
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-m.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
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
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
issuccess
.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.
payee_email
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.
payout_amount
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.
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-m.paypal.com/v1/payments/referenced-payouts-items/SOMEITEMID",
"rel": "self",
"method": "GET"
}
]
}
Common object definitions
currency_code
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
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.
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.
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 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
, orquery
.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.
link_description
href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
money
The three-character ISO-4217 currency code that identifies the currency.
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.
- An integer for currencies like
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.
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 avalue
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 afrom
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, thefrom
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 afrom
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, thefrom
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 avalue
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 thevalue
value. For test,equal
indicates that the value at the target location and the value thatvalue
defines are of the same JSON type. The data type of the value determines how equality is defined:
For more information, see 4.6. test.Type Considered equal if both values strings Contain the same number of Unicode characters and their code points are byte-by-byte equal. numbers Are numerically equal. arrays Contain 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. objects Contain 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
, andnull
)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.
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
destination
string
required
The destination can be one of the specified directive type that receives the payout.
type
enum
required
The directive type.
The possible values are:
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.
payout_directive_type
payout_directive_type
enum
The directive type.
The possible values are:
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.
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_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.
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_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.
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 thePrefer
request header.payout_directive
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.
referenced_payouts_item
item_id
string
The ID for the payout item request.
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
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
issuccess
.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.
payee_email
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.
payout_amount
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.
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
items
array (contains the referenced_payouts_item object)
An array of 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.