{ "openapi": "3.0.3", "info": { "title": "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 Payouts Reporting. The Payouts API uses the ISO 8601 Internet date and time format.", "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." }, { "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": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/" }, "paths": { "/v1/payments/payouts": { "post": { "summary": "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.
You can make payouts to one or more recipients.
Notes:
", "operationId": "payouts.post", "responses": { "201": { "description": "A successful request returns the HTTP 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" }, "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": "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"] } } }, "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.", "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" } } } } }, "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", "x-enumDescriptions": [ { "value": "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." }, { "value": "PENDING", "description": "Your payout requests were received and will be processed soon." }, { "value": "PROCESSING", "description": "Your payout requests were received and are now being processed." }, { "value": "SUCCESS", "description": "Your payout batch was processed and completed. Check the status of each item for any holds or unclaimed transactions." }, { "value": "CANCELED", "description": "The payouts file that was uploaded through the PayPal portal was cancelled by the sender." } ], "minLength": 1, "maxLength": 36, "pattern": "^[0-9A-Z_]+$", "enum": ["DENIED", "PENDING", "PROCESSING", "SUCCESS", "CANCELED"] }, "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: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"] }, "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": 1, "maxItems": 15000 }, "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": { "$ref": "#/components/schemas/error_details_list" }, "links": { "$ref": "#/components/schemas/link_description_list" } }, "required": ["name", "message", "debug_id"] }, "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" } }, "error_default": { "description": "The default error response.", "oneOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/error_409" }, { "$ref": "#/components/schemas/error_415" }, { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/error_500" }, { "$ref": "#/components/schemas/error_503" } ] }, "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_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", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "default": "body" }, "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_details_list": { "type": "array", "description": "An array of additional details about the error.", "items": { "$ref": "#/components/schemas/error_details-2" } }, "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_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" }, "funding_source": { "title": "Funding source", "description": "Identifies a funding source type.", "type": "string", "x-enumDescriptions": [ { "value": "BALANCE", "description": "Funded by balance." } ], "minLength": 1, "maxLength": 36, "pattern": "^[0-9A-Z_]+$", "enum": ["BALANCE"] }, "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}))?$" }, "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" ] } } }, "link_description_list": { "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" } }, "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 } } }, "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": { "$ref": "#/components/schemas/definitions-link_description_list" } } }, "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": { "$ref": "#/components/schemas/payout_batch_items_list" }, "links": { "$ref": "#/components/schemas/payout_batch_definitions-link_description_list" } } }, "payout_batch_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_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"] }, "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": { "$ref": "#/components/schemas/payout_batch_items_definitions-link_description_list" } }, "required": ["payout_item_id", "payout_batch_id", "payout_item"] }, "payout_batch_items_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_batch_items_list": { "type": "array", "description": "An array of individual items.", "items": { "$ref": "#/components/schemas/payout_batch_items" }, "minItems": 0, "maxItems": 15000 }, "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 } } }, "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"] }, "payout_item": { "type": "object", "title": "Payout Item", "description": "The payout item status and other details. 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.", "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:
If the 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:

PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.

If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

", "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_]+$", "x-enumDescriptions": [ { "value": "AWARDS", "description": "Awards payouts." }, { "value": "PRIZES", "description": "Prizes payouts." }, { "value": "DONATIONS", "description": "Donation payouts." }, { "value": "GOODS", "description": "Payouts for goods sold." }, { "value": "SERVICES", "description": "Payouts for services provided." }, { "value": "REBATES", "description": "Rebate payouts." }, { "value": "CASHBACK", "description": "Cashback payouts." }, { "value": "DISCOUNTS", "description": "Discount payouts." }, { "value": "NON_GOODS_OR_SERVICES", "description": "Payouts for any non-goods or services." } ], "enum": [ "AWARDS", "PRIZES", "DONATIONS", "GOODS", "SERVICES", "REBATES", "CASHBACK", "DISCOUNTS", "NON_GOODS_OR_SERVICES" ] }, "recipient_enum": { "title": "Recipient type", "description": "The ID type that identifies the payment receiver.", "type": "string", "x-enumDescriptions": [ { "value": "EMAIL", "description": "An unencrypted email. Value is a string of up to 127 single-byte characters." }, { "value": "PHONE", "description": "An unencrypted phone number." }, { "value": "PAYPAL_ID", "description": "An encrypted PayPal account number." } ], "minLength": 1, "maxLength": 36, "pattern": "^[0-9A-Z_]+$", "enum": ["EMAIL", "PHONE", "PAYPAL_ID"] }, "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", "x-enumDescriptions": [ { "value": "PAYPAL", "description": "PayPal Wallet." }, { "value": "VENMO", "description": "Venmo Wallet." } ], "default": "PAYPAL", "minLength": 1, "maxLength": 36, "pattern": "^[0-9A-Z_]+$", "enum": ["PAYPAL", "VENMO"] }, "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.
Note:

PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.

If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

", "minLength": 0, "maxLength": 256, "pattern": "^.*$" }, "recipient_type": { "type": "string", "description": "The ID type that identifies the recipient of the payment. For example, 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 POST/v1/payments/payouts-item/{payout_item_id}/cancel, the only possible transaction_status value is RETURNED.
", "type": "string", "x-enumDescriptions": [ { "value": "SUCCESS", "description": "Funds have been credited to the recipient’s account." }, { "value": "FAILED", "description": "This payout request has failed, so funds were not deducted from the sender’s account." }, { "value": "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." }, { "value": "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." }, { "value": "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." }, { "value": "ONHOLD", "description": "This payout request is being reviewed and is on hold." }, { "value": "BLOCKED", "description": "This payout request has been blocked." }, { "value": "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." }, { "value": "REVERSED", "description": "This payout request was reversed. This status is specific to web uploads." } ], "minLength": 1, "maxLength": 36, "pattern": "^[0-9A-Z_]+$", "enum": [ "SUCCESS", "FAILED", "PENDING", "UNCLAIMED", "RETURNED", "ONHOLD", "BLOCKED", "REFUNDED", "REVERSED" ] } }, "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": "^.*$" } } } } }