Send payouts

Use the Payouts API to send up to 500 disbursements in one API call to any email address or US mobile phone number. The Payouts API lets you easily send, track, and search for your previously made payouts. Payouts are available everywhere that Mass Payments are available. Payouts sent through the Payouts API appear as Mass Payments in your PayPal account, Instant Payment Notifications, and Mass Payment reports.

Fees

The sender pays Payouts fees at transaction time. US-sent domestic Payouts that are sent over the Payouts API are priced at $0.25 USD flat per transaction. Canadian-sent domestic Payouts are priced at $0.32 CAD flat per transaction. US- and Canadian-sent cross-border Payouts are priced just like Mass Payments (2% of each transaction, capped at $20 USD, and $23 CAD respectively). Payouts sent from any other country are priced just like Mass Payments.

Funds

The sending PayPal account must hold the total amount of funds being sent, in the currency being sent, plus any sending fees in PayPal balance at the time the Payouts are submitted. There is no limit on the total amount of the payout. In the U.S., each individual payment can be no more than $10,000.00 USD. For accounts in other countries, the maximum individual payment varies according to the payments standard sending limit.

Capabilities

In addition to simply sending multiple payments in one call, the Payouts API also includes these key capabilities.

Dual mode

The Payouts API can process your payouts asynchronously or synchronously. A batch payout is processed asynchronously, which means you retrieve the results at a later time through a status call. The Payout API defaults to this asynchronous mode. To use synchronous mode, which immediately returns the result of a single payout, see Create a single payout. Both modes accept the same request data.

Duplicate checking

PayPal can help you avoid duplicate batch submissions. PayPal checks the sender_batch_id before processing your payouts and if you have used that ID in the last 30 days, the batch request is rejected with an error message: Batch with given sender_batch_id already exists. The error response includes a HATEOAS link to the original batch payout with the same sender_batch_id. Also, the sender_item_id of an item must be unique within a given batch. However, the same sender_item_id can be used for another item in a different batch.

Status retrieval

Any time after you submit your batch, you can retrieve the status of all the items in your batch, using the PayPal generated batch_id. You can also retrieve the status of an individual item using the PayPal generated item_id. You can retrieve the status of the item even if the Payout item you submitted did not result in a PayPal transaction, such as in the case of a DECLINED Payout item. Your sent items with the status of UNCLAIMED can be canceled prior to the automatic 30-day return.

Note: Before you continue to read this guide, you should first create an app and learn how to make your first call.

Registration

Merchants in the United States can register to use Payouts in the Live environment as outlined in the following steps. Other merchants should contact their Account Manager or customer service to enable Payouts.

  1. If you have not already done so, go to My account and log in.
  2. If Payouts is not enabled, click the option to enable it and fill out the questionnaire.
  3. After approved for Payouts, if you have not already done so, create an application.
  4. Select the check box to enable Payouts for your application.