{ "openapi": "3.0.4", "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 Orders API. For more information, see the PayPal Checkout Overview.", "version": "2.13" }, "servers": [ { "url": "https://api-m.paypal.com", "description": "Server for https scheme." } ], "tags": [ { "name": "assets", "description": "Assets APIs for Checkout" }, { "name": "authorizations", "description": "Use the `/authorizations` resource to show details for, capture payment for, reauthorize, and void authorized payments." }, { "name": "cancel-payment", "description": "Use the /cancel-payment resource to cancel an order capture or order authorization by PayPal-Request-Id. The merchant triggers the cancel action." }, { "name": "captures", "description": "Use the `/captures` resource to show details for and refund a captured payment." }, { "name": "find-bin-details", "description": "Use the `/find-bin-details` resource to determine PayPal supported networks and retrieve BIN details for given card and payee." }, { "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." }, { "name": "refunds", "description": "Use the `/refunds` resource to show refund details." } ], "externalDocs": { "url": "/docs/checkout/" }, "paths": { "/v2/payments/authorizations/{authorization_id}": { "get": { "operationId": "authorizations.get", "summary": "Show details for authorized payment", "description": "Shows details for an authorized payment, by ID.", "tags": [ "authorizations" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "parameters": [ { "name": "authorization_id", "description": "The ID of the authorized payment for which to show details.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "examples": { "authorizations_get": { "summary": "Show Authorized Payment Details", "description": "Shows details for an authorized payment, by ID.", "value": "0VF52814937998046" }, "authorizations_get_with_supplementary_data": { "summary": "Show Authorized Payment Details", "description": "Shows details for an authorized payment, by ID.", "value": "0T620041CK889853A" }, "authorizations_get_with_metadata": { "summary": "Show Authorized Payment Details with Metadata", "description": "Shows details for an authorized payment with metadata.", "value": "0VF52814937998046" } } }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/paypal_auth_assertion" } ], "x-exampleFlows": [ { "title": "Show authorized payment details", "description": "Retrieves complete details for an authorized payment by ID.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/authorizations_get" ], "response_example": "responses/200/content/application~1json/examples/authorizations_get" }, { "title": "Show authorized payment with supplementary data", "description": "Retrieves details for an authorized payment by ID including supplementary data such as related order information.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/authorizations_get_with_supplementary_data" ], "response_example": "responses/200/content/application~1json/examples/authorizations_get_with_supplementary_data" }, { "title": "Show Authorized Payment Details with Metadata", "description": "Shows details for an authorized payment with metadata.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/authorizations_get_with_metadata" ], "response_example": "responses/200/content/application~1json/examples/authorizations_get_with_metadata" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK status code and a JSON response body that shows authorization details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization-2" }, "examples": { "authorizations_get": { "summary": "Show Authorized Payment Details", "description": "Shows details for an authorized payment, by ID.", "value": { "id": "0VF52814937998046", "status": "CREATED", "amount": { "value": "10.99", "currency_code": "USD" }, "invoice_id": "INVOICE-123", "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "payee": { "email_address": "merchant@example.com", "merchant_id": "7KNGBPH2U58GQ" }, "expiration_time": "2017-10-10T23:23:45Z", "create_time": "2017-09-11T23:23:45Z", "update_time": "2017-09-11T23:23:45Z", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046" }, { "rel": "capture", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/capture" }, { "rel": "void", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/void" }, { "rel": "reauthorize", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/reauthorize" } ] } }, "authorizations_get_with_metadata": { "summary": "Show Authorized Payment Details with Metadata", "description": "Shows details for an authorized payment with metadata.", "value": { "id": "0VF52814937998046", "status": "CREATED", "amount": { "value": "10.99", "currency_code": "USD" }, "invoice_id": "INVOICE-123", "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "payee": { "email_address": "merchant@example.com", "merchant_id": "7KNGBPH2U58GQ" }, "expiration_time": "2017-10-10T23:23:45Z", "create_time": "2017-09-11T23:23:45Z", "update_time": "2017-09-11T23:23:45Z", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046" }, { "rel": "capture", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/capture" }, { "rel": "void", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/void" }, { "rel": "reauthorize", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/reauthorize" } ] } }, "authorizations_get_with_supplementary_data": { "summary": "Show Authorized Payment Details", "description": "Shows details for an authorized payment, by ID.", "value": { "id": "0T620041CK889853A", "status": "CREATED", "amount": { "currency_code": "USD", "value": "100.00" }, "invoice_id": "OrderInvoice-23_10_2024_12_27_32_pm", "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "supplementary_data": { "related_ids": { "order_id": "25M43554V9523650M" } }, "payee": { "email_address": "merchant@example.com", "merchant_id": "YXZY75W2GKDQE" }, "expiration_time": "2024-11-21T17:27:36Z", "create_time": "2024-10-23T17:27:36Z", "update_time": "2024-10-23T17:27:36Z", "links": [ { "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/0T620041CK889853A", "rel": "self", "method": "GET" }, { "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/0T620041CK889853A/capture", "rel": "capture", "method": "POST" }, { "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/0T620041CK889853A/void", "rel": "void", "method": "POST" }, { "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/0T620041CK889853A/reauthorize", "rel": "reauthorize", "method": "POST" }, { "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/25M43554V9523650M", "rel": "up", "method": "GET" } ] } } } } } }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "404": { "$ref": "#/components/responses/404_error_response" }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } } } }, "/v2/payments/authorizations/{authorization_id}/capture": { "post": { "operationId": "authorizations.capture", "summary": "Capture authorized payment", "description": "Captures an authorized payment, by ID.", "tags": [ "authorizations" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "parameters": [ { "name": "authorization_id", "description": "The PayPal-generated ID for the authorized payment to capture.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "examples": { "example": { "summary": "Capture Authorized Payment", "description": "The PayPal-generated ID for the authorized payment to capture.", "value": "0VF52814937998046" } } }, { "$ref": "#/components/parameters/paypal_request_id" }, { "name": "Prefer", "description": "The preferred server response upon successful completion of the request. Value is:", "in": "header", "required": false, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "default": "return=minimal" }, "examples": { "authorizations_capture_200_idempotent_response": { "summary": "Capture Authorized Payment - 200 idempotent response", "description": "Captures an authorized payment, by ID.", "value": "return=representation" }, "authorizations_capture_with_prefer_header": { "summary": "Capture Authorized Payment with Prefer Request Header", "description": "Captures an authorized payment, by ID. Includes the `Prefer` request header.", "value": "return=representation" }, "authorizations_capture_empty_request": { "summary": "Capture Authorized Payment with an empty request", "description": "Captures an authorized payment, by ID.", "value": "return=representation" } } }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/paypal_auth_assertion" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture_request" }, "examples": { "authorizations_capture": { "summary": "Capture Authorized Payment", "description": "Captures an authorized payment, by ID.", "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" } }, "authorizations_capture_200_idempotent_response": { "summary": "Capture Authorized Payment - 200 idempotent response", "description": "Captures an authorized payment, by ID.", "value": { "amount": { "value": "1.00", "currency_code": "USD" }, "invoice_id": "CaptureInvoice-10142024", "final_capture": false } }, "authorizations_capture_empty_request": { "summary": "Capture Authorized Payment with an empty request", "description": "Captures an authorized payment, by ID.", "value": { } }, "authorizations_capture_with_prefer_header": { "summary": "Capture Authorized Payment with Prefer Request Header", "description": "Captures an authorized payment, by ID. Includes the `Prefer` request header.", "value": { "amount": { "value": "10.99", "currency_code": "USD" }, "invoice_id": "INVOICE-123", "final_capture": true } } } } } }, "x-exampleFlows": [ { "title": "Capture authorized payment", "description": "Captures an authorized payment by ID with specified amount and invoice details.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example" ], "request_example": "requestBody/content/application~1json/examples/authorizations_capture", "response_example": "responses/201/content/application~1json/examples/authorizations_capture" }, { "title": "Capture authorized payment with empty request body", "description": "Captures the full authorized amount by ID with an empty request body, using default values.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example", "parameters/@name=='Prefer'/examples/authorizations_capture_empty_request" ], "request_example": "requestBody/content/application~1json/examples/authorizations_capture_empty_request", "response_example": "responses/201/content/application~1json/examples/authorizations_capture_empty_request" }, { "title": "Capture with Prefer header for full representation", "description": "Captures an authorized payment by ID with the Prefer header set to return=representation to get complete capture details in the response.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example", "parameters/@name=='Prefer'/examples/authorizations_capture_with_prefer_header" ], "request_example": "requestBody/content/application~1json/examples/authorizations_capture_with_prefer_header", "response_example": "responses/201/content/application~1json/examples/authorizations_capture_with_prefer_header" }, { "title": "Idempotent capture request (200 response)", "description": "Demonstrates an idempotent capture request where the same PayPal-Request-Id is used, resulting in a 200 OK response with existing capture details.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example", "parameters/@name=='Prefer'/examples/authorizations_capture_200_idempotent_response" ], "request_example": "requestBody/content/application~1json/examples/authorizations_capture_200_idempotent_response", "response_example": "responses/200/content/application~1json/examples/authorizations_capture_200_idempotent_response" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK status code and a JSON response body that shows captured payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-2" }, "examples": { "authorizations_capture_200_idempotent_response": { "summary": "Capture Authorized Payment - 200 idempotent response", "description": "Captures an authorized payment, by ID.", "value": { "id": "23T524207X938445J", "amount": { "currency_code": "USD", "value": "100.00" }, "final_capture": false, "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "seller_receivable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.52" }, "net_amount": { "currency_code": "USD", "value": "0.48" }, "exchange_rate": { } }, "invoice_id": "OrderInvoice-10_10_2024_12_58_20_pm", "status": "COMPLETED", "create_time": "2024-10-14T21:29:26Z", "update_time": "2024-10-14T21:29:26Z", "links": [ { "href": "https://api-m.paypal.com/v2/payments/captures/23T524207X938445J", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v2/payments/captures/23T524207X938445J/refund", "rel": "refund", "method": "POST" }, { "href": "https://api-m.paypal.com/v2/payments/authorizations/6DR965477U7140544", "rel": "up", "method": "GET" } ] } } } } } }, "201": { "description": "A successful request returns the HTTP 201 Created status code and a JSON response body that shows captured payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-2" }, "examples": { "authorizations_capture": { "summary": "Capture Authorized Payment", "description": "Captures an authorized payment, by ID.", "value": { "id": "2GG279541U471931P", "status": "COMPLETED", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P" }, { "rel": "refund", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P/refund" }, { "rel": "up", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046" } ] } }, "authorizations_capture_empty_request": { "summary": "Capture Authorized Payment with an empty request", "description": "Captures an authorized payment, by ID.", "value": { "id": "7TK53561YB803214S", "amount": { "currency_code": "USD", "value": "100.00" }, "final_capture": true, "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "seller_receivable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "100.00" }, "paypal_fee": { "currency_code": "USD", "value": "3.98" }, "net_amount": { "currency_code": "USD", "value": "96.02" }, "exchange_rate": { } }, "invoice_id": "OrderInvoice-10_10_2024_12_58_20_pm", "status": "PENDING", "status_details": { "reason": "OTHER" }, "create_time": "2024-10-14T21:37:10Z", "update_time": "2024-10-14T21:37:10Z", "links": [ { "href": "https://api.msmaster.qa.paypal.com/v2/payments/captures/7TK53561YB803214S", "rel": "self", "method": "GET" }, { "href": "https://api.msmaster.qa.paypal.com/v2/payments/captures/7TK53561YB803214S/refund", "rel": "refund", "method": "POST" }, { "href": "https://api.msmaster.qa.paypal.com/v2/payments/authorizations/6DR965477U7140544", "rel": "up", "method": "GET" } ] } }, "authorizations_capture_with_prefer_header": { "summary": "Capture Authorized Payment with Prefer Request Header", "description": "Captures an authorized payment, by ID. Includes the `Prefer` request header.", "value": { "id": "2GG279541U471931P", "status": "COMPLETED", "status_details": { }, "amount": { "value": "10.99", "currency_code": "USD" }, "final_capture": true, "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "seller_receivable_breakdown": { "gross_amount": { "value": "10.99", "currency_code": "USD" }, "paypal_fee": { "value": "0.33", "currency_code": "USD" }, "net_amount": { "value": "10.66", "currency_code": "USD" } }, "invoice_id": "INV-123", "create_time": "2017-09-11T23:24:01Z", "update_time": "2017-09-11T23:24:01Z", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P" }, { "rel": "refund", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P/refund" }, { "rel": "up", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046" } ] } } } } } }, "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" }, "examples": { "authorizations_capture_400_validation_error": { "summary": "Capture Authorized Payment - 400 Bad Request - Validation Error", "description": "This code sample attempts to capture an authorized payment but the request fails because a validation error occurred.", "value": { "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "90bff07028f7f", "details": [ { "field": "/invoice_id", "value": "ABCDEFGHIJKLMNOPQRSTUVXYZABCDEFGHIJKLMNOPQRSTUVXYZABCDEFGHIJKLMNOPQRSTUVXYZABCDEFGHIJKLMNOPQRSTUVXYZ_this_invoice_is_too_long", "issue": "INVALID_STRING_MAX_LENGTH", "description": "The value of a field is too long." } ] } } } } } }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "404": { "$ref": "#/components/responses/404_error_response" }, "409": { "description": "The server has detected a conflict while processing this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "authorizations_capture_409_conflict": { "summary": "Capture Authorized Payment - 409 Conflict - Operation in Progress Error", "description": "This code sample attempts to capture an authorized payment but the request fails because a previous call for the given resource is in progress.", "value": { "name": "RESOURCE_CONFLICT", "debug_id": "b1d1f06c7246c", "message": "The server has detected a conflict while processing this request.", "details": [ { "issue": "PREVIOUS_REQUEST_IN_PROGRESS", "description": "A previous request on this resource is currently in progress. Please wait for some time and try again. It is best to space out the initial and the subsequent request(s) to avoid receiving this error." } ] } } } } } }, "422": { "description": "The request failed because it is semantically incorrect or failed business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "authorizations_capture_422_amount_limit_exceeded": { "summary": "Capture Authorized Payment - 422 Unprocessable Entity - Requested Amount Exceeds Limit Error", "description": "This code sample attempts to capture an authorized payment but the request fails because the requested amount exceeds the allowable limit.", "value": { "name": "UNPROCCESSABLE_ENTITY", "message": "The requested action could not be completed, is semantically incorrect, or failed business validation.", "debug_id": "90bff07028f7f", "details": [ { "field": "/amount/value", "value": "10.99", "issue": "MAX_CAPTURE_AMOUNT_EXCEEDED", "description": "Capture amount specified exceeded allowable limit. You can only capture up to the original authorization amount.", "location": "body" } ] } }, "authorizations_capture_422_expired": { "summary": "Capture Authorized Payment - 422 Unprocessable Entity - Authorization Expired Error", "description": "This code sample attempts to capture an authorized payment but the request fails because the authorization expired.", "value": { "name": "UNPROCCESSABLE_ENTITY", "message": "The requested action could not be completed, is semantically incorrect, or failed business validation.", "debug_id": "90bff07028f7f", "details": [ { "issue": "AUTHORIZATION_EXPIRED", "description": "The authorization has expired." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } }, "callbacks": { "capture_completed": { "$ref": "#/components/callbacks/capture_completed" }, "capture_declined": { "$ref": "#/components/callbacks/capture_declined" }, "capture_pending_kyc_incomplete": { "$ref": "#/components/callbacks/capture_pending_kyc_incomplete" } } } }, "/v2/payments/authorizations/{authorization_id}/reauthorize": { "post": { "operationId": "authorizations.reauthorize", "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.

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.

A reauthorized payment itself has a new honor period of three days.

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.

Supports only the `amount` request parameter.", "tags": [ "authorizations" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "parameters": [ { "name": "authorization_id", "description": "The PayPal-generated ID for the authorized payment to reauthorize.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "examples": { "example": { "summary": "Reauthorize Authorized Payment", "description": "The PayPal-generated ID for the authorized payment to reauthorize.", "value": "0VF52814937998046" } } }, { "$ref": "#/components/parameters/paypal_request_id" }, { "name": "Prefer", "description": "The preferred server response upon successful completion of the request. Value is:", "in": "header", "required": false, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "default": "return=minimal" }, "examples": { "authorizations_reauthorize_with_prefer_header": { "summary": "Reauthorize Authorized Payment with Prefer Request Header", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired. Includes the `Prefer` request header.", "value": "return=representation" } } }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/paypal_auth_assertion" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reauthorize_request" }, "examples": { "authorizations_reauthorize": { "summary": "Reauthorize Authorized Payment", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.", "value": { "amount": { "value": "10.99", "currency_code": "USD" } } }, "authorizations_reauthorize_200_idempotent_response": { "summary": "Reauthorize Authorized Payment - 200 idempotent response", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.", "value": { "amount": { "value": "10.99", "currency_code": "USD" } } }, "authorizations_reauthorize_empty_request": { "summary": "Reauthorize Authorized Payment with an empty request", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.", "value": { } }, "authorizations_reauthorize_with_prefer_header": { "summary": "Reauthorize Authorized Payment with Prefer Request Header", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired. Includes the `Prefer` request header.", "value": { "amount": { "value": "10.99", "currency_code": "USD" } } } } } } }, "x-exampleFlows": [ { "title": "Reauthorize payment after honor period", "description": "Reauthorizes an authorized payment by ID after the 3-day honor period has expired but within the 29-day authorization period.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example" ], "request_example": "requestBody/content/application~1json/examples/authorizations_reauthorize", "response_example": "responses/201/content/application~1json/examples/authorizations_reauthorize" }, { "title": "Reauthorize with empty request body", "description": "Reauthorizes an authorized payment by ID with an empty request body to reauthorize the full amount.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example" ], "request_example": "requestBody/content/application~1json/examples/authorizations_reauthorize_empty_request", "response_example": "responses/201/content/application~1json/examples/authorizations_reauthorize_empty_request" }, { "title": "Reauthorize with Prefer header for full representation", "description": "Reauthorizes an authorized payment by ID with the Prefer header set to return=representation to get complete reauthorization details in the response.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example", "parameters/@name=='Prefer'/examples/authorizations_reauthorize_with_prefer_header" ], "request_example": "requestBody/content/application~1json/examples/authorizations_reauthorize_with_prefer_header", "response_example": "responses/201/content/application~1json/examples/authorizations_reauthorize_with_prefer_header" }, { "title": "Idempotent reauthorization request (200 response)", "description": "Demonstrates an idempotent reauthorization request where the same PayPal-Request-Id is used, resulting in a 200 OK response with existing authorization details.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/example" ], "request_example": "requestBody/content/application~1json/examples/authorizations_reauthorize_200_idempotent_response", "response_example": "responses/200/content/application~1json/examples/authorizations_reauthorize_200_idempotent_response" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK status code and a JSON response body that shows the reauthorized payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization-2" }, "examples": { "authorizations_reauthorize_200_idempotent_response": { "summary": "Reauthorize Authorized Payment - 200 idempotent response", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.", "value": { "id": "8AA831015G517922L", "status": "CREATED", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L" }, { "rel": "capture", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/capture" }, { "rel": "void", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/void" }, { "rel": "reauthorize", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/reauthorize" } ] } } } } } }, "201": { "description": "A successful request returns the HTTP 201 Created status code and a JSON response body that shows the reauthorized payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization-2" }, "examples": { "authorizations_reauthorize": { "summary": "Reauthorize Authorized Payment", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.", "value": { "id": "8AA831015G517922L", "status": "CREATED", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L" }, { "rel": "capture", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/capture" }, { "rel": "void", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/void" }, { "rel": "reauthorize", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/reauthorize" } ] } }, "authorizations_reauthorize_empty_request": { "summary": "Reauthorize Authorized Payment with an empty request", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.", "value": { "id": "8AA831015G517922L", "status": "CREATED", "links": [ { "rel": "self", "method": "GET", "href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L" }, { "rel": "capture", "method": "POST", "href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L/capture" }, { "rel": "void", "method": "POST", "href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L/void" }, { "rel": "reauthorize", "method": "POST", "href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L/reauthorize" } ] } }, "authorizations_reauthorize_with_prefer_header": { "summary": "Reauthorize Authorized Payment with Prefer Request Header", "description": "Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired. Includes the `Prefer` request header.", "value": { "id": "8AA831015G517922L", "status": "CREATED", "amount": { "value": "10.99", "currency_code": "USD" }, "invoice_id": "INVOICE-123", "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "expiration_time": "2018-10-10T23:23:45Z", "create_time": "2018-09-11T23:23:45Z", "update_time": "2018-09-11T23:23:45Z", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L" }, { "rel": "capture", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/capture" }, { "rel": "void", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/void" }, { "rel": "reauthorize", "method": "POST", "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/reauthorize" } ] } } } } } }, "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" }, "examples": { "authorizations_reauthorize_400_validation_error": { "summary": "Reauthorize Authorized Payment - 400 Bad Request - Validation Error", "description": "This code sample attempts to reauthorize an authorized payment but the request fails due to a validation error.", "value": { "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "90bff07028f7f", "details": [ { "field": "/amount/value", "value": "123456789012345678901234567890123", "issue": "INVALID_STRING_MAX_LENGTH", "description": "the value of a field is too long.", "location": "body" } ] } } } } } }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "404": { "$ref": "#/components/responses/404_error_response" }, "422": { "description": "The request failed because it either is semantically incorrect or failed business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "authorizations_reauthorize_422_auth_currency_mismatch": { "summary": "Reauthorize Authorized Payment - 422 Unprocessable Entity - Reauthorization Currency Mismatch", "description": "This code sample attempts to reauthorize an authorized payment but the request fails because reauthorization currency does not matches with the original authorization currency.", "value": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90bff07028f7f", "details": [ { "issue": "AUTH_CURRENCY_MISMATCH", "description": "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." } ], "links": [ { "href": "https://developer.paypal.com/docs/api/payments/v2/#error-AUTH_CURRENCY_MISMATCH", "rel": "information_link" } ] } }, "authorizations_reauthorize_422_inside_honor_period": { "summary": "Reauthorize Authorized Payment - 422 Unprocessable Entity - Authorization in Honor Period Error", "description": "This code sample attempts to reauthorize an authorized payment but the request fails because the authorization is still within the honor period.", "value": { "name": "UNPROCCESSABLE_ENTITY", "message": "The requested action could not be completed, is semantically incorrect, or failed business validation.", "debug_id": "90bff07028f7f", "details": [ { "issue": "REAUTHORIZATION_TOO_SOON", "description": "Re-authorization is not allowed within the three-day honor period." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } } } }, "/v2/payments/authorizations/{authorization_id}/void": { "post": { "operationId": "authorizations.void", "summary": "Void authorized payment", "description": "Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.", "tags": [ "authorizations" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "parameters": [ { "name": "authorization_id", "description": "The PayPal-generated ID for the authorized payment to void.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "examples": { "authorizations_void": { "summary": "Void Authorized Payment", "description": "Voids an authorized PayPal account payment, by ID. You cannot void an authorized payment that has been fully captured.", "value": "0VF52814937998046" }, "authorizations_void_200_idempotent_response": { "summary": "Void Authorized Payment", "description": "Voids an authorized PayPal account payment, by ID. You cannot void an authorized payment that has been fully captured.", "value": "5C908745JK343851U" } } }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/paypal_auth_assertion" }, { "$ref": "#/components/parameters/paypal_request_id" }, { "name": "Prefer", "description": "The preferred server response upon successful completion of the request. Value is:", "in": "header", "required": false, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "default": "return=minimal" } } ], "x-exampleFlows": [ { "title": "Void authorized payment", "description": "Voids or cancels an authorized payment by ID. Returns minimal response with status code 204 No Content.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/authorizations_void" ] }, { "title": "Void authorized payment with full representation (200 response)", "description": "Voids or cancels an authorized payment by ID. Returns full representation when Prefer header is set to return=representation, resulting in 200 OK status code.", "parameter_examples": [ "parameters/@name=='authorization_id'/examples/authorizations_void_200_idempotent_response" ], "response_example": "responses/200/content/application~1json/examples/authorizations_void_200_idempotent_response" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK 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" }, "examples": { "authorizations_void_200_idempotent_response": { "summary": "Void Authorized Payment", "description": "Voids an authorized PayPal account payment, by ID. You cannot void an authorized payment that has been fully captured.", "value": { "id": "5C908745JK343851U", "status": "VOIDED", "amount": { "currency_code": "USD", "value": "100.00" }, "invoice_id": "OrderInvoice-10_10_2024_12_06_00_pm", "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "expiration_time": "2024-11-08T09:06:03-08:00", "create_time": "2024-10-10T10:06:03-07:00", "update_time": "2024-10-10T10:06:19-07:00", "links": [ { "href": "https://api.paypal.com/v2/payments/authorizations/5C908745JK343851U", "rel": "self", "method": "GET" } ] } } } } } }, "204": { "$ref": "#/components/responses/204_response" }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "404": { "$ref": "#/components/responses/404_error_response" }, "409": { "description": "The request failed because a previous call for the given resource is in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "authorizations_void_409_conflict": { "summary": "Void Authorized Payment - 409 Conflict - Operation in Progress Error", "description": "This code sample attempts to void an authorized payment but the request fails because a previous call for the given resource is in progress.", "value": { "name": "RESOURCE_CONFLICT", "debug_id": "b1d1f06c7246c", "message": "The server has detected a conflict while processing this request.", "details": [ { "issue": "PREVIOUS_REQUEST_IN_PROGRESS", "description": "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": { "description": "The request failed because it either is semantically incorrect or failed business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "authorizations_void_422_already_captured": { "summary": "Void Authorized Payment - 422 Unprocessable Entity - Authorization Previously Captured Error", "description": "This code sample attempts to void an authorized payment but the request fails because has already been captured and cannot be voided.", "value": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "a7b0de7cb97ad", "details": [ { "issue": "PREVIOUSLY_CAPTURED", "description": "Authorization has been previously captured and cannot be voided." } ], "links": [ { "href": "https://developer.paypal.com/docs/api/payments/v2/#error-PREVIOUSLY_CAPTURED", "rel": "information_link" } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } }, "callbacks": { "authorization_voided": { "$ref": "#/components/callbacks/authorization_voided" }, "authorization_voided_expired": { "$ref": "#/components/callbacks/authorization_voided_expired" } } } }, "/v2/payments/captures/{capture_id}": { "get": { "operationId": "captures.get", "summary": "Show captured payment details", "description": "Shows details for a captured payment, by ID.", "tags": [ "captures" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "parameters": [ { "name": "capture_id", "description": "The PayPal-generated ID for the captured payment for which to show details.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "examples": { "capture_get_with_paypal_fee_receivable_currency": { "summary": "Show Captured Payment Details", "description": "Shows details for a captured payment, by ID.", "value": "74L756601X447022Y" } } }, { "$ref": "#/components/parameters/authorization" } ], "x-exampleFlows": [ { "title": "Show captured payment details with paypal fee in receivable currency", "description": "Retrieves complete details for a captured payment by ID with PayPal fee breakdown.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/capture_get_with_paypal_fee_receivable_currency" ], "response_example": "responses/200/content/application~1json/examples/capture_get_with_paypal_fee_receivable_currency" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK status code and a JSON response body that shows captured payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-2" }, "examples": { "capture_get_with_paypal_fee_receivable_currency": { "summary": "Show Captured Payment Details", "description": "Shows details for a captured payment, by ID.", "value": { "id": "74L756601X447022Y", "amount": { "currency_code": "USD", "value": "100.00" }, "final_capture": true, "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "seller_receivable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "100.00" }, "paypal_fee": { "currency_code": "USD", "value": "3.98" }, "net_amount": { "currency_code": "USD", "value": "96.02" } }, "invoice_id": "OrderInvoice-23_10_2024_12_27_32_pm", "status": "COMPLETED", "supplementary_data": { "related_ids": { "order_id": "25M43554V9523650M", "authorization_id": "0T620041CK889853A" } }, "payee": { "email_address": "merchant@example.com", "merchant_id": "YXZY75W2GKDQE" }, "create_time": "2024-10-23T20:55:19Z", "update_time": "2024-10-23T20:55:19Z", "links": [ { "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/74L756601X447022Y", "rel": "self", "method": "GET" }, { "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/74L756601X447022Y/refund", "rel": "refund", "method": "POST" }, { "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/0T620041CK889853A", "rel": "up", "method": "GET" } ] } } } } } }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "404": { "$ref": "#/components/responses/404_error_response" }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } } } }, "/v2/payments/captures/{capture_id}/refund": { "post": { "operationId": "captures.refund", "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 amount object in the JSON request body.", "tags": [ "captures" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/refund" ] } ], "parameters": [ { "name": "capture_id", "description": "The PayPal-generated ID for the captured payment to refund.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "examples": { "captures_refund_200_idempotent_response": { "summary": "Refund Captured Payment - 200 idempotent response", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": "2GG279541U471931P" }, "captures_refund_empty_request": { "summary": "Refund Captured Payment with an empty request", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": "7TK53561YB803214S" }, "captures_refund_with_prefer_header": { "summary": "Refund Captured Payment", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": "2GG279541U471931P" }, "captures_refund_with_buyer_context": { "summary": "Refund Captured Payment with Buyer Context (Personal Account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a personal account buyer.", "value": "4ER00663XR761103C" }, "captures_refund_with_buyer_context_business": { "summary": "Refund Captured Payment with Buyer Context (Business Account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer.", "value": "51Y24067WX474121X" }, "captures_refund_with_buyer_context_guest": { "summary": "Refund Captured Payment with Buyer Context (Guest Checkout)", "description": "Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context without a transaction details URL.", "value": "53457045VC219825A" } } }, { "$ref": "#/components/parameters/paypal_request_id" }, { "name": "Prefer", "description": "The preferred server response upon successful completion of the request. Value is:", "in": "header", "required": false, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "default": "return=minimal" }, "examples": { "captures_refund_200_idempotent_response": { "summary": "Refund Captured Payment - 200 idempotent response", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": "return=representation" }, "captures_refund_with_prefer_header": { "summary": "Refund Captured Payment", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": "return=representation" }, "captures_refund_empty_request": { "summary": "Refund Captured Payment with an empty request", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": "return=representation" }, "captures_refund_with_buyer_context": { "summary": "Refund Captured Payment with Buyer Context (Personal Account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a personal account buyer.", "value": "return=representation" }, "captures_refund_with_buyer_context_business": { "summary": "Refund Captured Payment with Buyer Context (Business Account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer.", "value": "return=representation" }, "captures_refund_with_buyer_context_guest": { "summary": "Refund Captured Payment with Buyer Context (Guest Checkout)", "description": "Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context without a transaction details URL.", "value": "return=representation" } } }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/paypal_auth_assertion" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund_request" }, "examples": { "captures_refund_200_idempotent_response": { "summary": "Refund Captured Payment - 200 idempotent response", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": { "amount": { "value": "1.00", "currency_code": "USD" }, "invoice_id": "RefundInvoice-123", "custom_id": "RefundCustom-123" } }, "captures_refund_empty_request": { "summary": "Refund Captured Payment with an empty request", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": { } }, "captures_refund_with_prefer_header": { "summary": "Refund Captured Payment", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": { "amount": { "value": "10.99", "currency_code": "USD" }, "invoice_id": "INVOICE-123", "note": "Defective product" } }, "captures_refund_with_buyer_context": { "summary": "Refund Captured Payment with Buyer Context (Personal Account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a personal account buyer.", "value": { "amount": { "value": "1.00", "currency_code": "USD" }, "invoice_id": "RefundInvoice-19_03_2026_6_41_17_pm", "custom_id": "RefundCustom-19_03_2026_6_41_17_pm" } }, "captures_refund_with_buyer_context_business": { "summary": "Refund Captured Payment with Buyer Context (Business Account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer.", "value": { "amount": { "value": "1.00", "currency_code": "USD" }, "invoice_id": "RefundInvoice-19_03_2026_6_42_08_pm", "custom_id": "RefundCustom-19_03_2026_6_42_08_pm" } }, "captures_refund_with_buyer_context_guest": { "summary": "Refund Captured Payment with Buyer Context (Guest Checkout)", "description": "Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context without a transaction details URL.", "value": { "amount": { "value": "1.00", "currency_code": "USD" }, "invoice_id": "RefundInvoice-19_03_2026_7_05_42_pm", "custom_id": "RefundCustom-19_03_2026_7_05_42_pm" } } } } } }, "x-exampleFlows": [ { "title": "Partial refund of a captured payment", "description": "Refunds a portion of a captured payment by ID. Includes an amount object in the request body specifying the partial refund amount.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/captures_refund" ], "request_example": "requestBody/content/application~1json/examples/captures_refund", "response_example": "responses/201/content/application~1json/examples/captures_refund" }, { "title": "Full refund with empty request body", "description": "Refunds the full amount of a captured payment by ID. Includes an empty payload in the request body.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/captures_refund_empty_request", "parameters/@name=='Prefer'/examples/captures_refund_empty_request" ], "request_example": "requestBody/content/application~1json/examples/captures_refund_empty_request", "response_example": "responses/201/content/application~1json/examples/captures_refund_empty_request" }, { "title": "Refund with Prefer header for full representation", "description": "Refunds a captured payment by ID with the Prefer header set to return=representation to get the complete refund details in the response.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/captures_refund_with_prefer_header", "parameters/@name=='Prefer'/examples/captures_refund_with_prefer_header" ], "request_example": "requestBody/content/application~1json/examples/captures_refund_with_prefer_header", "response_example": "responses/201/content/application~1json/examples/captures_refund_with_prefer_header" }, { "title": "Refund with buyer context (personal account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details such as transaction ID, status, and a link to the buyer's transaction details page.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/captures_refund_with_buyer_context", "parameters/@name=='Prefer'/examples/captures_refund_with_buyer_context" ], "request_example": "requestBody/content/application~1json/examples/captures_refund_with_buyer_context", "response_example": "responses/201/content/application~1json/examples/captures_refund_with_buyer_context" }, { "title": "Refund with buyer context (business account)", "description": "Refunds a captured payment by ID where the buyer is a business account. The response includes buyer context with the transaction details URL pointing to the unified transactions page.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/captures_refund_with_buyer_context_business", "parameters/@name=='Prefer'/examples/captures_refund_with_buyer_context_business" ], "request_example": "requestBody/content/application~1json/examples/captures_refund_with_buyer_context_business", "response_example": "responses/201/content/application~1json/examples/captures_refund_with_buyer_context_business" }, { "title": "Refund with buyer context (guest checkout)", "description": "Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context with transaction details but no transaction details URL.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/captures_refund_with_buyer_context_guest", "parameters/@name=='Prefer'/examples/captures_refund_with_buyer_context_guest" ], "request_example": "requestBody/content/application~1json/examples/captures_refund_with_buyer_context_guest", "response_example": "responses/201/content/application~1json/examples/captures_refund_with_buyer_context_guest" }, { "title": "Idempotent refund request (200 response)", "description": "Demonstrates an idempotent refund request where the same PayPal-Request-Id is used, resulting in a 200 OK response with the existing refund details.", "parameter_examples": [ "parameters/@name=='capture_id'/examples/captures_refund_200_idempotent_response", "parameters/@name=='Prefer'/examples/captures_refund_200_idempotent_response" ], "request_example": "requestBody/content/application~1json/examples/captures_refund_200_idempotent_response", "response_example": "responses/200/content/application~1json/examples/captures_refund_200_idempotent_response" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund" }, "examples": { "captures_refund_200_idempotent_response": { "summary": "Refund Captured Payment - 200 idempotent response", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": { "id": "0K35355239430361V", "amount": { "currency_code": "USD", "value": "1.00" }, "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "1.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "11.00" } }, "invoice_id": "RefundInvoice-14_10_2024_4_58_32_pm", "custom_id": "RefundCustom-14_10_2024_4_58_32_pm", "status": "COMPLETED", "create_time": "2024-10-14T14:58:34-07:00", "update_time": "2024-10-14T14:58:34-07:00", "links": [ { "href": "https://api.paypal.com/v2/payments/refunds/0K35355239430361V", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/captures/7TK53561YB803214S", "rel": "up", "method": "GET" } ] } } } } } }, "201": { "description": "A successful request returns the HTTP 201 Created status code and a JSON response body that shows refund details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund" }, "examples": { "captures_refund_empty_request": { "summary": "Refund Captured Payment with an empty request", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": { "id": "58K15806CS993444T", "amount": { "currency_code": "USD", "value": "89.00" }, "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "89.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "89.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "100.00" } }, "invoice_id": "OrderInvoice-10_10_2024_12_58_20_pm", "status": "COMPLETED", "create_time": "2024-10-14T15:03:29-07:00", "update_time": "2024-10-14T15:03:29-07:00", "links": [ { "href": "https://api.msmaster.qa.paypal.com/v2/payments/refunds/58K15806CS993444T", "rel": "self", "method": "GET" }, { "href": "https://api.msmaster.qa.paypal.com/v2/payments/captures/7TK53561YB803214S", "rel": "up", "method": "GET" } ] } }, "captures_refund_with_prefer_header": { "summary": "Refund Captured Payment", "description": "Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an `amount` object.", "value": { "id": "1JU08902781691411", "amount": { "value": "10.99", "currency_code": "USD" }, "status": "COMPLETED", "note": "Defective product", "seller_payable_breakdown": { "gross_amount": { "value": "10.99", "currency_code": "USD" }, "paypal_fee": { "value": "0", "currency_code": "USD" }, "net_amount": { "value": "10.99", "currency_code": "USD" }, "total_refunded_amount": { "value": "10.99", "currency_code": "USD" } }, "invoice_id": "INVOICE-123", "create_time": "2018-09-11T23:24:19Z", "update_time": "2018-09-11T23:24:19Z", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411" }, { "rel": "up", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P" } ] } }, "captures_refund_with_buyer_context": { "summary": "Refund Captured Payment with Buyer Context", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details such as the buyer's transaction ID, status, and a link to the transaction details page.", "value": { "id": "8R659521N3692922R", "amount": { "currency_code": "USD", "value": "1.00" }, "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "1.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "2.00" } }, "invoice_id": "RefundInvoice-19_03_2026_6_41_17_pm", "custom_id": "RefundCustom-19_03_2026_6_41_17_pm", "status": "COMPLETED", "create_time": "2026-03-19T18:41:26+05:30", "update_time": "2026-03-19T18:41:26+05:30", "buyer_context": { "transaction_id": "6T1484390E680692N", "transaction_details_url": "https://www.paypal.com/myaccount/activities/details/6T1484390E680692N", "transaction_create_time": "2026-03-17T19:56:45+05:30", "transaction_update_time": "2026-03-17T19:56:45+05:30" }, "links": [ { "href": "https://api.paypal.com/v2/payments/refunds/8R659521N3692922R", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/captures/4ER00663XR761103C", "rel": "up", "method": "GET" } ] } }, "captures_refund_with_buyer_context_business": { "summary": "Refund Captured Payment with Buyer Context (Business Account)", "description": "Refunds a captured payment by ID. The response includes buyer context with the buyer-side transaction details for a business account buyer, with the transaction details URL pointing to the unified transactions page.", "value": { "id": "8VL67176625581325", "amount": { "currency_code": "USD", "value": "1.00" }, "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "1.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "2.00" } }, "invoice_id": "RefundInvoice-19_03_2026_6_42_08_pm", "custom_id": "RefundCustom-19_03_2026_6_42_08_pm", "status": "COMPLETED", "create_time": "2026-03-19T18:42:18+05:30", "update_time": "2026-03-19T18:42:18+05:30", "buyer_context": { "transaction_id": "55E00454BG761444L", "transaction_details_url": "https://www.paypal.com/unifiedtransactions/details/payment/55E00454BG761444L", "transaction_create_time": "2026-03-17T20:10:16+05:30", "transaction_update_time": "2026-03-17T20:10:16+05:30" }, "links": [ { "href": "https://api.paypal.com/v2/payments/refunds/8VL67176625581325", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/captures/51Y24067WX474121X", "rel": "up", "method": "GET" } ] } }, "captures_refund_with_buyer_context_guest": { "summary": "Refund Captured Payment with Buyer Context (Guest Checkout)", "description": "Refunds a captured payment by ID where the buyer checked out as a guest without a PayPal account. The response includes buyer context with the buyer-side transaction details but no transaction details URL.", "value": { "id": "0EN87552KK190061W", "amount": { "currency_code": "USD", "value": "1.00" }, "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "1.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "3.00" } }, "invoice_id": "RefundInvoice-19_03_2026_7_05_42_pm", "custom_id": "RefundCustom-19_03_2026_7_05_42_pm", "status": "COMPLETED", "create_time": "2026-03-19T19:05:51+05:30", "update_time": "2026-03-19T19:05:51+05:30", "buyer_context": { "transaction_id": "0BF77575VK4138745", "transaction_create_time": "2026-03-17T20:25:45+05:30", "transaction_update_time": "2026-03-17T20:25:45+05:30" }, "links": [ { "href": "https://api.paypal.com/v2/payments/refunds/0EN87552KK190061W", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/captures/53457045VC219825A", "rel": "up", "method": "GET" } ] } } } } } }, "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" }, "examples": { "capture_refund_400_invalid_request": { "summary": "Refund Captured Payment - 400 Bad Request - Validation Error", "description": "This code sample attempts to refund a captured payment, but the request fails because a validation error occurred.", "value": { "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema", "debug_id": "78916e688cf7f", "details": [ { "issue": "INVALID_STRING_LENGTH", "field": "/invoice_id", "value": "Fm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinqFm67fYiinq", "description": "The value of a field is either too short or too long.", "location": "body" } ], "links": [ { "href": "https://developer.paypal.com/docs/api/payments/v2/#error-INVALID_STRING_LENGTH", "rel": "information_link" } ] } } } } } }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "404": { "$ref": "#/components/responses/404_error_response" }, "409": { "description": "The request failed because a previous call for the given resource is in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "captures_refund_409_conflict": { "summary": "Refund Captured Payment - 409 Conflict - Operation in Progress Error", "description": "This code sample attempts to refund a captured payment but the request fails because a previous call for the given resource is in progress.", "value": { "name": "RESOURCE_CONFLICT", "debug_id": "b1d1f06c7246c", "message": "The server has detected a conflict while processing this request.", "details": [ { "issue": "PREVIOUS_REQUEST_IN_PROGRESS", "description": "A previous request on this resource is currently in progress. Please wait for some time and try again. It is best to space out the initial and the subsequent request(s) to avoid receiving this error." } ] } } } } } }, "422": { "description": "The request failed because it either is semantically incorrect or failed business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "captures_refund_422_amount_exceeded": { "summary": "Refund Captured Payment - 422 Unprocessable Entity - Refund Amount Exceeded Error", "description": "This code sample attempts to refund a captured payment, but the request fails because the refund amount has exceeded the capture amount.", "value": { "name": "UNPROCCESSABLE_ENTITY", "message": "The requested action could not be completed, is semantically incorrect, or failed business validation.", "debug_id": "90bff07028f7f", "details": [ { "issue": "REFUND_AMOUNT_EXCEEDED", "description": "The refund amount must be less than or equal to the capture amount that has not yet been refunded." } ] } }, "captures_refund_422_transaction_disputed": { "summary": "Refund Captured Payment - 422 Unprocessable Entity - Capture Disputed Partial Refund Error", "description": "This code sample attempts to partially refund a captured payment, but the request fails because the captured payment is currently under dispute.", "value": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90bff07028f7f", "details": [ { "issue": "TRANSACTION_DISPUTED", "description": "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." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } }, "callbacks": { "capture_refunded": { "$ref": "#/components/callbacks/capture_refunded" } } } }, "/v2/payments/find-eligible-methods": { "post": { "operationId": "find.eligible.methods", "summary": "Find a list of eligible payment methods.", "description": "Get a list of eligible payment methods based on the input parameters provided.", "tags": [ "find-eligible-methods" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/payments-ready", "Braintree:PaymentsReady", "https://uri.paypal.com/services/payments/client-payments-eligibility" ] } ], "parameters": [ { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/paypal_auth_assertion" }, { "$ref": "#/components/parameters/user_agent" }, { "$ref": "#/components/parameters/paypal_client_metadata_id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/find_eligible_methods_request" }, "examples": { "find_eligible_payment_methods_exclude_payment_sources": { "summary": "Eligible Payment Methods - Exclude listed payment methods", "description": "Eligible Payment Methods - Exclude listed payment methods", "value": { "customer": { "country_code": "US", "channel": { "browser_type": "SAFARI", "device_type": "MOBILE", "client_os": "IOS" } }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "100.00" } } ], "preferences": { "payment_source_constraint": { "constraint_type": "EXCLUDE", "payment_sources": [ "PAYPAL" ] } } } }, "find_eligible_payment_methods_for_partner_with_multiple_seller_purchase": { "summary": "Eligible Payment Methods for a customer who is purchasing from multiple sellers", "description": "Eligible Payment Methods for a customer who is purchasing from multiple sellers.", "value": { "customer": { "country_code": "US", "channel": { "browser_type": "SAFARI", "device_type": "MOBILE", "client_os": "IOS" } }, "purchase_units": [ { "payee": { "merchant_id": "NGHNXQ95SRMUY" }, "amount": { "currency_code": "USD", "value": "200.00" } }, { "payee": { "merchant_id": "2DDJ3PFG2VFFA" }, "amount": { "currency_code": "USD", "value": "300.00" } } ] } }, "find_eligible_payment_methods_merchant_sharing_user_agent_instead_of_channel": { "summary": "Eligible Payment Methods with User-Agent header", "description": "Eligible Payment Methods for merchant sharing User-Agent instead of channel.", "value": { "customer": { "country_code": "US" }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "100.00" } } ] } }, "find_eligible_payment_methods_not_requiring_payment_tokens": { "summary": "Eligible Payment Methods without payment token information", "description": "Eligible Payment Methods without payment token information.", "value": { "customer": { "country_code": "US", "channel": { "browser_type": "Safari", "device_type": "Mobile", "client_os": "iOs 16,3" } }, "purchase_units": [ { "payee": { "merchant_id": "NGHNXQ95SRMUY" }, "amount": { "currency_code": "USD", "value": "200.00" } } ] } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_only_honey_account_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "customer": { "country_code": "US", "email": "customer12345@gmail.com", "phone": { "country_code": "1", "national_number": "1234567890" } }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "200.00" } } ], "preferences": { "include_account_details": true, "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "PAYPAL", "VENMO" ] } } } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_phone_only_paypal_account_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "customer": { "country_code": "US", "email": "customer12345@gmail.com", "phone": { "country_code": "1", "national_number": "1234567890" } }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "200.00" } } ], "preferences": { "include_account_details": true, "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "PAYPAL", "VENMO" ] } } } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_phone_only_venmo_account_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "customer": { "country_code": "US", "email": "customer12345@gmail.com", "phone": { "country_code": "1", "national_number": "1234567890" } }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "200.00" } } ], "preferences": { "include_account_details": true, "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "PAYPAL", "VENMO" ] } } } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_phone_paypal_venmo_accounts_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "customer": { "country_code": "US", "email": "customer12345@gmail.com", "phone": { "country_code": "1", "national_number": "1234567890" } }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "200.00" } } ], "preferences": { "include_account_details": true, "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "PAYPAL", "VENMO" ] } } } }, "find_eligible_payment_methods_with_payment_tokens": { "summary": "Eligible Payment Methods - with payment tokens", "description": "Eligible Payment Methods for merchant with payment token information.", "value": { "customer": { "country_code": "US", "channel": { "browser_type": "Safari", "device_type": "Mobile", "client_os": "iOs 16,3" } }, "purchase_units": [ { "payee": { "merchant_id": "NGHNXQ95SRMUY" }, "amount": { "currency_code": "USD", "value": "200.00" } } ], "preferences": { "include_vault_tokens": true, "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "PAYPAL", "VENMO" ] } } } }, "find_eligible_payment_methods_cards_ios": { "summary": "Cards Payment Method", "description": "Find eligibility - Cards payment method for iOS device.", "value": { "customer": { "country_code": "US", "channel": { "device": "IOS", "browser": "CHROME" } }, "purchase_units": [ { "payee": { "merchant_id": "PLKLQWQKCUCMW" }, "amount": { "currency_code": "USD", "value": "100.00" } } ], "preferences": { "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "ADVANCED_CARDS" ] } } } }, "find_eligible_payment_methods_apple_pay": { "summary": "Apple Pay Payment Method", "description": "Find eligibility - Apple Pay payment method.", "value": { "customer": { "country_code": "US", "channel": { "device": "IOS", "browser": "CHROME" } }, "purchase_units": [ { "payee": { "merchant_id": "PLKLQWQKCUCMW" }, "amount": { "currency_code": "USD", "value": "100.00" } } ], "preferences": { "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "APPLE_PAY" ] } } } }, "find_eligible_payment_methods_400_with_invalid_schema": { "summary": "Eligible Payment Methods - 400 Invalid Request", "description": "This request attempts to get payment methods but the request fails as it has invalid length (3 instead of 2) for customer's country_code.", "value": { "customer": { "country_code": "USA" }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "100.00" } } ] } }, "find_eligible_payment_methods_422_invalid_currency_code": { "summary": "Eligible Payment Methods - 422 Unprocessable Entity", "description": "This request attempts to get payment methods but the request fails because the currency code passed doesn't exist.", "value": { "customer": { "country_code": "US" }, "purchase_units": [ { "amount": { "currency_code": "III", "value": "100.00" } } ] } }, "find_eligible_payment_methods_basic_cards_ios": { "summary": "Basic Cards Payment Method", "description": "Find eligibility - Basic Cards payment method for iOS device.", "value": { "customer": { "country_code": "US", "channel": { "device": "IOS", "browser": "CHROME" } }, "purchase_units": [ { "payee": { "merchant_id": "CT8MBLTVPBRKN" }, "amount": { "currency_code": "USD", "value": "100.00" } } ], "preferences": { "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "BASIC_CARDS" ] } } } }, "find_eligible_payment_methods_google_pay": { "summary": "Google Pay Payment Method", "description": "Find eligibility - Google Pay payment method.", "value": { "customer": { "country_code": "US", "channel": { "device": "IOS", "browser": "CHROME" } }, "purchase_units": [ { "payee": { "merchant_id": "PLKLQWQKCUCMW" }, "amount": { "currency_code": "USD", "value": "100.00" } } ], "preferences": { "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "GOOGLE_PAY" ] } } } }, "find_eligible_payment_methods_with_ach": { "summary": "Find Eligible Payment Methods with ACH", "description": "Eligible payment methods with ACH funding instrument for US customers.", "value": { "customer": { "country_code": "US", "email": "customer12345@gmail.com", "phone": { "country_code": "1", "national_number": "1234567890" } }, "purchase_units": [ { "amount": { "currency_code": "USD", "value": "200.00" } } ], "preferences": { "include_account_details": true, "payment_source_constraint": { "constraint_type": "INCLUDE", "payment_sources": [ "ACH" ] } } } } } } } }, "x-exampleFlows": [ { "title": "Find eligible payment methods excluding specific sources", "description": "Get eligible payment methods for a customer while excluding specific payment sources like PayPal. Useful for controlling which payment options are presented.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_exclude_payment_sources", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_exclude_payment_sources" }, { "title": "Find eligible payment methods for multiple seller purchase", "description": "Get eligible payment methods for a customer purchasing from multiple sellers. Returns payment methods that work for all payees in the transaction.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_for_partner_with_multiple_seller_purchase", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_for_partner_with_multiple_seller_purchase" }, { "title": "Find eligible payment methods with User-Agent header", "description": "Get eligible payment methods when merchant shares User-Agent header instead of channel information. The API derives device context from User-Agent.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_merchant_sharing_user_agent_instead_of_channel", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_merchant_sharing_user_agent_instead_of_channel" }, { "title": "Find eligible payment methods without payment tokens", "description": "Get eligible payment methods without requesting vaulted payment tokens. Returns basic eligibility information for PayPal, Venmo, and Pay Later options.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_not_requiring_payment_tokens", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_not_requiring_payment_tokens" }, { "title": "Customer recognition using email and phone", "description": "Get eligible payment methods along with PayPal and Venmo account confirmation by providing customer email and phone number. Includes account recognition and recommendations.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_with_account_details_searchedBy_email_phone_paypal_venmo_accounts_found", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_with_account_details_searchedBy_email_phone_paypal_venmo_accounts_found" }, { "title": "Find eligible payment methods with vaulted payment tokens", "description": "Get eligible payment methods including vaulted payment tokens for the customer. Returns saved PayPal and Venmo payment instruments.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_with_payment_tokens", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_with_payment_tokens" }, { "title": "Find eligible payment methods - Cards for iOS", "description": "Get eligible card payment methods for a customer on an iOS device. Returns supported card networks with eligibility and vaulting information.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_cards_ios", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_cards_ios" }, { "title": "Find eligible payment methods - Apple Pay", "description": "Get eligible Apple Pay payment method for a customer. Returns supported networks, merchant capabilities, and token notification URL.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_apple_pay", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_apple_pay" }, { "title": "Find eligible payment methods - 400 Invalid Request", "description": "Demonstrates a 400 error when the customer country_code has an invalid length of 3 characters instead of the required 2.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_400_with_invalid_schema", "response_example": "responses/400/content/application~1json/examples/find_eligible_payment_methods_400_with_invalid_schema" }, { "title": "Find eligible payment methods - 422 Invalid Currency Code", "description": "Demonstrates a 422 error when the currency code provided in purchase_units does not correspond to a valid currency.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_422_invalid_currency_code", "response_example": "responses/422/content/application~1json/examples/find_eligible_payment_methods_422_invalid_currency_code" }, { "title": "Find eligible payment methods - Basic Cards for iOS", "description": "Get eligible basic card payment methods for a customer on an iOS device.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_basic_cards_ios", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_basic_cards_ios" }, { "title": "Find eligible payment methods - Google Pay", "description": "Get eligible Google Pay payment method for a customer. Returns supported networks, merchant info, and tokenization specification.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_google_pay", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_google_pay" }, { "title": "Find eligible payment methods with ACH", "description": "Get eligible payment methods including ACH for US customers with account details recognition.", "request_example": "requestBody/content/application~1json/examples/find_eligible_payment_methods_with_ach", "response_example": "responses/200/content/application~1json/examples/find_eligible_payment_methods_with_ach" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK status code and a JSON response body that provides list of eligibile payments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/find_eligible_methods_response" }, "examples": { "find_eligible_payment_methods_exclude_payment_sources": { "summary": "Eligible Payment Methods - Exclude listed payment methods", "description": "Eligible Payment Methods - Exclude listed payment methods", "value": { "eligible_methods": { "venmo": { "can_be_vaulted": true } } } }, "find_eligible_payment_methods_for_partner_with_multiple_seller_purchase": { "summary": "Eligible Payment Methods for a customer who is purchasing from multiple sellers", "description": "Eligible Payment Methods for a customer who is purchasing from multiple sellers.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true } } } }, "find_eligible_payment_methods_merchant_sharing_user_agent_instead_of_channel": { "summary": "Eligible Payment Methods with User-Agent header", "description": "Eligible Payment Methods for merchant sharing User-Agent instead of channel.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true }, "venmo": { "can_be_vaulted": true } } } }, "find_eligible_payment_methods_not_requiring_payment_tokens": { "summary": "Eligible Payment Methods without payment token information", "description": "Eligible Payment Methods without payment token information.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true }, "venmo": { "can_be_vaulted": true }, "paypal_pay_later": { "can_be_vaulted": false } } } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_only_honey_account_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": false }, "venmo": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": false } } } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_phone_only_paypal_account_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": true, "recommended_priority": 1 }, "venmo": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": false } } } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_phone_only_venmo_account_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": false }, "venmo": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": true, "recommended_priority": 1 } } } }, "find_eligible_payment_methods_with_account_details_searchedBy_email_phone_paypal_venmo_accounts_found": { "summary": "Customer recognition using customer email and phone number", "description": "Eligible payment methods along with PayPal and Venmo account confirmation for merchants sharing customer email and phone number.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": true, "recommended_priority": 1 }, "venmo": { "can_be_vaulted": true, "eligible_in_paypal_network": true, "recommended": false } } } }, "find_eligible_payment_methods_with_payment_tokens": { "summary": "Eligible Payment Methods - with payment tokens", "description": "Eligible Payment Methods for merchant with payment token information.", "value": { "eligible_methods": { "paypal": { "can_be_vaulted": true }, "venmo": { "can_be_vaulted": true } } } }, "find_eligible_payment_methods_cards_ios": { "summary": "Cards Payment Method", "description": "Find eligibility - Cards payment method for iOS device.", "value": { "eligible_methods": { "advanced_cards": { "supports_installments": false, "vendors": [ { "eligible": true, "can_be_vaulted": true, "branded": false }, { "eligible": true, "can_be_vaulted": true, "branded": false }, { "eligible": true, "can_be_vaulted": true, "branded": false }, { "eligible": true, "can_be_vaulted": true, "branded": false }, { "eligible": true, "can_be_vaulted": true, "branded": false }, { "eligible": true, "can_be_vaulted": true, "branded": false }, { "eligible": true, "can_be_vaulted": true, "branded": false }, { "eligible": true, "can_be_vaulted": true, "branded": false } ] } } } }, "find_eligible_payment_methods_apple_pay": { "summary": "Apple Pay Payment Method", "description": "Find eligibility - Apple Pay payment method.", "value": { "eligible_methods": { "apple_pay": { "can_be_vaulted": true, "config": { "eligible": true, "merchant_country": "US", "supported_networks": [ "MASTERCARD", "DISCOVER", "VISA", "AMEX" ], "merchant_capabilities": [ "SUPPORTS_CREDIT", "SUPPORTS_DEBIT", "SUPPORTS_3DS" ], "token_notification_url": "https://api.msmaster.qa.paypal.com/v1/payment-provider/applepay" } } } } }, "find_eligible_payment_methods_basic_cards_ios": { "summary": "Basic Cards Payment Method", "description": "Find eligibility - Basic Cards payment method for iOS device.", "value": { "eligible_methods": { "basic_cards": { "supports_installments": false, "supports_inline_presentation_mode": true, "guest_enabled": true } } } }, "find_eligible_payment_methods_google_pay": { "summary": "Google Pay Payment Method", "description": "Find eligibility - Google Pay payment method.", "value": { "eligible_methods": { "google_pay": { "can_be_vaulted": false, "config": { "eligible": true, "merchant_country": "US", "api_version": 2, "api_version_minor": 1, "supported_networks": [ { "type": "CARD", "parameters": { "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ], "supported_networks": [ "MASTERCARD", "DISCOVER", "VISA", "AMEX" ], "billing_address_required": true, "assurance_details_required": true, "billing_address_parameters": { "format": "FULL" } }, "tokenization_specification": { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "paypalqa", "gateway_merchant_id": "PLKLQWQKCUCMW" } } } ], "merchant_info": { "merchant_origin": "www.shopify.com", "merchant_id": "BCR2DN4TXSDMV", "googlepay_partner_domain_verification_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJtZXJjaGFudElkIjoiQkNSMkRONFRYU0RNVlRLTSIsIm1lcmNoYW50T3JpZ2luIjoid3d3LnNob3BpZnkuY29tIiwiaWF0IjoxNzUzMTc0MzgyfQ.YkieJt4vMDkgTzpGqkRD5qYhSN9OSu7VtFOHkEQeA_BkkYbyfqlEbpk9lT5IdrK-h7AAavDqjVhHHj6hg4r9gg" } } } } } }, "find_eligible_payment_methods_with_ach": { "summary": "Find Eligible Payment Methods with ACH", "description": "Eligible payment methods with ACH funding instrument for US customers.", "value": { "eligible_methods": { "ach": { "can_be_vaulted": true } } } } } } } }, "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" }, "examples": { "find_eligible_payment_methods_400_with_invalid_schema": { "summary": "Eligible Payment Methods - 400 Invalid Request.", "description": "This request attempts to get payment methods but the request fails as it has invalid length (3 instead of 2) for customer's country_code.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema", "details": [ { "field": "/customer/country_code", "value": "USA", "location": "body", "issue": "INVALID_STRING_LENGTH", "description": "The value of a field is either too short or too long." } ], "links": [ { "href": "https://developer.paypal.com/docs/api/payments/v2/#errors", "rel": "information_link", "method": "GET", "encType": "application/json" } ] } } } } } }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "422": { "description": "The request failed because it either is semantically incorrect or failed business validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "find_eligible_payment_methods_422_invalid_currency_code": { "summary": "Eligible Payment Methods - 422 Unprocessable Entity", "description": "This request attempts to get payment methods but the request fails because the currency code passed doesn't exist.", "value": { "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "90bff07028f7f", "details": [ { "field": "/purchase_units/amount/currency_code", "value": "III", "issue": "INVALID_CURRENCY_CODE", "description": "Currency code is invalid. Please refer https://developer.paypal.com/docs/integration/direct/rest/currency-codes/ for list of supported currency codes." } ], "links": [ { "href": "https://developer.paypal.com/docs/api/payments/v2/#errors", "rel": "information_link", "method": "GET" } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } } } }, "/v2/payments/refunds/{refund_id}": { "get": { "operationId": "refunds.get", "summary": "Show refund details", "description": "Shows details for a refund, by ID.", "tags": [ "refunds" ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/payments/refund" ] } ], "parameters": [ { "name": "refund_id", "description": "The PayPal-generated ID for the refund for which to show details.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "examples": { "refunds_get_platform_fees": { "summary": "Show Refund Details with Platform Fees", "description": "Shows details for a refund, by ID, with platform fees.", "value": "1JU08902781691411" }, "refunds_get_with_buyer_context": { "summary": "Show Refund Details with Buyer Context (Personal Account)", "description": "Shows details for a refund, by ID, including buyer context with the buyer-side transaction details for a personal account buyer.", "value": "8R659521N3692922R" }, "refunds_get_with_buyer_context_business": { "summary": "Show Refund Details with Buyer Context (Business Account)", "description": "Shows details for a refund, by ID, including buyer context with the buyer-side transaction details for a business account buyer.", "value": "8VL67176625581325" }, "refunds_get_with_buyer_context_guest": { "summary": "Show Refund Details with Buyer Context (Guest Checkout)", "description": "Shows details for a refund, by ID, including buyer context for a guest checkout without a transaction details URL.", "value": "0EN87552KK190061W" } } }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/paypal_auth_assertion" } ], "x-exampleFlows": [ { "title": "Show refund details with platform fees", "description": "Retrieves details for a refund by ID including platform fees information.", "parameter_examples": [ "parameters/@name=='refund_id'/examples/refunds_get_platform_fees" ], "response_example": "responses/200/content/application~1json/examples/refunds_get_platform_fees" }, { "title": "Show refund details with buyer context (personal account)", "description": "Retrieves refund details by ID including buyer context with the buyer-side transaction details for a personal account buyer.", "parameter_examples": [ "parameters/@name=='refund_id'/examples/refunds_get_with_buyer_context" ], "response_example": "responses/200/content/application~1json/examples/refunds_get_with_buyer_context" }, { "title": "Show refund details with buyer context (business account)", "description": "Retrieves refund details by ID including buyer context with the buyer-side transaction details for a business account buyer.", "parameter_examples": [ "parameters/@name=='refund_id'/examples/refunds_get_with_buyer_context_business" ], "response_example": "responses/200/content/application~1json/examples/refunds_get_with_buyer_context_business" }, { "title": "Show refund details with buyer context (guest checkout)", "description": "Retrieves refund details by ID including buyer context for a guest checkout without a transaction details URL.", "parameter_examples": [ "parameters/@name=='refund_id'/examples/refunds_get_with_buyer_context_guest" ], "response_example": "responses/200/content/application~1json/examples/refunds_get_with_buyer_context_guest" } ], "responses": { "200": { "description": "A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund" }, "examples": { "refunds_get_platform_fees": { "summary": "Show Refund Details with Platform Fees", "description": "Shows details for a refund, by ID, with platform fees.", "value": { "id": "1JU08902781691411", "amount": { "value": "10.99", "currency_code": "USD" }, "status": "COMPLETED", "note": "Defective product", "seller_payable_breakdown": { "gross_amount": { "value": "10.99", "currency_code": "USD" }, "paypal_fee": { "value": "0.33", "currency_code": "USD" }, "platform_fees": [ { "amount": { "currency_code": "USD", "value": "1.00" }, "payee": { "email_address": "fee@example.com" } } ], "net_amount": { "value": "9.66", "currency_code": "USD" }, "total_refunded_amount": { "value": "10.99", "currency_code": "USD" } }, "invoice_id": "INVOICE-123", "create_time": "2018-09-11T23:24:19Z", "update_time": "2018-09-11T23:24:19Z", "links": [ { "rel": "self", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411" }, { "rel": "up", "method": "GET", "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P" } ] } }, "refunds_get_with_buyer_context": { "summary": "Show Refund Details with Buyer Context (Personal Account)", "description": "Shows details for a refund, by ID, including buyer context with the buyer-side transaction details for a personal account buyer. The transaction details URL points to the buyer's activity page.", "value": { "id": "8R659521N3692922R", "amount": { "currency_code": "USD", "value": "1.00" }, "status": "COMPLETED", "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "1.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "2.00" } }, "invoice_id": "RefundInvoice-19_03_2026_6_41_17_pm", "custom_id": "RefundCustom-19_03_2026_6_41_17_pm", "create_time": "2026-03-19T18:41:26+05:30", "update_time": "2026-03-19T18:41:26+05:30", "buyer_context": { "transaction_id": "6T1484390E680692N", "transaction_details_url": "https://www.paypal.com/myaccount/activities/details/6T1484390E680692N", "transaction_create_time": "2026-03-17T19:56:45+05:30", "transaction_update_time": "2026-03-17T19:56:45+05:30" }, "links": [ { "href": "https://api.paypal.com/v2/payments/refunds/8R659521N3692922R", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/captures/4ER00663XR761103C", "rel": "up", "method": "GET" } ] } }, "refunds_get_with_buyer_context_business": { "summary": "Show Refund Details with Buyer Context (Business Account)", "description": "Shows details for a refund, by ID, including buyer context with the buyer-side transaction details for a business account buyer. The transaction details URL points to the unified transactions page.", "value": { "id": "8VL67176625581325", "amount": { "currency_code": "USD", "value": "1.00" }, "status": "COMPLETED", "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "1.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "2.00" } }, "invoice_id": "RefundInvoice-19_03_2026_6_42_08_pm", "custom_id": "RefundCustom-19_03_2026_6_42_08_pm", "create_time": "2026-03-19T18:42:18+05:30", "update_time": "2026-03-19T18:42:18+05:30", "buyer_context": { "transaction_id": "55E00454BG761444L", "transaction_details_url": "https://www.paypal.com/unifiedtransactions/details/payment/55E00454BG761444L", "transaction_create_time": "2026-03-17T20:10:16+05:30", "transaction_update_time": "2026-03-17T20:10:16+05:30" }, "links": [ { "href": "https://api.paypal.com/v2/payments/refunds/8VL67176625581325", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/captures/51Y24067WX474121X", "rel": "up", "method": "GET" } ] } }, "refunds_get_with_buyer_context_guest": { "summary": "Show Refund Details with Buyer Context (Guest Checkout)", "description": "Shows details for a refund, by ID, including buyer context for a guest checkout. No transaction details URL is included since the buyer does not have a PayPal account.", "value": { "id": "0EN87552KK190061W", "amount": { "currency_code": "USD", "value": "1.00" }, "status": "COMPLETED", "seller_payable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "1.00" }, "paypal_fee": { "currency_code": "USD", "value": "0.00" }, "net_amount": { "currency_code": "USD", "value": "1.00" }, "total_refunded_amount": { "currency_code": "USD", "value": "3.00" } }, "invoice_id": "RefundInvoice-19_03_2026_7_05_42_pm", "custom_id": "RefundCustom-19_03_2026_7_05_42_pm", "create_time": "2026-03-19T19:05:51+05:30", "update_time": "2026-03-19T19:05:51+05:30", "buyer_context": { "transaction_id": "0BF77575VK4138745", "transaction_create_time": "2026-03-17T20:25:45+05:30", "transaction_update_time": "2026-03-17T20:25:45+05:30" }, "links": [ { "href": "https://api.paypal.com/v2/payments/refunds/0EN87552KK190061W", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/captures/53457045VC219825A", "rel": "up", "method": "GET" } ] } } } } } }, "401": { "$ref": "#/components/responses/401_error_response" }, "403": { "$ref": "#/components/responses/403_error_response" }, "404": { "$ref": "#/components/responses/404_error_response" }, "500": { "$ref": "#/components/responses/500_error_response" }, "default": { "$ref": "#/components/responses/default_response" } } } } }, "components": { "securitySchemes": { "Oauth2": { "type": "oauth2", "description": "OAuth 2.0 authentication", "flows": { "clientCredentials": { "tokenUrl": "https://api-m.paypal.com/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", "https://uri.paypal.com/services/payments/payments-ready": "Permission to get information about payment readiness.", "Braintree:PaymentsReady": "Permission to call PaymentsReady via BrainTree SDK.", "https://uri.paypal.com/services/payments/client-payments-eligibility": "Permission to get information about merchant's eligible payment methods." } } } } }, "parameters": { "paypal_request_id": { "name": "PayPal-Request-Id", "in": "header", "description": "A unique ID identifying the request header for idempotency purposes.", "required": false, "schema": { "description": "A unique ID identifying the request header for idempotency purposes.", "type": "string", "minLength": 1, "maxLength": 10000, "pattern": "^.*$" }, "examples": { "request_id": { "summary": "A request id.", "description": "A paypal-request-id header with a randomized value.", "value": "17e81d06-77ab-11e8-adc0-fa71639ebebc" } } }, "authorization": { "name": "Authorization", "in": "header", "description": "Holds authorization information for external API calls.", "required": false, "schema": { "$ref": "#/components/schemas/standard_header_schema" }, "examples": { "bearer": { "summary": "Bearer authorization.", "description": "An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.", "value": "Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" } } }, "paypal_auth_assertion": { "name": "PayPal-Auth-Assertion", "in": "header", "description": "Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.", "required": false, "schema": { "description": "Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.", "type": "string", "minLength": 1, "maxLength": 10000, "pattern": "^.*$" }, "examples": { "auth_assertion": { "summary": "An auth assertion.", "description": "A paypal-auth-assertion header with a randomized value.", "value": "eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9" } } }, "user_agent": { "name": "User-Agent", "in": "header", "description": "A characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent. API calls made by PayPal SDKs SHOULD be identified using this request header.", "required": false, "schema": { "$ref": "#/components/schemas/standard_header_schema" }, "examples": { "safari_on_ipad": { "summary": "A user-agent for Safari on iPad.", "description": "A user-agent header for Safari on iPad.", "value": "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405" } } }, "paypal_client_metadata_id": { "name": "PayPal-Client-Metadata-Id", "in": "header", "description": "A GUID value originating from Fraudnet and Dyson passed from external API clients via HTTP header. The value is used by Risk decisions to correlate calls which, in turn, might result in lower decline rates..", "required": false, "schema": { "$ref": "#/components/schemas/guid" }, "examples": { "guid": { "summary": "A GUID.", "description": "A paypal-client-metadata-id header with a randomized value.", "value": "1295065d-6f34-42dc-ac65-fac0c86af250" } } } }, "schemas": { "standard_header_schema": { "title": "Schema Object for standard headers", "description": "Standard headers are generally less restrictive in structure due to historical precedent across browsers, etc. This is a common schema for use in defining most standard headers.", "type": "string", "minLength": 1, "maxLength": 16000, "pattern": "^.*$" }, "email_address": { "description": "The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
", "type": "string", "minLength": 3, "maxLength": 254, "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])?|\\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-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])+)\\])$" }, "card_brand": { "title": "card_brand", "description": "The card network or brand. Applies to credit, debit, gift, and payment cards.", "type": "string", "enum": [ "VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "CARTE_BANCAIRE", "STAR_ACCESS", "PULSE", "NYCE", "ACCEL", "UNKNOWN" ], "x-enumDescriptions": { "VISA": "Visa card.", "MASTERCARD": "Mastercard card.", "DISCOVER": "Discover card.", "AMEX": "American Express card.", "SOLO": "Solo debit card.", "JCB": "Japan Credit Bureau card.", "STAR": "Military Star card.", "DELTA": "Delta Airlines card.", "SWITCH": "Switch credit card.", "MAESTRO": "Maestro credit card.", "CB_NATIONALE": "Carte Bancaire (CB) credit card.", "CONFIGOGA": "Configoga credit card.", "CONFIDIS": "Confidis credit card.", "ELECTRON": "Visa Electron credit card.", "CETELEM": "Cetelem credit card.", "CHINA_UNION_PAY": "China union pay credit card.", "DINERS": "The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services.", "ELO": "The Brazilian Elo card payment network.", "HIPER": "The Hiper - Ingenico ePayment network.", "HIPERCARD": "The Brazilian Hipercard payment network that's widely accepted in the retail market.", "RUPAY": "The RuPay payment network.", "GE": "The GE Credit Union 3Point card payment network.", "SYNCHRONY": "The Synchrony Financial (SYF) payment network.", "EFTPOS": "The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network.", "CARTE_BANCAIRE": "The Carte Bancaire payment network.", "STAR_ACCESS": "The Star Access payment network.", "PULSE": "The Pulse payment network.", "NYCE": "The NYCE payment network.", "ACCEL": "The Accel payment network.", "UNKNOWN": "UNKNOWN payment network." } }, "email": { "title": "email", "description": "The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
", "type": "string", "minLength": 3, "maxLength": 254, "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])+)\\]).*$" }, "network_transaction": { "title": "network_transaction", "description": "Reference values used by the card network to identify a transaction.", "type": "object", "properties": { "id": { "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 -.", "type": "string", "minLength": 9, "maxLength": 36, "pattern": "^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$" }, "date": { "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\". For some specific networks, such as MasterCard and Discover, this date field is mandatory when the `previous_network_transaction_reference_id` is passed.", "type": "string", "minLength": 4, "maxLength": 4, "pattern": "^[0-9]+$" }, "network": { "allOf": [ { "$ref": "#/components/schemas/card_brand" }, { "description": "Name of the card network through which the transaction was routed." } ] }, "acquirer_reference_number": { "description": "Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.", "type": "string", "minLength": 1, "maxLength": 36, "pattern": "^[a-zA-Z0-9]+$" } } }, "currency_code": { "description": "The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.", "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[\\S\\s]*$" }, "money": { "title": "Money", "description": "The currency and amount for a financial transaction, such as a balance or payment due.", "type": "object", "required": [ "currency_code", "value" ], "properties": { "currency_code": { "$ref": "#/components/schemas/currency_code" }, "value": { "description": "The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/).", "type": "string", "minLength": 0, "maxLength": 32, "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" } } }, "date_time": { "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.
Note: The regular expression provides guidance but does not reject all invalid dates.
", "type": "string", "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})$" }, "country_code-2": { "description": "The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
", "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "phone-2": { "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).", "type": "object", "required": [ "country_code", "national_number" ], "properties": { "country_code": { "title": "country_calling_code", "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).", "type": "string", "minLength": 1, "maxLength": 3, "pattern": "^[0-9]{1,3}?$" }, "national_number": { "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).", "type": "string", "minLength": 1, "maxLength": 14, "pattern": "^[0-9]{1,14}?$" }, "extension_number": { "description": "The extension number.", "type": "string", "minLength": 1, "maxLength": 15, "pattern": "^[0-9]{1,15}?$" } } }, "discount_with_breakdown": { "title": "discount_with_breakdown", "description": "The discount amount and currency code. For list of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/money" }, { "type": "object" } ] }, "amount_breakdown": { "title": "amount_breakdown", "description": "The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.", "type": "object", "properties": { "item_total": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The subtotal for all items. Required if the request includes `purchase_units[].items[].unit_amount`. Must equal the sum of `(items[].unit_amount * items[].quantity)` for all items. item_total.value can not be a negative number." } ] }, "shipping": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The shipping fee for all items within a given `purchase_unit`. shipping.value can not be a negative number." } ] }, "handling": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The handling fee for all items within a given `purchase_unit`. handling.value can not be a negative number." } ] }, "tax_total": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The total tax for all items. Required if the request includes `purchase_units.items.tax`. Must equal the sum of `(items[].tax * items[].quantity)` for all items. tax_total.value can not be a negative number." } ] }, "insurance": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The insurance fee for all items within a given `purchase_unit`. insurance.value can not be a negative number." } ] }, "shipping_discount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The shipping discount for all items within a given `purchase_unit`. shipping_discount.value can not be a negative number." } ] }, "discount": { "allOf": [ { "$ref": "#/components/schemas/discount_with_breakdown" }, { "description": "The discount for all items within a given `purchase_unit`. discount.value can not be a negative number." } ] } } }, "amount_with_breakdown": { "title": "amount_with_breakdown", "description": "The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify `amount.breakdown`, the amount equals `item_total` plus `tax_total` plus `shipping` plus `handling` plus `insurance` minus `shipping_discount` minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/money" }, { "type": "object", "properties": { "breakdown": { "$ref": "#/components/schemas/amount_breakdown" } } } ] }, "account_id-2": { "title": "PayPal Account Identifier", "description": "The account identifier for a PayPal account.", "type": "string", "minLength": 13, "maxLength": 13, "pattern": "^[2-9A-HJ-NP-Z]{13}$" }, "payee_base": { "title": "payee_base", "description": "The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.", "type": "object", "properties": { "email_address": { "allOf": [ { "$ref": "#/components/schemas/email" }, { "description": "The email address of merchant." } ] }, "merchant_id": { "allOf": [ { "$ref": "#/components/schemas/account_id-2" }, { "description": "The encrypted PayPal account ID of the merchant." } ] } } }, "payee": { "title": "payee", "description": "The merchant who receives the funds and fulfills the order. The merchant is also known as the payee.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/payee_base" }, { "type": "object" } ] }, "link_schema": { "title": "Link Schema", "description": "The request data or link target.", "type": "object", "properties": { "additionalItems": { "title": "additional_items", "description": "Any additional items.", "type": "object" }, "dependencies": { "title": "Dependencies", "description": "The dependencies.", "type": "object" }, "items": { "title": "Items", "description": "An item.", "type": "object" }, "definitions": { "title": "Definitions", "description": "Definitions.", "type": "object" }, "patternProperties": { "title": "pattern_properties", "description": "The pattern properties.", "type": "object" }, "properties": { "title": "Properties", "description": "The properties.", "type": "object" }, "allOf": { "title": "all_of", "description": "An array of sub-schemas. The data must validate against all sub-schemas.", "type": "array", "minItems": 0, "maxItems": 32767, "items": { "title": "all_of_item", "description": "A sub-schema against which the data must validate.", "type": "object" } }, "anyOf": { "title": "any_of", "description": "An array of sub-schemas. The data must validate against one or more sub-schemas.", "type": "array", "minItems": 0, "maxItems": 32767, "items": { "title": "any_of_item", "description": "A sub-schema against which the data must validate.", "type": "object" } }, "oneOf": { "title": "one_of", "description": "An array of sub-schemas. The data must validate against one sub-schema.", "type": "array", "minItems": 0, "maxItems": 32767, "items": { "title": "one_of_item", "description": "A sub-schema against which the data must validate.", "type": "object" } }, "not": { "title": "Not", "description": "Not.", "type": "object" }, "links": { "description": "An array of links.", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "title": "link", "description": "A link.", "type": "object", "readOnly": true } }, "fragmentResolution": { "title": "fragment_resolution", "description": "The fragment resolution.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "media": { "title": "Media", "description": "The media type and context-encoding scheme.", "type": "object", "properties": { "type": { "description": "The media type. See [Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types](https://tools.ietf.org/html/rfc2046).", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "binaryEncoding": { "title": "binary_encoding", "description": "The content-encoding scheme. See [Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies](https://tools.ietf.org/html/rfc2045).", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" } } }, "pathStart": { "title": "path_start", "description": "To apply this schema to the instances' URIs, start the URIs with this value.", "type": "string", "minLength": 0, "maxLength": 2147483647, "format": "uri" } } }, "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": 2147483647, "pattern": "^[\\S\\s]*$" }, "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": 2147483647, "pattern": "^[\\S\\s]*$" }, "method": { "description": "The HTTP method required to make the related call.", "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH" ], "x-enumDescriptions": { "GET": "The HTTP GET method.", "POST": "The HTTP POST method.", "PUT": "The HTTP PUT method.", "DELETE": "The HTTP DELETE method.", "HEAD": "The HTTP HEAD method.", "CONNECT": "The HTTP CONNECT method.", "OPTIONS": "The HTTP OPTIONS method.", "PATCH": "The HTTP PATCH method." } }, "title": { "description": "The link title.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "mediaType": { "title": "media_type", "description": "The media type, as defined by [RFC 2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link target.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "encType": { "title": "enc_type", "description": "The media type in which to submit the request data.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "default": "application/json" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/link_schema" }, { "description": "The schema that describes the request data." } ] }, "targetSchema": { "allOf": [ { "$ref": "#/components/schemas/link_schema" }, { "title": "target_schema", "description": "The schema that describes the link target." } ] } } }, "error_details": { "title": "Error Details", "description": "The error details. Required for client-side `4XX` errors.", "type": "object", "required": [ "issue" ], "properties": { "field": { "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.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "value": { "description": "The value of the field that caused the error.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "location": { "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "default": "body" }, "issue": { "description": "The unique, fine-grained application-level error code.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "links": { "description": "An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links) that are either relevant to the issue by providing additional information or offering potential resolutions.", "type": "array", "minItems": 1, "maxItems": 4, "readOnly": true, "items": { "allOf": [ { "$ref": "#/components/schemas/link_description" }, { "title": "link_description", "readOnly": true } ] } }, "description": { "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.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" } } }, "error": { "title": "Error", "description": "The error details.", "type": "object", "required": [ "debug_id", "message", "name" ], "properties": { "name": { "description": "The human-readable, unique name of the error.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "message": { "description": "The message that describes the error.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "debug_id": { "description": "The PayPal internal ID. Used for correlation purposes.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "details": { "description": "An array of additional details about the error.", "type": "array", "minItems": 0, "maxItems": 32767, "items": { "allOf": [ { "$ref": "#/components/schemas/error_details" }, { "title": "error_details" } ] } }, "links": { "description": "An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "allOf": [ { "$ref": "#/components/schemas/link_description" }, { "title": "link_description", "readOnly": true } ] } } } }, "authorization_status_details": { "title": "authorization_status_details", "description": "The details of the authorized payment status.", "type": "object", "properties": { "reason": { "title": "Authorization Incomplete Reason", "description": "The reason why the authorized status is `PENDING`.", "type": "string", "enum": [ "PENDING_REVIEW", "DECLINED_BY_RISK_FRAUD_FILTERS" ], "x-enumDescriptions": { "PENDING_REVIEW": "Authorization is pending manual review.", "DECLINED_BY_RISK_FRAUD_FILTERS": "Risk Filter set by the payee failed for the transaction." } } } }, "authorization_status": { "title": "authorization_status", "description": "The status fields and status details for an authorized payment.", "type": "object", "properties": { "status": { "title": "Authorization Status", "description": "The status for the authorized payment.", "type": "string", "enum": [ "CREATED", "CAPTURED", "DENIED", "PARTIALLY_CAPTURED", "VOIDED", "PENDING" ], "x-enumDescriptions": { "CREATED": "The authorized payment is created. No captured payments have been made for this authorized payment.", "CAPTURED": "The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.", "DENIED": "PayPal cannot authorize funds for this authorized payment.", "PARTIALLY_CAPTURED": "A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.", "VOIDED": "The authorized payment was voided. No more captured payments can be made against this authorized payment.", "PENDING": "The created authorization is in pending state. For more information, see status.details." }, "readOnly": true }, "status_details": { "allOf": [ { "$ref": "#/components/schemas/authorization_status_details" }, { "description": "The details of the authorized order pending status.", "readOnly": true } ] } } }, "seller_protection": { "title": "seller_protection", "description": "The level of protection offered as defined by [PayPal Seller Protection for Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection).", "type": "object", "properties": { "status": { "title": "Seller Protection Status", "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).", "type": "string", "enum": [ "ELIGIBLE", "PARTIALLY_ELIGIBLE", "NOT_ELIGIBLE" ], "x-enumDescriptions": { "ELIGIBLE": "Your PayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment.", "PARTIALLY_ELIGIBLE": "Your PayPal balance remains intact if the customer claims that they did not receive an item.", "NOT_ELIGIBLE": "This transaction is not eligible for seller protection." }, "readOnly": true }, "dispute_categories": { "description": "An array of conditions that are covered for the transaction.", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "title": "dispute_category", "description": "The condition that is covered for the transaction.", "type": "string", "enum": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ], "x-enumDescriptions": { "ITEM_NOT_RECEIVED": "The payer paid for an item that they did not receive.", "UNAUTHORIZED_TRANSACTION": "The payer did not authorize the payment." } } } } }, "link_schema-2": { "title": "Link Schema", "description": "The request data or link target.", "type": "object", "properties": { "additionalItems": { "title": "additional_items", "description": "Any additional items.", "type": "object" }, "dependencies": { "title": "Dependencies", "description": "Any Dependencies.", "type": "object" }, "items": { "title": "Items", "description": "An item.", "type": "object" }, "definitions": { "title": "Definitions", "description": "Definitions.", "type": "object" }, "patternProperties": { "title": "pattern_properties", "description": "The pattern properties.", "type": "object" }, "properties": { "title": "Properties", "description": "Properties.", "type": "object" }, "allOf": { "title": "all_of", "description": "An array of sub-schemas. The data must validate against all sub-schemas.", "type": "array", "minItems": 0, "maxItems": 32767, "items": { "title": "all_of_item", "description": "A sub-schema against which the data must validate.", "type": "object" } }, "anyOf": { "title": "any_of", "description": "An array of sub-schemas. The data must validate against one or more sub-schemas.", "type": "array", "minItems": 0, "maxItems": 32767, "items": { "title": "any_of_item", "description": "A sub-schema against which the data must validate.", "type": "object" } }, "oneOf": { "title": "one_of", "description": "An array of sub-schemas. The data must validate against one sub-schema.", "type": "array", "minItems": 0, "maxItems": 32767, "items": { "title": "one_of_item", "description": "A sub-schema against which the data must validate.", "type": "object" } }, "not": { "title": "Not", "description": "Not.", "type": "object" }, "links": { "description": "An array of links.", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "title": "link", "description": "A link.", "type": "object", "readOnly": true } }, "fragmentResolution": { "title": "fragment_resolution", "description": "The fragment resolution.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "media": { "title": "Media", "description": "The media type and context-encoding scheme.", "type": "object", "properties": { "type": { "description": "The media type. See [Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types](https://tools.ietf.org/html/rfc2046).", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "binaryEncoding": { "title": "binary_encoding", "description": "The content-encoding scheme. See [Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies](https://tools.ietf.org/html/rfc2045).", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" } } }, "pathStart": { "title": "path_start", "description": "To apply this schema to the instances' URIs, start the URIs with this value.", "type": "string", "minLength": 0, "maxLength": 2147483647, "format": "uri" } } }, "link_description-2": { "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": 2147483647, "pattern": "^[\\S\\s]*$" }, "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": 2147483647, "pattern": "^[\\S\\s]*$" }, "method": { "description": "The HTTP method required to make the related call.", "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH" ], "x-enumDescriptions": { "GET": "The HTTP GET method.", "POST": "The HTTP POST method.", "PUT": "The HTTP PUT method.", "DELETE": "The HTTP DELETE method.", "HEAD": "The HTTP HEAD method.", "CONNECT": "The HTTP CONNECT method.", "OPTIONS": "The HTTP OPTIONS method.", "PATCH": "The HTTP PATCH method." } }, "title": { "description": "The link title.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "mediaType": { "title": "media_type", "description": "The media type, as defined by [RFC 2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link target.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" }, "encType": { "title": "enc_type", "description": "The media type in which to submit the request data.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "default": "application/json" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/link_schema-2" }, { "description": "The schema that describes the request data." } ] }, "targetSchema": { "allOf": [ { "$ref": "#/components/schemas/link_schema-2" }, { "title": "target_schema", "description": "The schema that describes the link target." } ] } } }, "activity_timestamps": { "title": "activity_timestamps", "description": "The date and time stamps that are common to authorized payment, captured payment, and refund transactions.", "type": "object", "properties": { "create_time": { "allOf": [ { "$ref": "#/components/schemas/date_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 } ] }, "update_time": { "allOf": [ { "$ref": "#/components/schemas/date_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 } ] } } }, "authorization": { "title": "authorization", "description": "The authorized payment transaction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/authorization_status" }, { "type": "object", "properties": { "id": { "description": "The PayPal-generated ID for the authorized payment.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "readOnly": true }, "amount": { "allOf": [ { "$ref": "#/components/schemas/amount_with_breakdown" }, { "description": "The amount for this authorized payment.", "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", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "readOnly": true }, "custom_id": { "description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.", "type": "string", "minLength": 0, "maxLength": 255, "pattern": "^[\\S\\s]*$" }, "network_transaction_reference": { "allOf": [ { "$ref": "#/components/schemas/network_transaction" } ] }, "seller_protection": { "allOf": [ { "$ref": "#/components/schemas/seller_protection" }, { "readOnly": true } ] }, "expiration_time": { "allOf": [ { "$ref": "#/components/schemas/date_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).", "readOnly": true } ] }, "links": { "description": "An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "allOf": [ { "$ref": "#/components/schemas/link_description-2" }, { "title": "link_description" } ] } } } }, { "$ref": "#/components/schemas/activity_timestamps" } ] }, "related_ids": { "title": "Related Identifiers", "description": "Identifiers related to a specific resource.", "type": "object", "properties": { "order_id": { "description": "Order ID related to the resource.", "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Z0-9]+$" }, "authorization_id": { "description": "Authorization ID related to the resource.", "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Z0-9]+$" }, "capture_id": { "description": "Capture ID related to the resource.", "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Z0-9]+$" } } }, "supplementary_data": { "title": "Payment Supplementary Data", "description": "The supplementary data.", "type": "object", "properties": { "related_ids": { "allOf": [ { "$ref": "#/components/schemas/related_ids" }, { "readOnly": true } ] } } }, "authorization-2": { "title": "Authorization", "description": "The authorized payment transaction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/authorization" }, { "type": "object", "properties": { "supplementary_data": { "allOf": [ { "$ref": "#/components/schemas/supplementary_data" }, { "readOnly": true } ] }, "payee": { "allOf": [ { "$ref": "#/components/schemas/payee_base" }, { "readOnly": true } ] } } } ] }, "supplementary_purchase_data": { "title": "Capture Identifier", "description": "The capture identification-related fields. Includes the invoice ID, custom ID, note to payer, and soft descriptor.", "type": "object", "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", "minLength": 1, "maxLength": 127, "pattern": "^.{1,127}$" }, "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", "minLength": 1, "maxLength": 255, "pattern": "^.{1,255}$" } } }, "platform_fee": { "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.", "type": "object", "required": [ "amount" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "title": "amount", "description": "The fee for this transaction." } ] }, "payee": { "allOf": [ { "$ref": "#/components/schemas/payee_base" }, { "title": "payee", "description": "The recipient of the fee for this transaction." } ] } } }, "disbursement_mode": { "title": "disbursement_mode", "description": "The funds that are held on behalf of the merchant.", "type": "string", "enum": [ "INSTANT", "DELAYED" ], "x-enumDescriptions": { "INSTANT": "The funds are released to the merchant immediately.", "DELAYED": "The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration." }, "default": "INSTANT" }, "payment_instruction": { "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.", "type": "object", "properties": { "platform_fees": { "description": "An array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability.", "type": "array", "minItems": 0, "maxItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/platform_fee" }, { "title": "platform_fee" } ] } }, "disbursement_mode": { "allOf": [ { "$ref": "#/components/schemas/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 Complete Payments Platform for Marketplaces and Platforms capability." } ] }, "payee_pricing_tier_id": { "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.", "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^.*$" }, "payee_receivable_fx_rate_id": { "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.", "type": "string", "minLength": 1, "maxLength": 4000, "pattern": "^.*$" } } }, "capture_request": { "title": "Capture Request", "description": "Captures either a portion or the full authorized amount of an authorized payment.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/supplementary_purchase_data" }, { "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/amount_with_breakdown" }, { "description": "The amount to capture with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, gratuity and discounts, if any. 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.
If you specify `amount.breakdown`, the amount equals `item_total` plus `tax_total` plus `shipping` plus `handling` plus `insurance` plus 'gratuity' minus `shipping_discount` minus discount.
The amount must be a positive number. The `amount.value` field supports up to 15 digits preceding the decimal. For a list of supported currencies, decimal precision, and maximum charge amount, see the PayPal REST APIs Currency Codes." } ] }, "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", "minLength": 0, "maxLength": 127, "pattern": "^[\\S\\s]*$" }, "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": { "allOf": [ { "$ref": "#/components/schemas/payment_instruction" }, { "not": { "required": [ "payee_pricing_tier_id" ] } } ] }, "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", "minLength": 0, "maxLength": 255, "pattern": "^[\\S\\s]*$" }, "soft_descriptor": { "description": "The payment descriptor on the payer's account statement.", "type": "string", "minLength": 0, "maxLength": 22, "pattern": "^[\\S\\s]*$" } } } ] }, "capture_status_details": { "title": "capture_status_details", "description": "The details of the captured payment status.", "type": "object", "properties": { "reason": { "title": "Capture Incomplete Reason", "description": "The reason why the captured payment status is `PENDING` or `DENIED`.", "type": "string", "enum": [ "BUYER_COMPLAINT", "CHARGEBACK", "ECHECK", "INTERNATIONAL_WITHDRAWAL", "OTHER", "PENDING_REVIEW", "RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION", "REFUNDED", "TRANSACTION_APPROVED_AWAITING_FUNDING", "UNILATERAL", "VERIFICATION_REQUIRED", "DECLINED_BY_RISK_FRAUD_FILTERS" ], "x-enumDescriptions": { "BUYER_COMPLAINT": "The payer initiated a dispute for this captured payment with PayPal.", "CHARGEBACK": "The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.", "ECHECK": "The payer paid by an eCheck that has not yet cleared.", "INTERNATIONAL_WITHDRAWAL": "Visit your online account. In your **Account Overview**, accept and deny this payment.", "OTHER": "No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.", "PENDING_REVIEW": "The captured payment is pending manual review.", "RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION": "The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.", "REFUNDED": "The captured funds were refunded.", "TRANSACTION_APPROVED_AWAITING_FUNDING": "The payer must send the funds for this captured payment. This code generally appears for manual EFTs.", "UNILATERAL": "The payee does not have a PayPal account.", "VERIFICATION_REQUIRED": "The payee's PayPal account is not verified.", "DECLINED_BY_RISK_FRAUD_FILTERS": "Risk Filter set by the payee failed for the transaction." } } } }, "capture_status": { "title": "capture_status", "description": "The status and status details of a captured payment.", "type": "object", "properties": { "status": { "title": "Capture Status", "description": "The status of the captured payment.", "type": "string", "enum": [ "COMPLETED", "DECLINED", "PARTIALLY_REFUNDED", "PENDING", "REFUNDED", "FAILED" ], "x-enumDescriptions": { "COMPLETED": "The funds for this captured payment were credited to the payee's PayPal account.", "DECLINED": "The funds could not be captured.", "PARTIALLY_REFUNDED": "An amount less than this captured payment's amount was partially refunded to the payer.", "PENDING": "The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.", "REFUNDED": "An amount greater than or equal to this captured payment's amount was refunded to the payer.", "FAILED": "There was an error while capturing payment." }, "readOnly": true }, "status_details": { "allOf": [ { "$ref": "#/components/schemas/capture_status_details" }, { "description": "The details of the captured payment status.", "readOnly": true } ] } } }, "exchange_rate": { "title": "exchange_rate", "description": "The exchange rate that determines the amount to convert from one currency to another currency.", "type": "object", "readOnly": true, "properties": { "source_currency": { "allOf": [ { "$ref": "#/components/schemas/currency_code" }, { "description": "The source currency from which to convert an amount." } ] }, "target_currency": { "allOf": [ { "$ref": "#/components/schemas/currency_code" }, { "description": "The target currency to which to convert an amount." } ] }, "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", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$" } } }, "seller_receivable_breakdown": { "title": "Seller Receivable Breakdown", "description": "The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.", "type": "object", "required": [ "gross_amount" ], "properties": { "gross_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The amount for this captured payment in the currency of the transaction." } ] }, "paypal_fee": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The applicable fee for this captured payment in the currency of the transaction." } ] }, "paypal_fee_in_receivable_currency": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "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'." } ] }, "net_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee minus the platform_fees." } ] }, "receivable_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "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 net_amount times exchange_rate." } ] }, "exchange_rate": { "allOf": [ { "$ref": "#/components/schemas/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." } ] }, "platform_fees": { "description": "An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.", "type": "array", "minItems": 0, "maxItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/platform_fee" }, { "title": "platform_fee" } ] } } } }, "processor_response": { "title": "processor_response", "description": "The processor response information for payment requests, such as direct credit card transactions.", "type": "object", "properties": { "avs_code": { "description": "The address verification code for Visa, Discover, Mastercard, or American Express transactions.", "type": "string", "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" ], "x-enumDescriptions": { "0": "For Maestro, all address information matches.", "1": "For Maestro, none of the address information matches.", "2": "For Maestro, part of the address information matches.", "3": "For Maestro, the merchant did not provide AVS information. It was not processed.", "4": "For Maestro, the address was not checked or the acquirer had no response. The service is not available.", "A": "For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct.", "B": "For Visa, Mastercard, or Discover transactions, the address matches. International A.", "C": "For Visa, Mastercard, or Discover transactions, no values match. International N.", "D": "For Visa, Mastercard, or Discover transactions, the address and postal code match. International X.", "E": "For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match.", "F": "For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches.", "G": "For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches.", "I": "For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable.", "M": "For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match.", "N": "For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect.", "P": "For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only.", "R": "For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable.", "S": "For Visa, Mastercard, Discover, or American Express, the service is not supported.", "U": "For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available.", "W": "For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.", "X": "For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.", "Y": "For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct.", "Z": "For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct.", "Null": "For Maestro, no AVS response was obtained." }, "readOnly": true }, "cvv_code": { "description": "The card verification value code for for Visa, Discover, Mastercard, or American Express.", "type": "string", "enum": [ "E", "I", "M", "N", "P", "S", "U", "X", "All others", "0", "1", "2", "3", "4" ], "x-enumDescriptions": { "0": "For Maestro, the CVV2 matched.", "1": "For Maestro, the CVV2 did not match.", "2": "For Maestro, the merchant has not implemented CVV2 code handling.", "3": "For Maestro, the merchant has indicated that CVV2 is not present on card.", "4": "For Maestro, the service is not available.", "E": "For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response.", "I": "For Visa, Mastercard, Discover, or American Express, invalid or null.", "M": "For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches.", "N": "For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match.", "P": "For Visa, Mastercard, Discover, or American Express, it was not processed.", "S": "For Visa, Mastercard, Discover, or American Express, the service is not supported.", "U": "For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified.", "X": "For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available.", "All others": "For Visa, Mastercard, Discover, or American Express, error." }, "readOnly": true }, "response_code": { "description": "Processor response code for the non-PayPal payment processor errors.", "type": "string", "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" ], "x-enumDescriptions": { "1000": "PARTIAL_AUTHORIZATION.", "1300": "INVALID_DATA_FORMAT.", "1310": "INVALID_AMOUNT.", "1312": "INVALID_TRANSACTION_CARD_ISSUER_ACQUIRER.", "1317": "INVALID_CAPTURE_DATE.", "1320": "INVALID_CURRENCY_CODE.", "1330": "INVALID_ACCOUNT.", "1335": "INVALID_ACCOUNT_RECURRING.", "1340": "INVALID_TERMINAL.", "1350": "INVALID_MERCHANT.", "1352": "RESTRICTED_OR_INACTIVE_ACCOUNT.", "1360": "BAD_PROCESSING_CODE.", "1370": "INVALID_MCC.", "1380": "INVALID_EXPIRATION.", "1382": "INVALID_CARD_VERIFICATION_VALUE.", "1384": "INVALID_LIFE_CYCLE_OF_TRANSACTION.", "1390": "INVALID_ORDER.", "1393": "TRANSACTION_CANNOT_BE_COMPLETED.", "5100": "GENERIC_DECLINE.", "5110": "CVV2_FAILURE.", "5120": "INSUFFICIENT_FUNDS.", "5130": "INVALID_PIN.", "5135": "DECLINED_PIN_TRY_EXCEEDED.", "5140": "CARD_CLOSED.", "5150": "PICKUP_CARD_SPECIAL_CONDITIONS. Try using another card. Do not retry the same card.", "5160": "UNAUTHORIZED_USER.", "5170": "AVS_FAILURE.", "5180": "INVALID_OR_RESTRICTED_CARD. Try using another card. Do not retry the same card.", "5190": "SOFT_AVS.", "5200": "DUPLICATE_TRANSACTION.", "5210": "INVALID_TRANSACTION.", "5400": "EXPIRED_CARD.", "5500": "INCORRECT_PIN_REENTER.", "5650": "DECLINED_SCA_REQUIRED.", "5700": "TRANSACTION_NOT_PERMITTED. Outside of scope of accepted business.", "5710": "TX_ATTEMPTS_EXCEED_LIMIT.", "5800": "REVERSAL_REJECTED.", "5900": "INVALID_ISSUE.", "5910": "ISSUER_NOT_AVAILABLE_NOT_RETRIABLE.", "5920": "ISSUER_NOT_AVAILABLE_RETRIABLE.", "5930": "CARD_NOT_ACTIVATED.", "5950": "DECLINED_DUE_TO_UPDATED_ACCOUNT. External decline as an updated card has been issued.", "6300": "ACCOUNT_NOT_ON_FILE.", "7600": "APPROVED_NON_CAPTURE.", "7700": "ERROR_3DS.", "7710": "AUTHENTICATION_FAILED.", "7800": "BIN_ERROR.", "7900": "PIN_ERROR.", "8000": "PROCESSOR_SYSTEM_ERROR.", "8010": "HOST_KEY_ERROR.", "8020": "CONFIGURATION_ERROR.", "8030": "UNSUPPORTED_OPERATION.", "8100": "FATAL_COMMUNICATION_ERROR.", "8110": "RETRIABLE_COMMUNICATION_ERROR.", "8220": "SYSTEM_UNAVAILABLE.", "9100": "DECLINED_PLEASE_RETRY. Retry.", "9500": "SUSPECTED_FRAUD. Try using another card. Do not retry the same card.", "9510": "SECURITY_VIOLATION.", "9520": "LOST_OR_STOLEN. Try using another card. Do not retry the same card.", "9530": "HOLD_CALL_CENTER. The merchant must call the number on the back of the card. POS scenario.", "9540": "REFUSED_CARD.", "9600": "UNRECOGNIZED_RESPONSE_CODE.", "0000": "APPROVED.", "00N7": "CVV2_FAILURE_POSSIBLE_RETRY_WITH_CVV.", "0100": "REFERRAL.", "0390": "ACCOUNT_NOT_FOUND.", "0500": "DO_NOT_HONOR.", "0580": "UNAUTHORIZED_TRANSACTION.", "0800": "BAD_RESPONSE_REVERSAL_REQUIRED.", "0880": "CRYPTOGRAPHIC_FAILURE.", "0890": "UNACCEPTABLE_PIN.", "0960": "SYSTEM_MALFUNCTION.", "0R00": "CANCELLED_PAYMENT.", "10BR": "ISSUER_REJECTED.", "PCNR": "CONTINGENCIES_NOT_RESOLVED.", "PCVV": "CVV_FAILURE.", "PP06": "ACCOUNT_CLOSED. A previously open account is now closed", "PPRN": "REATTEMPT_NOT_PERMITTED.", "PPAD": "BILLING_ADDRESS.", "PPAB": "ACCOUNT_BLOCKED_BY_ISSUER.", "PPAE": "AMEX_DISABLED.", "PPAG": "ADULT_GAMING_UNSUPPORTED.", "PPAI": "AMOUNT_INCOMPATIBLE.", "PPAR": "AUTH_RESULT.", "PPAU": "MCC_CODE.", "PPAV": "ARC_AVS.", "PPAX": "AMOUNT_EXCEEDED.", "PPBG": "BAD_GAMING.", "PPC2": "ARC_CVV.", "PPCE": "CE_REGISTRATION_INCOMPLETE.", "PPCO": "COUNTRY.", "PPCR": "CREDIT_ERROR.", "PPCT": "CARD_TYPE_UNSUPPORTED.", "PPCU": "CURRENCY_USED_INVALID.", "PPD3": "SECURE_ERROR_3DS.", "PPDC": "DCC_UNSUPPORTED.", "PPDI": "DINERS_REJECT.", "PPDV": "AUTH_MESSAGE.", "PPDT": "DECLINE_THRESHOLD_BREACH.", "PPEF": "EXPIRED_FUNDING_INSTRUMENT.", "PPEL": "EXCEEDS_FREQUENCY_LIMIT.", "PPER": "INTERNAL_SYSTEM_ERROR.", "PPEX": "EXPIRY_DATE.", "PPFE": "FUNDING_SOURCE_ALREADY_EXISTS.", "PPFI": "INVALID_FUNDING_INSTRUMENT.", "PPFR": "RESTRICTED_FUNDING_INSTRUMENT.", "PPFV": "FIELD_VALIDATION_FAILED.", "PPGR": "GAMING_REFUND_ERROR.", "PPH1": "H1_ERROR.", "PPIF": "IDEMPOTENCY_FAILURE.", "PPII": "INVALID_INPUT_FAILURE.", "PPIM": "ID_MISMATCH.", "PPIT": "INVALID_TRACE_ID.", "PPLR": "LATE_REVERSAL.", "PPLS": "LARGE_STATUS_CODE.", "PPMB": "MISSING_BUSINESS_RULE_OR_DATA.", "PPMC": "BLOCKED_Mastercard.", "PPMD": "DEPRECATED The PPMD value has been deprecated.", "PPNC": "NOT_SUPPORTED_NRC.", "PPNL": "EXCEEDS_NETWORK_FREQUENCY_LIMIT.", "PPNM": "NO_MID_FOUND.", "PPNT": "NETWORK_ERROR.", "PPPH": "NO_PHONE_FOR_DCC_TRANSACTION.", "PPPI": "INVALID_PRODUCT.", "PPPM": "INVALID_PAYMENT_METHOD.", "PPQC": "QUASI_CASH_UNSUPPORTED.", "PPRE": "UNSUPPORT_REFUND_ON_PENDING_BC.", "PPRF": "INVALID_PARENT_TRANSACTION_STATUS.", "PPRR": "MERCHANT_NOT_REGISTERED.", "PPS0": "BANKAUTH_ROW_MISMATCH.", "PPS1": "BANKAUTH_ROW_SETTLED.", "PPS2": "BANKAUTH_ROW_VOIDED.", "PPS3": "BANKAUTH_EXPIRED.", "PPS4": "CURRENCY_MISMATCH.", "PPS5": "CREDITCARD_MISMATCH.", "PPS6": "AMOUNT_MISMATCH.", "PPSC": "ARC_SCORE.", "PPSD": "STATUS_DESCRIPTION.", "PPSE": "AMEX_DENIED.", "PPTE": "VERIFICATION_TOKEN_EXPIRED.", "PPTF": "INVALID_TRACE_REFERENCE.", "PPTI": "INVALID_TRANSACTION_ID.", "PPTR": "VERIFICATION_TOKEN_REVOKED.", "PPTT": "TRANSACTION_TYPE_UNSUPPORTED.", "PPTV": "INVALID_VERIFICATION_TOKEN.", "PPUA": "USER_NOT_AUTHORIZED.", "PPUC": "CURRENCY_CODE_UNSUPPORTED.", "PPUE": "UNSUPPORT_ENTITY.", "PPUI": "UNSUPPORT_INSTALLMENT.", "PPUP": "UNSUPPORT_POS_FLAG.", "PPUR": "UNSUPPORTED_REVERSAL.", "PPVC": "VALIDATE_CURRENCY.", "PPVE": "VALIDATION_ERROR.", "PPVT": "VIRTUAL_TERMINAL_UNSUPPORTED." }, "readOnly": true }, "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", "enum": [ "01", "02", "03", "04", "21", "22", "24", "25", "26", "27", "28", "29", "30", "40", "43" ], "x-enumDescriptions": { "21": "For Mastercard, the card holder has been unsuccessful at canceling recurring payment through merchant. Stop recurring payment requests. For Visa, all recurring payments were canceled for the card number requested. Stop recurring payment requests.", "22": "For Mastercard, merchant does not qualify for product code.", "24": "For Mastercard, retry after 1 hour.", "25": "For Mastercard, retry after 24 hours.", "26": "For Mastercard, retry after 2 days.", "27": "For Mastercard, retry after 4 days.", "28": "For Mastercard, retry after 6 days.", "29": "For Mastercard, retry after 8 days.", "30": "For Mastercard, retry after 10 days .", "40": "For Mastercard, consumer non-reloadable prepaid card.", "43": "For Mastercard, consumer multi-use virtual card number.", "01": "For Mastercard, expired card account upgrade or portfolio sale conversion. Obtain new account information before next billing cycle.", "02": "For Mastercard, over credit limit or insufficient funds. Retry the transaction 72 hours later. For Visa, the card holder wants to stop only one specific payment in the recurring payment relationship. The merchant must NOT resubmit the same transaction. The merchant can continue the billing process in the subsequent billing period.", "03": "For Mastercard, account closed as fraudulent. Obtain another type of payment from customer due to account being closed or fraud. Possible reason: Account closed as fraudulent. For Visa, the card holder wants to stop all recurring payment transactions for a specific merchant. Stop recurring payment requests.", "04": "For Mastercard, token requirements not fulfilled for this token type." }, "readOnly": true } } }, "capture": { "title": "capture", "description": "A captured payment.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/capture_status" }, { "type": "object", "properties": { "id": { "description": "The PayPal-generated ID for the captured payment.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "readOnly": true }, "amount": { "allOf": [ { "$ref": "#/components/schemas/amount_with_breakdown" }, { "description": "The amount for this captured payment.", "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", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "readOnly": true }, "custom_id": { "description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.", "type": "string", "minLength": 0, "maxLength": 255, "pattern": "^[\\S\\s]*$" }, "network_transaction_reference": { "allOf": [ { "$ref": "#/components/schemas/network_transaction" } ] }, "seller_protection": { "allOf": [ { "$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": { "allOf": [ { "$ref": "#/components/schemas/seller_receivable_breakdown" }, { "readOnly": true } ] }, "disbursement_mode": { "allOf": [ { "$ref": "#/components/schemas/disbursement_mode" } ] }, "links": { "description": "An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "allOf": [ { "$ref": "#/components/schemas/link_description-2" }, { "title": "link_description" } ] } }, "processor_response": { "allOf": [ { "$ref": "#/components/schemas/processor_response" }, { "description": "An object that provides additional processor information for a direct credit card transaction." } ] } } }, { "allOf": [ { "$ref": "#/components/schemas/activity_timestamps" } ] } ] }, "capture-2": { "title": "Captured Payment", "description": "A captured payment.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/capture" }, { "type": "object", "properties": { "supplementary_data": { "allOf": [ { "$ref": "#/components/schemas/supplementary_data" }, { "description": "An object that provides supplementary/additional data related to a payment transaction.", "readOnly": true } ] }, "payee": { "allOf": [ { "$ref": "#/components/schemas/payee_base" }, { "readOnly": true } ] } } } ] }, "reauthorize_request": { "title": "Reauthorize Request", "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.

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.

A reauthorized payment itself has a new honor period of three days.

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.

Supports only the `amount` request parameter.", "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The amount to reauthorize for an authorized payment." } ] } } }, "payment_instruction-2": { "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.", "type": "object", "properties": { "platform_fees": { "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.", "type": "array", "minItems": 0, "maxItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/platform_fee" }, { "title": "platform_fee", "not": { "required": [ "payee" ] } } ] } } } }, "refund_request": { "title": "Refund Request", "description": "Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an amount object in the request body.", "type": "object", "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "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 captured amount - previous refunds is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured." } ] }, "custom_id": { "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.", "type": "string", "minLength": 1, "maxLength": 127, "pattern": "^.*$" }, "invoice_id": { "description": "The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode.", "type": "string", "minLength": 1, "maxLength": 127, "pattern": "^.*$" }, "note_to_payer": { "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.", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "payment_instruction": { "allOf": [ { "$ref": "#/components/schemas/payment_instruction-2" }, { "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." } ] } } }, "refund_status_details": { "title": "refund_status_details", "description": "The details of the refund status.", "type": "object", "properties": { "reason": { "title": "Refund Incomplete Reason", "description": "The reason why the refund has the `PENDING` or `FAILED` status.", "type": "string", "enum": [ "ECHECK" ], "x-enumDescriptions": { "ECHECK": "The customer's account is funded through an eCheck, which has not yet cleared." } } } }, "refund_status": { "title": "refund_status", "description": "The refund status with details.", "type": "object", "properties": { "status": { "title": "Refund Status With Details", "description": "The status of the refund.", "type": "string", "enum": [ "CANCELLED", "FAILED", "PENDING", "COMPLETED" ], "x-enumDescriptions": { "CANCELLED": "The refund was cancelled.", "FAILED": "The refund could not be processed.", "PENDING": "The refund is pending. For more information, see status_details.reason.", "COMPLETED": "The funds for this transaction were debited to the customer's account." }, "readOnly": true }, "status_details": { "allOf": [ { "$ref": "#/components/schemas/refund_status_details" }, { "description": "The details of the refund status.", "readOnly": true } ] } } }, "net_amount_breakdown_item": { "title": "net_amount_breakdown", "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.", "type": "object", "properties": { "payable_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The net amount debited from the merchant's PayPal account.", "readOnly": true } ] }, "converted_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The converted payable amount.", "readOnly": true } ] }, "exchange_rate": { "allOf": [ { "$ref": "#/components/schemas/exchange_rate" }, { "description": "The exchange rate that determines the amount that was debited from the merchant's PayPal account.", "readOnly": true } ] } } }, "buyer_context": { "title": "Buyer Context", "description": "The buyer context for the refund transaction.", "type": "object", "properties": { "transaction_id": { "description": "The PayPal generated transaction ID associated with the buyer's refund.", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9a-zA-Z_-]+$", "readOnly": true }, "transaction_details_url": { "description": "The URL for the buyer to view the transaction details.", "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "readOnly": true }, "transaction_create_time": { "allOf": [ { "$ref": "#/components/schemas/date_time" }, { "description": "The date and time when the buyer's refund transaction was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true } ] }, "transaction_update_time": { "allOf": [ { "$ref": "#/components/schemas/date_time" }, { "description": "The date and time when the buyer's refund transaction was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true } ] } } }, "refund": { "title": "refund", "description": "The refund information.", "type": "object", "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/refund_status" } ] }, { "title": "Refund Properties", "description": "The detailed properties of the refund transaction, including identifiers, amounts, breakdowns, and associated metadata.", "type": "object", "properties": { "id": { "description": "The PayPal-generated ID for the refund.", "type": "string", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "readOnly": true }, "amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The amount that the payee refunded to the payer.", "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", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "readOnly": true }, "custom_id": { "description": "The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9-_.,]*$" }, "acquirer_reference_number": { "description": "Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.", "type": "string", "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", "minLength": 0, "maxLength": 2147483647, "pattern": "^[\\S\\s]*$", "readOnly": true }, "seller_payable_breakdown": { "title": "Seller Payable Breakdown", "description": "The breakdown of the refund.", "type": "object", "readOnly": true, "properties": { "gross_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The amount that the payee refunded to the payer.", "readOnly": true } ] }, "paypal_fee": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "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.", "readOnly": true } ] }, "paypal_fee_in_receivable_currency": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "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'.", "readOnly": true } ] }, "net_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "description": "The net amount that the payee's account is debited in the transaction currency. The net amount is calculated as gross_amount minus paypal_fee minus platform_fees.", "readOnly": true } ] }, "net_amount_in_receivable_currency": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "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'.", "readOnly": true } ] }, "platform_fees": { "description": "An array of platform or partner fees, commissions, or brokerage fees for the refund.", "type": "array", "minItems": 0, "maxItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/platform_fee" }, { "title": "platform_fee" } ] } }, "net_amount_breakdown": { "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.", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "allOf": [ { "$ref": "#/components/schemas/net_amount_breakdown_item" }, { "title": "net_amount_breakdown_item" } ] } }, "total_refunded_amount": { "allOf": [ { "$ref": "#/components/schemas/money" }, { "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." } ] } } }, "payer": { "allOf": [ { "$ref": "#/components/schemas/payee_base" }, { "description": "The details associated with the merchant for this transaction.", "readOnly": true } ] }, "buyer_context": { "allOf": [ { "$ref": "#/components/schemas/buyer_context" }, { "description": "The buyer context for the refund transaction.", "readOnly": true } ] }, "links": { "description": "An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "type": "array", "minItems": 0, "maxItems": 32767, "readOnly": true, "items": { "allOf": [ { "$ref": "#/components/schemas/link_description-2" }, { "title": "link_description" } ] } } } }, { "allOf": [ { "$ref": "#/components/schemas/activity_timestamps" } ] } ] }, "guid": { "title": "GUID", "description": "A Globally Unique Identifier (GUID) value.", "type": "string", "minLength": 1, "maxLength": 68, "pattern": "^[A-Za-z0-9-{}(),]*$" }, "find_eligible_methods_request_customer_channel": { "title": "Customer Channel", "description": "Channel through which the request is being posted.", "type": "object", "properties": { "browser_type": { "description": "The browser used by the customer. Example: Safari, Chrome, etc.", "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[0-9a-zA-Z_,. -]+$" }, "client_os": { "description": "The operating system on the device used by the customer. Example: iOS 16.5, Android 30, etc.", "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[0-9a-zA-Z_,. -]+$" }, "device_type": { "description": "The type of device used by the customer. Example: Mobile, Desktop, Tablet, etc.", "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[0-9a-zA-Z_,. -]+$" } } }, "find_eligible_methods_request_customer": { "title": "Customer", "description": "Customer who is making a purchase from the merchant/partner.", "type": "object", "properties": { "country_code": { "allOf": [ { "$ref": "#/components/schemas/country_code-2" }, { "description": "Country from which the customer is purchasing products/services from the merchant/partner. Result will factor in local payment methods that are available in the country mentioned. Value should be in the 2-character ISO 3166-1 code format." } ] }, "channel": { "allOf": [ { "$ref": "#/components/schemas/find_eligible_methods_request_customer_channel" }, { "description": "Channel through which the request is being posted. This object intends to collect information such as browser, operating system, device of the buyer. If both channel and User-Agent header are passed, data passed in the channel object takes precedence and User-Agent header will be used for information not provided in channel object." } ] }, "email": { "$ref": "#/components/schemas/email_address" }, "phone": { "allOf": [ { "$ref": "#/components/schemas/phone-2" }, { "not": { "required": [ "extension_number" ] } } ] } } }, "eligibility_purchase_unit_request": { "title": "eligibility_purchase_unit_request", "description": "Purchase unit for payment eligibility.", "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/amount_with_breakdown" }, "payee": { "$ref": "#/components/schemas/payee" } } }, "payment_method": { "title": "payment_method", "description": "Set of unique payment methods.", "type": "string", "enum": [ "PAYPAL", "VENMO", "PAYPAL_CREDIT", "PAYPAL_PAY_LATER", "ACH" ], "x-enumDescriptions": { "PAYPAL": "PAYPAL", "VENMO": "VENMO", "PAYPAL_CREDIT": "PAYPAL_CREDIT", "PAYPAL_PAY_LATER": "PAYPAL_PAY_LATER", "ACH": "ACH" } }, "find_eligible_methods_request_preferences": { "title": "Preferences", "description": "Preferences of merchant/partner consuming the API.", "type": "object", "properties": { "payment_flow": { "title": "Payment Flow", "description": "This field specifies the payment flow, expected to provide a hint about which payment action the customer is intending to perform.", "type": "string", "enum": [ "ONE_TIME_PAYMENT", "RECURRING_PAYMENT", "VAULT_WITH_PAYMENT", "VAULT_WITHOUT_PAYMENT" ], "x-enumDescriptions": { "ONE_TIME_PAYMENT": "Indicates that a customer is attempting to acquire a product within the context of a purchase. Most often, this will be the standard PayPal Checkout experience.", "RECURRING_PAYMENT": "Indicates that the customer is in the recurring payment experience.", "VAULT_WITH_PAYMENT": "Indicates that the customer is entering through checkout and continue to the vaulting experience.", "VAULT_WITHOUT_PAYMENT": "Indicates that the customer is in the vaulting experience without any purchase." } }, "intent": { "type": "string", "description": "The intent of the payment flow, specifying the purpose of the payment operation.", "enum": [ "CAPTURE", "AUTHORIZE", "ORDER", "TOKENIZE", "SUBSCRIPTION", "UNKNOWN" ], "x-enumDescriptions": { "CAPTURE": "The intent to capture payment immediately after customer approval.", "AUTHORIZE": "The intent to authorize a payment for capture later.", "ORDER": "The intent to create an order for authorized payments that can be captured later in parts or in full.", "TOKENIZE": "The intent to tokenize payment details without processing a payment.", "SUBSCRIPTION": "The intent to process a payment as part of a subscription.", "UNKNOWN": "Used when the intent is not specified or does not match any known values." } }, "include_account_details": { "description": "If this value is set to true, response will include confirmation if the customer has PayPal and/or Venmo accounts if they are eligible payment methods. Value defaults to false.", "type": "boolean", "default": "false" }, "include_vault_tokens": { "description": "If this value is set to true, response will include vaulted token information if the eligible funding source has any instrument vaulted for the customer. Value defaults to false.", "type": "boolean", "default": "false" }, "vault": { "description": "This field determines whether the selected payment method is intended to be stored for future use (vaulted) or used as a one-time payment. Value defaults to false.", "type": "boolean", "default": "false" }, "payment_source_constraint": { "title": "Payment Source Constraint", "description": "Payment source constraint defines the payment methods that needs to be included/excluded for eligibility assessment. If not passed, all payment methods will be assessed for eligibility.", "type": "object", "required": [ "constraint_type", "payment_sources" ], "properties": { "constraint_type": { "description": "Constraint type defines whether given payment sources needs to be included or excluded.", "type": "string", "enum": [ "INCLUDE", "EXCLUDE" ], "x-enumDescriptions": { "INCLUDE": "If this value is passed for constraint type, only the payment methods listed in payment_sources array will be assessed for eligibility.", "EXCLUDE": "If this value is passed for constraint type, all the payment sources listed in payment_sources array will be excluded for eligibility assessment." } }, "payment_sources": { "description": "Set of unique payment methods that will be included/excluded for eligibility assessment.", "type": "array", "minItems": 1, "maxItems": 75, "items": { "$ref": "#/components/schemas/payment_method" } } } } } }, "find_eligible_methods_request": { "title": "Find Eligible Payment Methods Request", "description": "Request to get list of eligible payment methods.", "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/find_eligible_methods_request_customer" }, "purchase_units": { "description": "Array of purchase units.", "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/eligibility_purchase_unit_request" } }, "preferences": { "$ref": "#/components/schemas/find_eligible_methods_request_preferences" } } }, "credit_product_button_code": { "title": "Credit Button Eligibility Button Code", "description": "The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.", "type": "string", "enum": [ "CREDIT", "PAYLATER", "PAY_IN_3", "PAY_IN_4" ], "x-enumDescriptions": { "CREDIT": "Open ended credit products.", "PAYLATER": "Pay Later suite of products.", "PAY_IN_3": "Pay In 3 suite of products.", "PAY_IN_4": "Pay In 4 suite of products." } }, "payment_method_common": { "title": "Common response fields", "description": "Common response fields for all payment methods.", "type": "object", "properties": { "can_be_vaulted": { "description": "Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.", "type": "boolean", "default": false }, "country_code": { "allOf": [ { "$ref": "#/components/schemas/country_code-2" }, { "description": "Returns a country_code which is derived from the buyer's country." } ] }, "product_code": { "allOf": [ { "$ref": "#/components/schemas/credit_product_button_code" }, { "description": "Returns a product code." } ] } } }, "payment_method_eligible_in_paypal_network": { "title": "PayPal services member indicator", "description": "Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to \"true\" in the API request.", "type": "boolean" }, "paypal": { "title": "Response for PayPal", "description": "Response for PayPal.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "type": "object", "properties": { "eligible_in_paypal_network": { "$ref": "#/components/schemas/payment_method_eligible_in_paypal_network" }, "recommended": { "description": "Indicates if the payment method is recommended or not. A true value indicates the customer is payment ready and this payment method may be presented upfront.", "type": "boolean", "default": "false" }, "recommended_priority": { "description": "This value is included in the response when recommended is true for a payment method. It indicates the priority of recommendation for payment readiness of eligible payment methods with lowest number taking the highest precedence.", "type": "integer", "minimum": 1, "maximum": 3 } } } ] }, "venmo": { "title": "Response for Venmo", "description": "Response for Venmo.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "type": "object", "properties": { "eligible_in_paypal_network": { "$ref": "#/components/schemas/payment_method_eligible_in_paypal_network" }, "recommended": { "description": "Indicates if the payment method is recommended or not. A true value indicates the customer is payment ready and this payment method may be presented upfront.", "type": "boolean", "default": "false" }, "recommended_priority": { "description": "This value is included in the response when recommended is true for a payment method. It indicates the priority of recommendation for payment readiness of eligible payment methods with lowest number taking the highest precedence.", "type": "integer", "minimum": 1, "maximum": 3 } } } ] }, "applepay_config": { "type": "object", "title": "Apple Pay Config", "description": "Configuration details for Apple Pay payment method.", "properties": { "eligible": { "type": "boolean", "description": "Indicates if Apple Pay is eligible." }, "merchant_country": { "allOf": [ { "$ref": "#/components/schemas/country_code-2" }, { "description": "Merchant country code." } ] }, "supported_networks": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Supported card networks.", "items": { "type": "string", "description": "Supported card network identifier.", "enum": [ "MASTERCARD", "DISCOVER", "VISA", "AMEX" ], "x-enumDescriptions": { "MASTERCARD": "MasterCard network.", "DISCOVER": "Discover network.", "VISA": "Visa network.", "AMEX": "American Express network." } } }, "merchant_capabilities": { "type": "array", "description": "An array of the payment capabilities that the merchant supports.", "minItems": 1, "maxItems": 10, "items": { "type": "string", "description": "Merchant payment capability identifier.", "enum": [ "SUPPORTS_CREDIT", "SUPPORTS_DEBIT", "SUPPORTS_3DS" ], "x-enumDescriptions": { "SUPPORTS_CREDIT": "Merchant supports credit card payments.", "SUPPORTS_DEBIT": "Merchant supports debit card payments.", "SUPPORTS_3DS": "Merchant supports 3D Secure authentication." } } }, "token_notification_url": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "Token notification url for recurring payment request.", "format": "uri" } }, "required": [ "eligible", "merchant_country", "supported_networks", "merchant_capabilities", "token_notification_url" ] }, "applepay": { "type": "object", "title": "Eligibility Response for ApplePay", "description": "Response for ApplePay.", "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "properties": { "config": { "$ref": "#/components/schemas/applepay_config" } } } ] }, "googlepay_billing_address_parameters": { "type": "object", "title": "Billing Address Parameters", "description": "Configuration parameters for billing address collection in Google Pay.", "properties": { "format": { "type": "string", "enum": [ "FULL" ], "x-enumDescriptions": { "FULL": "Full billing address format." }, "description": "Billing address format." } } }, "googlepay_payment_method_parameters": { "type": "object", "title": "Payment Method Parameters", "description": "Parameters specific to the payment method configuration.", "properties": { "allowed_auth_methods": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "description": "Authentication method identifier for Google Pay transactions.", "enum": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ], "x-enumDescriptions": { "PAN_ONLY": "Authentication method using only the primary account number.", "CRYPTOGRAM_3DS": "Authentication method using 3DS cryptogram." } }, "description": "Allowed authentication methods." }, "supported_networks": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "description": "Supported card network identifier for Google Pay.", "enum": [ "MASTERCARD", "DISCOVER", "VISA", "AMEX" ], "x-enumDescriptions": { "MASTERCARD": "MasterCard network.", "DISCOVER": "Discover network.", "VISA": "Visa network.", "AMEX": "American Express network." } }, "description": "Allowed card networks." }, "billing_address_required": { "type": "boolean", "description": "Whether billing address is required." }, "assurance_details_required": { "type": "boolean", "description": "Whether assurance details are required." }, "billing_address_parameters": { "$ref": "#/components/schemas/googlepay_billing_address_parameters" } } }, "googlepay_tokenization_parameters": { "type": "object", "title": "Tokenization Parameters", "description": "Parameters for configuring payment tokenization with the gateway.", "properties": { "gateway": { "type": "string", "minLength": 2, "maxLength": 255, "pattern": "^[a-zA-Z0-9_-]+$", "description": "Payment gateway name." }, "gateway_merchant_id": { "allOf": [ { "$ref": "#/components/schemas/account_id-2" }, { "description": "Gateway merchant ID." } ] } } }, "googlepay_tokenization_specification": { "type": "object", "title": "Tokenization Specification", "description": "Specification for payment method tokenization in Google Pay.", "properties": { "type": { "type": "string", "enum": [ "PAYMENT_GATEWAY" ], "x-enumDescriptions": { "PAYMENT_GATEWAY": "Tokenization using a payment gateway." }, "description": "Tokenization type." }, "parameters": { "$ref": "#/components/schemas/googlepay_tokenization_parameters" } } }, "googlepay_payment_method": { "type": "object", "title": "Payment Method", "description": "Configuration for a specific payment method supported by Google Pay.", "properties": { "type": { "type": "string", "enum": [ "CARD" ], "x-enumDescriptions": { "CARD": "Card payment method." }, "description": "Type of payment method." }, "parameters": { "$ref": "#/components/schemas/googlepay_payment_method_parameters" }, "tokenization_specification": { "$ref": "#/components/schemas/googlepay_tokenization_specification" } } }, "googlepay_merchant_info": { "type": "object", "title": "Merchant Information", "description": "Merchant-specific information required for Google Pay integration.", "properties": { "merchant_origin": { "type": "string", "minLength": 4, "maxLength": 253, "pattern": "^[a-zA-Z0-9.-]+$", "description": "Merchant origin." }, "merchant_id": { "allOf": [ { "$ref": "#/components/schemas/account_id-2" }, { "description": "Merchant ID." } ] }, "googlepay_partner_domain_verification_jwt": { "type": "string", "minLength": 10, "maxLength": 2000, "pattern": "^[A-Za-z0-9_.-]+$", "description": "JWT token used for Google Pay partner domain verification to authenticate the merchant's domain." } } }, "googlepay_config": { "type": "object", "title": "Google Pay Config", "description": "Configuration details for Google Pay payment method.", "properties": { "eligible": { "type": "boolean", "description": "Indicates if Google Pay is eligible." }, "merchant_country": { "allOf": [ { "$ref": "#/components/schemas/country_code-2" }, { "description": "Merchant country code." } ] }, "api_version": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Google Pay API version." }, "api_version_minor": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Google Pay API minor version." }, "allowed_payment_methods": { "type": "array", "description": "Allowed payment methods for Google Pay.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/googlepay_payment_method" } }, "merchant_info": { "$ref": "#/components/schemas/googlepay_merchant_info" } } }, "googlepay": { "type": "object", "title": "Eligibility Response for GooglePay", "description": "Response for GooglePay.", "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "properties": { "config": { "$ref": "#/components/schemas/googlepay_config" } } } ] }, "card_brand-2": { "description": "The card brand.", "type": "string", "enum": [ "AMEX", "CB_NATIONALE", "CETELEM", "COFIDIS", "COFINOGA", "CHINA_UNION_PAY", "DELTA", "DISCOVER", "ELECTRON", "ELO", "HIPER", "HIPERCARD", "JCB", "MAESTRO", "MASTER_CARD", "SOLO", "STAR", "SWITCH", "VISA", "GE", "RUPAY", "SYNCHRONY", "DINERS", "GIROCARD", "CARNET", "V_PAY" ], "x-enumDescriptions": { "AMEX": "The American Express payment network.", "CB_NATIONALE": "Carte Bleue Nationale (CBN), a major debit card payment system operating in France.", "CETELEM": "Cetelem, a brand of BNP Paribas Personal Finance, is a French financial institution specializing in financing individuals consumer credit activities.", "COFIDIS": "Cofidis is a French company, now majority owned by the Crédit Mutuel, based in Villeneuve-d'Ascq, that offers a payment method that allows you to make bank card payments in 3 or 4 times, PayPal payment in 4 times, or one Euro consumer credit.", "COFINOGA": "Cofinoga, a brand of BNP Paribas Personal Finance, is a credit specialist in France. It offers a card that allows you to pay for credit online purchases.", "CHINA_UNION_PAY": "China UnionPay (CUP) or UnionPay International (UPI) is a Chinese financial services corporation headquartered in Shanghai, China. It provides bank card services and a major card scheme in mainland China.", "DELTA": "The Delta Air Lines online payment network.", "DISCOVER": "The Discover Financial Services (DFS) banking and payment services capability network.", "ELECTRON": "The Visa Electron debit card payment network. It's offered by issuing banks in every country with the exception of Canada, Australia, Argentina, Ireland, and the United States.", "ELO": "The Brazilian Elo card payment network.", "HIPER": "The Hiper - Ingenico ePayment network.", "HIPERCARD": "The Brazilian Hipercard payment network that's widely accepted in the retail market.", "JCB": "The Japan Credit Bureau (JCB) card payment network.", "MAESTRO": "The Maestro debit card payment network owned by Mastercard.", "MASTER_CARD": "The Mastercard Incorporated payment network.", "SOLO": "The Hatton National BankFinance's SOLO digital wallet payment network.", "STAR": "The STAR payment network.", "SWITCH": "The Switch payment network.", "VISA": "The Visa Inc. payment network.", "GE": "The GE Credit Union 3Point card payment network.", "RUPAY": "The RuPay payment network.", "SYNCHRONY": "The Synchrony Financial (SYF) payment network.", "DINERS": "The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services.", "GIROCARD": "Girocard is an interbank network and debit card service connecting virtually all German ATMs and banks.", "CARNET": "Carnet is a fuel card.", "V_PAY": "V Pay is a Single Euro Payments Area (SEPA) debit card for use in Europe, issued by Visa Europe." } }, "card_vendor": { "type": "object", "title": "Card Vendor", "description": "Configuration for a specific card vendor or network.", "properties": { "network": { "allOf": [ { "$ref": "#/components/schemas/card_brand-2" }, { "description": "The card network identifier." } ] }, "eligible": { "type": "boolean", "description": "Indicates if the vendor is eligible." }, "can_be_vaulted": { "type": "boolean", "description": "Indicates if the vendor's payment method can be saved for future use." }, "branded": { "type": "boolean", "description": "Indicates if the vendor has branded customization." } }, "required": [ "network", "eligible", "can_be_vaulted", "branded" ] }, "advanced_cards": { "type": "object", "title": "Advanced Cards Config", "description": "Configuration details for advanced card payment methods including credit and debit card processing capabilities.", "properties": { "can_be_vaulted": { "type": "boolean", "description": "Indicates if the payment method can be saved for future use." }, "supports_installments": { "type": "boolean", "description": "Indicates if installment payment option is available." }, "vendors": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Payment card vendors configuration.", "items": { "$ref": "#/components/schemas/card_vendor" } } } }, "basic_cards": { "type": "object", "title": "Basic Cards Config", "description": "Configuration details for basic card payment methods including credit and debit card processing capabilities.", "properties": { "can_be_vaulted": { "type": "boolean", "description": "Indicates if the payment method can be saved for future use." }, "supports_installments": { "type": "boolean", "description": "Indicates if installment payment option is available." }, "guest_enabled": { "type": "boolean", "description": "Indicates if guest checkout is enabled for this payment method." }, "supports_inline_presentation_mode": { "type": "boolean", "description": "Indicates if inline presentation mode is supported for this payment method." } } }, "ach": { "type": "object", "title": "Response for ACH", "description": "Response for ACH payment method.", "properties": { "can_be_vaulted": { "description": "Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.", "type": "boolean", "default": false } } }, "payment_methods": { "title": "Payment Methods", "description": "List of payment methods.", "type": "object", "properties": { "paypal": { "allOf": [ { "$ref": "#/components/schemas/paypal" }, { "description": "PayPal payment method." } ] }, "venmo": { "allOf": [ { "$ref": "#/components/schemas/venmo" }, { "description": "Venmo payment method." } ] }, "paypal_credit": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "PayPal Credit payment method." } ] }, "paypal_pay_later": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "PayPal Pay Later payment method." } ] }, "ideal": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Ideal payment method." } ] }, "apple_pay": { "allOf": [ { "$ref": "#/components/schemas/applepay" }, { "description": "ApplePay payment method." } ] }, "google_pay": { "allOf": [ { "$ref": "#/components/schemas/googlepay" }, { "description": "GooglePay payment method." } ] }, "advanced_cards": { "allOf": [ { "$ref": "#/components/schemas/advanced_cards" }, { "description": "Represents card payments, specifically for Advanced Credit and Debit Card Processing." } ] }, "basic_cards": { "allOf": [ { "$ref": "#/components/schemas/basic_cards" }, { "description": "Represents card payments, specifically for Basic Credit and Debit Card Processing." } ] }, "ach": { "allOf": [ { "$ref": "#/components/schemas/ach" }, { "description": "ACH payment method." } ] }, "blik": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Blik payment method." } ] }, "p24": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "P24 payment method." } ] }, "eps": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Eps payment method." } ] }, "bancontact": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Bancontact payment method." } ] }, "swish": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Swish payment method." } ] }, "klarna": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Klarna payment method." } ] }, "mbway": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "MB WAY payment method." } ] }, "boletobancario": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Boleto Bancario payment method." } ] }, "twint": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "TWINT payment method." } ] }, "bizum": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Bizum payment method." } ] }, "afterpay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Afterpay payment method." } ] }, "zip": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Zip payment method." } ] }, "satispay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Satispay payment method." } ] }, "trustly": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Trustly payment method." } ] }, "mybank": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "MyBank payment method." } ] }, "alipay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Alipay payment method." } ] }, "wechatpay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "WeChatpay payment method." } ] }, "grabpay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Grabpay payment method." } ] }, "oxxo_pay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Oxxo Pay payment method." } ] }, "multibanco": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Multibanco payment method." } ] }, "verkkopankki": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Verkkopankki payment method." } ] }, "bancomatpay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Bancomatpay payment method." } ] }, "payu": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "PayU payment method." } ] }, "blik_pay_later": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Blik Pay Later payment method." } ] }, "floa_pay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Floa payment method." } ] }, "dragonpay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "DragonPay payment method." } ] }, "paysera": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Paysera payment method." } ] }, "lithuania_banks": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Lithuania Banks payment method." } ] }, "latvia_banks": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Latvia Banks payment method." } ] }, "thailand_banks": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Thailand Banks payment method." } ] }, "estonia_banks": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Estonia Banks payment method." } ] }, "alfamart": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Alfamart payment method." } ] }, "doku": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Doku payment method." } ] }, "indonesia_banks": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Indonesia Banks payment method." } ] }, "indomaret": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Indomaret payment method." } ] }, "jenius_pay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Jenius Pay payment method." } ] }, "kredivo": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Kredivo payment method." } ] }, "linkaja": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "LinkAja payment method." } ] }, "ovo": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "OVO payment method." } ] }, "paysafecard": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Paysafecard payment method." } ] }, "skrill": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Skrill payment method." } ] }, "wero": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Wero payment method." } ] }, "fiuu_cash": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "FIUU Cash payment method." } ] }, "gopay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "GoPay payment method." } ] }, "fpx": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "FPX payment method." } ] }, "pay_upon_invoice": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Pay Upon Invoice payment method." } ] }, "pix_international": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "PIX International payment method." } ] }, "scalapay": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Scalapay payment method." } ] }, "crypto": { "allOf": [ { "$ref": "#/components/schemas/payment_method_common" }, { "description": "Crypto as Alternate payment method." } ] } } }, "find_eligible_methods_response": { "title": "paypal_response", "description": "Eligible payment methods.", "type": "object", "properties": { "eligible_methods": { "allOf": [ { "$ref": "#/components/schemas/payment_methods" }, { "description": "List of payment methods that are eligible." } ] }, "supplementary_data": { "title": "Supplementary Data", "description": "Contains supplementary data related to the eligibility check.", "type": "object", "properties": { "buyer_country_code": { "allOf": [ { "$ref": "#/components/schemas/country_code-2" }, { "description": "Returns a country_code which is derived from the buyer's country." } ] } } } } } }, "responses": { "default_response": { "description": "Default response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "generic": { "summary": "Default response.", "description": "Example catch all response, should not be encountered in practice.", "value": { "name": "INTERNAL_SERVER_ERROR", "debug_id": "b1d1f06c7246c", "message": "An internal server error has occurred." } } } } } }, "401_error_response": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "generic": { "summary": "Generic 'Unauthorized' error.", "description": "Example response for unauthorized request.", "value": { "name": "AUTHENTICATION_FAILURE", "debug_id": "b1d1f06c7246c", "message": "Authentication failed due to missing Authorization header, or invalid authentication credentials." } } } } } }, "403_error_response": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "generic": { "summary": "Generic 'Forbidden' error.", "description": "Example response for a forbidden request.", "value": { "name": "NOT_AUTHORIZED", "debug_id": "b1d1f06c7246c", "message": "Authorization failed due to insufficient permissions." } } } } } }, "404_error_response": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "generic": { "summary": "Generic 'Not Found' error.", "description": "Example response for a request to a resource that does not exist.", "value": { "name": "RESOURCE_NOT_FOUND", "debug_id": "b1d1f06c7246c", "message": "The specified resource does not exist." } } } } } }, "500_error_response": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "generic": { "summary": "Generic internal server error.", "description": "Example response for a request that fails for reasons internal to the server.", "value": { "name": "INTERNAL_SERVER_ERROR", "debug_id": "b1d1f06c7246c", "message": "An internal server error has occurred." } } } } } }, "204_response": { "description": "No Content." } }, "callbacks": { "authorization_created": { "authorizations/{$request.path.authorization_id}": { "post": { "summary": "Authorization created notification", "description": "Notification sent when the authorization is created.", "operationId": "authorizations.created.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Authorization Created Event", "description": "Webhook event notification for authorization created.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.AUTHORIZATION.CREATED" ], "x-enumDescriptions": { "PAYMENT.AUTHORIZATION.CREATED": "A payment authorization was created." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/authorization-2" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "authorization_created": { "summary": "Authorization created event", "description": "Webhook notification when the authorization is created.", "value": { "id": "WH-5VE77420C3914002P-5G649181HP975980P", "event_version": "1.0", "create_time": "2022-10-27T22:00:21.590Z", "resource_type": "authorization", "resource_version": "2.0", "event_type": "PAYMENT.AUTHORIZATION.CREATED", "summary": "A successful payment authorization was created for $ 10.0 USD", "resource": { "amount": { "value": "10.00", "currency_code": "USD" }, "seller_protection": { "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ], "status": "ELIGIBLE" }, "supplementary_data": { "related_ids": { "order_id": "91A92299SF4077927" } }, "update_time": "2022-10-27T22:00:17Z", "create_time": "2022-10-27T22:00:17Z", "expiration_time": "2022-11-25T22:00:17Z", "links": [ { "method": "GET", "rel": "self", "href": "https://api-m.paypal.com/v2/payments/authorizations/91T13242G72341823" }, { "method": "POST", "rel": "capture", "href": "https://api-m.paypal.com/v2/payments/authorizations/91T13242G72341823/capture" }, { "method": "POST", "rel": "void", "href": "https://api-m.paypal.com/v2/payments/authorizations/91T13242G72341823/void" }, { "method": "POST", "rel": "reauthorize", "href": "https://api-m.paypal.com/v2/payments/authorizations/91T13242G72341823/reauthorize" } ], "id": "91T13242G72341823", "status": "CREATED" }, "links": [ { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-5VE77420C3914002P-5G649181HP975980P", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-5VE77420C3914002P-5G649181HP975980P/resend", "rel": "resend", "method": "POST" } ] } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "capture_completed": { "captures/{$request.path.capture_id}": { "post": { "summary": "Capture completed notification", "description": "Notification sent when the capture is completed.", "operationId": "captures.completed.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Capture Completed Event", "description": "Webhook event notification for capture completed.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.CAPTURE.COMPLETED" ], "x-enumDescriptions": { "PAYMENT.CAPTURE.COMPLETED": "A payment capture was completed." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/capture-2" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "capture_completed": { "summary": "Capture completed event", "description": "Webhook notification when the capture is completed.", "value": { "id": "WH-152442318H6474839-1HN0997948621344U", "event_version": "1.0", "create_time": "2022-10-27T22:32:49.870Z", "resource_type": "capture", "resource_version": "2.0", "event_type": "PAYMENT.CAPTURE.COMPLETED", "summary": "Payment completed for $ 10.0 USD", "resource": { "amount": { "value": "10.00", "currency_code": "USD" }, "seller_protection": { "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ], "status": "ELIGIBLE" }, "supplementary_data": { "related_ids": { "order_id": "28U14622MW998902M" } }, "update_time": "2022-10-27T22:32:45Z", "create_time": "2022-10-27T22:32:45Z", "final_capture": true, "seller_receivable_breakdown": { "paypal_fee": { "value": "0.84", "currency_code": "USD" }, "gross_amount": { "value": "10.00", "currency_code": "USD" }, "net_amount": { "value": "9.16", "currency_code": "USD" } }, "links": [ { "method": "GET", "rel": "self", "href": "https://api-m.paypal.com/v2/payments/captures/27C890397M291943E" }, { "method": "POST", "rel": "refund", "href": "https://api-m.paypal.com/v2/payments/captures/27C890397M291943E/refund" }, { "method": "GET", "rel": "up", "href": "https://api-m.paypal.com/v2/checkout/orders/28U14622MW998902M" } ], "id": "27C890397M291943E", "status": "COMPLETED" }, "links": [ { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-152442318H6474839-1HN0997948621344U", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-152442318H6474839-1HN0997948621344U/resend", "rel": "resend", "method": "POST" } ] } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "capture_declined": { "captures/{$request.path.capture_id}/declined": { "post": { "summary": "Capture declined notification", "description": "Notification sent when capture for authorization is declined.", "operationId": "captures.declined.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Capture Declined Event", "description": "Webhook event notification for capture declined.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.CAPTURE.DECLINED" ], "x-enumDescriptions": { "PAYMENT.CAPTURE.DECLINED": "A payment capture was declined." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/capture-2" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "capture_declined": { "summary": "Capture declined event", "description": "Webhook notification when capture for authorization is declined.", "value": { "id": "WH-30Y09481LL7353048-6K675100AV972021E", "create_time": "2022-09-21T18:41:07.071Z", "event_type": "PAYMENT.CAPTURE.DECLINED", "event_version": "1.0", "resource_type": "capture", "resource_version": "2.0", "summary": "A payment capture for $ 50.0 USD was declined.", "resource": { "id": "40222075YX552741V", "status": "DECLINED", "amount": { "currency_code": "USD", "value": "50.00" }, "final_capture": false, "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "disbursement_mode": "INSTANT", "seller_receivable_breakdown": { "gross_amount": { "currency_code": "USD", "value": "50.00" }, "paypal_fee": { "currency_code": "USD", "value": "2.24" }, "net_amount": { "currency_code": "USD", "value": "47.76" } }, "invoice_id": "1663785654", "supplementary_data": { "related_ids": { "order_id": "6AY135578D653613P", "authorization_id": "3U5721406T774122W" } }, "create_time": "2022-09-21T18:40:22Z", "update_time": "2022-09-21T18:41:03Z", "links": [ { "href": "https://api-m.paypal.com/v2/payments/captures/40222075YX552741V", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v2/payments/authorizations/3U5721406T774122W", "rel": "up", "method": "GET" } ] }, "links": [ { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-30Y09481LL7353048-6K675100AV972021E", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-30Y09481LL7353048-6K675100AV972021E/resend", "rel": "resend", "method": "POST" } ] } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "capture_pending_kyc_incomplete": { "captures/{$request.path.capture_id}/pending": { "post": { "summary": "Capture pending KYC incomplete notification", "description": "Notification sent when capture a sale order for a merchant with incomplete KYC status, and the partner is enabled for Progressive Onboarding.", "operationId": "captures.pending.kyc_incomplete.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Capture Pending KYC Incomplete Event", "description": "Webhook event notification for capture pending due to incomplete KYC.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.CAPTURE.PENDING" ], "x-enumDescriptions": { "PAYMENT.CAPTURE.PENDING": "A payment capture is pending due to incomplete KYC." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/capture-2" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "capture_pending_kyc_incomplete": { "summary": "Capture pending KYC incomplete event", "description": "Webhook notification when capture a sale order for a merchant with incomplete KYC status.", "value": { "id": "WH-36845715LW9646800-7FJ097926K9003132", "event_version": "1.0", "create_time": "2025-07-08T22:07:56.096Z", "resource_type": "capture", "resource_version": "2.0", "event_type": "PAYMENT.CAPTURE.PENDING", "summary": "Payment pending for $ 80.0 USD", "resource": { "id": "30N459334R4656637", "amount": { "currency_code": "USD", "value": "80.00" }, "final_capture": true, "seller_protection": { "status": "NOT_ELIGIBLE" }, "disbursement_mode": "INSTANT", "status": "PENDING", "status_details": { "reason": "KYC_HOLD" }, "processor_response": { "avs_code": "A", "cvv_code": "S", "response_code": "0000" }, "supplementary_data": { "related_ids": { "order_id": "9XF68199B43440616" } }, "payee": { "merchant_id": "972Y8QJUSCK3W" }, "create_time": "2025-07-08T22:07:50Z", "update_time": "2025-07-08T22:07:50Z", "links": [ { "href": "https://msmaster1intdev52.dev52.cbf.dev.paypalinc.com:25137/v2/payments/captures/30N459334R4656637", "rel": "self", "method": "GET" }, { "href": "https://msmaster1intdev52.dev52.cbf.dev.paypalinc.com:25137/v2/payments/captures/30N459334R4656637/refund", "rel": "refund", "method": "POST" }, { "href": "https://msmaster1intdev52.dev52.cbf.dev.paypalinc.com:25137/v2/checkout/orders/9XF68199B43440616", "rel": "up", "method": "GET" } ], "network_transaction_reference": { "id": "752835256460198", "network": "VISA" } }, "links": [ { "href": "https://msmaster1intdev52.dev52.cbf.dev.paypalinc.com:14084/v1/notifications/webhooks-events/WH-36845715LW9646800-7FJ097926K9003132", "rel": "self", "method": "GET" }, { "href": "https://msmaster1intdev52.dev52.cbf.dev.paypalinc.com:14084/v1/notifications/webhooks-events/WH-36845715LW9646800-7FJ097926K9003132/resend", "rel": "resend", "method": "POST" } ] } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "authorization_voided": { "authorizations/{$request.path.authorization_id}/void": { "post": { "summary": "Authorization voided notification", "description": "Notification sent when the authorization is voided.", "operationId": "authorizations.voided.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Authorization Voided Event", "description": "Webhook event notification for authorization voided.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.AUTHORIZATION.VOIDED" ], "x-enumDescriptions": { "PAYMENT.AUTHORIZATION.VOIDED": "A payment authorization was voided." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/authorization-2" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "authorization_voided": { "summary": "Authorization voided event", "description": "Webhook notification when the authorization is voided.", "value": { "id": "WH-30Y09481LL7353048-6K675100AV972020E", "create_time": "2022-09-21T18:41:07.071Z", "event_type": "PAYMENT.AUTHORIZATION.VOIDED", "event_version": "1.0", "resource_type": "authorization", "resource_version": "2.0", "summary": "A payment authorization was voided", "resource": { "id": "3C679366HH908993F", "status": "VOIDED", "amount": { "currency_code": "USD", "value": "100.00" }, "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "supplementary_data": { "related_ids": { "order_id": "6AY135578D653613P" } }, "expiration_time": "2022-10-20T18:40:22Z", "create_time": "2022-09-21T18:40:22Z", "update_time": "2022-09-21T18:41:03Z", "links": [ { "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F", "rel": "self", "method": "GET" } ] }, "links": [ { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-30Y09481LL7353048-6K675100AV972020E", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-30Y09481LL7353048-6K675100AV972020E/resend", "rel": "resend", "method": "POST" } ] } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "authorization_voided_expired": { "authorizations/{$request.path.authorization_id}/void-expired": { "post": { "summary": "Authorization voided due to expiry notification", "description": "Notification sent when the authorization is voided due to expiry.", "operationId": "authorizations.voided.expired.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Authorization Voided Expired Event", "description": "Webhook event notification for authorization voided due to expiry.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.AUTHORIZATION.VOIDED" ], "x-enumDescriptions": { "PAYMENT.AUTHORIZATION.VOIDED": "A payment authorization was voided due to expiration." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/authorization-2" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "authorization_voided_expired": { "summary": "Authorization voided due to expiry event", "description": "Webhook notification when the authorization is voided due to expiry.", "value": { "id": "WH-30Y09481LL7353048-6K675100AV972020E", "create_time": "2022-09-21T18:41:07.071Z", "event_type": "PAYMENT.AUTHORIZATION.VOIDED", "event_version": "1.0", "resource_type": "authorization", "resource_version": "2.0", "summary": "A payment authorization was expired", "resource": { "id": "3C679366HH908993F", "status": "VOIDED", "amount": { "currency_code": "USD", "value": "100.00" }, "seller_protection": { "status": "ELIGIBLE", "dispute_categories": [ "ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION" ] }, "supplementary_data": { "related_ids": { "order_id": "6AY135578D653613P" } }, "expiration_time": "2022-10-20T18:40:22Z", "create_time": "2022-09-21T18:40:22Z", "update_time": "2022-09-21T18:41:03Z", "links": [ { "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F", "rel": "self", "method": "GET" } ] }, "links": [ { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-30Y09481LL7353048-6K675100AV972020E", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-30Y09481LL7353048-6K675100AV972020E/resend", "rel": "resend", "method": "POST" } ] } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "capture_refunded": { "captures/{$request.path.capture_id}/refunds": { "post": { "summary": "Capture refunded notification", "description": "Notification sent when a capture is refunded.", "operationId": "captures.refunded.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Capture Refunded Event", "description": "Webhook event notification for capture refunded.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.CAPTURE.REFUNDED" ], "x-enumDescriptions": { "PAYMENT.CAPTURE.REFUNDED": "A payment capture was refunded." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/refund" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "capture_refunded": { "summary": "Capture refunded event", "description": "Webhook notification when a capture is refunded.", "value": { "id": "WH-3UE850097C805102A-18305212AB1299210", "event_version": "1.0", "create_time": "2022-10-27T22:34:27.088Z", "resource_type": "refund", "resource_version": "2.0", "event_type": "PAYMENT.CAPTURE.REFUNDED", "summary": "A $ 5.0 USD capture payment was refunded", "resource": { "seller_payable_breakdown": { "total_refunded_amount": { "value": "5.00", "currency_code": "USD" }, "paypal_fee": { "value": "0.00", "currency_code": "USD" }, "gross_amount": { "value": "5.00", "currency_code": "USD" }, "net_amount": { "value": "5.00", "currency_code": "USD" } }, "amount": { "value": "5.00", "currency_code": "USD" }, "update_time": "2022-10-27T15:34:22-07:00", "create_time": "2022-10-27T15:34:22-07:00", "invoice_id": "1666910062", "links": [ { "method": "GET", "rel": "self", "href": "https://api-m.paypal.com/v2/payments/refunds/3NG36268BJ600681V" }, { "method": "GET", "rel": "up", "href": "https://api-m.paypal.com/v2/payments/captures/27C890397M291943E" } ], "id": "3NG36268BJ600681V", "note_to_payer": "Defective product", "status": "COMPLETED" }, "links": [ { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-3UE850097C805102A-18305212AB1299210", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-3UE850097C805102A-18305212AB1299210/resend", "rel": "resend", "method": "POST" } ] } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "refund_completed": { "refunds/{$request.path.refund_id}": { "post": { "summary": "Refund completed notification", "description": "Notification sent when non referenced credit request have been processed.", "operationId": "refunds.completed.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Refund Completed Event", "description": "Webhook event notification for refund completed.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "event_version": { "type": "string", "description": "The version of the event.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "create_time": { "description": "The date and time when the webhook event notification was created.", "allOf": [ { "$ref": "#/components/schemas/date_time" } ] }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "minLength": 1, "maxLength": 100, "pattern": "^.*$" }, "resource_version": { "type": "string", "description": "The version of the resource.", "minLength": 1, "maxLength": 50, "pattern": "^.*$" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "enum": [ "PAYMENT.REFUND.COMPLETED" ], "x-enumDescriptions": { "PAYMENT.REFUND.COMPLETED": "A payment refund was completed." } }, "summary": { "type": "string", "description": "A summary description for the event notification.", "minLength": 1, "maxLength": 500, "pattern": "^.*$" }, "resource": { "allOf": [ { "$ref": "#/components/schemas/refund" } ] }, "links": { "type": "array", "description": "An array of request-related HATEOAS links.", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description-2" } } } }, "examples": { "refund_completed": { "summary": "Refund completed event", "description": "Webhook notification when non referenced credit request have been processed.", "value": { "id": "WH-COC11055RA711503B-4YM959094A144403T", "create_time": "2019-12-05T21:21:49.000Z", "event_type": "PAYMENT.REFUND.COMPLETED", "resource_type": "refund", "resource_version": "2.0", "summary": "Non Referenced Credit Completed", "resource": { "id": "1JU08902781691411", "amount": { "value": "10.99", "currency_code": "USD" }, "status": "COMPLETED", "note_to_payer": "Defective product", "seller_payable_breakdown": { "gross_amount": { "value": "10.99", "currency_code": "USD" }, "paypal_fee": { "value": "0", "currency_code": "USD" }, "net_amount": { "value": "10.99", "currency_code": "USD" }, "total_refunded_amount": { "value": "10.99", "currency_code": "USD" } }, "create_time": "2019-11-18T11:24:19Z", "update_time": "2018-11-18T11:24:19Z", "links": [ { "rel": "self", "method": "GET", "href": "https://api.paypal.com/v2/payments/refunds/1JU08902781691411" } ] }, "links": [ { "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-COC11055RA711503B-4YM959094A144403T", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-COC11055RA711503B-4YM959094A144403T/resend", "rel": "resend", "method": "POST" } ], "event_version": "1.0" } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/event_type", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "verification_verified": { "verifications/{$request.path.id}": { "post": { "summary": "Payment verification verified notification", "description": "Notification sent when payment verification has been verified.", "operationId": "verifications.verified.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Verification Verified Event", "description": "Webhook event notification for payment verification verified.", "properties": { "context_id": { "type": "string", "description": "The context ID for the payment verification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "idempotent": { "type": "boolean", "description": "Indicates if the operation is idempotent." } } }, "examples": { "verification_verified": { "summary": "Payment verification verified event", "description": "Webhook notification when payment verification has been verified.", "value": { "context_id": "50K38686VU458603L", "payment": { "payment_id": "50K38686VU458603L", "status": "COMPLETED", "intent": "VERIFICATION", "payment_source": { "card": { "name": "**********", "expiry": "2029-02", "last_digits": "9107", "type": "DEBIT", "bin_details": { "bin": "41252417", "issuing_bank": "BPCE", "bin_country_code": "FR", "products": [ "ELECTRONIC", "GOLD", "CONSUMER", "NON_ELECTRONIC", "CASH_WITHDRAWAL" ] }, "available_networks": [ "VISA" ], "billing_address": { "address_line_1": "**********", "admin_area_2": "**********", "postal_code": "**********", "country_code": "FR" } } }, "verification": { "verification_status": "VERIFIED", "verification_id": "8P908649EK0538737", "network_transaction_reference": { "id": "385195638562731", "network": "VISA" } }, "amount": { "currency_code": "EUR", "value": "0.00" }, "transaction_context": { }, "links": [ { "href": "https://api.paypal.com/v2/payments/payment/50K38686VU458603L", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/verification/8P908649EK0538737", "rel": "self", "method": "GET" } ] }, "idempotent": false } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/payment", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } }, "verification_failed": { "verifications/{$request.path.id}/failed": { "post": { "summary": "Payment verification failed notification", "description": "Notification sent when payment verification has failed.", "operationId": "verifications.failed.callback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Verification Failed Event", "description": "Webhook event notification for payment verification failed.", "properties": { "context_id": { "type": "string", "description": "The context ID for the payment verification.", "minLength": 1, "maxLength": 255, "pattern": "^.*$" }, "idempotent": { "type": "boolean", "description": "Indicates if the operation is idempotent." } } }, "examples": { "verification_failed": { "summary": "Payment verification failed event", "description": "Webhook notification when payment verification has failed.", "value": { "context_id": "3DT72694M7836131K", "payment": { "payment_id": "3DT72694M7836131K", "status": "COMPLETED", "intent": "VERIFICATION", "payment_source": { "card": { "name": "**********", "expiry": "2029-02", "last_digits": "6514", "type": "DEBIT", "bin_details": { "bin": "47666427", "issuing_bank": "CAIXABANK SA", "bin_country_code": "ES", "products": [ "CONSUMER" ] }, "available_networks": [ "VISA" ], "billing_address": { "address_line_1": "**********", "admin_area_2": "**********", "postal_code": "**********", "country_code": "FR" } } }, "verification": { "verification_status": "FAILED", "verification_id": "3Y969738N8657733W" }, "amount": { "currency_code": "EUR", "value": "0.00" }, "transaction_context": { }, "links": [ { "href": "https://api.paypal.com/v2/payments/payment/3DT72694M7836131K", "rel": "self", "method": "GET" }, { "href": "https://api.paypal.com/v2/payments/verification/3Y969738N8657733W", "rel": "self", "method": "GET" } ] }, "idempotent": false } } } } } }, "responses": { "204": { "description": "Your server implementation should return this HTTP status code if the data was received successfully." }, "400": { "description": "Your server should return this HTTP status code if the request is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": { "invalid_request": { "summary": "Invalid webhook request.", "description": "Request with malformed data.", "value": { "name": "INVALID_REQUEST", "debug_id": "b1d1f06c7246c", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "/payment", "location": "body", "issue": "INVALID_PARAMETER_SYNTAX", "description": "The value of a field does not conform to the expected format." } ] } } } } } }, "500": { "$ref": "#/components/responses/500_error_response" } } } } } } } }