Batch payouts

Use the Payouts API to create and show details for batch payouts.

For more information about payouts, see Payouts.

Deprecation notice:

Synchronous mode will soon be deprecated and is no longer available for new integrations but continues to be supported for existing integrations. A synchronous mode payout immediately returns the results of the payout.

Integration steps

This task flow shows how you might typically use the Payouts REST API:

1. Required Meet the prerequisites.
2. Required Create batch payout.
3. Optional Show batch payout details.

Prerequisites

Before you can use the Payouts API, you must make your first call and learn about HTTP request headers. If you are a non-US developer, see International Developer Questions.

Create batch payout

You make batch payouts in asynchronous payout mode, which is the default mode.

Note: In asynchronous mode, sync_mode=false.

In this mode, you can specify a maximum of 500 individual payouts in one API call. Exceeding 500 payouts in one call returns the HTTP 400 (Bad Request) status code.

The create batch payout request must include a sender_batch_header object.

Either the sender_batch_header object or each payout item object must include a recipient_type value, which specifies the type of receiver data that identifies the recipient.

The recipient_type has one of these values:

EMAIL Unencrypted email.
PAYPAL_ID Encrypted PayPal account number.
PHONE Unencrypted phone number.

These rules apply to the recipient_type:

  • If the sender_batch_header includes a recipient_type value, any payout items without a recipient_type value use the recipient_type value in the sender_batch_header.
  • If the sender_batch_header omits the recipient_type value, each payout item must include its own recipient_type value.

Include the payouts to individual recipients in the items array in the JSON request body. Specify data for a single payout to one recipient in each item in the array. All items in a batch payout must specify the same currency.

This sample request creates a batch payout for four recipients. Because sync_mode=false is the default, it is omitted from the URI.

In this request, the sender_batch_header does not contain a recipient_type attribute. Consequently, each payment in the items array must define a recipient_type:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payouts \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "sender_batch_header": {
  "sender_batch_id": "2014021801",
  "email_subject": "You have a payout!"
  },
  "items": [
  {
    "recipient_type": "EMAIL",
    "amount": {
    "value": "9.87",
    "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "sender_item_id": "201403140001",
    "receiver": "anybody01@gmail.com"
  },
  {
    "recipient_type": "PHONE",
    "amount": {
    "value": "112.34",
    "currency": "USD"
    },
    "note": "Thanks for your support!",
    "sender_item_id": "201403140002",
    "receiver": "91-734-234-1234"
  },
  {
    "recipient_type": "PHONE",
    "amount": {
    "value": "5.32",
    "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "sender_item_id": "201403140003",
    "receiver": "408-234-1234"
  },
  {
    "recipient_type": "PHONE",
    "amount": {
    "value": "5.32",
    "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "sender_item_id": "201403140004",
    "receiver": "408-234-1234"
  }
  ]
}'

An EMAIL recipient type uses the recipient email address to identify the recipient. A PHONE recipient type uses a phone number to identify the recipient.

For information about the URI parameters, see Parameters. For information about request body parameters, see Request.

The response shows information about the batch payout, including the payout batch ID:

{
  "batch_header": {
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a payout!"
    },
    "payout_batch_id": "12345678",
    "batch_status": "PENDING"
  }
}

Next, you can show batch payout details.

Show batch payout details

To show details for all items in your batch payout, use the payout_batch_id from the previous response. You can specify the option fields query parameter to filter the fields that are returned in the response. This example specifies fields=batch_header, which tells the API to return only the batch_header in the response:

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payouts/12345678?fields=batch_header \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

The response shows only batch header information for the batch payout. The batch header information includes the payout batch ID, the batch status, and other information:

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

For information about the response fields, see Response.

For information about the payout status values, see batch_status.

Additional information