API integration

Integrate with Payouts 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).

How it works

When you initiate a payouts request, the Payouts API:

Validates your request and processes the payouts.
Sends you a status report.
Notifies recipients that they have a payment.

Know before you code

Complete the steps in Authentication to get the following sandbox account information from the Developer Dashboard:
- Your personal and business sandbox accounts
- Your access token
Generate a PayPal-Auth-Assertion header using Merchant's payer ID.
Request access to PayPal Payouts.
Set up your PayPal business account for Payouts:
- Confirm your identity
- Confirm your email
- Link your bank account
- Add enough money to cover your payout total, including fees
This integration uses the Payouts REST API.

Important: Partner can get the credentials from the API caller account. This access token will be used in subsequent Payout API calls until it expires in 8 hours. It is recommended by PayPal that partner always have a token cached. Once a token has 'lived' for at least 7 hours, partner can request a new access token. This would allow two access tokens to be operational between hours 7-8 of the older access token. If the partner attempts to request a new access token prior to hour 7, the access token creation response will contain the current and existing access token.

Create a payout

Choose which type of payout you'd like to create.

3rd Party

To create a payout, pass the base required data, sender_batch_header and items, and the following additional information in the body of the call. The array is first. It's properties follow.

Property	Requirement
sender_batch_header (array)	Required
`sender_batch_id`	Required
`email_subject`	Required
additional_information (array)	Required
`sender_name`	Required
`sender_institution_id`	Required
`sender_phone`	Recommended
`sender_email`	Recommended
`sender_address_street_1`	Required
`sender_address_street_2`	Required
`sender_address_city`	Required
`sender_address_state`	Required
`sender_address_postal_code`	Required

The sample request below creates a payout in USD for a PayPal recipient the API endpoint Create batch payout.

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts
2       -H "Content-Type: application/json"
3       -H "Authorization: Bearer <Access-Token>"
4       -H "PayPal-Auth-Assertion: <Auth-Assertion>"
5       -d '{
6            "sender_batch_header": {
7              "sender_batch_id": "2014021801",
8              "recipient_type": "EMAIL",
9              "email_subject": "You have money!",
10              "email_message": "You received a payment. Thanks for using our service!",
11              "additional_information": {
12                "sender_name": "John Doe",
13                "sender_institution_id": "12345",
14                "sender_address_street_1": "1234 Some Street",
15                "sender_address_city": "Poughkeepsie",
16                "sender_address_postal_code": "12601",
17                "sender_address_country_code": "US"
18              }
19            },
20            "items": [
21              {
22                "amount": {
23                  "value": "9.87",
24                  "currency": "USD"
25                },
26                "sender_item_id": "201403140001",
27                "recipient_wallet": "PAYPAL",
28                "receiver": "[email protected]"
29              }
30            ]
31          }'

Modify the code

Copy the code sample above and modify the following values:

Change Access-Token to your access token.

Change PayPal-Auth-Assertion to your header.

Optional: To send a payout in a different currency, set the currency parameter to the payment's currency code. You'll need to make a separate API call for each currency type. PayPal can automatically exchange payments for some currencies , even when you don't hold a balance in that currency.

Notes:

Payout items default to the recipient_type in the sender_batch_header. If there's no recipient_type in the sender_batch_header, each item must include its own recipient_type.

While sender_email is not required, we strongly recommend sending it in the request as it's presented in the recipient's transaction activity. If not populated, this field defaults to the email address of the PayPal financial partner.

Step result

A successful request returns:

A return status code of HTTP 201 Created.

A JSON response body with the payout_batch_id. Use the payout_batch_id in the show payout batch details endpoint to get a detailed record of each item in the payout.

Tip: You can log into your PayPal business account and see payout details on the Activity and Reports pages.

Sample response

1{
2        "batch_header": {
3          "payout_batch_id": "EM6HRZLA9M9XW",
4          "batch_status": "PENDING",
5          "sender_batch_header": {
6            "sender_batch_id": "2014021801",
7            "recipient_type": "EMAIL",
8            "email_subject": "You have money!",
9            "email_message": "You received a payment. Thanks for using our service!"
10          }
11      },
12      "links": [
13          {
14            "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/EM6HRZLA9M9XW",
15            "rel": "self",
16            "method": "GET",
17            "encType": "application/json"
18          }
19        ]
20      }

4th-Party

To create a payout, pass the base required data, sender_batch_header and items, and the following additional information in the body of the call. The array is first. It's properties follow.

Property	Requirement
sender_batch_header (array)	Required
`sender_batch_id`	Required
`email_subject`	Required
additional_information (array)	Required
`sender_name`	Required
`sender_institution_id`	Required
`sender_phone`	Recommended
`sender_email`	Recommended
`sender_address_street_1`	Required
`sender_address_street_2`	Required
`sender_address_city`	Required
`sender_address_state`	Required
`sender_address_postal_code`	Required
additional_partner_details (array)	Required
`intermediary_institution_name`	Required
`intermediary_institution_address_city`	Required
`intermediary_institution_address_country_code`	Required

The sample request below creates a payout in USD for a PayPal recipient the API endpoint Create batch payout.

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts
2         -H "Content-Type: application/json"
3         -H "Authorization: Bearer <Access-Token>"
4         -H "PayPal-Auth-Assertion: <Auth-Assertion>"
5         -d '{
6              "sender_batch_header": {
7                "sender_batch_id": "2014021801",
8                "recipient_type": "EMAIL",
9                "email_subject": "You have money!",
10                "email_message": "You received a payment. Thanks for using our service!",
11                "additional_information": {
12                  "sender_name": "John Doe",
13                  "sender_institution_id": "12345",
14                  "sender_address_street_1": "1234 Some Street",
15                  "sender_address_city": "Poughkeepsie",
16                  "sender_address_postal_code": "12601",
17                  "sender_address_country_code": "US"
18                }
19              },
20              "items": [
21                {
22                  "amount": {
23                    "value": "9.87",
24                    "currency": "USD"
25                  },
26                  "sender_item_id": "201403140001",
27                  "recipient_wallet": "PAYPAL",
28                  "receiver": "[email protected]"
29                }
30              ]
31            }'

Modify the code

Copy the code sample above and modify the following values:

Change Access-Token to your access token.

Change PayPal-Auth-Assertion to your header.

Optional: To send a payout in a different currency, set the currency parameter to the payment's currency code. You'll need to make can automatically exchange payments for some currencies , even when you don't hold a balance in that currency.

Notes:

Payout items default to the recipient_type in the sender_batch_header. If there's no recipient_type in the sender_batch_header, each item must include its own recipient_type.

While sender_email is not required, we strongly recommend sending it in the request as it's presented in the recipient's transaction activity. If not populated, this field defaults to the email address of the PayPal financial partner.

Step result

A successful request returns:

A return status code of HTTP 201 Created.

A JSON response body with the payout_batch_id. Use the payout_batch_id in the show payout batch details endpoint to get a detailed record of each item in the payout.

Tip: You can log into your PayPal business account and see payout details on the Activity and Reports pages.

Sample response

1{
2          "batch_header": {
3            "payout_batch_id": "EM6HRZLA9M9XW",
4            "batch_status": "PENDING",
5            "sender_batch_header": {
6              "sender_batch_id": "2014021801",
7              "recipient_type": "EMAIL",
8              "email_subject": "You have money!",
9              "email_message": "You received a payment. Thanks for using our service!"
10            }
11        },
12        "links": [
13            {
14              "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/EM6HRZLA9M9XW",
15              "rel": "self",
16              "method": "GET",
17              "encType": "application/json"
18            }
19          ]
20        }

API integration

How it works

Know before you code

Create a payout

3rd Party

Modify the code

Step result

Sample response

4th-Party

Modify the code

Step result

Sample response

Additional information

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more