Customize Payouts API integration

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.

For example, you can request only the batch_header for a summary.

Sample request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/12345678?fields=batch_header \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'

Sample response

{
  "batch_header": {
    "payout_batch_id": "12345678",
    "batch_status": "ACKNOWLEDGED",
    "time_created": "2014-01-27T10:17:00Z",
    "time_completed": "2014-01-27T11:17:39.00Z",
    "sender_payout_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a payout!"
    },
    "amount": {
      "value": "435.85",
      "currency": "USD"
    }
  }
}

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

Note: For more information about currency conversion, country exclusions, and restrictions, see Currency conversion.

Sample request

curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/5UXD2E8A7EBQJ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'

Sample response

{
  "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": "[email protected]",
        "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"
    }
  ]
}

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.

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.