openapi: 3.2.0 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.12" servers: - url: https://api-m.sandbox.paypal.com description: PayPal API Sandbox 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 - $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 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_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: authorizations_capture: summary: Capture Authorized Payment description: Captures an authorized payment, by ID. value: 0VF52814937998046 authorizations_capture_200_idempotent_response: summary: Capture Authorized Payment - 200 idempotent response description: Captures an authorized payment, by ID. value: 6DR965477U7140544 authorizations_capture_empty_request: summary: Capture Authorized Payment with an empty request description: Captures an authorized payment, by ID. value: 6DR965477U7140544 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: 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/authorizations_capture 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/authorizations_capture_empty_request - 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/authorizations_capture_with_prefer_header - 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/authorizations_capture_200_idempotent_response - 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 - $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 - $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 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: 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 "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 id: customer_4029352050 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 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 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 payment_tokens: - id: fgh6561t payment_source: paypal: email_address: john.doe@example.com links: - rel: self href: https://api-m.paypal.com/v3/vault/payment-tokens/fgh656 method: GET - rel: delete href: https://api-m.paypal.com/v3/vault/payment-tokens/fgh656 method: DELETE - id: hg654s1t payment_source: venmo: user_name: johndoe links: - rel: self href: https://api-m.paypal.com/v3/vault/payment-tokens/hg654s method: GET - rel: delete href: https://api-m.paypal.com/v3/vault/payment-tokens/hg654s method: DELETE "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 - $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 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 "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: /api/oauth-proxy 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 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 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 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 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 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 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 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 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/money" - description: The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured. 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 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 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" 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" 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 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" 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 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 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 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 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. id: description: The unique ID for a customer in merchant's or partner's system of records. type: string minLength: 1 maxLength: 36 pattern: ^[0-9a-zA-Z_-]+$ 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 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 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" 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 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 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 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. payer_base: title: payer_base description: The customer who approves and pays for the order. The customer is also known as the payer. type: object properties: email_address: allOf: - $ref: "#/components/schemas/email" - description: The email address of the payer. payer_id: allOf: - $ref: "#/components/schemas/account_id-2" - description: The PayPal-assigned ID for the payer. readOnly: true venmo_payment_token_info: title: venmo_payment_token description: Payment Token info for Venmo payment source. type: object properties: user_name: description: The Venmo username, as chosen by the user. type: string minLength: 1 maxLength: 50 pattern: ^[-a-zA-Z0-9_]*$ payment_token: title: payment_token description: Vaulted instrument for a payment-method. type: object properties: id: title: id description: The PayPal-generated ID for the vault token. type: string minLength: 7 maxLength: 36 pattern: ^[0-9a-zA-Z_-]+$ payment_source: title: The vaulted payment method details description: The vaulted payment method details. type: object properties: paypal: allOf: - $ref: "#/components/schemas/payer_base" - not: required: - payer_id venmo: $ref: "#/components/schemas/venmo_payment_token_info" links: description: An array of related [HATEOAS links](/api/rest/responses/#hateoas). type: array minItems: 1 maxItems: 32 readOnly: true items: $ref: "#/components/schemas/link_description" find_eligible_methods_response: title: paypal_response description: Eligible payment methods along with applicable vault tokens, if requested. type: object properties: eligible_methods: allOf: - $ref: "#/components/schemas/payment_methods" - description: List of payment methods that are eligible. payment_tokens: description: Payment tokens for vaulted instruments, if available. This object will be included only if include_vault_tokens is set to true in the request. type: array minItems: 1 maxItems: 64 items: allOf: - $ref: "#/components/schemas/payment_token" - description: Payment Token. 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 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 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 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 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 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 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 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 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" x-errors: - name: AUTH_CAPTURE_CURRENCY_MISMATCH message: Currency of capture must be the same as currency of authorization. description:
Verify the currency of the capture and try the request again. - name: AUTHENTICATION_FAILURE message: Authentication failed due to missing authorization header, or invalid authentication credentials. description:
Account validations failed for the user. - name: AUTHORIZATION_ALREADY_CAPTURED message: Authorization has already been captured. description:
If `final_capture` is set to to `true`, additional captures are not possible against the authorization. - name: AUTHORIZATION_DENIED message: A denied authorization cannot be captured. description:
You cannot capture a denied authorization. - name: AUTHORIZATION_EXPIRED message: An expired authorization cannot be captured. description:
You cannot capture an expired authorization. - name: AUTHORIZATION_VOIDED message: A voided authorization cannot be captured or reauthorized. description:
You cannot capture or reauthorize a voided authorization. - name: CANNOT_BE_ZERO_OR_NEGATIVE message: Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported. description:
Specify a different value and try the request again. - name: CANNOT_BE_VOIDED message: A reauthorization cannot be voided. Please void the original parent authorization. description:
You cannot void a reauthorized payment. You must void the original parent authorized payment. - name: REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK message: The requested action could not be performed, semantically incorrect, or failed business validation. description:
Refunds not allowed on this capture due to a chargeback on the card or bank. Please contact the payee to resolve the chargeback. - name: TRANSACTION_DISPUTED message: 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. description:
Refund for an amount less than the remaining transaction amount cannot be processed at this time because of an open dispute on the capture. Please visit the PayPal Resolution Center to view the details. - name: CAPTURE_FULLY_REFUNDED message: The capture has already been fully refunded. description:
You cannot capture additional refunds against this capture. - name: CARD_BRAND_NOT_SUPPORTED description: Refund cannot be issued to this card. The card brand `card_brand` is not supported. Please try again with another card. - name: CARD_BILLING_ADDRESS_COUNTRY_NOT_SUPPORTED description: Specified country is not currently supported for payment processing. - name: CARD_EXPIRED description: The card is expired. - name: CARD_ISSUER_COUNTRY_NOT_SUPPORTED description: Card is issued by a financial institution for a country (e.g. Cuba, Iran, North Korea, Syria) that is not current supported for payment processing. - name: CURRENCY_NOT_SUPPORTED_FOR_CARD_BRAND description: Currency not supported for card specified. Card is `card_brand`. Only `currency_code` is supported for this brand of card. - name: CURRENCY_NOT_SUPPORTED_FOR_COUNTRY description: Currency code not supported for card payments in your country. - name: DECIMAL_PRECISION message: The value of the field should not be more than two decimal places. description:
If the currency supports decimals, only two decimal place precision is supported. - name: DECIMALS_NOT_SUPPORTED message: Currency does not support decimals. description:
Currency does not support decimals. Please refer to https://developer.paypal.com/docs/api/reference/currency-codes/ for more information. - name: DUPLICATE_INVOICE_ID message: Requested invoice number has been previously captured. Possible duplicate transaction. description:
Payment for this invoice was already captured. - name: INSTRUMENT_DECLINED description: The instrument presented was either declined by the processor or bank, or it can't be used for this payment. - name: INVALID_ACCOUNT_STATUS message: Account validations failed for the user. description:
The user account could not be validated. - name: INVALID_CARD_NUMBER description: The card number is invalid. - name: INTERNAL_SERVER_ERROR message: An internal server error has occurred. description:
Try your request again later. - name: RATE_LIMIT_REACHED message: Too many requests. Blocked due to rate limiting. description: The rate limit was reached. - name: INVALID_CURRENCY_CODE message: Currency code should be a three-character ISO-4217 currency code. description:
Currency code is invalid or is not currently supported. Please refer https://developer.paypal.com/docs/api/reference/currency-codes/ for list of supported currency codes. - name: INVALID_INVOICE_ID message: Specified invoice_id does not exist. description:
Please check the invoice_id and try again. - name: INVALID_PARAMETER_SYNTAX message: The value of the field does not conform to the expected format. description:
Verify the specification for supported `pattern` and try the request again. - name: INVALID_PARAMETER_VALUE message: The value of a field is invalid. description:
Verify the specification for the allowed values and try the request again. - name: INVALID_PAYEE_ACCOUNT message: Payee account is invalid. description:
Verify the payee account information and try the request again. - name: INVALID_PLATFORM_FEES_AMOUNT message: The `platform_fees` amount cannot be greater than the capture amount. description:
Verify the `platform_fees` amount and try the request again. - name: PLATFORM_FEES_NOT_SUPPORTED message: The API Caller is not enabled to process transactions by specifying 'platform_fees'. Please work with your PayPal Account Manager to enable this option for your account. description:
Verify the API caller is enabled to process the transaction with platform fees. - name: DELAYED_DISBURSEMENT_NOT_SUPPORTED message: The API Caller is not enabled to process transactions by specifying disbursement mode as delayed. description:
Verify the API caller is enabled to process transaction with delayed disbursement. - name: INVALID_PLATFORM_FEES_ACCOUNT message: The specified platform_fees payee account is either invalid or account setup is incomplete. Please work with your PayPal Account Manager to enable this option for your account. description:
Verify the platform fee account set up is completed or correct account. - name: PAYEE_NOT_CONSENTED description: Payee does not have appropriate consent to allow the API caller to process this type of transaction on their behalf. Your current setup requires the 'payee' to provide a consent before this transaction can be processed successfully. - name: INVALID_RESOURCE_ID message: Specified resource ID does not exist. Please check the resource ID and try again. description:
Verify the resource ID and try the request again. - name: INVALID_STRING_LENGTH message: The value of a field is either too short or too long. description:
Verify the specification for the supported `min` and `max` values and try the request again. - name: INVALID_STRING_MAX_LENGTH message: The value of a field is too long. description:
The parameter string is too long. - name: MAX_CAPTURE_AMOUNT_EXCEEDED message: Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the order amount. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer. description:
Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits. - name: MAX_CAPTURE_COUNT_EXCEEDED message: Maximum number of allowable captures has been reached. No additional captures are possible for this authorization. Please contact customer service or your account manager to change the number of captures that be made for a given authorization. description:
You cannot make additional captures. - name: MAX_NUMBER_OF_REFUNDS_EXCEEDED message: You have exceeded the number of refunds that can be processed per capture. description:
Please contact customer support or your account manager to review the number of refunds that can be processed per capture. - name: MAX_REFUND_LIMIT_EXCEEDED description: Refund amount exceeds allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits. - name: MISSING_REQUIRED_PARAMETER message: A required field / parameter is missing. description:
Verify the specification for `required` fields and try the request again. - name: MULTIPLE_AUTHORIZATIONS_FOUND message: Cannot void multiple authorizations. description:
Specified invoice_id is associated with more than one authorization. - name: NOT_AUTHORIZED message: You do not have permission to access or perform operations on this resource. description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction. - name: PARTIAL_REFUND_NOT_ALLOWED message: You cannot do a refund for an amount less than the original capture amount. description:
Specify an amount equal to the capture amount or omit the `amount` object from the request. Then, try the request again. - name: PAYEE_ACCOUNT_LOCKED_OR_CLOSED message: Transaction could not complete because payee account is locked or closed. description:
To get more information about the status of the account, call Customer Support. - name: PAYEE_ACCOUNT_RESTRICTED message: Payee account is restricted. description:
To get more information about the status of the account, call Customer Support. - name: PAYER_ACCOUNT_LOCKED_OR_CLOSED message: The payer account cannot be used for this transaction. description:
Contact the payer for an alternate payment method. - name: PAYER_ACCOUNT_RESTRICTED message: Payer account is restricted. description:
To get more information about the status of the account, call Customer Support. - name: PAYER_CANNOT_PAY message: Payer cannot pay for this transaction. description:
Please contact the payer to find other ways to pay for this transaction. - name: PENDING_CAPTURE message: Cannot initiate a refund as the capture is pending. description:
Capture is typically pending when the payer has funded the transaction by using an e-check or bank account. - name: PERMISSION_DENIED message: You do not have permission to access or perform operations on this resource. description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction. - name: PERMISSION_NOT_GRANTED message: Payee of the authorization has not granted permission to perform capture on the authorization. description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to capture the authorization. - name: PREVIOUSLY_CAPTURED message: Authorization has been previously captured and hence cannot be voided. description:
This authorized payment was already captured. You cannot capture it again. - name: PREVIOUSLY_VOIDED message: Authorization has been previously voided and hence cannot be voided again. description:
This authorized payment was already voided. You cannot void it again. - name: REFUND_AMOUNT_EXCEEDED message: The refund amount must be less than or equal to the capture amount that has not yet been refunded. description:
Verify the refund amount and try the request again. - name: REFUND_AMOUNT_TOO_LOW message: The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account. description:
The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account. - name: REFUND_CAPTURE_CURRENCY_MISMATCH message: Refund must be in the same currency as the capture. description:
Verify the currency of the refund and try the request again. - name: REFUND_FAILED_INSUFFICIENT_FUNDS message: Refund cannot be processed due to insufficient funds. description:
Capture could not be refunded due to insufficient funds. Please check to see if you have sufficient funds in your PayPal account or if the bank account linked to your PayPal account is verified and has sufficient funds. - name: REFUND_NOT_ALLOWED message: Capture cannot be refunded. description:
You cannot refund this capture. - name: REFUND_TIME_LIMIT_EXCEEDED message: You are over the time limit to perform a refund on this capture. description:
The refund cannot be issued at this time. - name: TRANSACTION_REFUSED message: PayPal's internal controls prevent authorization from being captured. description:
For more information about this transaction, contact customer support. - name: REFUND_NOT_SUPPORTED_FOR_PAYMENT_SOURCE message: Refund was refused by the payment source. description:
Refunds are not supported for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means. - name: REFUND_TIME_EXCEEDED_FOR_PAYMENT_SOURCE message: Refund was refused by the payment source. description:
The time limit set by the payer's selected payment source to refund this transaction has expired. Contact the payer directly to arrange a refund via alternative means. - name: REFUND_FAILED_BY_PAYMENT_SOURCE message: Refund was refused by the payment source. description:
We're unable to process refunds for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means. - name: PREVIOUS_REQUEST_IN_PROGRESS message: 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. description:
This scenario only occurs when making multiple API requests on the same resource within a very short duration. To resolve this, API callers need to make subsequent requests with a delay. - name: REAUTHORIZATION_NOT_SUPPORTED message: A reauthorize cannot be attempted on an authorization_id that is the result of a prior reauthorization or on an authorization made on an Order saved using the `v2/orders/id/save` API. - name: AUTH_CURRENCY_MISMATCH message: 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. - name: SHIPPING_ADDRESS_INVALID message: Address field does not match the corresponding validation regex. - name: SHIPPING_ADDRESS_NOT_ALLOWED_BY_RESIDENCE_COUNTRY message: The provided shipping address is not allowed by buyer's residency country. - name: UPDATE_AUTHORIZATION_NOT_SUPPORTED message: Update authorization is not allowed for this type of authorization. - name: REFUND_TRANSACTION_REFUSED description: PayPal's internal controls or user account settings prevent refund from being processed. - name: MAX_PAYER_AMOUNT_LIMIT_EXCEEDED description: Refund amount exceeds the allowed cumulative limit that the payer can refund. - name: MAX_PAYEE_AMOUNT_LIMIT_EXCEEDED description: Refund amount exceeds the allowed cumulative limit that the payee can receive. - name: PAYER_REFUND_AMOUNT_LIMIT_EXCEEDED description: Refund amount exceeds per transaction limit that the payer can refund. - name: PAYEE_REFUND_AMOUNT_LIMIT_EXCEEDED description: Refund amount exceeds per transaction limit that the payee can receive. - name: DUPLICATE_REFUND description: Requested invoice_id has been previously refunded. Possible duplicate transaction. - name: CANNOT_REFUND_SELF description: The payer and payee for the refund cannot be same. - name: REFUND_FUNDS_NOT_AVAILABLE description: There is no valid funding instrument linked to the account from which refund can be processed. - name: REFUND_REFUSED_BY_PROCESSOR description: The funding instrument linked to the account has been declined by either the processor or PayPal internal system. - name: PLATFORM_FEE_NOT_ENABLED message: The API Caller account is not setup to be able to process refunds with 'platform_fees'. Please contact your Account Manager. This feature is useful when you want to contribute a portion of the 'platform_fees' you had capture as part of the refund being processed. - name: REFUND_IS_RESTRICTED message: This refund can only be processed by the API caller that had 'captured' the transaction. If you facilitate your transactions via a platform/partner, please initiate a refund through them. - name: PLATFORM_FEE_EXCEEDED message: Platform fee amount specified exceeds the amount that is available for refund. You can only refund up to the available platform fee amount. This error is also returned when no platform_fee was specified or was zero when the payment was captured. - name: CURRENCY_MISMATCH message: All amounts specified should be in the same currency. Please ensure that the currency for the 'amount' and that of 'platform_fees.amount' is the same. - name: CANNOT_BE_NEGATIVE description: Must be greater than or equal to 0. - name: INVALID_SECURITY_CODE_LENGTH description: The security_code length is invalid for the specified card brand. - name: CARD_TYPE_NOT_SUPPORTED description: Processing of this card type is not supported. Use another type of card. - name: TRANSACTION_REFUSED description: The request was refused. - name: CURRENCY_NOT_SUPPORTED_FOR_CARD_TYPE description: Currency code not supported for direct card payments using this card type. See [Currency codes](/docs/api/reference/currency-codes/) for list of supported currency codes. - name: INVALID_FX_RATE_ID description: The specified FX Rate ID is not valid. - name: PAYEE_FX_RATE_ID_EXPIRED description: The specified FX Rate ID has expired. - name: PAYEE_FX_RATE_ID_CURRENCY_MISMATCH description: The specified FX Rate ID is for a currency that does not match with the currency of this request. - name: FX_RATE_CHANGE_DUE_TO_MARKET_EVENT description: The FX rate associated with the specified FX rate ID has been changed due to market events. Please refer to the provided new_fx_id link to retrieve a new FX rate ID and try the request again. - name: INVALID_ARRAY_LENGTH message: Request is not well-formed, syntactically incorrect, or violates schema. description:
The number of items in an array parameter is too small or too large. - name: MALFORMED_REQUEST_JSON message: Request is not well-formed, syntactically incorrect, or violates schema. description: The request JSON is not well formed. - name: INVALID_COUNTRY_CODE message: The requested action could not be performed, semantically incorrect, or failed business validation. description:
Country code is invalid. Please refer to https://developer.paypal.com/docs/integration/direct/rest/country-codes/ for a list of supported country codes. - name: MULTI_CURRENCY_CODE message: The requested action could not be performed, semantically incorrect, or failed business validation. description:
Multiple differing values of currency_code are not supported. Entire request must have the same currency_code. - name: PAYEE_ACCOUNT_INVALID message: The requested action could not be performed, semantically incorrect, or failed business validation. description:
Payee account specified is invalid. Please check the `payee.merchant_id` specified and try again. - name: COMPLIANCE_VIOLATION description: Transaction is declined due to compliance violation. - name: DUPLICATE_TRANSACTION description: Duplicate invoice Id detected. - name: AUTHORIZATION_AMOUNT_EXCEEDED description: Authorization amount specified exceeded allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer. - name: REAUTHORIZATION_TOO_SOON description: A reauthorization is only allowed once from Day 4 to Day 29 since the date of the original authorization. - name: CAPTURED_AMOUNT_FULLY_REFUNDED description: The captured amount has already been fully refunded. - name: REFUND_CURRENCY_MISMATCH description: Refund must be in the same currency as the capture. - name: REAUTHORIZATION_DECLINED_BY_PROCESSOR description: The reauthorization was declined by the processor. - name: REAUTHORIZATION_NOT_SUPPORTED_FOR_PAYMENT_SOURCE description: Reauthorization is not supported for the payment source. - name: KYC_HOLD message: The merchant's KYC status is incomplete. description: The payment was pending due to the merchant's incomplete KYC status.