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.

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.

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

Send payouts

1. Generate access token

The access token is a server-side token that helps with app authentication when your app accesses PayPal API resources. In your server-side code, use the following sample code to create the access token.

When you call the /v1/oauth2/token endpoint:

• Encode your app credentials (Client ID:Secret) in Base64 format and use them in the request.
• Include these data parameters:
  • grant_type: Set to client_credentials to specify that your app is requesting to exchange client ID and secret for an access token.
  • response_type: Set to token to request a server-side access token.

Response: The success response contains the access token in the access_token response parameter. Use th retrieved access token in all server-side API calls to authenticate your app.

curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -u 'BASE64_ENCODED_CLIENT_ID_AND_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'response_type=token'

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. Send a POST request to the /v1/payments/payouts endpoint with your JSON request body and headers.
4. Review the API response to confirm the payout batch was created and track its status.

Request body parameters

Parameter name	Required/Optional	Description
sender_batch_header	Required	Metadata for payout batch. Includes sender_batch_id.
items	Required	Array of payout items. Each item is an object.
items.amount	Required	Contains value (amount to send) and currency (three-letter code).
items.receiver	Required	Recipient identifier. For example, user@example.com, +15555550123, @venmousername, PAYPALUSERID123 Possible values: email, US phone, Venmo handle, PayPal account ID For Venmo, use US phone, email, or handle
items.recipient_type	Optional	Type of recipient identifier. Possible values: PHONE, EMAIL, USER_HANDLE, PAYPAL_ID Default value: EMAIL
items.recipient_wallet	Optional	Set to Venmo to send payout to Venmo. Omit or set to PayPal for PayPal accounts.
items.note	Optional	Note to recipient.
items.sender_item_id	Required	Unique ID for tracking payout item.

Notes:

• If recipient_type is set in sender_batch_header, all items use that type unless overridden per item.
• 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, set recipient_wallet to Venmo and use PHONE, EMAIL, or USER_HANDLE for the recipient.
• To use a Venmo handle, set recipient_type to USER_HANDLE and pass the handle in receiver.

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": "Thanks 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

After you submit the payout batch, you get a response with HTTP status 201 Created.

The response includes:

• batch_header.payout_batch_id: Unique ID for the payout batch
• batch_header.batch_status: Status of the payout batch
• links: URLs to get batch or item status

What happens next

• The response gives you payout_batch_id and the first batch_status.
• The payout batch can be processed right away or later. If batch_status is PENDING, check again later.
• If you see errors or failed items, review the error details. 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. The API treats this as the same request for 30 days.

3. Retrieve payout batch status

To check the status of a payout batch:

1. Send a GET request to /v1/payments/payouts/{id}. Replace {id} with the payout batch ID.
2. Review the response for the current status and details.

Response parameters

Parameter name	Description
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, PENDING, PROCESSING, DENIED, CANCELED
items	Array of payout items with details for each item
links	URLs to get batch or item status

What happens next

Take action based on the value of batch_status:

• 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 cancelled. Review the reason and resubmit if needed

Notes:

• If batch_status is PENDING or PROCESSING, check again later.
• If batch_status is DENIED or CANCELED, review the reason and take action if needed.
• If the request fails, log the error and try again.
• Use webhooks for real-time updates about payout events.

Next steps

1. Set up webhooks to get real-time notifications about payout events, such as completed or failed payouts.
2. Test and go live by testing your integration in the sandbox environment. After handling any errors, go to production.

API Reference

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