Use Payouts APIs

You can use this method to send payouts to multiple recipients with a single API call. You can send payouts to PayPal accounts and Venmo users.

Useful resource: PayPal API Executor

Important information

Rate limiting guideline

We do not have a published rate limiting policy. To ensure site security and stability for merchants, we might temporarily apply rate limiting when we see unusual or abusive traffic. We hold the rate limit until we know the traffic is safe. For Payouts APIs, we allow 400 POST requests per minute. If you get an HTTP 429 Unprocessable Entity - RATE_LIMIT_REACHED message it means you have exceeded the rate limit. If this affects your integration, contact Merchant Technical Support.

You can use webhooks for status updates instead of repeated API calls through polling and reuse OAuth 2.0 access tokens (till their expiry time) to avoid unnecessary requests.

Payouts APIs SDK

You can use the PayPal Payouts SDK as an alternative to direct API integration. The SDK provides methods for authentication, request construction, and error handling in multiple programming languages. For more information, see the Payouts SDK and APIs reference.

End-to-end workflow

Prerequisites

• Complete all mandatory steps to get started.
• Ensure your PayPal production business account is set up.
• Ensure to fund your business account.

Send payouts

1. Generate access token

The access token is a server-side token that helps PayPal to authenticate your app when it accesses PayPal resources. In your server-side code, implement the code to create the access token. In the code, when you call the /v1/oauth2/token endpoint, ensure to include the response_type data parameter and set its value to token. Use the generated access token in all your server-side API calls to authenticate your app.

2. Create payout batch

1. Prepare your request by including all required request body parameters in JSON format.
2. Add the access token to the Authorization header as Bearer <ACCESS-TOKEN>.
3. Implement idempotency through the PayPal-Request-Id header parameter.
4. Send the POST request to the /v1/payments/payouts endpoint with your JSON request body and headers.
5. Review the API response to confirm the payout batch is created.

Request body parameters

Parameter name	Data type	Description
sender_batch_header Required	object	Metadata for the payout batch. Includes sender_batch_id, which you can use to prevent duplicate requests.
items Required	array	Array of payout items. Each item is an object.
items.amount Required	object	Contains value (amount to send) and currency (three-letter code). To pay a recipient in their local currency, set the currency parameter to the local currency code. PayPal converts the payment to the specified currency and applies a conversion fees. When you retrieve the payout details, the response shows the funding source, payout amount, fees, and other currency conversion details. For a sample request and response for cross-currency payouts, see Pay in local currency. Note: Review country exclusions and restrictions before sending cross-currency payouts.
items.receiver Required	string	Recipient identifier. For example, user@example.com, +15555550123, @venmousername, PAYPALUSERID123
items.recipient_type	string	Type of recipient identifier. Possible values: PHONE, EMAIL, USER_HANDLE, PAYPAL_ID Default value: EMAIL Notes: If the recipient type is set in sender_batch_header, all items use that type unless overridden per item. To use a Venmo handle, set the recipient type to USER_HANDLE and pass the handle in receiver.
items.recipient_wallet	string	Possible values: Venmo: Set to Venmo to send a payout to a Venmo account. Note: Venmo payouts are available only in the US. If the recipient does not have a Venmo account, they receive instructions to create one and claim the payout. For Venmo payouts, use PHONE, EMAIL, or USER_HANDLE for the recipient. PayPal: Set to PayPal to send a payout to a PayPal account.
items.note	string	Note to recipient.
items.sender_item_id Required	string	Unique ID for tracking payout item.

Sample request

curl -X POST https://api.paypal.com/v1/payments/payouts \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "sender_batch_header": {
      "sender_batch_id": "UNIQUE-BATCH-ID",
      "email_subject": "You have a payout!"
    },
    "items": [
      {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "10.00",
          "currency": "USD"
        },
        "receiver": "recipient@example.com",
        "note": "Thank you for your business!"
        "sender_item_id": "ITEM-ID-1"
      },
      {
        "recipient_type": "PHONE",
        "amount": {
          "value": "10.00",
          "currency": "USD"
        },
        "receiver": "+15555550123",
        "note": "Thanks for using Venmo!",
        "sender_item_id": "ITEM-ID-2"
      }
    ]
  }'

Sample response

{
  "batch_header": {
    "payout_batch_id": "3TRXJ4Z8XJ8QY",
    "batch_status": "PENDING"
  },
  "links": [
    {
      "href": "https://api.paypal.com/v1/payments/payouts/3TRXJ4Z8XJ8QY",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Response parameters

A successful request returns 201 Created, along with the batch ID and status. The response includes the following parameters:

Parameter name	Description and further actions
batch_header.payout_batch_id	Unique ID for the payout batch. Use this ID to track or reference the batch in future API calls.
batch_header.batch_status	Status of the payout batch. Possible values: SUCCESS, PENDING, PROCESSING, DENIED, CANCELED. Notes: The batch may be processed immediately or later. If the status is PENDING, check again later. If you see errors or failed items, review the error details and notify the user if needed. To retry after a server error (such as HTTP 5xx), send the request again with the same sender_batch_id within 30 days.
links	URLs to get batch or item status. Use these URLs to check the status of the batch or individual items.

3. Track status

After placing the payouts request, you can code your app to check on the payout status in two ways:

• Poll for updates
• Use webhooks

Poll for updates

1. Send a GET request to /v1/payments/payouts/{id}. Replace {id} with the payout batch ID. You can customize the request and choose which information to get in the response. See Get specific payouts details.
2. Review the response parameters for the current status and take subsequent actions.

Parameter name	Description and further actions
batch_header.payout_batch_id	Unique ID for the payout batch. Example: 3TRXJ4Z8XJ8QY
batch_header.batch_status	Status of the payout batch. Possible values: SUCCESS: The payout batch was processed and completed. No further action is needed. PENDING: The payout batch is waiting to be processed. Check again later. PROCESSING: The payout batch is being processed. Check again later. DENIED: The payout requests were denied. Review error messages and take action. CANCELED: The payout batch was canceled. Review the reason and resubmit if needed. Notes: If the request fails, log the error and try again. You can use webhooks for real-time updates about payout events.
items	Array of payout items with details for each item
links	URLs to get batch or item status

Use webhooks

Webhook events are external events that your app does not know about unless it receives event notifications. For example, a payout processed or completed is a webhook event. You can subscribe to such events and register a callback (listener) URL. When the event occurs, PayPal sends a notification to the registered callback URL. You can code your app to perform relevant actions based on the event notification it receives.

To handle webhook events:

1. Review the list of webhook events for Payouts and select the events for your app to subscribe.
2. Subscribe to the selected webhook events through one of the following means:

• PayPal developer account: Log in to your account, go to App details page > Features > Webhooks, and subscribe to webhook events.
• Webhooks management API.

3. In your server-side app code, define a webhook handler that:

• Listens to the webhook event.
• Confirms receipt of the webhook event to PayPal.
• Verifies the source of the event notification.
• Performs further actions based on event data.

For more information, see Webhooks overview and Webhooks integration guide.

4. Handle errors

PayPal uses standard HTTP status codes to indicate the result of an API request:

• 2xx: Success
• 4xx: Incorrect request (for example, missing parameter)
• 5xx: PayPal server error

When an API call returns an error, the response includes a JSON body with the error details and HATEOAS links to help you diagnose and resolve issues. In your app code, include the logic to review the error code, message, and related links to determine the cause. Implement actions based on the error processing. For more information, see API responses.

5. Test

Use the PayPal sandbox environment to ensure your integration works as expected and meets all business and technical requirements before you go live.

Testing your Payouts APIs integration involves:

• Testing end-to-end payouts flow to verify money movement from your business account to your personal account (in case of PayPal payouts) or out of your business account (in case of Venmo payouts).
• Testing API calls.

Test API calls: use test values and simulate responses

To simulate Payouts API responses, inject test values in the request payload or as a path parameter in the request URL. These methods allow you to trigger specific error responses without creating actual payouts.

For a list of all test values, see Reference.

Sample to inject test value in the request payload

Trigger	Test value	Simulated error response
items[0]/note	ERRPYO002	SENDER_EMAIL_UNCONFIRMED

Sample request

curl -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": "1524086406556",
      "email_subject": "This email is related to simulation"
    },
    "items": [
      {
        "recipient_type": "EMAIL",
        "receiver": "payouts-simulator-receiver@paypal.com",
        "note": "ERRPYO002",
        "sender_item_id": "15240864065560",
        "amount": 
        {
          "currency": "USD",
          "value": "1.00"
        }
      }
    ]
  }'

Sample response

{
  "name": "SENDER_EMAIL_UNCONFIRMED",
  "message": "Authorization error occurred",
  "debug_id": "ca787bdf80d7a",
  "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/#errors"
}

Sample to specify test value as path parameter

Path parameter	Test value	Simulated error response
/v1/payments/payouts/	ERRPYO015	CLOSED_MARKET

Sample request

curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/ERRPYO015 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'

Sample response

{
  "batch_header": {
    "payout_batch_id": "DQCP2UAJCBMNY",
    "batch_status": "SUCCESS",
    "time_created": "2017-08-21T11:22:33Z",
    "time_completed": "2017-08-21T11:22:54Z",
    "sender_batch_header": {
      "email_subject": "user test case"
    },
    "amount": {
      "currency": "USD",
      "value": "190.0"
    },
    "fees": {
      "currency": "USD",
      "value": "0.0"
    }
  },
  "items": [
    {
      "payout_item_id": "RWD4Y3H9VV8BA",
      "transaction_status": "FAILED",
      "errors": {
        "name": "CLOSED_MARKET",
        "message": "Payouts to this market are not supported.",
        "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/#errors",
        "details": []
      },
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/RWD4Y3H9VV8BA",
          "rel": "item",
          "method": "GET",
          "encType": "application/json"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/DQCP2UAJCBMNY",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}

6. Go live

1. Set up business production account.
2. Set up production webhooks to get real-time notifications about payout events, such as completed or failed payouts.
3. Move your app to production.

API Reference

• Generate access token: POST /v1/oauth2/token
• Create payout batch: POST /v1/payments/payouts
• Track status: GET /v1/payments/payouts/{id}