openapi: 3.0.3
info:
title: Paypal Subscriptions Authorizations Payouts API
description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
version: '1.6'
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.
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: receiver@example.com
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
components:
schemas:
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
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}))?$
payout_item_detail:
type: object
title: Payout Item Detail
description: The details for a sender-created payout to a single recipient.
properties:
recipient_type:
$ref: '#/components/schemas/recipient_enum'
amount:
description: The currency and amount of payout item. Might be an integer for currencies like `JPY` that are not typically fractional or a decimal fraction for currencies like `TND` that are subdivided into thousandths. 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).
$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.
minLength: 0
maxLength: 127
pattern: ^.*$
sender_item_id:
type: string
description: A sender-specified ID number. Tracks the payout in an accounting system.
minLength: 0
maxLength: 63
pattern: ^.*$
recipient_name:
description: The name of the recipient where money is credited. For `UNCLAIMED` payments, the recipient name is populated after the payment is claimed.
$ref: '#/components/schemas/name'
recipient_wallet:
description: The recipient wallet.
$ref: '#/components/schemas/recipient_wallet_enum'
purpose:
description: The purpose of the transaction.
$ref: '#/components/schemas/purpose_enum'
required:
- amount
- receiver
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
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
required:
- href
- rel
properties:
href:
type: string
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.
rel:
type: string
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).
method:
type: string
description: The HTTP method required to make the related call.
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
payout_batch_items:
type: object
title: Payout Item
description: The payout item status and other details.
properties:
payout_item_id:
type: string
description: The ID for the payout item. Viewable when you show details for a payout.
minLength: 0
maxLength: 30
pattern: ^.*$
transaction_id:
type: string
description: The PayPal-generated ID for the transaction.
minLength: 0
maxLength: 30
pattern: ^.*$
activity_id:
type: string
description: The unique PayPal-generated common ID created to link sender side and receiver side transaction. Used for tracking.
minLength: 0
maxLength: 30
pattern: ^.*$
transaction_status:
$ref: '#/components/schemas/transaction_enum'
payout_item_fee:
description: The fee, in U.S. dollars.
$ref: '#/components/schemas/currency'
payout_batch_id:
type: string
description: The PayPal-generated ID for the payout.
minLength: 0
maxLength: 30
pattern: ^.*$
payout_item:
description: The sender-provided information for the payout item.
$ref: '#/components/schemas/payout_item_detail'
currency_conversion:
description: The currency conversion applicable for this payout item.
$ref: '#/components/schemas/payout_currency_conversion'
time_processed:
type: string
format: date-time
minLength: 0
maxLength: 100
description: The date and time when this item was last processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
errors:
$ref: '#/components/schemas/error'
links:
type: array
description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
minItems: 0
maxItems: 15000
required:
- payout_item_id
- payout_batch_id
- payout_item
payout_sender_batch_header:
type: object
title: Payout Sender Batch Header
description: The sender-provided header for a payout request.
properties:
sender_batch_id:
type: string
description: The 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:
$ref: '#/components/schemas/recipient_enum'
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 with a maximum length of 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: ^.*$
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
payout_batch:
type: object
title: Payout Batch
description: The PayPal-generated batch status.
properties:
total_items:
description: The total number of items in the full result list.
type: integer
minimum: 0
maximum: 15000
total_pages:
description: The total number of pages.
type: integer
minimum: 0
maximum: 1000
batch_header:
description: A payout header. Includes the generated payout status.
$ref: '#/components/schemas/payout_batch_header'
items:
type: array
description: An array of individual items.
items:
$ref: '#/components/schemas/payout_batch_items'
minItems: 0
maxItems: 15000
links:
type: array
description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
minItems: 0
maxItems: 15000
batch_enum:
title: Batch status
description: The payouts status.
type: string
minLength: 1
maxLength: 36
pattern: ^[0-9A-Z_]+$
enum:
- DENIED
- PENDING
- PROCESSING
- SUCCESS
- CANCELED
name:
type: object
title: Name
description: The name of the party.
properties:
prefix:
type: string
description: The prefix, or title, to the party's name.
maxLength: 140
given_name:
type: string
description: When the party is a person, the party's given, or first, name.
maxLength: 140
surname:
type: string
description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
maxLength: 140
middle_name:
type: string
description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
maxLength: 140
suffix:
type: string
description: The suffix for the party's name.
maxLength: 140
alternate_full_name:
type: string
description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
maxLength: 300
full_name:
type: string
description: When the party is a person, the party's full name.
maxLength: 300
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
payout:
type: object
title: Create Payout Response
description: The create payout response.
properties:
batch_header:
description: The payout header.
$ref: '#/components/schemas/payout_header'
links:
type: array
description: An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
minItems: 1
maxItems: 15000
payout_batch_header:
type: object
title: Payout Batch Header
description: The payout header that is returned in response to a payout header request. Shows details for an entire payout request.
properties:
payout_batch_id:
type: string
description: The PayPal-generated ID for a payout.
minLength: 0
maxLength: 30
pattern: ^.*$
batch_status:
description: The PayPal-generated payout status. If the payout passes preliminary checks, the status is `PENDING`.
$ref: '#/components/schemas/batch_enum'
time_created:
type: string
format: date-time
minLength: 0
maxLength: 100
description: The date and time when processing for the payout began, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
time_completed:
type: string
format: date-time
description: The date and time when processing for the payout was completed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
minLength: 0
maxLength: 100
time_closed:
type: string
format: date-time
description: The date and time when the payout was closed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). A payout is considered closed when all items in a batch are processed and the available balance from the temporary hold is released.
minLength: 0
maxLength: 100
sender_batch_header:
description: The original payout header, as provided by the payment sender.
$ref: '#/components/schemas/payout_sender_batch_header'
funding_source:
description: The ID to differentiate a PayPal balance-funded transaction from a PayPal treasury-funded transaction.
$ref: '#/components/schemas/funding_source'
amount:
description: The currency and total amount requested for the payouts.
$ref: '#/components/schemas/currency'
fees:
description: The currency and amount of the total estimate for the applicable payouts fees. Initially, the fee is `0`. The fee is populated after the payout moves to the `PROCESSING` state.
$ref: '#/components/schemas/currency'
required:
- payout_batch_id
- batch_status
- sender_batch_header
recipient_wallet_enum:
title: Recipient wallet
description: The wallet where the recipient receives the payout. Payouts to Venmo recipients require a 'note' string and a US mobile phone number.
type: string
default: PAYPAL
minLength: 1
maxLength: 36
pattern: ^[0-9A-Z_]+$
enum:
- PAYPAL
- VENMO
- RECIPIENT_SELECTED
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: ^.*$
payout_currency_conversion:
type: object
title: Currency conversion resource
description: The currency conversion resource.
properties:
from_amount:
$ref: '#/components/schemas/currency'
description: The amount that is converted from.
to_amount:
$ref: '#/components/schemas/currency'
description: The amount that is converted to.
exchange_rate:
type: string
description: The exchange rate that is applied for this payout.
pattern: ^.*$
minLength: 0
maxLength: 30
recipient_enum:
title: Recipient type
description: The ID type that identifies the payment receiver.
type: string
minLength: 1
maxLength: 36
pattern: ^[0-9A-Z_]+$
enum:
- EMAIL
- PHONE
- PAYPAL_ID
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'
funding_source:
title: Funding source
description: Identifies a funding source type.
type: string
minLength: 1
maxLength: 36
pattern: ^[0-9A-Z_]+$
enum:
- BALANCE
transaction_enum:
title: Transaction status
description: The item transaction status.<blockquote><strong>Note:</strong> For <code>POST/v1/payments/payouts-item/{payout_item_id}/cancel</code>, the only possible <code>transaction_status</code> value is <code>RETURNED</code>.</blockquote>
type: string
minLength: 1
maxLength: 36
pattern: ^[0-9A-Z_]+$
enum:
- SUCCESS
- FAILED
- PENDING
- UNCLAIMED
- RETURNED
- ONHOLD
- BLOCKED
- REFUNDED
- REVERSED
payout_header:
type: object
title: Payout Header
description: The payout header that is returned in response to a payout header request. Shows details for an entire payout request.
properties:
payout_batch_id:
type: string
description: The PayPal-generated ID for a payout.
minLength: 0
maxLength: 30
pattern: ^.*$
batch_status:
description: The PayPal-generated payout status. If the payout passes preliminary checks, the status is `PENDING`.
$ref: '#/components/schemas/batch_enum'
time_created:
type: string
format: date-time
minLength: 0
maxLength: 100
description: The date and time when processing for the payout began, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
sender_batch_header:
description: The original payout header, as provided by the payment sender.
$ref: '#/components/schemas/payout_sender_batch_header'
required:
- batch_status
- payout_batch_id
- sender_batch_header
error:
type: object
title: Error
description: The error details.
properties:
name:
type: string
description: The human-readable, unique name of the error.
message:
type: string
description: The message that describes the error.
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
information_link:
type: string
description: The information link, or URI, that shows detailed information about this error for the developer.
readOnly: true
details:
type: array
description: An array of additional details about the error.
items:
$ref: '#/components/schemas/error_details-2'
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
$ref: '#/components/schemas/link_description'
readOnly: true
required:
- name
- message
- debug_id
create_payout_request:
type: object
title: Create Payout Request
description: The create payout request.
properties:
sender_batch_header:
description: The sender-provided payout header for a payout request.
$ref: '#/components/schemas/sender_batch_header'
items:
type: array
description: An array of individual payout items.
maxItems: 15000
minItems: 1
items:
$ref: '#/components/schemas/payout_item'
required:
- sender_batch_header
- items
error_details-2:
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:
type: string
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-payouts-api-openapi.yml