PayPal Payouts API
The PayPal Payouts API lets businesses send mass payments to multiple recipients with a single API call, useful for marketplaces, affiliates, rewards programs, and contractor payouts.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Payouts
description: Use the Payouts API to make payments to multiple PayPal or Venmo recipients. The Payouts API is a fast, convenient way to send commissions, rebates, rewards, and general disbursements. You can send up to 15,000 payments per call. If you integrated the Payouts API before September 1, 2017, you receive transaction reports through <a href="/docs/archive/mass-pay/integration-guide/MassPayReporting/">Mass Payments Reporting</a>. Otherwise, <a href="/docs/payouts/features/view-reports/">view reports from your PayPal Business account</a>. The Payouts API uses the <a href="https://tools.ietf.org/html/rfc3339#section-5.6">ISO 8601 Internet date and time format</a>.
version: '1.9'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Payouts
description: Use the `/payouts` resource to create a batch payout, update the status for a batch payout, show the status of a batch payout with the transaction status and other data for individual payout items, and request approval for a batch payout.
- name: Payouts-Item
description: Use the `/payouts-item` resource to show payout item details and cancel an unclaimed payout item.
externalDocs:
url: https://developer.paypal.com/docs/api/payments.payouts-batch/v1/
paths:
"/v1/payments/payouts":
post:
summary: Paypal Create batch payout
description: Creates a batch payout. In the JSON request body, pass a `sender_batch_header` and an `items` array. The `sender_batch_header` defines how to handle the payout. The `items` array defines the payout items.<br/>You can make payouts to one or more recipients.<blockquote><strong>Notes:</strong> <ul><li><p>PayPal does not process duplicate payouts. If you specify a <code>sender_batch_id</code> that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate <code>sender_batch_id</code> and includes a HATEOAS link to the original payout with the same <code>sender_batch_id</code>.</p><p>If you receive an HTTP <code>5<i>nn</i></code> status code, you can safely retry the request with the same <code>sender_batch_id</code>.</p></li><li><p>The Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the <code>PayPal-Partner-Attribution-Id</code> request header.</p><p>For information about the <code>PayPal-Partner-Attribution-Id</code> header, see <a href="/api/rest/requests/#http-request-headers">HTTP request headers</a>. To learn about or request a BN code, contact your partner manager or see <a href="https://www.paypal.com/us/webapps/mpp/partner-program">PayPal Partner Program</a>.</p></li></ul></blockquote>
operationId: payouts.post
responses:
'201':
description: A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows the ID for the payout and payout details. To show payout status, use the <code>payout_batch_id</code> value that appears in the response. If the initial scan that checks for syntax errors, missing or duplicated keywords, and more succeeds, the <code>batch_status</code> is <code>PENDING</code>. The initial scan checks for syntax errors and missing or duplicated keywords. The API does not immediately validate some payout item values, such as the receiver phone numbers.
content:
application/json:
schema:
"$ref": "#/components/schemas/payout"
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/paypal_request_id"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/create_payout_request"
examples:
create_payout_request:
value:
sender_batch_header:
sender_batch_id: Payouts_2018_100007
email_subject: You have a payout!
email_message: You have received a payout! Thanks for using our service!
items:
- recipient_type: EMAIL
amount:
value: '9.87'
currency: USD
note: Thanks for your patronage!
sender_item_id: '201403140001'
receiver: [email protected]
alternate_notification_method:
phone:
country_code: '91'
national_number: '9999988888'
notification_language: fr-FR
- recipient_type: PHONE
amount:
value: '112.34'
currency: USD
note: Thanks for your support!
sender_item_id: '201403140002'
receiver: 91-734-234-1234
- recipient_type: PAYPAL_ID
amount:
value: '5.32'
currency: USD
note: Thanks for your patronage!
sender_item_id: '201403140003'
receiver: G83JXTJ5EHCQ2
security:
- Oauth2:
- https://uri.paypal.com/payments/payouts
tags:
- Payouts
"/v1/payments/payouts/{id}":
get:
summary: Paypal Show payout batch details
description: Shows the latest status of a batch payout. Includes the transaction status and other data for individual payout items.
operationId: payouts.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows batch payout details.
content:
application/json:
schema:
"$ref": "#/components/schemas/payout_batch"
'404':
description: Resource Not Found.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/id"
- "$ref": "#/components/parameters/fields"
- "$ref": "#/components/parameters/page"
- "$ref": "#/components/parameters/page_size"
- "$ref": "#/components/parameters/total_required"
security:
- Oauth2:
- https://uri.paypal.com/payments/payouts
tags:
- Payouts
"/v1/payments/payouts-item/{payout_item_id}":
get:
summary: Paypal Show payout item details
description: Shows details for a payout item, by ID. A <code>payout_item_id</code> helps you identify denied payments. If a payment is denied, you can use the <code>payout_item_id</code> to identify the payment even if it lacks a <code>transaction_id</code>.
operationId: payouts-item.get
responses:
'200':
description: A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body with a <code>payout_item_details</code> object, which contains data about a payout item including the transaction status.
content:
application/json:
schema:
"$ref": "#/components/schemas/payout_item-2"
'404':
description: Resource Not Found.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/payout_item_id"
security:
- Oauth2:
- https://uri.paypal.com/payments/payouts
tags:
- Payouts-Item
"/v1/payments/payouts-item/{payout_item_id}/cancel":
post:
summary: Paypal Cancel unclaimed payout item
description: Cancels an unclaimed payout item, by ID. If no one claims the unclaimed item within 30 days, the API automatically returns the funds to the sender. Use this call to cancel the unclaimed item before the automatic 30-day refund. You can cancel payout items with a <code>transaction_status</code> of <code>UNCLAIMED</code>.
operationId: payouts-item.cancel
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code with a JSON response body that shows payout item details.
content:
application/json:
schema:
"$ref": "#/components/schemas/payout_item-2"
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'404':
description: Resource Not Found.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
default:
description: The error response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error"
parameters:
- "$ref": "#/components/parameters/payout_item_id"
security:
- Oauth2:
- https://uri.paypal.com/payments/payouts
tags:
- Payouts-Item
components:
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/payments/payouts: Payout to a list of recipients.
https://uri.paypal.com/services/payments/payouts-item/reverse: For reversing a completed payout item.
schemas:
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
"$ref": "#/components/schemas/error_location"
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
type: string
minLength: 0
maxLength: 20000
pattern: "^.*$"
rel:
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
type: string
minLength: 0
maxLength: 100
pattern: "^.*$"
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 6
pattern: "^[A-Z]*$"
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
error_400:
type: object
title: Bad Request Error
description: Request is not well-formed, syntactically incorrect, or violates schema.
properties:
name:
type: string
enum:
- INVALID_REQUEST
message:
type: string
enum:
- Request is not well-formed, syntactically incorrect, or violates schema.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_401:
type: object
title: Unauthorized Error
description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
properties:
name:
type: string
enum:
- AUTHENTICATION_FAILURE
message:
type: string
enum:
- Authentication failed due to missing authorization header, or invalid authentication credentials.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_415:
type: object
title: Unsupported Media Type Error
description: The server does not support the request payload's media type.
properties:
name:
type: string
enum:
- UNSUPPORTED_MEDIA_TYPE
message:
type: string
enum:
- The server does not support the request payload's media type.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_500:
type: object
title: Internal Server Error
description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.
properties:
name:
type: string
enum:
- INTERNAL_SERVER_ERROR
message:
type: string
enum:
- An internal server error occurred.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
name: INTERNAL_SERVER_ERROR
message: An internal server error occurred.
debug_id: 90957fca61718
links:
- href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR
rel: information_link
error_503:
type: object
title: Service Unavailable Error
description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
properties:
name:
type: string
enum:
- SERVICE_UNAVAILABLE
message:
type: string
enum:
- Service Unavailable.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
example:
name: SERVICE_UNAVAILABLE
message: Service Unavailable.
debug_id: 90957fca61718
information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
sender_batch_header:
type: object
title: Sender Batch Header
description: The sender-provided payout header for a payout request.
properties:
sender_batch_id:
type: string
description: A sender-specified ID number. Tracks the payout in an accounting system.<blockquote><strong>Note:</strong> <p>PayPal does not process duplicate payouts. If you specify a <code>sender_batch_id</code> that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate <code>sender_batch_id</code> and includes a HATEOAS link to the original payout with the same <code>sender_batch_id</code>.</p><p>If you receive an HTTP <code>5<i>nn</i></code> status code, you can safely retry the request with the same <code>sender_batch_id</code>. The API completes a payment only once for a <code>sender_batch_id</code> that is used within 30 days.</p></blockquote>
minLength: 0
maxLength: 256
pattern: "^.*$"
recipient_type:
type: string
description: The ID type that identifies the recipient of the payment. For example, <code>EMAIL</code>.
minLength: 0
maxLength: 13
pattern: "^.*$"
email_subject:
type: string
description: The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.
minLength: 0
maxLength: 255
pattern: "^.*$"
email_message:
type: string
description: The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
minLength: 0
maxLength: 1000
pattern: "^.*$"
note:
type: string
description: The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.
minLength: 0
maxLength: 1000
pattern: "^.*$"
currency:
type: object
title: Currency
description: The currency and amount for a financial transaction, such as a balance or payment due.
properties:
currency:
type: string
description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/).
value:
type: string
description: The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).
required:
- currency
- value
phone:
type: object
title: Phone
description: The phone number in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
properties:
country_code:
type: string
description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 3
pattern: "^[0-9]{1,3}?$"
national_number:
type: string
description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 14
pattern: "^[0-9]{1,14}?$"
extension_number:
type: string
description: The extension number.
minLength: 1
maxLength: 15
pattern: "^[0-9]{1,15}?$"
required:
- country_code
- national_number
alternate_notification_method:
type: object
title: Alternate Notification Method
description: Captures additional notification modes to reach out to the receiver regarding this payment.
properties:
phone:
description: The mobile phone number of the receiver.
"$ref": "#/components/schemas/phone"
language:
type: string
description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/).
format: ppaas_common_language_v3
maxLength: 10
minLength: 2
pattern: "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$"
application_context:
type: object
title: Application Context
description: Metadata for Venmo transactions.
properties:
social_feed_privacy:
type: string
default: PRIVATE
description: This attribute controls the privacy of a payout transaction in recipient’s feed. PUBLIC, FRIENDS_ONLY & PRIVATE are the values that can be used. PUBLIC - The payment displays on the recipient's public Venmo feed. FRIENDS_ONLY - The payment displays only to the recipient's Venmo friends. PRIVATE - The payment displays only on the recipient's personal feed. Defaults to `PRIVATE` if left blank.
minLength: 1
maxLength: 15
pattern: "^.*$"
holler_url:
type: string
description: Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151.
format: uri
minLength: 1
maxLength: 1000
deprecated: true
logo_url:
type: string
description: 'Link to a logo that displays as the sender''s profile image in the recipient''s Venmo feed. Used to add or update the business profile image. Max image size: 1024 x 1024 pixels. The image should be square and maximum URL length is 2000.'
format: uri
minLength: 0
maxLength: 1000
purpose_enum:
type: string
title: Purpose
description: The purpose of the transaction.
minLength: 1
maxLength: 40
pattern: "^[A-Z0-9_]+$"
enum:
- AWARDS
- PRIZES
- DONATIONS
- GOODS
- SERVICES
- REBATES
- CASHBACK
- DISCOUNTS
- NON_GOODS_OR_SERVICES
payout_item:
type: object
title: Payout Item
description: The sender-created payout to a recipient.
properties:
recipient_type:
type: string
description: The recipient type. Value is:<ul><li><p><code>EMAIL</code>. The unencrypted email. Value is a string of up to 127 single-byte characters.</p></li><li><p><code>PHONE</code>. The unencrypted phone number.</p><blockquote><strong>Note:</strong> The PayPal sandbox does not support the <code>PHONE</code> recipient type.</blockquote></li><li><p><code>PAYPAL_ID</code>. The encrypted PayPal account number.</p></li><li><p><code>USER_HANDLE</code>. User handle (or) Username associated with Venmo account.</p></li></ul><br/>If the <code>sender_batch_header</code> includes the <code>recipient_type</code> attribute, payout items use the <code>recipient_type</code> of the <code>sender_batch_header</code>, unless a payout item has its own <code>recipient_type</code> attribute. If the <code>sender_batch_header</code> omits the <code>recipient_type</code> attribute, each payout item must include its own <code>recipient_type</code> value.
minLength: 0
maxLength: 13
pattern: "^.*$"
amount:
description: The currency and amount to pay the receiver.
"$ref": "#/components/schemas/currency"
note:
type: string
description: The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.
minLength: 0
maxLength: 4000
pattern: "^.*$"
receiver:
type: string
description: The receiver of the payment. Corresponds to the `recipient_type` value in the request. Max value of up to 127 single-byte characters.
minLength: 0
maxLength: 127
pattern: "^.*$"
sender_item_id:
type: string
description: The sender-specified ID number. Tracks the payout in an accounting system.
minLength: 0
maxLength: 63
pattern: "^.*$"
recipient_wallet:
type: string
description: The recipient wallet.
default: PAYPAL
minLength: 0
maxLength: 36
pattern: "^.*$"
alternate_notification_method:
description: Captures additional notification modes to reach out to the receiver regarding this payment.
"$ref": "#/components/schemas/alternate_notification_method"
notification_language:
"$ref": "#/components/schemas/language"
description: The language in which to show the payout recipient's email message. Used only when the recipient do
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-payouts-openapi-original.yml