Payouts API Integration

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

Set up your development environment

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 make payouts in asynchronous payout mode.

In this mode, 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.

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 the sender_batch_header includes a recipient_type, payout items without a specified recipient_type use the recipient_type in the 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 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:

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:

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.

Test Payouts

The PayPal sandbox enables you to pass specific information in a request to simulate positive and negative test scenarios. The simulated responses mimic actual API responses without calling downstream services. You can handle these responses in your code to manage your buyer’s experience.

For easy API development and testing, download the latest version of Postman. Then, download the Payouts collection .