Integrate API

APICurrentLast updated: October 27th 2021, @ 12:33:35 pm


The Payouts API enables you to send payouts programmatically to your recipients. This page explains everything you need to know about making payouts using the Payouts API.

How it works

When you initiate a payouts request, the Payouts API:

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

Know before you code

Create a payout

The sample request below creates a payout in USD for three recipients: two PayPal recipients and one Venmo recipient using the API endpoint Create batch payout.

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",
    "recipient_type": "EMAIL",
    "email_subject": "You have money!",
    "email_message": "You received a payment. Thanks for using our service!"
  },
  "items": [
    {
      "amount": {
        "value": "9.87",
        "currency": "USD"
      },
      "sender_item_id": "201403140001",
      "recipient_wallet": "PAYPAL",
      "receiver": "<receiver@example.com>"
    },
    {
      "amount": {
        "value": "112.34",
        "currency": "USD"
      },
      "sender_item_id": "201403140002",
      "recipient_wallet": "PAYPAL",
      "receiver": "<receiver2@example.com>"
    },
    {
      "recipient_type": "PHONE",
      "amount": {
        "value": "5.32",
        "currency": "USD"
      },
      "note": "Thanks for using our service!",
      "sender_item_id": "201403140003",
      "recipient_wallet": "VENMO",
      "receiver": "<408-234-1234>"
    }
  ]
}'

Modify the code

Copy the code sample above and modify the following values:

  • Change Access-Token to your access token.
  • Change <receiver@example.com> and <receiver2@example.com> to sandbox account email addresses.
  • Change <408-234-1234> to a sandbox account phone number.
  • Optional: To send payments to Venmo recipients, set recipient_wallet to VENMO. Include a U.S. mobile number and a note in the payout item.
  • 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.

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

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

{
  "batch_header": {
    "payout_batch_id": "Y4JB5BNLE8Z88",
    "batch_status": "PENDING",
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "recipient_type": "EMAIL",
      "email_subject": "You have money!",
      "email_message": "You received a payment. Thanks for using our service!"
    }
  },
  "links": [{
    "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/Y4JB5BNLE8Z88",
    "rel": "self",
    "method": "GET",
    "encType": "application/json"
  }]
}

Error Handling

Each PayPal API call returns an HTTP status code. Some API calls also return JSON response bodies that include information about the resource including one or more contextual HATEOAS links. PayPal uses conventional HTTP response codes to indicate the success or failure of an API request. In general, these codes are as follows:

  • 2xx codes indicate success.
  • 4xx codes indicate an error that failed given the information provided, for example, a required parameter was omitted or a charge failed.
  • 5xx codes indicate an error with PayPal's servers.

For more details on HTTP status codes and responses, see the API Responses section. Visit our API basics page to learn more about HTML status codes.

Idempotent requests

Idempotency allows you to safely resend the same request multiple times without the action being carried out more than once.

This means that if you try to create a payout which, due to network downtime (5xx status codes), meant you did not get a response from our servers, you can safely retry the transaction using the same idempotency key without risk of repeating the payout.

If you change any values in the subsequent request to the unique-reference-id header from a request, the request will be duplicated.

You can retry idempotent calls that fail with network timeouts (HTTP 5xx codes) for as long as the server stores the ID. If a duplicate request is found with the same idempotency key, we return the latest state of the payout that was created as part of the first transaction.

To see examples of these requests, see the API basics page.

Note: If you send two simultaneous API requests with same PayPal-Request-Id header, we will process the first request and fail the second request.

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 on Payouts API error messages, see Payouts Error Messages.

Next

Customize your integration.

See also