Payouts API integration
APILegacyLast updated: April 6th 2022, @ 4:06:12 pm
This page describes how to use the Payouts API to send up to 15,000 individual payouts in one API call to email addresses, US mobile phone numbers, or Payer IDs (an encrypted PayPal account number).
Set up your development environment
Note: Before you set up your development environment, complete the prerequisites.
Before you can integrate Payouts, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.
Then, return to this page to integrate Payouts.
Create payout
You can specify up to 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_batch_header
object.
Either the sender_batch_header
object or each payout item object must include a recipient_type
, 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 there's a
recipient_type
in thesender_batch_header
, payout items use therecipient_type
in the header unless an item has its ownrecipient_type
.If there's no
recipient_type
in thesender_batch_header
, each payout item must include its ownrecipient_type
.
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_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-m.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!",
"email_message": "You have received a payout! Thanks for using our service!"
},
"items": [
{
"recipient_type": "EMAIL",
"amount": {
"value": "9.87",
"currency": "USD"
},
"note": "Thanks for your patronage!",
"sender_item_id": "201403140001",
"receiver": "receiver@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 Executor.
The response shows information about the payout, including the payout ID:
{
"batch_header": {
"sender_batch_header": {
"sender_batch_id": "2014021801",
"email_subject": "You have a payout!"
},
"payout_batch_id": "12345678",
"batch_status": "PENDING"
}
}
Tip: Send payments to Venmo recipients by setting
recipient_wallet
toVenmo
. Include a US mobile number inreceiver
and a message innote
.
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-m.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",
"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"
}
}
}
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.
Next
Test your Payouts API integration.