# Use Payouts API (/api/payouts) Send payouts programmatically using the Payouts API, including creating a payout batch, tracking status, handling errors, and testing your integration. You can use this pattern to send payouts to multiple recipients with a single API call. > **Tip:** You can send payouts to PayPal accounts and Venmo users. **Useful resource**: [PayPal Postman collection](/api/rest/postman/) ## Important information [#important-information] Ensure to review the following information before you send payouts. ### Rate-limiting guideline [#rate-limiting-guideline] PayPal does not have a published rate-limiting policy. To ensure site security and stability for merchants, we might temporarily apply rate limiting if we see unusual or abusive traffic. We hold the rate limit until we know the traffic is safe. For Payouts API, we allow 400 POST requests per minute. If you get an HTTP `429 Too Many Requests - RATE_LIMIT_REACHED` message, you have exceeded the rate limit. If this affects your integration, contact Merchant Technical Support. You can [use webhooks](#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 SDK [#payouts-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 [Payouts SDK](/sdk/payouts). ## End-to-end workflow [#end-to-end-workflow] ![Payouts API end-to-end workflow diagram](https://www.paypalobjects.com/ppdevdocs/Payouts%20APIs.png) ## Prerequisites [#prerequisites] * Complete all mandatory steps to [set up your sandbox account](/payouts/use-payouts/set-up#set-up-sandbox-account-for-payouts-api-integration). * Ensure your [PayPal business account is set up](/payouts/use-payouts/set-up#set-up-live-account). * Ensure to [fund your business account](/payouts/use-payouts/set-up#fund-your-account). ## Send payouts [#send-payouts] You can use the procedures in this section to send payouts using the Payouts API. ### 1. Create payout batch [#1-create-payout-batch] Use a [valid access token](/api/rest#2-get-access-token) and make a POST call to the `/v1/payments/payouts` endpoint. > **Tip:** You can use the > > `PayPal-Request-Id` > > header parameter to > > [implement idempotency](/api/payouts/customize#implement-idempotency) > > . Include the following parameters: | Parameter | Action | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `sender_batch_header`
Required, object | Use the `sender_batch_id` within this header to [prevent duplicate requests](/api/payouts/customize#prevent-duplicate-requests). | | `items.amount`
Required, object | To pay a recipient in their local currency, set the `currency` parameter to the [local currency code](/payouts/supported-features#eligible-countries-and-their-feature-sets). PayPal converts the payment to the specified currency and applies 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 recipients in their local currency](/api/payouts/customize#pay-recipients-in-their-local-currency).
> **Note:** Review [country exclusions and restrictions](/payouts/currency-conversion#restrictions) before sending cross-currency payouts. | | `items.receiver`
Required, string | Pass the value that identifies the recipient.
For example, [user@example.com](mailto:user@example.com), +15555550123, @venmousername, PAYPALUSERID123 | | `items.recipient_type`
string | For Venmo payouts, set the recipient type to `USER_HANDLE` and pass the handle in `items.receiver`.

**Possible values**: `PHONE`, `EMAIL`, `USER_HANDLE`, `PAYPAL_ID`

**Default value**: `EMAIL`
> **Note:** If you set the recipient type in `sender_batch_header`, all items use that type unless you override it per item. | | `items.recipient_wallet`
string | Set the recipient wallet type.

**Possible values**:**Venmo**: Set to `Venmo` to send a payout to a Venmo account. Use `PHONE`, `EMAIL`, or `USER_HANDLE` as the `recipient_type`. > **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.**PayPal**: Set to `PayPal` to send a payout to a PayPal account. This is the default value. | For information on all parameters, see the [API reference](/api/payments.payouts-batch/v1/payouts-post). ```shell Sample request lines expandable theme={null} curl -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Request-Id: REQUEST-ID' \ -d '{ "sender_batch_header": { "sender_batch_id": "Batch-123", "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" } ] }' ``` ```json Sample response lines theme={null} { "batch_header": { "payout_batch_id": "3TRXJ4Z8XJ8QY", "batch_status": "PENDING", "sender_batch_header": { "sender_batch_id": "Batch-123", "email_subject": "You have a payout!" }, }, "links": [ { "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/3TRXJ4Z8XJ8QY", "rel": "self", "method": "GET", "encType": "application/json" } ] } ``` A successful call returns a `201 Created` response. The response includes the following parameters: | Parameter | Description | Further action | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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`. | PayPal may process the batch immediately or later. If the status is `PENDING`, check again later.

To retry after a server error (such as HTTP `5xx`), send the request again with the same `sender_batch_id` within 30 days. | | `batch_header.sender_batch_header` | Metadata of the payout batch that the sender originally provided in the payout request. | You can use it to match the response with your original request parameters. | | `links` | URLs to get batch or item status. | Use these URLs to check the status of the batch or individual items. | ### 2. Track status [#2-track-status] After placing the payouts request, you can code your app to track the payout status by [polling for updates](#poll-for-updates) or [using webhooks](#use-webhooks). #### Poll for updates [#poll-for-updates] Use a [valid access token](/api/rest#2-get-access-token) and make a GET call to the `/v1/payments/payouts/{ID}` endpoint.
**Path parameter**: `ID` is the `payout_batch_id` returned in the Create payout batch response. > **Tip:** You can customize the request and choose which information to get in the response. See > > [Get specific payouts details](/api/payouts/customize#get-specific-payout-details) > > . ```shell Sample request lines theme={null} curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/MJ77GF8MQ2TF6 \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'Content-Type: application/json' ``` ```json Sample response lines expandable theme={null} { "total_items": 3, "total_pages": 1, "batch_header": { "payout_batch_id": "MJ77GF8MQ2TF6", "batch_status": "SUCCESS", "time_created": "2023-04-10T20:16:44Z", "time_completed": "2023-04-10T20:16:45Z", "sender_batch_header": { "sender_batch_id": "Payouts_1681157804", "email_subject": "You have a payout!", "email_message": "You have received a payout! Thanks for using our service!" }, "funding_source": "BALANCE", "amount": { "currency": "USD", "value": "60.00" }, "fees": { "currency": "USD", "value": "0.50" } }, "items": [ { "payout_item_id": "CX64X3KPCVYLC", "transaction_id": "4XH44110EC095525K", "activity_id": "0KJ317812H109105P", "transaction_status": "UNCLAIMED", "payout_item_fee": { "currency": "USD", "value": "0.25" }, "payout_batch_id": "MJ77GF8MQ2TF6", "payout_item": { "recipient_type": "EMAIL", "amount": { "currency": "USD", "value": "10.00" }, "note": "Thanks for your patronage!", "receiver": "recipient@example.com", "sender_item_id": "201403140001", "recipient_wallet": "PAYPAL" }, "time_processed": "2023-04-10T20:16:45Z", "links": [ { "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/CX64X3KPCVYLC", "rel": "item", "method": "GET" } ] }, { "payout_item_id": "S697W7QJMAEX4", "transaction_id": "0FY48488BY887313U", "transaction_status": "UNCLAIMED", "payout_item_fee": { "currency": "USD", "value": "0.25" }, "payout_item": { "recipient_type": "PHONE", "amount": { "currency": "USD", "value": "20.00" }, "note": "Thanks for your support!", "receiver": "15562941698", "sender_item_id": "201403140002", "recipient_wallet": "PAYPAL" }, "time_processed": "2023-04-10T20:16:45Z" }, { "payout_item_id": "J64P4FHTAY7UN", "transaction_status": "FAILED", "payout_item_fee": { "currency": "USD", "value": "0.00" }, "payout_item": { "recipient_type": "PAYPAL_ID", "amount": { "currency": "USD", "value": "30.00" }, "note": "Thanks for your patronage!", "receiver": "invalid@example.com", "sender_item_id": "201403140003", "recipient_wallet": "PAYPAL" }, "errors": { "name": "RECEIVER_ACCOUNT_INVALID", "message": "Receiver's account is invalid." } } ], "links": [ { "href": "https://api.sandbox.paypal.com/v1/payments/payouts/MJ77GF8MQ2TF6?page_size=1000&page=1", "rel": "self", "method": "GET" } ] } ``` A successful call returns a `200 OK` response. The response includes the following parameters: | Parameter | Description | Action | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_header.batch_status` | Status of the payout batch.

**Possible values**:
`SUCCESS`: PayPal has processed and completed the payout batch.`PENDING`: PayPal has queued the payout batch for processing.`PROCESSING`: PayPal is processing the payout batch.`DENIED`: PayPal has denied the payout requests.`CANCELED`: PayPal has canceled the payout batch. | If the status is `PENDING` or `PROCESSING`, check again later.
If the status is `DENIED` or `CANCELED`, review the error message or reason and resubmit if needed. > **Tip:** For real-time updates about payout events, use webhooks. | | `batch_header.sender_batch_header` | Metadata of the payout batch that the sender originally provided in the payout request. | You can use it to match the response with your original request parameters. | | `items` | Array of payout items with details for each item. | Use the `payout_item_id` to [track the status of each payout item](/payouts/use-payouts/track-payout-item-status). | | `links` | URLs to get batch or item status. | You can use them to poll for updates. | > **Note:** For information on all parameters, see > > API reference > > . #### Use webhooks [#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. ### 3. Handle errors [#3-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. ### 4. Test [#4-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 API 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 [#test-api-calls-use-test-values-and-simulate-responses] To simulate Payouts API responses, inject test values in the [request payload](#sample-test-value-in-request-payload) or as a [path parameter in the request URL](#sample-test-value-as-path-parameter). These methods allow you to trigger specific error responses without creating actual payouts. #### Sample - test value in request payload | Trigger | Test value | Simulated error response | | -------------- | ---------- | -------------------------- | | items\[0]/note | ERRPYO002 | `SENDER_EMAIL_UNCONFIRMED` | ```shell Sample request lines expandable theme={null} 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" } } ] }' ``` ```json Sample response lines theme={null} { "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 - test value as path parameter | Path parameter | Test value | Simulated error response | | --------------------- | ---------- | ------------------------ | | /v1/payments/payouts/ | ERRPYO015 | `CLOSED_MARKET` | ```bash Sample request lines theme={null} curl -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/ERRPYO015 \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' ``` ```json Sample response lines expandable theme={null} { "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" } ] } ``` ### 5. Go live [#5-go-live] 1. [Set up live account](/payouts/use-payouts/set-up#set-up-live-account). 2. [Set up webhooks](/api/rest/webhooks) to get real-time notifications about payout events, such as completed or failed payouts. 3. [Go live with your app](/api/rest/production).