PayPal MCP Server
by arbuthnot-eth
Verified
- PayPal-MCP
- APIs
{
"openapi": "3.0.3",
"info": {
"title": "Payments",
"description": "Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the <a href=\"/docs/api/orders/v2/\">Orders API</a>. For more information, see the <a href=\"/docs/checkout/\">PayPal Checkout Overview</a>.",
"version": "2.5",
"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": "authorizations",
"description": "Use the `/authorizations` resource to show details for, capture payment for, reauthorize, and void authorized payments."
},
{
"name": "captures",
"description": "Use the `/captures` resource to show details for and refund a captured payment."
},
{
"name": "refunds",
"description": "Use the `/refunds` resource to show refund details."
},
{
"name": "assets",
"description": "Assets APIs for Checkout"
},
{
"name": "cancel-payment",
"description": "Use the <code>/cancel-payment</code> resource to cancel an order capture or order authorization by <code>PayPal-Request-Id</code>. The merchant triggers the cancel action."
},
{
"name": "find-eligible-methods",
"description": "Use the `/find-eligible-methods` resource to show list of eligible payment methods for given customer/order context."
},
{
"name": "payment-resource-operations",
"description": "Use the `/payment-resource-operations` resource to show verifications details."
}
],
"externalDocs": {
"url": "https://developer.paypal.com/docs/api/payments/v2/"
},
"paths": {
"/v2/payments/authorizations/{authorization_id}": {
"get": {
"summary": "Show details for authorized payment",
"description": "Shows details for an authorized payment, by ID.",
"operationId": "authorizations.get",
"parameters": [
{
"$ref": "#/components/parameters/authorization_id"
}
],
"responses": {
"200": {
"description": "A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows authorization details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/authorization-2"
}
}
}
},
"401": {
"description": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_401"
}
}
}
},
"403": {
"description": "The request failed because the caller has insufficient permissions.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_403"
},
{
"$ref": "#/components/schemas/403"
}
]
}
}
}
},
"404": {
"description": "The request failed because the resource does not exist.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_404"
},
{
"$ref": "#/components/schemas/404"
}
]
}
}
}
},
"500": {
"description": "The request failed because an internal server error occurred."
},
"default": {
"$ref": "#/components/responses/default"
}
},
"tags": [
"authorizations"
],
"security": [
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
]
}
},
"/v2/payments/authorizations/{authorization_id}/capture": {
"post": {
"summary": "Capture authorized payment",
"description": "Captures an authorized payment, by ID.",
"operationId": "authorizations.capture",
"parameters": [
{
"$ref": "#/components/parameters/authorization_id"
},
{
"$ref": "#/components/parameters/paypal_request_id"
},
{
"$ref": "#/components/parameters/prefer"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture_request"
},
"examples": {
"capture_request": {
"value": {
"amount": {
"value": "10.99",
"currency_code": "USD"
},
"invoice_id": "INVOICE-123",
"final_capture": true,
"note_to_payer": "If the ordered color is not available, we will substitute with a different color free of charge.",
"soft_descriptor": "Bob's Custom Sweaters"
}
}
}
}
}
},
"responses": {
"201": {
"description": "A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows captured payment details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture-2"
}
}
}
},
"400": {
"description": "The request failed because it is not well-formed or is syntactically incorrect or violates schema.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_400"
},
{
"$ref": "#/components/schemas/400"
}
]
}
}
}
},
"401": {
"description": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_401"
}
}
}
},
"403": {
"description": "The request failed because the caller has insufficient permissions.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_403"
},
{
"$ref": "#/components/schemas/403"
}
]
}
}
}
},
"404": {
"description": "The request failed because the resource does not exist.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_404"
},
{
"$ref": "#/components/schemas/404"
}
]
}
}
}
},
"422": {
"description": "The request failed because it is semantically incorrect or failed business validation.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_422"
},
{
"$ref": "#/components/schemas/422"
}
]
}
}
}
},
"500": {
"description": "The request failed because an internal server error occurred."
},
"default": {
"$ref": "#/components/responses/default"
}
},
"tags": [
"authorizations"
],
"security": [
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
]
}
},
"/v2/payments/authorizations/{authorization_id}/reauthorize": {
"post": {
"summary": "Reauthorize authorized payment",
"description": "Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires.<br/><br/>If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.<br/><br/>A reauthorized payment itself has a new honor period of three days.<br/><br/>You can reauthorize an authorized payment from 4 to 29 days after the 3-day honor period. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.<br/><br/>Supports only the `amount` request parameter.<blockquote><strong>Note:</strong> This request is currently not supported for Partner use cases.</blockquote>",
"operationId": "authorizations.reauthorize",
"parameters": [
{
"$ref": "#/components/parameters/authorization_id"
},
{
"$ref": "#/components/parameters/paypal_request_id"
},
{
"$ref": "#/components/parameters/prefer"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/reauthorize_request"
},
"examples": {
"reauthorize_request": {
"value": {
"amount": {
"value": "10.99",
"currency_code": "USD"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows the reauthorized payment details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/authorization-2"
}
}
}
},
"400": {
"description": "The request failed because it is not well-formed or is syntactically incorrect or violates schema.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_400"
},
{
"$ref": "#/components/schemas/authorizations.reauthorize-400"
}
]
}
}
}
},
"401": {
"description": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_401"
}
}
}
},
"403": {
"description": "The request failed because the caller has insufficient permissions.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_403"
},
{
"$ref": "#/components/schemas/403"
}
]
}
}
}
},
"404": {
"description": "The request failed because the resource does not exist.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_404"
},
{
"$ref": "#/components/schemas/404"
}
]
}
}
}
},
"422": {
"description": "The request failed because it either is semantically incorrect or failed business validation.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_422"
},
{
"$ref": "#/components/schemas/authorizations.reauthorize-422"
}
]
}
}
}
},
"500": {
"description": "The request failed because an internal server error occurred."
},
"default": {
"$ref": "#/components/responses/default"
}
},
"tags": [
"authorizations"
],
"security": [
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
]
}
},
"/v2/payments/authorizations/{authorization_id}/void": {
"post": {
"summary": "Void authorized payment",
"description": "Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.",
"operationId": "authorizations.void",
"parameters": [
{
"$ref": "#/components/parameters/authorization_id"
},
{
"$ref": "#/components/parameters/paypal_auth_assertion"
},
{
"$ref": "#/components/parameters/prefer"
}
],
"responses": {
"200": {
"description": "A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows authorization details. This response is returned when the Prefer header is set to return=representation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/authorization-2"
}
}
}
},
"204": {
"description": "A successful request returns the HTTP <code>204 No Content</code> status code with no JSON response body. This response is returned when the Prefer header is set to return=minimal."
},
"400": {
"description": "The request failed because it is not well-formed or is syntactically incorrect or violates schema.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_400"
}
}
}
},
"401": {
"description": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_401"
},
{
"$ref": "#/components/schemas/401"
}
]
}
}
}
},
"403": {
"description": "The request failed because the caller has insufficient permissions.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_403"
},
{
"$ref": "#/components/schemas/403"
}
]
}
}
}
},
"404": {
"description": "The request failed because the resource does not exist.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_404"
},
{
"$ref": "#/components/schemas/404"
}
]
}
}
}
},
"409": {
"description": "The request failed because a previous call for the given resource is in progress.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_409"
},
{
"$ref": "#/components/schemas/409"
}
]
}
}
}
},
"422": {
"description": "The request failed because it either is semantically incorrect or failed business validation.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_422"
},
{
"$ref": "#/components/schemas/authorizations.void-422"
}
]
}
}
}
},
"500": {
"description": "The request failed because an internal server error occurred."
},
"default": {
"$ref": "#/components/responses/default"
}
},
"tags": [
"authorizations"
],
"security": [
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
]
}
},
"/v2/payments/captures/{capture_id}": {
"get": {
"summary": "Show captured payment details",
"description": "Shows details for a captured payment, by ID.",
"operationId": "captures.get",
"parameters": [
{
"$ref": "#/components/parameters/capture_id"
}
],
"responses": {
"200": {
"description": "A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows captured payment details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture-2"
}
}
}
},
"401": {
"description": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_401"
}
}
}
},
"403": {
"description": "The request failed because the caller has insufficient permissions.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_403"
},
{
"$ref": "#/components/schemas/403"
}
]
}
}
}
},
"404": {
"description": "The request failed because the resource does not exist.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_404"
},
{
"$ref": "#/components/schemas/404"
}
]
}
}
}
},
"500": {
"description": "The request failed because an internal server error occurred."
},
"default": {
"$ref": "#/components/responses/default"
}
},
"tags": [
"captures"
],
"security": [
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
]
}
},
"/v2/payments/captures/{capture_id}/refund": {
"post": {
"summary": "Refund captured payment",
"description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an <code>amount</code> object in the JSON request body.",
"operationId": "captures.refund",
"parameters": [
{
"$ref": "#/components/parameters/capture_id"
},
{
"$ref": "#/components/parameters/paypal_request_id"
},
{
"$ref": "#/components/parameters/prefer"
},
{
"$ref": "#/components/parameters/paypal_auth_assertion"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund_request"
},
"examples": {
"refund_request": {
"value": {
"amount": {
"value": "10.00",
"currency_code": "USD"
},
"invoice_id": "INVOICE-123",
"note_to_payer": "DefectiveProduct",
"payment_instruction": {
"platform_fees": [
{
"amount": {
"currency_code": "USD",
"value": "1.00"
}
}
]
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows refund details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund"
}
}
}
},
"400": {
"description": "The request failed because it is not well-formed or is syntactically incorrect or violates schema.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_400"
},
{
"$ref": "#/components/schemas/captures.refund-400"
}
]
}
}
}
},
"401": {
"description": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_401"
},
{
"$ref": "#/components/schemas/401"
}
]
}
}
}
},
"403": {
"description": "The request failed because the caller has insufficient permissions.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_403"
},
{
"$ref": "#/components/schemas/403"
}
]
}
}
}
},
"404": {
"description": "The request failed because the resource does not exist.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_404"
},
{
"$ref": "#/components/schemas/404"
}
]
}
}
}
},
"409": {
"description": "The request failed because a previous call for the given resource is in progress.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_409"
},
{
"$ref": "#/components/schemas/409"
}
]
}
}
}
},
"422": {
"description": "The request failed because it either is semantically incorrect or failed business validation.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_422"
},
{
"$ref": "#/components/schemas/captures.refund-422"
}
]
}
}
}
},
"500": {
"description": "The request failed because an internal server error occurred."
},
"default": {
"$ref": "#/components/responses/default"
}
},
"tags": [
"captures"
],
"security": [
{
"Oauth2": [
"https://uri.paypal.com/services/payments/refund"
]
}
]
}
},
"/v2/payments/refunds/{refund_id}": {
"get": {
"summary": "Show refund details",
"description": "Shows details for a refund, by ID.",
"operationId": "refunds.get",
"parameters": [
{
"$ref": "#/components/parameters/refund_id"
}
],
"responses": {
"200": {
"description": "A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows refund details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund"
}
}
}
},
"401": {
"description": "Authentication failed due to missing authorization header, or invalid authentication credentials.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_401"
},
{
"$ref": "#/components/schemas/401"
}
]
}
}
}
},
"403": {
"description": "The request failed because the caller has insufficient permissions.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_403"
},
{
"$ref": "#/components/schemas/403"
}
]
}
}
}
},
"404": {
"description": "The request failed because the resource does not exist.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/error_404"
},
{
"$ref": "#/components/schemas/404"
}
]
}
}
}
},
"500": {
"description": "The request failed because an internal server error occurred."
},
"default": {
"$ref": "#/components/responses/default"
}
},
"tags": [
"refunds"
],
"security": [
{
"Oauth2": [
"https://uri.paypal.com/services/payments/refund"
]
}
]
}
}
},
"components": {
"securitySchemes": {
"Oauth2": {
"type": "oauth2",
"description": "OAuth 2.0 authentication",
"flows": {
"clientCredentials": {
"tokenUrl": "/v1/oauth2/token",
"scopes": {
"https://uri.paypal.com/services/payments/payment/authcapture": "Permission to do non-real time payments like capture on authorization",
"https://uri.paypal.com/services/payments/refund": "Permission to initiate a refund on a capture transaction",
"https://uri.paypal.com/services/payments/non-referenced-credit": "Permission to initiate non referenced credit",
"https://uri.paypal.com/services/payments/realtimepayment": "Permission to do any real time payment, with support for sale/authorize/order intents",
"https://uri.paypal.com/services/payments/reversepayment": "Permission to do any reverse payment"
}
}
}
}
},
"responses": {
"default": {
"description": "The default response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_default"
}
}
}
}
},
"schemas": {
"400": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "INVALID_PARAMETER_VALUE",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_PARAMETER_VALUE"
]
},
"description": {
"type": "string",
"enum": [
"The value of a field is invalid."
]
}
}
},
{
"title": "MISSING_REQUIRED_PARAMETER",
"properties": {
"issue": {
"type": "string",
"enum": [
"MISSING_REQUIRED_PARAMETER"
]
},
"description": {
"type": "string",
"enum": [
"A required field / parameter is missing."
]
}
}
},
{
"title": "INVALID_STRING_LENGTH",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_STRING_LENGTH"
]
},
"description": {
"type": "string",
"enum": [
"The value of a field is either too short or too long."
]
}
}
},
{
"title": "INVALID_STRING_MAX_LENGTH",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_STRING_MAX_LENGTH"
]
},
"description": {
"type": "string",
"enum": [
"The value of a field is too long."
]
}
}
},
{
"title": "INVALID_PARAMETER_SYNTAX",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_PARAMETER_SYNTAX"
]
},
"description": {
"type": "string",
"enum": [
"The value of a field does not conform to the expected format."
]
}
}
}
]
}
}
}
},
"401": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "INVALID_ACCOUNT_STATUS",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_ACCOUNT_STATUS"
]
},
"description": {
"type": "string",
"enum": [
"Account validations failed for the user."
]
}
}
}
]
}
}
}
},
"403": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "PERMISSION_DENIED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PERMISSION_DENIED"
]
},
"description": {
"type": "string",
"enum": [
"You do not have permission to access or perform operations on this resource."
]
}
}
}
]
}
}
}
},
"404": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "INVALID_RESOURCE_ID",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_RESOURCE_ID"
]
},
"description": {
"type": "string",
"enum": [
"Specified resource ID does not exist. Please check the resource ID and try again."
]
}
}
}
]
}
}
}
},
"409": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "PREVIOUS_REQUEST_IN_PROGRESS",
"properties": {
"issue": {
"type": "string",
"enum": [
"PREVIOUS_REQUEST_IN_PROGRESS"
]
},
"description": {
"type": "string",
"enum": [
"A previous request on this resource is currently in progress. Please wait for sometime and try again. It is best to space out the initial and the subsequent request(s) to avoid receiving this error."
]
}
}
}
]
}
}
}
},
"422": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "INVALID_CURRENCY_CODE",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_CURRENCY_CODE"
]
},
"description": {
"type": "string",
"enum": [
"Currency code is invalid or is not currently supported. Please refer https://developer.paypal.com/docs/api/reference/currency-codes/ for list of supported currency codes."
]
}
}
},
{
"title": "CANNOT_BE_ZERO_OR_NEGATIVE",
"properties": {
"issue": {
"type": "string",
"enum": [
"CANNOT_BE_ZERO_OR_NEGATIVE"
]
},
"description": {
"type": "string",
"enum": [
"Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported."
]
}
}
},
{
"title": "DECIMAL_PRECISION",
"properties": {
"issue": {
"type": "string",
"enum": [
"DECIMAL_PRECISION"
]
},
"description": {
"type": "string",
"enum": [
"If the currency supports decimals, only two decimal place precision is supported."
]
}
}
},
{
"title": "DECIMALS_NOT_SUPPORTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"DECIMALS_NOT_SUPPORTED"
]
},
"description": {
"type": "string",
"enum": [
"Currency does not support decimals. Please refer to https://developer.paypal.com/docs/api/reference/currency-codes/ for more information."
]
}
}
},
{
"title": "TRANSACTION_REFUSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"TRANSACTION_REFUSED"
]
},
"description": {
"type": "string",
"enum": [
"PayPal's internal controls prevent authorization from being captured."
]
}
}
},
{
"title": "AUTHORIZATION_VOIDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTHORIZATION_VOIDED"
]
},
"description": {
"type": "string",
"enum": [
"A voided authorization cannot be captured or reauthorized. "
]
}
}
},
{
"title": "MAX_CAPTURE_COUNT_EXCEEDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"MAX_CAPTURE_COUNT_EXCEEDED"
]
},
"description": {
"type": "string",
"enum": [
"Maxmimum number of allowable captures has been reached. No additional captures are possible for this authorization. Contact Customer Service or your account manager to change the number of captures for a given authorization."
]
}
}
},
{
"title": "DUPLICATE_INVOICE_ID",
"properties": {
"issue": {
"type": "string",
"enum": [
"DUPLICATE_INVOICE_ID"
]
},
"description": {
"type": "string",
"enum": [
"Requested invoice_id has been previously captured. Possible duplicate transaction."
]
}
}
},
{
"title": "AUTH_CAPTURE_CURRENCY_MISMATCH",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTH_CAPTURE_CURRENCY_MISMATCH"
]
},
"description": {
"type": "string",
"enum": [
"Currency of capture must be the same as currency of authorization."
]
}
}
},
{
"title": "PAYER_CANNOT_PAY",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYER_CANNOT_PAY"
]
},
"description": {
"type": "string",
"enum": [
"Payer cannot pay for this transaction. Please contact the payer to find other ways to pay for this transaction."
]
}
}
},
{
"title": "AUTHORIZATION_DENIED",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTHORIZATION_DENIED"
]
},
"description": {
"type": "string",
"enum": [
"An denied authorization cannot be captured."
]
}
}
},
{
"title": "AUTHORIZATION_EXPIRED",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTHORIZATION_EXPIRED"
]
},
"description": {
"type": "string",
"enum": [
"An expired authorization cannot be captured."
]
}
}
},
{
"title": "AUTHORIZATION_ALREADY_CAPTURED",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTHORIZATION_ALREADY_CAPTURED"
]
},
"description": {
"type": "string",
"enum": [
"Authorization has previously been captured."
]
}
}
},
{
"title": "MAX_CAPTURE_AMOUNT_EXCEEDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"MAX_CAPTURE_AMOUNT_EXCEEDED"
]
},
"description": {
"type": "string",
"enum": [
"Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the order amount. The ability to over capture is subjected to regulatory approvals."
]
}
}
},
{
"title": "TRANSACTION_REFUSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"TRANSACTION_REFUSED"
]
},
"description": {
"type": "string",
"enum": [
"PayPal's internal controls prevent authorization from being captured."
]
}
}
},
{
"title": "PAYEE_ACCOUNT_LOCKED_OR_CLOSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYEE_ACCOUNT_LOCKED_OR_CLOSED"
]
},
"description": {
"type": "string",
"enum": [
"Transaction could not complete because payee account is locked or closed."
]
}
}
},
{
"title": "PAYER_ACCOUNT_LOCKED_OR_CLOSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYER_ACCOUNT_LOCKED_OR_CLOSED"
]
},
"description": {
"type": "string",
"enum": [
"The payer account cannot be used for this transaction."
]
}
}
},
{
"title": "PAYEE_ACCOUNT_RESTRICTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYEE_ACCOUNT_RESTRICTED"
]
},
"description": {
"type": "string",
"enum": [
"Payee account is restricted."
]
}
}
}
]
}
}
}
},
"error_details": {
"title": "Error Details",
"type": "object",
"description": "The error details. Required for client-side `4XX` errors.",
"properties": {
"field": {
"type": "string",
"description": "The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors."
},
"value": {
"type": "string",
"description": "The value of the field that caused the error."
},
"location": {
"$ref": "#/components/schemas/error_location"
},
"issue": {
"type": "string",
"description": "The unique, fine-grained application-level error code."
},
"description": {
"type": "string",
"description": "The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value."
}
},
"required": [
"issue"
]
},
"error_location": {
"type": "string",
"description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.",
"enum": [
"body",
"path",
"query"
],
"default": "body"
},
"error_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_link_description": {
"title": "Link Description",
"description": "The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.",
"type": "object",
"required": [
"href",
"rel"
],
"properties": {
"href": {
"description": "The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.",
"type": "string",
"minLength": 0,
"maxLength": 20000,
"pattern": "^.*$"
},
"rel": {
"description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).",
"type": "string",
"minLength": 0,
"maxLength": 100,
"pattern": "^.*$"
},
"method": {
"description": "The HTTP method required to make the related call.",
"type": "string",
"minLength": 3,
"maxLength": 6,
"pattern": "^[A-Z]*$",
"enum": [
"GET",
"POST",
"PUT",
"DELETE",
"PATCH"
]
}
}
},
"error_400": {
"type": "object",
"title": "Bad Request Error",
"description": "Request is not well-formed, syntactically incorrect, or violates schema.",
"properties": {
"name": {
"type": "string",
"enum": [
"INVALID_REQUEST"
]
},
"message": {
"type": "string",
"enum": [
"Request is not well-formed, syntactically incorrect, or violates schema."
]
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error_details"
}
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
}
},
"error_401": {
"type": "object",
"title": "Unauthorized Error",
"description": "Authentication failed due to missing Authorization header, or invalid authentication credentials.",
"properties": {
"name": {
"type": "string",
"enum": [
"AUTHENTICATION_FAILURE"
]
},
"message": {
"type": "string",
"enum": [
"Authentication failed due to missing authorization header, or invalid authentication credentials."
]
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error_details"
}
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
}
},
"error_403": {
"type": "object",
"title": "Not Authorized Error",
"description": "The client is not authorized to access this resource, although it may have valid credentials. ",
"properties": {
"name": {
"type": "string",
"enum": [
"NOT_AUTHORIZED"
]
},
"message": {
"type": "string",
"enum": [
"Authorization failed due to insufficient permissions."
]
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error_details"
}
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
}
},
"error_404": {
"type": "object",
"title": "Not found Error",
"description": "The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.",
"properties": {
"name": {
"type": "string",
"enum": [
"RESOURCE_NOT_FOUND"
]
},
"message": {
"type": "string",
"enum": [
"The specified resource does not exist."
]
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error_details"
}
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
}
},
"error_409": {
"type": "object",
"title": "Resource Conflict Error",
"description": "The server has detected a conflict while processing this request.",
"properties": {
"name": {
"type": "string",
"enum": [
"RESOURCE_CONFLICT"
]
},
"message": {
"type": "string",
"enum": [
"The server has detected a conflict while processing this request."
]
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error_details"
}
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
}
},
"error_415": {
"type": "object",
"title": "Unsupported Media Type Error",
"description": "The server does not support the request payload's media type.",
"properties": {
"name": {
"type": "string",
"enum": [
"UNSUPPORTED_MEDIA_TYPE"
]
},
"message": {
"type": "string",
"enum": [
"The server does not support the request payload's media type."
]
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error_details"
}
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
}
},
"error_422": {
"type": "object",
"title": "Unprocessable Entity Error",
"description": "The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.",
"properties": {
"name": {
"type": "string",
"enum": [
"UNPROCESSABLE_ENTITY"
]
},
"message": {
"type": "string",
"enum": [
"The requested action could not be performed, semantically incorrect, or failed business validation."
]
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error_details"
}
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
}
},
"error_500": {
"type": "object",
"title": "Internal Server Error",
"description": "This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.",
"properties": {
"name": {
"type": "string",
"enum": [
"INTERNAL_SERVER_ERROR"
]
},
"message": {
"type": "string",
"enum": [
"An internal server error occurred."
]
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
},
"example": {
"name": "INTERNAL_SERVER_ERROR",
"message": "An internal server error occurred.",
"debug_id": "90957fca61718",
"links": [
{
"href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR",
"rel": "information_link"
}
]
}
},
"error_503": {
"type": "object",
"title": "Service Unavailable Error",
"description": "The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.",
"properties": {
"name": {
"type": "string",
"enum": [
"SERVICE_UNAVAILABLE"
]
},
"message": {
"type": "string",
"enum": [
"Service Unavailable."
]
},
"debug_id": {
"type": "string",
"description": "The PayPal internal ID. Used for correlation purposes."
},
"links": {
"description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).",
"type": "array",
"minItems": 0,
"maxItems": 10000,
"items": {
"$ref": "#/components/schemas/error_link_description"
}
}
},
"example": {
"name": "SERVICE_UNAVAILABLE",
"message": "Service Unavailable.",
"debug_id": "90957fca61718",
"information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE"
}
},
"authorization_status_details": {
"title": "Auhorization Status Details",
"description": "The details of the authorized payment status.",
"type": "object",
"properties": {
"reason": {
"description": "The reason why the authorized status is `PENDING`.",
"type": "string",
"minLength": 1,
"maxLength": 24,
"pattern": "^[A-Z_]+$",
"enum": [
"PENDING_REVIEW"
]
}
}
},
"authorization_status": {
"type": "object",
"title": "Authorization Status",
"description": "The status fields for an authorized payment.",
"properties": {
"status": {
"description": "The status for the authorized payment.",
"type": "string",
"readOnly": true,
"enum": [
"CREATED",
"CAPTURED",
"DENIED",
"PARTIALLY_CAPTURED",
"VOIDED",
"PENDING"
]
},
"status_details": {
"description": "The details of the authorized order pending status.",
"readOnly": true,
"$ref": "#/components/schemas/authorization_status_details"
}
}
},
"currency_code": {
"description": "The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.",
"type": "string",
"format": "ppaas_common_currency_code_v2",
"minLength": 3,
"maxLength": 3
},
"money": {
"type": "object",
"title": "Money",
"description": "The currency and amount for a financial transaction, such as a balance or payment due.",
"properties": {
"currency_code": {
"$ref": "#/components/schemas/currency_code"
},
"value": {
"type": "string",
"description": "The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/).",
"maxLength": 32,
"pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$"
}
},
"required": [
"currency_code",
"value"
]
},
"card_brand": {
"type": "string",
"title": "Card Brand",
"description": "The card network or brand. Applies to credit, debit, gift, and payment cards.",
"minLength": 1,
"maxLength": 255,
"pattern": "^[A-Z_]+$",
"enum": [
"VISA",
"MASTERCARD",
"DISCOVER",
"AMEX",
"SOLO",
"JCB",
"STAR",
"DELTA",
"SWITCH",
"MAESTRO",
"CB_NATIONALE",
"CONFIGOGA",
"CONFIDIS",
"ELECTRON",
"CETELEM",
"CHINA_UNION_PAY"
]
},
"network_transaction_reference": {
"type": "object",
"title": "Network Transaction Reference",
"description": "Reference values used by the card network to identify a transaction.",
"properties": {
"id": {
"type": "string",
"minLength": 9,
"maxLength": 36,
"pattern": "^[a-zA-Z0-9-]+$",
"description": "Transaction reference id returned by the scheme. For Visa and Amex, this is the \"Tran id\" field in response. For MasterCard, this is the \"BankNet reference id\" field in response. For Discover, this is the \"NRID\" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -."
},
"date": {
"type": "string",
"minLength": 4,
"maxLength": 4,
"pattern": "^[0-9]+$",
"description": "The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as \"BankNet reference date."
},
"network": {
"description": "Name of the card network through which the transaction was routed.",
"$ref": "#/components/schemas/card_brand"
},
"acquirer_reference_number": {
"type": "string",
"description": "Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.",
"minLength": 1,
"maxLength": 36,
"pattern": "^[a-zA-Z0-9]+$"
}
},
"required": [
"id"
]
},
"seller_protection": {
"type": "object",
"description": "The level of protection offered as defined by [PayPal Seller Protection for Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection).",
"title": "Seller Protection",
"properties": {
"status": {
"type": "string",
"description": "Indicates whether the transaction is eligible for seller protection. For information, see [PayPal Seller Protection for Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection).",
"readOnly": true,
"enum": [
"ELIGIBLE",
"PARTIALLY_ELIGIBLE",
"NOT_ELIGIBLE"
]
},
"dispute_categories": {
"type": "array",
"description": "An array of conditions that are covered for the transaction.",
"items": {
"type": "string",
"description": "The condition that is covered for the transaction.",
"enum": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"readOnly": true
}
}
},
"date_time": {
"type": "string",
"description": "The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>",
"format": "ppaas_date_time_v3",
"minLength": 20,
"maxLength": 64,
"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$"
},
"link_description": {
"type": "object",
"title": "Link Description",
"description": "The request-related [HATEOAS link](/api/rest/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"
]
}
}
},
"activity_timestamps": {
"type": "object",
"description": "The date and time stamps that are common to authorized payment, captured payment, and refund transactions.",
"title": "Transaction Date and Time Stamps",
"properties": {
"create_time": {
"description": "The date and time when the transaction occurred, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true,
"$ref": "#/components/schemas/date_time"
},
"update_time": {
"description": "The date and time when the transaction was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true,
"$ref": "#/components/schemas/date_time"
}
}
},
"authorization": {
"type": "object",
"title": "Authorization",
"description": "The authorized payment transaction.",
"allOf": [
{
"$ref": "#/components/schemas/authorization_status"
},
{
"properties": {
"id": {
"description": "The PayPal-generated ID for the authorized payment.",
"type": "string",
"readOnly": true
},
"amount": {
"description": "The amount for this authorized payment.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"invoice_id": {
"description": "The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.",
"type": "string",
"readOnly": true
},
"custom_id": {
"type": "string",
"description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.",
"maxLength": 127
},
"network_transaction_reference": {
"$ref": "#/components/schemas/network_transaction_reference"
},
"seller_protection": {
"$ref": "#/components/schemas/seller_protection",
"readOnly": true
},
"expiration_time": {
"description": "The date and time when the authorized payment expires, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"$ref": "#/components/schemas/date_time",
"readOnly": true
},
"links": {
"description": "An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
"type": "array",
"readOnly": true,
"items": {
"$ref": "#/components/schemas/link_description"
}
}
}
},
{
"$ref": "#/components/schemas/activity_timestamps"
}
]
},
"related_ids": {
"type": "object",
"title": "Related Identifiers",
"description": "Identifiers related to a specific resource.",
"properties": {
"order_id": {
"type": "string",
"description": "Order ID related to the resource.",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Z0-9]+$"
},
"authorization_id": {
"type": "string",
"description": "Authorization ID related to the resource.",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Z0-9]+$"
},
"capture_id": {
"type": "string",
"description": "Capture ID related to the resource.",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Z0-9]+$"
}
}
},
"supplementary_data": {
"title": "Supplementary Data",
"type": "object",
"description": "The supplementary data.",
"properties": {
"related_ids": {
"description": "Identifiers related to a specific resource.",
"readOnly": true,
"$ref": "#/components/schemas/related_ids"
}
}
},
"email": {
"type": "string",
"description": "The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>",
"format": "merchant_common_email_address_v2",
"maxLength": 254,
"minLength": 3,
"pattern": "(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\x7f]|\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21-\\x5a\\x53-\\x7f]|\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])"
},
"account_id": {
"type": "string",
"title": "PayPal Account Identifier",
"description": "The account identifier for a PayPal account.",
"format": "ppaas_payer_id_v3",
"minLength": 13,
"maxLength": 13,
"pattern": "^[2-9A-HJ-NP-Z]{13}$"
},
"payee_base": {
"type": "object",
"title": "Merchant Base",
"description": "The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.",
"properties": {
"email_address": {
"description": "The email address of merchant.",
"$ref": "#/components/schemas/email"
},
"merchant_id": {
"description": "The encrypted PayPal account ID of the merchant.",
"$ref": "#/components/schemas/account_id"
}
}
},
"authorization-2": {
"type": "object",
"title": "Authorization",
"description": "The authorized payment transaction.",
"allOf": [
{
"$ref": "#/components/schemas/authorization"
},
{
"properties": {
"supplementary_data": {
"description": "An object that provides supplementary/additional data related to a payment transaction.",
"readOnly": true,
"$ref": "#/components/schemas/supplementary_data"
},
"payee": {
"description": "The details associated with the merchant for this transaction.",
"$ref": "#/components/schemas/payee_base",
"readOnly": true
}
}
}
]
},
"supplementary_purchase_data": {
"type": "object",
"title": "Capture Identifier",
"description": "The capture identification-related fields. Includes the invoice ID, custom ID, note to payer, and soft descriptor.",
"properties": {
"invoice_id": {
"description": "The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.",
"type": "string",
"maxLength": 127,
"minLength": 1,
"pattern": "^.{1,127}$"
},
"note_to_payer": {
"type": "string",
"description": "An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.",
"maxLength": 255,
"minLength": 1,
"pattern": "^.{1,255}$"
}
}
},
"platform_fee": {
"type": "object",
"title": "Platform Fee",
"description": "The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit.",
"properties": {
"amount": {
"description": "The fee for this transaction.",
"$ref": "#/components/schemas/money"
},
"payee": {
"description": "The recipient of the fee for this transaction. If you omit this value, the default is the API caller.",
"$ref": "#/components/schemas/payee_base"
}
},
"required": [
"amount"
]
},
"disbursement_mode": {
"type": "string",
"title": "Disbursement Mode",
"description": "The funds that are held on behalf of the merchant.",
"default": "INSTANT",
"minLength": 1,
"maxLength": 16,
"pattern": "^[A-Z_]+$",
"enum": [
"INSTANT",
"DELAYED"
]
},
"payment_instruction": {
"type": "object",
"title": "Payment Instruction",
"description": "Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.",
"properties": {
"platform_fees": {
"type": "array",
"description": "An array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability.",
"minItems": 0,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/platform_fee"
}
},
"disbursement_mode": {
"description": "The funds that are held payee by the marketplace/platform. This field is only applicable to merchants that been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability.",
"$ref": "#/components/schemas/disbursement_mode"
},
"payee_pricing_tier_id": {
"type": "string",
"description": "This field is only enabled for selected merchants/partners to use and provides the ability to trigger a specific pricing rate/plan for a payment transaction. The list of eligible 'payee_pricing_tier_id' would be provided to you by your Account Manager. Specifying values other than the one provided to you by your account manager would result in an error.",
"minLength": 1,
"maxLength": 20,
"pattern": "^.*$"
},
"payee_receivable_fx_rate_id": {
"type": "string",
"description": "FX identifier generated returned by PayPal to be used for payment processing in order to honor FX rate (for eligible integrations) to be used when amount is settled/received into the payee account.",
"maxLength": 4000,
"minLength": 1,
"pattern": "^.*$"
}
}
},
"capture_request": {
"title": "Capture Request",
"type": "object",
"description": "Captures either a portion or the full authorized amount of an authorized payment.",
"allOf": [
{
"$ref": "#/components/schemas/supplementary_purchase_data"
},
{
"properties": {
"amount": {
"description": "The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.",
"$ref": "#/components/schemas/money"
},
"invoice_id": {
"description": "The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.",
"type": "string",
"maxLength": 127
},
"final_capture": {
"description": "Indicates whether you can make additional captures against the authorized payment. Set to `true` if you do not intend to capture additional payments against the authorization. Set to `false` if you intend to capture additional payments against the authorization.",
"type": "boolean",
"default": false
},
"payment_instruction": {
"$ref": "#/components/schemas/payment_instruction"
},
"note_to_payer": {
"description": "An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.",
"type": "string",
"maxLength": 255
},
"soft_descriptor": {
"description": "The payment descriptor on the payer's account statement.",
"type": "string",
"maxLength": 22
}
}
}
]
},
"capture_status_details": {
"title": "Capture Status Details",
"description": "The details of the captured payment status.",
"type": "object",
"properties": {
"reason": {
"description": "The reason why the captured payment status is `PENDING` or `DENIED`.",
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Z_]+$",
"enum": [
"BUYER_COMPLAINT",
"CHARGEBACK",
"ECHECK",
"INTERNATIONAL_WITHDRAWAL",
"OTHER",
"PENDING_REVIEW",
"RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION",
"REFUNDED",
"TRANSACTION_APPROVED_AWAITING_FUNDING",
"UNILATERAL",
"VERIFICATION_REQUIRED"
]
}
}
},
"capture_status": {
"type": "object",
"title": "Capture Status",
"description": "The status of a captured payment.",
"properties": {
"status": {
"description": "The status of the captured payment.",
"type": "string",
"readOnly": true,
"enum": [
"COMPLETED",
"DECLINED",
"PARTIALLY_REFUNDED",
"PENDING",
"REFUNDED",
"FAILED"
]
},
"status_details": {
"description": "The details of the captured payment status.",
"readOnly": true,
"$ref": "#/components/schemas/capture_status_details"
}
}
},
"exchange_rate": {
"description": "The exchange rate that determines the amount to convert from one currency to another currency.",
"type": "object",
"title": "Exchange Rate",
"properties": {
"source_currency": {
"description": "The source currency from which to convert an amount.",
"$ref": "#/components/schemas/currency_code"
},
"target_currency": {
"description": "The target currency to which to convert an amount.",
"$ref": "#/components/schemas/currency_code"
},
"value": {
"description": "The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point.",
"type": "string"
}
},
"readOnly": true
},
"seller_receivable_breakdown": {
"type": "object",
"title": "Seller Receivable Breakdown",
"description": "The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.",
"properties": {
"gross_amount": {
"description": "The amount for this captured payment in the currency of the transaction.",
"$ref": "#/components/schemas/money"
},
"paypal_fee": {
"description": "The applicable fee for this captured payment in the currency of the transaction.",
"$ref": "#/components/schemas/money"
},
"paypal_fee_in_receivable_currency": {
"description": "The applicable fee for this captured payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'.",
"$ref": "#/components/schemas/money"
},
"net_amount": {
"description": "The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as <code>gross_amount</code> minus the <code>paypal_fee</code> minus the <code>platform_fees</code>.",
"$ref": "#/components/schemas/money"
},
"receivable_amount": {
"description": "The net amount that is credited to the payee's PayPal account. Returned only when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. The amount is computed as <code>net_amount</code> times <code>exchange_rate</code>.",
"$ref": "#/components/schemas/money"
},
"exchange_rate": {
"description": "The exchange rate that determines the amount that is credited to the payee's PayPal account. Returned when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds.",
"$ref": "#/components/schemas/exchange_rate"
},
"platform_fees": {
"type": "array",
"description": "An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.",
"minItems": 0,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/platform_fee"
}
}
},
"required": [
"gross_amount"
]
},
"processor_response": {
"type": "object",
"title": "Processor Response",
"description": "The processor response information for payment requests, such as direct credit card transactions.",
"properties": {
"avs_code": {
"description": "The address verification code for Visa, Discover, Mastercard, or American Express transactions.",
"type": "string",
"readOnly": true,
"enum": [
"A",
"B",
"C",
"D",
"E",
"F",
"G",
"I",
"M",
"N",
"P",
"R",
"S",
"U",
"W",
"X",
"Y",
"Z",
"Null",
"0",
"1",
"2",
"3",
"4"
]
},
"cvv_code": {
"description": "The card verification value code for for Visa, Discover, Mastercard, or American Express.",
"type": "string",
"readOnly": true,
"enum": [
"E",
"I",
"M",
"N",
"P",
"S",
"U",
"X",
"All others",
"0",
"1",
"2",
"3",
"4"
]
},
"response_code": {
"description": "Processor response code for the non-PayPal payment processor errors.",
"type": "string",
"readOnly": true,
"enum": [
"0000",
"00N7",
"0100",
"0390",
"0500",
"0580",
"0800",
"0880",
"0890",
"0960",
"0R00",
"1000",
"10BR",
"1300",
"1310",
"1312",
"1317",
"1320",
"1330",
"1335",
"1340",
"1350",
"1352",
"1360",
"1370",
"1380",
"1382",
"1384",
"1390",
"1393",
"5100",
"5110",
"5120",
"5130",
"5135",
"5140",
"5150",
"5160",
"5170",
"5180",
"5190",
"5200",
"5210",
"5400",
"5500",
"5650",
"5700",
"5710",
"5800",
"5900",
"5910",
"5920",
"5930",
"5950",
"6300",
"7600",
"7700",
"7710",
"7800",
"7900",
"8000",
"8010",
"8020",
"8030",
"8100",
"8110",
"8220",
"9100",
"9500",
"9510",
"9520",
"9530",
"9540",
"9600",
"PCNR",
"PCVV",
"PP06",
"PPRN",
"PPAD",
"PPAB",
"PPAE",
"PPAG",
"PPAI",
"PPAR",
"PPAU",
"PPAV",
"PPAX",
"PPBG",
"PPC2",
"PPCE",
"PPCO",
"PPCR",
"PPCT",
"PPCU",
"PPD3",
"PPDC",
"PPDI",
"PPDV",
"PPDT",
"PPEF",
"PPEL",
"PPER",
"PPEX",
"PPFE",
"PPFI",
"PPFR",
"PPFV",
"PPGR",
"PPH1",
"PPIF",
"PPII",
"PPIM",
"PPIT",
"PPLR",
"PPLS",
"PPMB",
"PPMC",
"PPMD",
"PPNC",
"PPNL",
"PPNM",
"PPNT",
"PPPH",
"PPPI",
"PPPM",
"PPQC",
"PPRE",
"PPRF",
"PPRR",
"PPS0",
"PPS1",
"PPS2",
"PPS3",
"PPS4",
"PPS5",
"PPS6",
"PPSC",
"PPSD",
"PPSE",
"PPTE",
"PPTF",
"PPTI",
"PPTR",
"PPTT",
"PPTV",
"PPUA",
"PPUC",
"PPUE",
"PPUI",
"PPUP",
"PPUR",
"PPVC",
"PPVE",
"PPVT"
]
},
"payment_advice_code": {
"description": "The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.",
"type": "string",
"readOnly": true,
"enum": [
"01",
"02",
"03",
"21"
]
}
}
},
"capture": {
"type": "object",
"title": "Capture",
"description": "A captured payment.",
"allOf": [
{
"$ref": "#/components/schemas/capture_status"
},
{
"properties": {
"id": {
"description": "The PayPal-generated ID for the captured payment.",
"type": "string",
"readOnly": true
},
"amount": {
"description": "The amount for this captured payment.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"invoice_id": {
"description": "The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.",
"type": "string",
"readOnly": true
},
"custom_id": {
"type": "string",
"description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.",
"maxLength": 127
},
"network_transaction_reference": {
"$ref": "#/components/schemas/network_transaction_reference"
},
"seller_protection": {
"$ref": "#/components/schemas/seller_protection",
"readOnly": true
},
"final_capture": {
"description": "Indicates whether you can make additional captures against the authorized payment. Set to `true` if you do not intend to capture additional payments against the authorization. Set to `false` if you intend to capture additional payments against the authorization.",
"type": "boolean",
"default": false,
"readOnly": true
},
"seller_receivable_breakdown": {
"$ref": "#/components/schemas/seller_receivable_breakdown",
"readOnly": true
},
"disbursement_mode": {
"$ref": "#/components/schemas/disbursement_mode"
},
"links": {
"description": "An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
"type": "array",
"readOnly": true,
"items": {
"$ref": "#/components/schemas/link_description"
}
},
"processor_response": {
"description": "An object that provides additional processor information for a direct credit card transaction.",
"$ref": "#/components/schemas/processor_response"
}
}
},
{
"$ref": "#/components/schemas/activity_timestamps"
}
]
},
"capture-2": {
"type": "object",
"title": "Capture",
"description": "A captured payment.",
"allOf": [
{
"$ref": "#/components/schemas/capture"
},
{
"properties": {
"supplementary_data": {
"description": "An object that provides supplementary/additional data related to a payment transaction.",
"readOnly": true,
"$ref": "#/components/schemas/supplementary_data"
},
"payee": {
"description": "The details associated with the merchant for this transaction.",
"$ref": "#/components/schemas/payee_base",
"readOnly": true
}
}
}
]
},
"reauthorize_request": {
"title": "Reauthorize Request",
"type": "object",
"description": "Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. You can reauthorize a payment only once from days four to 29.<br/><br/>If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.<br/><br/>A reauthorized payment itself has a new honor period of three days.<br/><br/>You can reauthorize an authorized payment once. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.<br/><br/>Supports only the `amount` request parameter.<blockquote><strong>Note:</strong> This request is currently not supported for Partner use cases.</blockquote>",
"properties": {
"amount": {
"description": "The amount to reauthorize for an authorized payment.",
"$ref": "#/components/schemas/money"
}
}
},
"authorizations.reauthorize-400": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "MISSING_REQUIRED_PARAMETER",
"properties": {
"issue": {
"type": "string",
"enum": [
"MISSING_REQUIRED_PARAMETER"
]
},
"description": {
"type": "string",
"enum": [
"A required field / parameter is missing."
]
}
}
},
{
"title": "INVALID_STRING_LENGTH",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_STRING_LENGTH"
]
},
"description": {
"type": "string",
"enum": [
"The value of a field is either too short or too long."
]
}
}
},
{
"title": "INVALID_STRING_MAX_LENGTH",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_STRING_MAX_LENGTH"
]
},
"description": {
"type": "string",
"enum": [
"The value of a field is too long."
]
}
}
},
{
"title": "INVALID_PARAMETER_SYNTAX",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_PARAMETER_SYNTAX"
]
},
"description": {
"type": "string",
"enum": [
"The value of a field does not conform to the expected format."
]
}
}
}
]
}
}
}
},
"authorizations.reauthorize-422": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "INVALID_CURRENCY_CODE",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_CURRENCY_CODE"
]
},
"description": {
"type": "string",
"enum": [
"Currency code is invalid or is not currently supported. Please refer https://developer.paypal.com/docs/api/reference/currency-codes/ for list of supported currency codes."
]
}
}
},
{
"title": "CANNOT_BE_ZERO_OR_NEGATIVE",
"properties": {
"issue": {
"type": "string",
"enum": [
"CANNOT_BE_ZERO_OR_NEGATIVE"
]
},
"description": {
"type": "string",
"enum": [
"Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported."
]
}
}
},
{
"title": "DECIMAL_PRECISION",
"properties": {
"issue": {
"type": "string",
"enum": [
"DECIMAL_PRECISION"
]
},
"description": {
"type": "string",
"enum": [
"If the currency supports decimals, only two decimal place precision is supported."
]
}
}
},
{
"title": "DECIMALS_NOT_SUPPORTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"DECIMALS_NOT_SUPPORTED"
]
},
"description": {
"type": "string",
"enum": [
"Currency does not support decimals. Please refer to https://developer.paypal.com/docs/api/reference/currency-codes/ for more information."
]
}
}
},
{
"title": "TRANSACTION_REFUSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"TRANSACTION_REFUSED"
]
},
"description": {
"type": "string",
"enum": [
"PayPal's internal controls prevent authorization from being captured."
]
}
}
},
{
"title": "AUTHORIZATION_VOIDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTHORIZATION_VOIDED"
]
},
"description": {
"type": "string",
"enum": [
"A voided authorization cannot be captured or reauthorized. "
]
}
}
},
{
"title": "PAYER_CANNOT_PAY",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYER_CANNOT_PAY"
]
},
"description": {
"type": "string",
"enum": [
"Payer cannot pay for this transaction. Please contact the payer to find other ways to pay for this transaction."
]
}
}
},
{
"title": "AUTHORIZATION_ALREADY_CAPTURED",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTHORIZATION_ALREADY_CAPTURED"
]
},
"description": {
"type": "string",
"enum": [
"Authorization has previously been captured."
]
}
}
},
{
"title": "PAYEE_ACCOUNT_LOCKED_OR_CLOSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYEE_ACCOUNT_LOCKED_OR_CLOSED"
]
},
"description": {
"type": "string",
"enum": [
"Transaction could not complete because payee account is locked or closed."
]
}
}
},
{
"title": "PAYER_ACCOUNT_LOCKED_OR_CLOSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYER_ACCOUNT_LOCKED_OR_CLOSED"
]
},
"description": {
"type": "string",
"enum": [
"The payer account cannot be used for this transaction."
]
}
}
},
{
"title": "PAYEE_ACCOUNT_RESTRICTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYEE_ACCOUNT_RESTRICTED"
]
},
"description": {
"type": "string",
"enum": [
"Payee account is restricted."
]
}
}
},
{
"title": "REAUTHORIZATION_NOT_SUPPORTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"REAUTHORIZATION_NOT_SUPPORTED"
]
},
"description": {
"type": "string",
"enum": [
"A reauthorize cannot be attempted on an authorization_id that is the result of a prior reauthorization or on an authorization made on an Order saved using the `v2/orders/id/save` API."
]
}
}
},
{
"title": "AUTH_CURRENCY_MISMATCH",
"properties": {
"issue": {
"type": "string",
"enum": [
"AUTH_CURRENCY_MISMATCH"
]
},
"description": {
"type": "string",
"enum": [
"The currency specified during reauthorization should be the same as the currency specified in the original authorization. Please check the currency of the authorization for which you are trying to reauthorize and try again."
]
}
}
}
]
}
}
}
},
"authorizations.void-422": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "PREVIOUSLY_CAPTURED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PREVIOUSLY_CAPTURED"
]
},
"description": {
"type": "string",
"enum": [
"Authorization has been previously captured and hence cannot be voided."
]
}
}
},
{
"title": "PREVIOUSLY_VOIDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PREVIOUSLY_VOIDED"
]
},
"description": {
"type": "string",
"enum": [
"Authorization has been previously voided and hence cannot be voided again."
]
}
}
},
{
"title": "CANNOT_BE_VOIDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"CANNOT_BE_VOIDED"
]
},
"description": {
"type": "string",
"enum": [
"A reauthorization cannot be voided. Please void the original parent authorization."
]
}
}
}
]
}
}
}
},
"payment_instruction-2": {
"type": "object",
"title": "Payment Instruction",
"description": "Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.",
"properties": {
"platform_fees": {
"type": "array",
"description": "Specifies the amount that the API caller will contribute to the refund being processed. The amount needs to be lower than platform_fees amount originally captured or the amount that is remaining if multiple refunds have been processed. This field is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.",
"minItems": 0,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/platform_fee"
}
}
}
},
"refund_request": {
"title": "Refund Request",
"type": "object",
"description": "Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an <code>amount</code> object in the request body.",
"properties": {
"amount": {
"description": "The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to <code>captured amount - previous refunds</code> is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured.",
"$ref": "#/components/schemas/money"
},
"custom_id": {
"type": "string",
"description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. The pattern is defined by an external party and supports Unicode.",
"minLength": 1,
"maxLength": 127,
"pattern": "^.*$"
},
"invoice_id": {
"type": "string",
"description": "The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode.",
"minLength": 1,
"maxLength": 127,
"pattern": "^.*$"
},
"note_to_payer": {
"type": "string",
"description": "The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. The pattern is defined by an external party and supports Unicode.",
"minLength": 1,
"maxLength": 255,
"pattern": "^.*$"
},
"payment_instruction": {
"description": "Any additional refund instructions to be set during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.",
"$ref": "#/components/schemas/payment_instruction-2"
}
}
},
"refund_status_details": {
"title": "Refund Status Details",
"description": "The details of the refund status.",
"type": "object",
"properties": {
"reason": {
"description": "The reason why the refund has the `PENDING` or `FAILED` status.",
"type": "string",
"enum": [
"ECHECK"
]
}
}
},
"refund_status": {
"type": "object",
"description": "The refund status.",
"title": "Refund Status",
"properties": {
"status": {
"description": "The status of the refund.",
"type": "string",
"readOnly": true,
"enum": [
"CANCELLED",
"FAILED",
"PENDING",
"COMPLETED"
]
},
"status_details": {
"description": "The details of the refund status.",
"readOnly": true,
"$ref": "#/components/schemas/refund_status_details"
}
}
},
"net_amount_breakdown_item": {
"type": "object",
"title": "Net Amount Breakdown Item",
"description": "The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds.",
"properties": {
"payable_amount": {
"description": "The net amount debited from the merchant's PayPal account.",
"readOnly": true,
"$ref": "#/components/schemas/money"
},
"converted_amount": {
"description": "The converted payable amount.",
"readOnly": true,
"$ref": "#/components/schemas/money"
},
"exchange_rate": {
"description": "The exchange rate that determines the amount that was debited from the merchant's PayPal account.",
"readOnly": true,
"$ref": "#/components/schemas/exchange_rate"
}
}
},
"refund": {
"type": "object",
"title": "Refund",
"description": "The refund information.",
"allOf": [
{
"$ref": "#/components/schemas/refund_status"
},
{
"properties": {
"id": {
"description": "The PayPal-generated ID for the refund.",
"type": "string",
"readOnly": true
},
"amount": {
"description": "The amount that the payee refunded to the payer.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"invoice_id": {
"description": "The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.",
"type": "string",
"readOnly": true
},
"custom_id": {
"type": "string",
"description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.",
"minLength": 1,
"maxLength": 127,
"pattern": "^[A-Za-z0-9-_.,]*$"
},
"acquirer_reference_number": {
"type": "string",
"description": "Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.",
"minLength": 1,
"maxLength": 36,
"pattern": "^[a-zA-Z0-9]+$"
},
"note_to_payer": {
"description": "The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.",
"type": "string",
"readOnly": true
},
"seller_payable_breakdown": {
"description": "The breakdown of the refund.",
"type": "object",
"title": "Merchant Payable Breakdown",
"properties": {
"gross_amount": {
"description": "The amount that the payee refunded to the payer.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"paypal_fee": {
"description": "The PayPal fee that was refunded to the payer in the currency of the transaction. This fee might not match the PayPal fee that the payee paid when the payment was captured.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"paypal_fee_in_receivable_currency": {
"description": "The PayPal fee that was refunded to the payer in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"net_amount": {
"description": "The net amount that the payee's account is debited in the transaction currency. The net amount is calculated as <code>gross_amount</code> minus <code>paypal_fee</code> minus <code>platform_fees</code>.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"net_amount_in_receivable_currency": {
"description": "The net amount that the payee's account is debited in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.",
"$ref": "#/components/schemas/money",
"readOnly": true
},
"platform_fees": {
"type": "array",
"description": "An array of platform or partner fees, commissions, or brokerage fees for the refund.",
"minItems": 0,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/platform_fee"
}
},
"net_amount_breakdown": {
"type": "array",
"description": "An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds.",
"items": {
"$ref": "#/components/schemas/net_amount_breakdown_item"
},
"readOnly": true
},
"total_refunded_amount": {
"description": "The total amount refunded from the original capture to date. For example, if a payer makes a $100 purchase and was refunded $20 a week ago and was refunded $30 in this refund, the `gross_amount` is $30 for this refund and the `total_refunded_amount` is $50.",
"$ref": "#/components/schemas/money"
}
},
"readOnly": true
},
"payer": {
"description": "The details associated with the merchant for this transaction.",
"$ref": "#/components/schemas/payee_base",
"readOnly": true
},
"links": {
"description": "An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
"type": "array",
"readOnly": true,
"items": {
"$ref": "#/components/schemas/link_description"
}
}
}
},
{
"$ref": "#/components/schemas/activity_timestamps"
}
]
},
"captures.refund-400": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "MISSING_REQUIRED_PARAMETER",
"properties": {
"issue": {
"type": "string",
"enum": [
"MISSING_REQUIRED_PARAMETER"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "INVALID_PARAMETER_SYNTAX",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_PARAMETER_SYNTAX"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "INVALID_STRING_LENGTH",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_STRING_LENGTH"
]
},
"description": {
"type": "string"
}
}
}
]
}
}
}
},
"captures.refund-422": {
"properties": {
"details": {
"type": "array",
"items": {
"anyOf": [
{
"title": "CANNOT_BE_ZERO_OR_NEGATIVE",
"properties": {
"issue": {
"type": "string",
"enum": [
"CANNOT_BE_ZERO_OR_NEGATIVE"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "DECIMAL_PRECISION",
"properties": {
"issue": {
"type": "string",
"enum": [
"DECIMAL_PRECISION"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "DECIMALS_NOT_SUPPORTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"DECIMALS_NOT_SUPPORTED"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "INVALID_CURRENCY_CODE",
"properties": {
"issue": {
"type": "string",
"enum": [
"INVALID_CURRENCY_CODE"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "CURRENCY_MISMATCH",
"properties": {
"issue": {
"type": "string",
"enum": [
"CURRENCY_MISMATCH"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "CANNOT_BE_NEGATIVE",
"properties": {
"issue": {
"type": "string",
"enum": [
"CANNOT_BE_NEGATIVE"
]
},
"description": {
"type": "string"
}
}
},
{
"title": "CAPTURE_FULLY_REFUNDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"CAPTURE_FULLY_REFUNDED"
]
},
"description": {
"type": "string",
"enum": [
"The capture has already been fully refunded"
]
}
}
},
{
"title": "REFUND_CAPTURE_CURRENCY_MISMATCH",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_CAPTURE_CURRENCY_MISMATCH"
]
},
"description": {
"type": "string",
"enum": [
"Refund must be in the same currency as the capture"
]
}
}
},
{
"title": "REFUND_NOT_ALLOWED",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_NOT_ALLOWED"
]
},
"description": {
"type": "string",
"enum": [
"Capture cannot be refunded."
]
}
}
},
{
"title": "REFUND_TIME_LIMIT_EXCEEDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_TIME_LIMIT_EXCEEDED"
]
},
"description": {
"type": "string",
"enum": [
"You are over the time limit to perform a refund on this capture"
]
}
}
},
{
"title": "REFUND_AMOUNT_EXCEEDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_AMOUNT_EXCEEDED"
]
},
"description": {
"type": "string",
"enum": [
"The refund amount must be less than or equal to the capture amount that has not yet been refunded."
]
}
}
},
{
"title": "REFUND_AMOUNT_TOO_LOW",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_AMOUNT_TOO_LOW"
]
},
"description": {
"type": "string",
"enum": [
"The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account."
]
}
}
},
{
"title": "REFUND_FAILED_INSUFFICIENT_FUNDS",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_FAILED_INSUFFICIENT_FUNDS"
]
},
"description": {
"type": "string",
"enum": [
"Capture could not be refunded due to insufficient funds. Please check to see if you have sufficient funds in your PayPal account or if the bank account linked to your PayPal account is verified and has sufficient funds."
]
}
}
},
{
"title": "PARTIAL_REFUND_NOT_ALLOWED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PARTIAL_REFUND_NOT_ALLOWED"
]
},
"description": {
"type": "string",
"enum": [
"You cannot do a refund less than the original capture amount."
]
}
}
},
{
"title": "MAX_NUMBER_OF_REFUNDS_EXCEEDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"MAX_NUMBER_OF_REFUNDS_EXCEEDED"
]
},
"description": {
"type": "string",
"enum": [
"You have exceeded the maximum number of refund attempts for this capture."
]
}
}
},
{
"title": "PENDING_CAPTURE",
"properties": {
"issue": {
"type": "string",
"enum": [
"PENDING_CAPTURE"
]
},
"description": {
"type": "string",
"enum": [
"Cannot initiate a refund as the capture is pending. Capture is typically pending when the payer has funded the transaction using e-check/bank funded."
]
}
}
},
{
"title": "DUPLICATE_INVOICE_ID",
"properties": {
"issue": {
"type": "string",
"enum": [
"DUPLICATE_INVOICE_ID"
]
},
"description": {
"type": "string",
"enum": [
"Invoice ID was previously used to refund a capture."
]
}
}
},
{
"title": "PAYEE_ACCOUNT_LOCKED_OR_CLOSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYEE_ACCOUNT_LOCKED_OR_CLOSED"
]
},
"description": {
"type": "string",
"enum": [
"Transaction could not complete because payee account is locked or closed."
]
}
}
},
{
"title": "PAYER_ACCOUNT_LOCKED_OR_CLOSED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYER_ACCOUNT_LOCKED_OR_CLOSED"
]
},
"description": {
"type": "string",
"enum": [
"The payer account cannot be used for this transaction."
]
}
}
},
{
"title": "PAYEE_ACCOUNT_RESTRICTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PAYEE_ACCOUNT_RESTRICTED"
]
},
"description": {
"type": "string",
"enum": [
"Payee account is restricted."
]
}
}
},
{
"title": "REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK"
]
},
"description": {
"type": "string",
"enum": [
"Refunds are not allowed on this capture due to a chargeback on the card or bank. Please contact the payee to resolve the chargeback."
]
}
}
},
{
"title": "TRANSACTION_DISPUTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"TRANSACTION_DISPUTED"
]
},
"description": {
"type": "string",
"enum": [
"Partial refunds cannot be offered at this time because there is an open case on this transaction. Visit the PayPal Resolution Center to review this case."
]
}
}
},
{
"title": "PLATFORM_FEE_EXCEEDED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PLATFORM_FEE_EXCEEDED"
]
},
"description": {
"type": "string",
"enum": [
"Platform fee amount specified exceeds the amount that is available for refund. You can only refund up to the available platform fee amount. This error is also returned when no platform_fee was specified or was zero when the payment was captured."
]
}
}
},
{
"title": "REFUND_IS_RESTRICTED",
"properties": {
"issue": {
"type": "string",
"enum": [
"REFUND_IS_RESTRICTED"
]
},
"description": {
"type": "string",
"enum": [
"This refund can only be processed by the API caller that had 'captured' the transaction. If you facilitate your transactions via a platform/partner, please initiate a refund through them."
]
}
}
},
{
"title": "PLATFORM_FEE_NOT_ENABLED",
"properties": {
"issue": {
"type": "string",
"enum": [
"PLATFORM_FEE_NOT_ENABLED"
]
},
"description": {
"type": "string",
"enum": [
"The API Caller account is not setup to be able to process refunds with 'platform_fees'. Please contact your Account Manager. This feature is useful when you want to contribute a portion of the 'platform_fees' you had capture as part of the refund being processed."
]
}
}
}
]
}
}
}
}
},
"parameters": {
"authorization_id": {
"name": "authorization_id",
"in": "path",
"description": "The PayPal-generated ID for the authorized payment to void.",
"required": true,
"schema": {
"type": "string"
}
},
"paypal_request_id": {
"name": "PayPal-Request-Id",
"in": "header",
"description": "The server stores keys for 45 days.",
"required": false,
"schema": {
"type": "string"
}
},
"prefer": {
"name": "Prefer",
"in": "header",
"description": "The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul>",
"required": false,
"schema": {
"type": "string",
"default": "return=minimal"
}
},
"paypal_auth_assertion": {
"name": "PayPal-Auth-Assertion",
"in": "header",
"description": "An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see [PayPal-Auth-Assertion](/docs/api/reference/api-requests/#paypal-auth-assertion).<blockquote><strong>Note:</strong>For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.</blockquote>",
"required": false,
"schema": {
"type": "string"
}
},
"capture_id": {
"name": "capture_id",
"in": "path",
"description": "The PayPal-generated ID for the captured payment to refund.",
"required": true,
"schema": {
"type": "string"
}
},
"refund_id": {
"name": "refund_id",
"in": "path",
"description": "The PayPal-generated ID for the refund for which to show details.",
"required": true,
"schema": {
"type": "string"
}
}
}
}
}