Notes:", "operationId": "payouts.post", "responses": { "201": { "description": "A successful request returns the HTTP
PayPal does not process duplicate payouts. If you specify a
sender_batch_idthat was used in the last 30 days, the API rejects the request with an error message that shows the duplicatesender_batch_idand includes a HATEOAS link to the original payout with the samesender_batch_id.If you receive an HTTP
5nnstatus code, you can safely retry the request with the samesender_batch_id.The Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the
PayPal-Partner-Attribution-Idrequest header.For information about the
PayPal-Partner-Attribution-Idheader, see HTTP request headers. To learn about or request a BN code, contact your partner manager or see PayPal Partner Program.
201 Created status code and a JSON response body that shows the ID for the payout and payout details. To show payout status, use the payout_batch_id value that appears in the response. If the initial scan that checks for syntax errors, missing or duplicated keywords, and more succeeds, the batch_status is PENDING. 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"
}
}
}
},
"security": [
{
"Oauth2": [
"https://uri.paypal.com/payments/payouts"
]
}
],
"tags": [
"payouts"
]
}
},
"/v1/payments/payouts/{id}": {
"get": {
"summary": "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": "Show payout item details",
"description": "Shows details for a payout item, by ID. A payout_item_id helps you identify denied payments. If a payment is denied, you can use the payout_item_id to identify the payment even if it lacks a transaction_id.",
"operationId": "payouts-item.get",
"responses": {
"200": {
"description": "A successful request returns the HTTP 200 OK status code and a JSON response body with a payout_item_details object, which contains data about a payout item including the transaction status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payout_item"
}
}
}
},
"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": "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 transaction_status of UNCLAIMED.",
"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"
}
}
}
},
"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"
]
}
}
},
"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."
},
{
"name": "payouts-statistics",
"description": "Use the `/payouts-statistics` resource to show statistics for a batch payout by date range."
},
{
"name": "payouts-disbursement-notifications",
"description": "Use the `payouts/disbursement-notifications` resource for status updates from VENMO"
},
{
"name": "payout-application-status",
"description": "Use the `/payout-applications` resource to fetch and update payout status of the application."
}
],
"externalDocs": {
"url": "/docs/payouts/"
},
"servers": [
{
"url": "https://api-m.sandbox.paypal.com",
"description": "PayPal API Sandbox"
}
],
"components": {
"securitySchemes": {
"Oauth2": {
"type": "oauth2",
"description": "Oauth 2.0 authentication",
"flows": {
"clientCredentials": {
"tokenUrl": "/api/oauth-proxy",
"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.",
"https://uri.paypal.com/services/payments/payout-applications/status": "For retrieving payouts application status",
"https://uri.paypal.com/services/payments/payout-applications/update-status": "For updating payouts application status"
}
}
}
}
},
"responses": {
"default": {
"description": "The default response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_default"
}
}
}
}
},
"schemas": {
"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"
}
}
},
"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
}
}
},
"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"
],
"oneOf": [
{
"type": "string",
"enum": [
"DENIED"
],
"description": "Your payout requests were denied, so they were not processed. Check the error messages to see any steps necessary to fix these issues."
},
{
"type": "string",
"enum": [
"PENDING"
],
"description": "Your payout requests were received and will be processed soon."
},
{
"type": "string",
"enum": [
"PROCESSING"
],
"description": "Your payout requests were received and are now being processed."
},
{
"type": "string",
"enum": [
"SUCCESS"
],
"description": "Your payout batch was processed and completed. Check the status of each item for any holds or unclaimed transactions."
},
{
"type": "string",
"enum": [
"CANCELED"
],
"description": "The payouts file that was uploaded through the PayPal portal was cancelled by the sender."
}
]
},
"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": {
"$ref": "#/components/schemas/payout_item_request_list"
}
},
"required": [
"sender_batch_header",
"items"
]
},
"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:payout_item_id helps you identify denied payments. If a payment is denied, you can use the payout_item_id to identify the payment even if it lacks a transaction_id.",
"properties": {
"payout_item_id": {
"type": "string",
"description": "The ID for the payout item. Visible 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 that links the sender- and receiver-side transactions. Used for tracking.",
"minLength": 0,
"maxLength": 30,
"pattern": "^.*$"
},
"transaction_status": {
"$ref": "#/components/schemas/transaction_enum"
},
"payout_item_fee": {
"description": "The estimate for the payout fee. Initially, the fee is `0`. The fee is populated after the item moves to the `PENDING` state",
"$ref": "#/components/schemas/currency"
},
"payout_batch_id": {
"type": "string",
"description": "The PayPal-generated ID for the payout batch.",
"minLength": 0,
"maxLength": 30,
"pattern": "^.*$"
},
"sender_batch_id": {
"type": "string",
"description": "A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.",
"minLength": 0,
"maxLength": 256,
"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",
"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).",
"minLength": 1,
"maxLength": 100
},
"errors": {
"$ref": "#/components/schemas/error",
"description": "The error details."
},
"links": {
"$ref": "#/components/schemas/payout_item_definitions-link_description_list"
}
},
"required": [
"payout_item_id",
"payout_batch_id",
"payout_item"
]
},
"payout_item_definitions-link_description_list": {
"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
},
"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"
]
},
"payout_item_request": {
"type": "object",
"title": "Payout Item",
"description": "The sender-created payout to a recipient.",
"properties": {
"recipient_type": {
"type": "string",
"description": "The recipient type. Value is:EMAIL. The unencrypted email. Value is a string of up to 127 single-byte characters.
PHONE. The unencrypted phone number.
Note: The PayPal sandbox does not support the PHONE recipient type.PAYPAL_ID. The encrypted PayPal account number.
USER_HANDLE. User handle (or) Username associated with Venmo account.
sender_batch_header includes the recipient_type attribute, payout items use the recipient_type of the sender_batch_header, unless a payout item has its own recipient_type attribute. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type 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 does not have a PayPal account. If you omit the language or provide invalid language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account."
},
"application_context": {
"description": "Metadata for accepting additional information from merchants to Venmo.",
"$ref": "#/components/schemas/application_context"
},
"purpose": {
"description": "The purpose of the transaction.",
"$ref": "#/components/schemas/purpose_enum"
}
},
"required": [
"amount",
"receiver"
]
},
"payout_item_request_list": {
"type": "array",
"description": "An array of individual payout items.",
"maxItems": 15000,
"minItems": 1,
"items": {
"$ref": "#/components/schemas/payout_item_request"
}
},
"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.Note:", "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": "^.*$" } } }, "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" ] }, "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" ], "oneOf": [ { "type": "string", "enum": [ "AWARDS" ], "description": "Awards payouts." }, { "type": "string", "enum": [ "PRIZES" ], "description": "Prizes payouts." }, { "type": "string", "enum": [ "DONATIONS" ], "description": "Donation payouts." }, { "type": "string", "enum": [ "GOODS" ], "description": "Payouts for goods sold." }, { "type": "string", "enum": [ "SERVICES" ], "description": "Payouts for services provided." }, { "type": "string", "enum": [ "REBATES" ], "description": "Rebate payouts." }, { "type": "string", "enum": [ "CASHBACK" ], "description": "Cashback payouts." }, { "type": "string", "enum": [ "DISCOUNTS" ], "description": "Discount payouts." }, { "type": "string", "enum": [ "NON_GOODS_OR_SERVICES" ], "description": "Payouts for any non-goods or services." } ] }, "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" ], "oneOf": [ { "type": "string", "enum": [ "EMAIL" ], "description": "An unencrypted email. Value is a string of up to 127 single-byte characters." }, { "type": "string", "enum": [ "PHONE" ], "description": "An unencrypted phone number." }, { "type": "string", "enum": [ "PAYPAL_ID" ], "description": "An encrypted PayPal account number." } ] }, "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" ], "oneOf": [ { "type": "string", "enum": [ "PAYPAL" ], "description": "PayPal Wallet." }, { "type": "string", "enum": [ "VENMO" ], "description": "Venmo Wallet." } ] }, "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.PayPal does not process duplicate payouts. If you specify a
sender_batch_idthat was used in the last 30 days, the API rejects the request with an error message that shows the duplicatesender_batch_idand includes a HATEOAS link to the original payout with the samesender_batch_id.If you receive an HTTP
5nnstatus code, you can safely retry the request with the samesender_batch_id. The API completes a payment only once for asender_batch_idthat is used within 30 days.
Note:", "minLength": 0, "maxLength": 256, "pattern": "^.*$" }, "recipient_type": { "type": "string", "description": "The ID type that identifies the recipient of the payment. For example,PayPal does not process duplicate payouts. If you specify a
sender_batch_idthat was used in the last 30 days, the API rejects the request with an error message that shows the duplicatesender_batch_idand includes a HATEOAS link to the original payout with the samesender_batch_id.If you receive an HTTP
5nnstatus code, you can safely retry the request with the samesender_batch_id. The API completes a payment only once for asender_batch_idthat is used within 30 days.
EMAIL.",
"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": "^.*$"
}
}
},
"transaction_enum": {
"title": "Transaction status",
"description": "The item transaction status.Note: For", "type": "string", "minLength": 1, "maxLength": 36, "pattern": "^[0-9A-Z_]+$", "enum": [ "SUCCESS", "FAILED", "PENDING", "UNCLAIMED", "RETURNED", "ONHOLD", "BLOCKED", "REFUNDED", "REVERSED" ], "oneOf": [ { "type": "string", "enum": [ "SUCCESS" ], "description": "Funds have been credited to the recipient’s account." }, { "type": "string", "enum": [ "FAILED" ], "description": "This payout request has failed, so funds were not deducted from the sender’s account." }, { "type": "string", "enum": [ "PENDING" ], "description": "Payout request has been submitted and is being processed. Recipient will get the funds once the request is processed successfully, else the funds will be returned to you." }, { "type": "string", "enum": [ "UNCLAIMED" ], "description": "The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds are returned to your account." }, { "type": "string", "enum": [ "RETURNED" ], "description": "Funds have been returned to your account. This can be because the recipient has not claimed this payout, or you have cancelled the payout." }, { "type": "string", "enum": [ "ONHOLD" ], "description": "This payout request is being reviewed and is on hold." }, { "type": "string", "enum": [ "BLOCKED" ], "description": "This payout request has been blocked." }, { "type": "string", "enum": [ "REFUNDED" ], "description": "Funds have been refunded back to your account. This is because the recipient(PayPal Business verified account) has issued a refund for the payout initiated by you." }, { "type": "string", "enum": [ "REVERSED" ], "description": "This payout request was reversed. This status is specific to web uploads." } ] } }, "parameters": { "paypal_request_id": { "name": "PayPal-Request-Id", "in": "header", "description": "The server stores keys for 30 days.", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^.*$" } }, "id": { "name": "id", "in": "path", "description": "The ID of the payout for which to show details.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^.*$" } }, "fields": { "name": "fields", "in": "query", "description": "Shows details for only the specified fields.", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^.*$" } }, "page": { "name": "page", "in": "query", "description": "A non-zero integer representing the page of the results.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 1 } }, "page_size": { "name": "page_size", "in": "query", "description": "The maximum number of results to return at one time. Value is a non-negative, non-zero integer. If the user chooses pagination, the maximum page is `1000`.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "total_required": { "name": "total_required", "in": "query", "description": "Indicates whether to show the total items and total pages count in the response.", "schema": { "type": "boolean", "default": false } }, "payout_item_id": { "name": "payout_item_id", "in": "path", "description": "The ID of the payout item to cancel.", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^.*$" } } } }, "x-errors": [ { "name": "ACCOUNT_RESTRICTED", "message": "Access to your account has been restricted. Contact your account manager or our customer service team for assistance." }, { "name": "ACCOUNT_UNCONFIRMED_EMAIL", "message": "You need to be a verified PayPal account holder to send payouts. You can verify your account by confirming your email and your bank account or credit card. Contact your account manager or our customer service team for assistance." }, { "name": "AUTHORIZATION_ERROR", "message": "Your account is not authorized to use payouts. Contact your account manager or our customer service team for assistance." }, { "name": "BATCH_NOT_COMPLETED", "message": "This payout batch is still being processed. Please try again later." }, { "name": "CLOSED_MARKET", "message": "This account is not allowed to receive payouts from other countries. Try re-sending this payout to another account." }, { "name": "CURRENCY_COMPLIANCE", "message": "Due to currency compliance regulations, you are not allowed to make this transaction." }, { "name": "CURRENCY_NOT_SUPPORTED_FOR_RECEIVER", "message": "This currency cannot be accepted for this recipient’s account. You can re-send this payout with a different currency." }, { "name": "DUPLICATE_ITEM", "message": "This transaction is duplicated in this batch. Please check the Ref_ID / Sender_Item_ID." }, { "name": "GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK", "message": "The recipient lives in a country that is not allowed to accept this payout." }, { "name": "GAMER_FAILED_FUNDING_SOURCE_CHECK", "message": "The funding source that was selected for this payout is not allowed. Try again by using your PayPal balance instead." }, { "name": "GAMING_INVALID_PAYMENT_FLOW", "message": "This payment flow is not allowed for gaming merchant accounts." }, { "name": "INSUFFICIENT_FUNDS", "message": "You have insufficient funds in your PayPal balance. You'll need to add funds to your account to complete the payout." }, { "name": "INTERNAL_ERROR", "message": "An error occurred while processing this payout request. Please re-submit this payout as a new batch or file." }, { "name": "ITEM_ALREADY_CANCELLED", "message": "This payout request has already been cancelled." }, { "name": "ITEM_CANCELLATION_FAILED", "message": "An error occurred while processing this payout request. Try again in a few minutes." }, { "name": "ITEM_INCORRECT_STATUS", "message": "You can only cancel items that are unclaimed." }, { "name": "VALIDATION_ERROR", "message": "JSON request is malformed. Check your request format and try again." }, { "name": "NEGATIVE_BALANCE", "message": "You have insufficient funds in your PayPal balance. You'll need to add funds to your account to complete the payout." }, { "name": "NON_HOLDING_CURRENCY", "message": "Your account does not have a PayPal balance in this currency. Try again with a currency that has funds in your PayPal account, or change your account settings to this currency." }, { "name": "PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE", "message": "This payout is pending because the recipient has set their account preferences to review credits in this currency. The recipient has been notified. Check back later for the status of this payout." }, { "name": "POS_LIMIT_EXCEEDED", "message": "You have exceeded the POS cumulative spending limit. Contact your account manager or our customer service team for assistance." }, { "name": "RATE_LIMIT_VALIDATION_FAILURES", "message": "Your request has been blocked due to multiple failed attempts. Please try again later." }, { "name": "RECEIVER_ACCOUNT_LOCKED", "message": "We were not able to send a payout because the recipient’s account is inactive or restricted. Funds have been returned to your account." }, { "name": "RECEIVER_COUNTRY_NOT_ALLOWED", "message": "We can’t send this payout because the recipient lives in a country where payouts are not allowed." }, { "name": "RECEIVER_STATE_RESTRICTED", "message": "We can’t send this payout because the recipient lives in a state where payouts are not allowed." }, { "name": "RECEIVER_UNCONFIRMED", "message": "The recipient’s email or phone number is unconfirmed. Any payments made to this account will be marked as Unclaimed until the recipient confirms their account information. Funds will be returned to your account if they are not claimed within 30 days." }, { "name": "RECEIVER_UNREGISTERED", "message": "The recipient for this payout does not have an account. A link to sign up for an account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds will be returned to your account." }, { "name": "RECEIVER_ACCOUNT_LIMITATION", "message": "The recipient's account is currently under limitation. Any payments made to this account will be on hold until the issue is resolved. Funds will be returned to your account if the limitation is not resolved within 30 days of the sent payout.", "description": "The recipient's account is currently under limitation. Any payments made to this account will be on hold until the issue is resolved. Funds will be returned to your account if the limitation is not resolved within 30 days of the sent payout." }, { "name": "RECEIVER_YOUTH_ACCOUNT", "message": "We were not able to send a payout because the recipient has a youth account. Please check with the recipient for an alternate account to receive the payout." }, { "name": "RECEIVING_LIMIT_EXCEEDED", "message": "The recipient cannot accept this payout, because it exceeds the amount they can receive at this time. Please resubmit your payout request for a different amount." }, { "name": "REFUSED_ACCESS_DENIED", "message": "Your account is not allowed to send money. Check with your primary account holder to get permission to send money." }, { "name": "RECEIVER_REFUSED", "message": "The recipient has refused this payout in this currency. Try resending in a different currency." }, { "name": "REGULATORY_BLOCKED", "message": "This transaction is blocked due to regulatory compliance restrictions." }, { "name": "REGULATORY_PENDING", "message": "This transaction is pending, while it is reviewed for compliance with government regulations." }, { "name": "REQUIRED_SCOPE_MISSING", "message": "The access token doesn't have the required scope. You'll need to use the access token with the correct scope to send a payout." }, { "name": "RISK_DECLINE", "message": "This transaction was declined due to risk concerns." }, { "name": "SELF_PAY_NOT_ALLOWED", "message": "You can’t send a payout to yourself. Try sending it to a different account." }, { "name": "SENDER_ACCOUNT_LOCKED", "message": "You can’t send a payout now, because your account is locked or inactive. Contact your account manager or our customer service team for assistance." }, { "name": "SENDER_ACCOUNT_UNVERIFIED", "message": "To send a payout, you need to have a verified PayPal account. You can verify your account by confirming your bank account or credit card. Contact your account manager or our customer service team for assistance." }, { "name": "SENDER_STATE_RESTRICTED", "message": "Your address is in a state where payouts are not allowed. Contact your account manager or our customer service team for assistance." }, { "name": "SPENDING_LIMIT_EXCEEDED", "message": "You’ve exceeded your spending limit. Contact your account manager or our customer service team for assistance." }, { "name": "TRANSACTION_DECLINED_BY_TRAVEL_RULE", "message": "Your payout request does not comply with travel rule regulations. To send this payout, you’ll need to update and verify your account information. Contact your account manager or our customer service team for assistance." }, { "name": "TRANSACTION_LIMIT_EXCEEDED", "message": "This payout request has exceeded the limit for this type of transaction. The funds have been returned to your account." }, { "name": "UNDEFINED", "message": "An error occurred while processing this payout request. Try again in a few minutes, or try resending as part of a new request or file." }, { "name": "UNVERIFIED_RECIPIENT_NOT_SUPPORTED", "message": "This payout request was not completed because the recipient has not verified their account. Your account is only allowed to send payout to verified accounts." }, { "name": "USER_BUSINESS_ERROR", "message": "An error occurred while processing this payout request. For batch processing, try again with a different `sender_batch_ID`. For single payout items, try again with email or payer ID as recipient type." }, { "name": "USER_COUNTRY_NOT_ALLOWED", "message": "Your address is in a country where payouts are not allowed. Contact your account manager or our customer service team for assistance." }, { "name": "USER_FUNDING_SOURCE_INELIGIBLE", "message": "The funding source for this payout is not allowed. Try again by using your PayPal balance instead." }, { "name": "ZERO_AMOUNT", "message": "Please provide a valid payment amount." }, { "name": "APPROVER_DENIED", "message": "Payout request rejected by the approver. Please check with your approver." }, { "name": "INVALID_EMAIL", "message": "Email Address doesn’t exist. Try again with the correct Email Id." }, { "name": "PHONE_NUMBER_INVALID", "message": "We were unable to deliver the Payout SMS to this recipient. This might be due to an invaild or incorrect phone number. Any amount deducted from this account will be returned shortly." }, { "name": "PHONE_NUMBER_SMS_OPTOUT", "message": "The receiver of this payout has opted out of PayPal SMS services. We were unable to deliver the payout SMS for the receiver to claim. Any amount deducted from this account will be returned shortly." }, { "name": "RECEIVER_ACCOUNT_NOT_ELIGIBLE", "message": "The receiver account is not eligible to receive the payout sent." }, { "name": "RECEIVER_ACCOUNT_UNVERIFIED", "message": "Your Payout request does not comply with the receiver country regulations. To send this payout, the receiver needs to update and verify their account information." } ] }POST/v1/payments/payouts-item/{payout_item_id}/cancel, the only possibletransaction_statusvalue isRETURNED.