Skip to main content
You can use the procedures in this section to customize your Payouts API integration to support global payments, optimize API responses, and ensure reliable payout processing.

​
Pay recipients in their local currency

You can pay recipients in any supported currency, even if your PayPal account does not hold a balance in that currency. To do this, set the items.amount.currency parameter in your payout request to the appropriate currency code. PayPal automatically converts currencies and applies relevant fees. This helps you reach recipients globally and simplify cross-border payments.
For more information about currency conversion, country exclusions, and restrictions, see Currency conversion.
Use a valid access token and make a GET call to the /v1/payments/payouts/{ID} endpoint. Path parameter: ID is the payout_batch_id returned in the Create payout batch response. 
curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/5UXD2E8A7EBQJ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'
A successful call returns a 200 OK response with the payout details, including currency conversion fee details for each payout item.

​
Get specific payout details

When you track payouts status, you can use the fields query parameter and customize the response to return only the information you need. This enables you to tailor the API output for summary reporting or reconciliation. Requesting specific fields reduces response size and improves performance. Use a valid access token and make a GET call to the /v1/payments/payouts/{ID}?fields={FIELDS} endpoint. Path parameter: ID is the payout_batch_id returned in the Create payout batch response. Query parameter: FIELDS are the specific fields that you need in the response. For example, you can request only the batch_header for a summary. 
curl -v -X GET 'https://api-m.sandbox.paypal.com/v1/payments/payouts/NNX8XK9T3CGWN?fields=batch_header' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'
A successful call returns a 200 OK response with the requested details of the payout batch.

​
Prevent duplicate requests

You can prevent the processing of duplicate batch payouts. To do this, in the create payout batch request, use a unique sender_batch_id for each batch. If you reuse a sender_batch_id from the last 30 days, the API rejects the request and returns an error with a HATEOAS link to the original batch. When you retry a request after an HTTP 5xx error, use the same sender_batch_id as the original request to ensure PayPal processes only one batch, even if you submit multiple requests.

​
Implement idempotency

You can retry a payout request multiple times and still ensure that it has the effect of only one successful request, through idempotency. To implement idempotency:
  • Include a unique, self-generated idempotency key as the PayPal-Request-Id header-parameter value for each payout request.
  • Use the same idempotency key when you retry the request due to a network issue or HTTP 5xx server error.
  • If the payout details already exist, PayPal returns the current state of the payout. This ensures you create only one payout for each unique key.
If PayPal receives two simultaneous requests with the same PayPal-Request-Id (idempotency key), PayPal processes only the first request. The second request fails with an error indicating the duplicate key. For more information, see PayPal-Request-Id.