# Customize Payouts API integration (/api/payouts/customize) Customize your Payouts API integration to pay recipients in local currency, get specific payout details, prevent duplicate requests, and implement idempotency. 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 [#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](/api/payouts#1-create-payout-batch) to the appropriate [currency code](/payouts/currency-conversion). PayPal automatically converts currencies and applies relevant fees. This helps you reach recipients globally and simplify cross-border payments. > **Note:** See a list of supported > > [Countries and features](/payouts/supported-features) > > for more information. Use a [valid access token](/api/rest#2-get-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](/api/payouts#1-create-payout-batch) response. ```shell Sample request lines theme={null} curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/5UXD2E8A7EBQJ \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' ``` ```json Sample response lines expandable theme={null} { "total_items": 1, "total_pages": 1, "batch_header": { "payout_batch_id": "5UXD2E8A7EBQJ", "batch_status": "SUCCESS", "time_created": "2024-07-03T10:30:00Z", "time_completed": "2024-07-03T10:32:15Z", "sender_batch_header": { "sender_batch_id": "Payouts_2024_100001", "email_subject": "You have a payout!", "email_message": "Congratulations! You have received a payout." }, "funding_source": "BALANCE", "amount": { "currency": "USD", "value": "108.50" }, "fees": { "currency": "USD", "value": "1.95" } }, "items": [ { "payout_item_id": "9MYSR9GT8AEUG", "transaction_id": "2JE19762AW167960J", "activity_id": "3E158638XS0329103", "transaction_status": "SUCCESS", "payout_item_fee": { "currency": "USD", "value": "1.95" }, "payout_batch_id": "5UXD2E8A7EBQJ", "payout_item": { "recipient_type": "EMAIL", "amount": { "currency": "EUR", "value": "100.00" }, "note": "Thank you for your business!", "receiver": "recipient.europe@example.com", "sender_item_id": "EUR_PAYOUT_001" }, "currency_conversion": { "from_amount": { "currency": "USD", "value": "108.50" }, "to_amount": { "currency": "EUR", "value": "100.00" }, "exchange_rate": "0.9217" }, "time_processed": "2024-07-03T10:31:45Z" } ], "links": [ { "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/5UXD2E8A7EBQJ", "rel": "self", "method": "GET" } ] } ``` 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 [#get-specific-payout-details] When you [track payouts status](/api/payouts#poll-for-updates), 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](/api/payouts#1-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. ```shell Sample request lines theme={null} 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' ``` ```json Sample response lines expandable theme={null} { "batch_header": { "payout_batch_id": "NNX8XK9T3CGWN", "batch_status": "SUCCESS", "time_created": "2025-07-31T07:00:57Z", "time_completed": "2025-07-31T07:01:26Z", "sender_batch_header": { "sender_batch_id": "Payouts_1753945252", "email_subject": "You have a payout!", "email_message": "Congratulations! You have received a payout." }, "funding_source": "BALANCE", "amount": { "currency": "USD", "value": "10.00" }, "fees": { "currency": "USD", "value": "0.25" } }, "items": [], "links": [{ "href": "https://api.sandbox.paypal.com/v1/payments/payouts/NNX8XK9T3CGWN?page_size=1000&page=1", "rel": "self", "method": "GET", "encType": "application/json" }] } ``` A successful call returns a `200 OK` response with the requested details of the payout batch. ## Prevent duplicate requests [#prevent-duplicate-requests] You can prevent the processing of duplicate batch payouts. To do this, in the [create payout batch request](/api/payouts#1-create-payout-batch), 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 [#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. > **Note:** 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 > > .