payouts

Payouts API Integration

This guide describes how to use the Payouts API to send a maximum of 15,000 individual payouts in one API call to an email address or US mobile phone number or Payer ID (an encrypted PayPal account number).

Note: Payouts are available everywhere that Mass Payments are available. Payouts that you send through the Payouts API appear as Mass Payments in your PayPal account and in Mass Payment reports.

Prerequisites

To use Large Batch Payouts, you must have:

  1. A PayPal Business account with a confirmed email address and bank account. If you don't have a PayPal Business account, sign up now.

  2. Payouts enabled.

    1. US merchants—To enable Payouts, you can complete either of the following actions:
      1. Contact your Account Manager or PayPal customer support.
      2. Enable Payouts from My Account:
        1. Log in to the Developer Dashboard and go to My Account.
        2. Under Permissions name, locate Payouts and click the Enable link.
        3. Click Enable, complete the form and click Submit. When you've been approved, you'll receive an email from a PayPal representative.
    2. Non-US merchants—To enable Payouts, contact your Account Manager or PayPal customer support.

1. Make your first call

Once your account is enabled to use the Payouts API, create a PayPal REST app and get an access token:

1. Create a PayPal app.
When you create an app, PayPal generates a set of OAuth credentials.
2. Get an access token.
Pass the OAuth credentials in a get access token call.
In response, the PayPal authorization server issues an access token.
3. Make REST API calls.
Use the access token for authentication when you make REST API calls.

2. Create payout

You make payouts in asynchronous payout mode.

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

The create payout request must include a sender_payout_header object.

Either the sender_payout_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_payout_header includes a recipient_type value, any payout items without a recipient_type value use the recipient_type value in the sender_payout_header.

  • If the sender_payout_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 payout must specify the same currency.

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

In this request, the sender_payout_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_payout_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@example.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 domestic phone number to identify the recipient.

Tip: Make test calls to the Payments API using the PayPal API Explorer.

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

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

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

3. Show payout details

To show details for all items in your 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 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_payout_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.

Duplicate payout requests

PayPal prevents duplicate batches from being processed. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request and returns an error message that indicates the duplicate sender_batch_id and includes a HATEOAS link to the original batch payout with the same sender_batch_id. If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. In any case, the API completes a payment only once for a specific sender_batch_id that is used within 30 days.

For more information about the payout status values, see payout_enumerations in the Payouts API reference pages.

Next, you can set up webhook notifications or view reports.

Additional information

Feedback