openapi: 3.2.0 info: title: Payments description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the Payments REST API to easily and securely accept online and mobile payments. The payments name space contains resource collections for payments, sales, refunds, authorizations, captures, and orders.
Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.
You can enable customers to make PayPal and credit card payments with only a few clicks, depending on the country. You can accept an immediate payment or authorize a payment and capture it later. You can show details for completed payments, refunds, and authorizations. You can make full or partial refunds. You also can void or re-authorize authorizations. For more information, see the Payments overview. version: "1.12" contact: {} servers: - url: https://api-m.sandbox.paypal.com description: PayPal API Sandbox tags: - name: payment description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the /payment resource to create a sale, an authorized payment, or an order. A sale is a direct credit card payment, stored credit card payment, or PayPal payment. An authorized payment places funds on hold to be captured later. An order is a purchase that a customer has approved but for which the funds are not placed on hold. You can also use this resource to execute approved PayPal payments and show details for, update, and list payments. For more information, see also . - name: sale description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
A sale is a completed payment. Use the /sale resource to show sale details and refund a sale. For more information, see also Refund payments. - name: authorization description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the /authorization resource and related sub-resources to show details for, capture, void, and reauthorize an authorization. - name: orders description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the /orders resource to authorize, capture, void, and show details for an order.
Note: You cannot refund an order directly. Instead, you must refund a completed payment for an order. For integration information, see Orders and refund payment.
For more information, see also Orders. - name: capture description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the /capture resource and sub-resources to show details for and refund captured payments. - name: refund description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the /refund resource to show details for a refund on direct and captured payments. - name: receipt description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the /receipt resource to show details for a payment receipt. externalDocs: url: https://developer.paypal.com/docs/api/payments/v1/ paths: /v1/payments/payment: post: summary: Create payment description: '
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Creates a sale, an authorized payment to be captured later, or an order. To create a sale, authorization, or order, include the payment details in the JSON request body. Set the intent to sale, authorize, or order.
Note: TPP Clients (Third Party Providers in the context of PSD2 regulation) are restricted from using authorize and order intents.
Include payer, transaction details, and, for PayPal payments only, redirect URLs. The combination of the payment_method and funding_instrument determines the type of payment that is created. For more information, see Payments REST API.' operationId: payment.create responses: "201": description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows payment details. content: application/json: schema: $ref: "#/components/schemas/payment" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/paypal_partner_attribution_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/payment" examples: payment: value: intent: sale payer: payment_method: paypal transactions: - amount: total: "30.11" currency: USD details: subtotal: "30.00" tax: "0.07" shipping: "0.03" handling_fee: "1.00" shipping_discount: "-1.00" insurance: "0.01" description: The payment transaction description. custom: EBAY_EMS_90048630024435 invoice_number: "48787589673" payment_options: allowed_payment_method: INSTANT_FUNDING_SOURCE soft_descriptor: ECHI5786786 item_list: items: - name: hat description: Brown hat. quantity: "5" price: "3" tax: "0.01" sku: "1" currency: USD - name: handbag description: Black handbag. quantity: "1" price: "15" tax: "0.02" sku: product34 currency: USD shipping_address: recipient_name: Brian Robinson line1: 4th Floor line2: "Unit #34" city: San Jose country_code: US postal_code: "95131" phone: "011862212345678" state: CA note_to_payer: Contact us for any questions on your order. redirect_urls: return_url: https://example.com/return cancel_url: https://example.com/cancel security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/paymentcard - Oauth2: - https://uri.paypal.com/services/payments/channelpartner tags: - payment get: summary: List payments description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Lists payments that are completed. Payments that you just created with the create payment call do not appear in the list.

The list shows the payments that are made to the merchant who makes the call. To filter the payments that appear in the response, you can specify one or more optional query and pagination parameters. See Filtering and pagination. operationId: payment.list responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists payments with payment details. content: application/json: schema: $ref: "#/components/schemas/payment_history" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/count" - $ref: "#/components/parameters/start_id" - $ref: "#/components/parameters/start_index" - $ref: "#/components/parameters/start_time" - $ref: "#/components/parameters/end_time" - $ref: "#/components/parameters/payee_id" - $ref: "#/components/parameters/sort_by" - $ref: "#/components/parameters/sort_order" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture - Oauth2: - https://uri.paypal.com/services/checkout/onetimepayment tags: - payment /v1/payments/payment/{payment_id}: get: summary: Show payment details description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a payment, by ID, that has yet to complete. For example, shows details for a payment that was created, approved, or failed. operationId: payment.get responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows payment details. content: application/json: schema: $ref: "#/components/schemas/payment" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/payment_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - payment patch: summary: Partially update payment description: '
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Partially updates a payment, by ID. You can update the amount, shipping address, invoice ID, and custom data. You cannot update a payment after the payment executes.
Note: TPP Clients (Third Party Providers in the context of PSD2 regulation) are restricted from patching amount once authorized.
' operationId: payment.update responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows payment details. content: application/json: schema: $ref: "#/components/schemas/payment" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/payment_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/patch_request" examples: patch_request: value: - op: replace path: /transactions/0/amount value: total: "18.37" currency: EUR details: subtotal: "13.37" shipping: "5.00" - op: add path: /transactions/0/item_list/shipping_address value: recipient_name: Anna Gruneberg line1: Kathwarinenhof 1 city: Flensburg postal_code: "24939" country_code: DE security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/channelpartner tags: - payment /v1/payments/payment/{payment_id}/execute: post: summary: Execute approved PayPal payment description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Executes a PayPal payment that the customer has approved. You can optionally update one or more transactions when you execute the payment.
Important: This call works only after a customer has approved the payment. For more information, learn about PayPal payments.
operationId: payment.execute responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the executed payment. content: application/json: schema: $ref: "#/components/schemas/payment" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/paypal_request_id" - $ref: "#/components/parameters/paypal_partner_attribution_id" - $ref: "#/components/parameters/payment_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/payment_execution" examples: payment_execution: value: payer_id: CR87QHB7JTRSC security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment tags: - payment /v1/payments/sale/{sale_id}: get: summary: Show sale details description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a sale, by ID. Returns only sales that were created through the REST API. operationId: sale.get responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows sale details. content: application/json: schema: $ref: "#/components/schemas/sale" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/sale_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - sale /v1/payments/sale/{sale_id}/refund: post: summary: Refund sale description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Refunds a sale, by ID. For a full refund, do not include the amount object in the JSON request body. For a partial refund, include an amount object in the JSON request body. operationId: sale.refund responses: "200": description: A successful idempotent request returns the HTTP `200 Created` status code and a JSON response body that shows details for the refunded sale. content: application/json: schema: $ref: "#/components/schemas/detailed_refund" "201": description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the refunded sale. content: application/json: schema: $ref: "#/components/schemas/detailed_refund" "409": description: The request failed because a previous call for the given resource is in progress. content: application/json: schema: $ref: "#/components/schemas/error" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/paypal_request_id" - $ref: "#/components/parameters/sale_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/refund_request" examples: refund_request: value: amount: total: "100.00" currency: USD invoice_number: INV-7654321 security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/refund - Oauth2: - https://uri.paypal.com/services/payments/unilateralrefund tags: - sale /v1/payments/authorization/{authorization_id}: get: summary: Show authorization details description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for an authorization, by ID. operationId: authorization.get 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" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/authorization_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - authorization /v1/payments/authorization/{authorization_id}/capture: post: summary: Capture authorization description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Captures and processes an authorization, by ID. The original payment call must specify an intent of authorize. operationId: authorization.capture responses: "201": description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the captured authorization. content: application/json: schema: $ref: "#/components/schemas/capture" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/authorization_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/capture" examples: capture: value: amount: currency: USD total: "4.54" is_final_capture: true security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - authorization /v1/payments/authorization/{authorization_id}/void: post: summary: Void authorization description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Voids, or cancels, an authorization, by ID. You cannot void a fully captured authorization. operationId: authorization.void responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the voided authorization. content: application/json: schema: $ref: "#/components/schemas/authorization" "409": description: The request failed because a previous call for the given resource is in progress. content: application/json: schema: $ref: "#/components/schemas/error" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/paypal_request_id" - $ref: "#/components/parameters/authorization_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - authorization /v1/payments/authorization/{authorization_id}/reauthorize: post: summary: Re-authorize payment description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Re-authorizes a PayPal account payment, by authorization ID. To ensure that funds are still available, re-authorize a payment after the initial three-day honor period. Supports only the amount request parameter. You can re-authorize a payment only once from four to 29 days after three-day honor period for the original authorization expires. If 30 days have passed from the original authorization, you must create a new authorization instead. A re-authorized payment itself has a new three-day honor period. You can re-authorize a transaction once for up to 115% of the originally authorized amount, not to exceed an increase of $75 USD. operationId: authorization.reauthorize responses: "201": description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the re-authorized authorization. content: application/json: schema: $ref: "#/components/schemas/authorization" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/authorization_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/authorization" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - authorization /v1/payments/orders/{order_id}: get: summary: Show order details description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for an order, by ID. operationId: orders.get responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the voided authorization. content: application/json: schema: $ref: "#/components/schemas/order" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/order_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - orders /v1/payments/orders/{order_id}/capture: post: summary: Capture order description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Captures a payment for an order, by ID. To use this call, the original payment call must specify an order intent. In the JSON request body, include the payment amount and indicate whether this capture is the final capture for the authorization. operationId: orders.capture responses: "201": description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the captured order. content: application/json: schema: $ref: "#/components/schemas/capture" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/order_id" requestBody: $ref: "#/components/requestBodies/capture" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - orders /v1/payments/orders/{order_id}/do-void: post: summary: Void order description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Voids, or cancels, an order, by ID. You can only void orders that are either in the PENDING or AUTHORIZED states or those in the CAPTURED state that are not fully captured. operationId: orders.void responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the voided order. content: application/json: schema: $ref: "#/components/schemas/order" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/paypal_request_id" - $ref: "#/components/parameters/order_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - orders /v1/payments/orders/{order_id}/authorize: post: summary: Authorize order description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Authorizes an order, by ID. In the JSON request body, include an amount object. operationId: orders.authorize responses: "201": description: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the authorized order. content: application/json: schema: $ref: "#/components/schemas/authorization" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/order_id" requestBody: content: application/json: schema: $ref: "#/components/schemas/order" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - orders /v1/payments/capture/{capture_id}: get: summary: Show captured payment details description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a captured payment, by ID. operationId: capture.get responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the captured payment. content: application/json: schema: $ref: "#/components/schemas/capture" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/capture_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/realtimepayment - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture tags: - capture /v1/payments/capture/{capture_id}/refund: post: summary: Refund captured payment description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Refunds a captured payment, by ID. In the JSON request body, include an amount object. operationId: capture.refund responses: "200": description: A successful idempotent request returns the HTTP `200 OK` status code and a JSON response body that shows details for the captured payment. content: application/json: schema: $ref: "#/components/schemas/detailed_refund" "201": description: A successful request returns the HTTP `201 OK` status code and a JSON response body that shows details for the captured payment. content: application/json: schema: $ref: "#/components/schemas/detailed_refund" "409": description: The request failed because a previous call for the given resource is in progress. content: application/json: schema: $ref: "#/components/schemas/error" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/paypal_request_id" - $ref: "#/components/parameters/capture_id" requestBody: $ref: "#/components/requestBodies/refund_request" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/refund - Oauth2: - https://uri.paypal.com/services/payments/unilateralrefund tags: - capture /v1/payments/refund/{refund_id}: get: summary: Show refund details description:
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a refund, by ID. operationId: refund.get 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" default: description: The error details. content: application/json: schema: $ref: "#/components/schemas/error" parameters: - $ref: "#/components/parameters/refund_id" security: - Oauth2: - https://api.paypal.com/v1/payments/.* - Oauth2: - https://uri.paypal.com/services/payments/payment - Oauth2: - https://uri.paypal.com/services/payments/refund tags: - refund components: requestBodies: capture: content: application/json: schema: $ref: "#/components/schemas/capture" refund_request: content: application/json: schema: $ref: "#/components/schemas/refund_request" securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /api/oauth-proxy scopes: https://api.paypal.com/v1/payments/.*: Deprecated. Legacy payment scope. It will be replaced with new scopes https://uri.paypal.com/services/payments/payment: New special privileged scope available to do payment. This will be available to internal clients only 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/payment/authcapture: "Permission to do non-real time payments like authorization on order or capture on authorization or an order " https://uri.paypal.com/services/payments/refund: Permission to initiate a refund/reversal on a sale or capture transaction https://uri.paypal.com/services/payments/paymentcard: Permission to do unbranded credit or debit card payments https://uri.paypal.com/services/payments/futurepayments: Permission for future or pre-approved payment. https://uri.paypal.com/services/payments/channelpartner: Permission to explicitly specify the receiver of a payment on request payload. https://uri.paypal.com/services/payments/unilateralrefund: This scope enables partners/facilitators to perform unilateralrefund and also refund. https://uri.paypal.com/services/checkout/onetimepayment: This scope enable buyer's checkout flow to load payment information. schemas: error_details: title: Error Details type: object description: The error details. Required for client-side `4XX` errors. properties: field: type: string description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors. value: type: string description: The value of the field that caused the error. location: $ref: "#/components/schemas/error_location" issue: type: string description: The unique, fine-grained application-level error code. description: type: string description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value. required: - issue error_location: type: string description: The location of the field that caused the error. Value is `body`, `path`, or `query`. enum: - body - path - query default: body error_link_description: title: Link Description description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information. type: object required: - href - rel properties: href: description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. type: string minLength: 0 maxLength: 20000 pattern: ^.*$ rel: description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). type: string minLength: 0 maxLength: 100 pattern: ^.*$ method: description: The HTTP method required to make the related call. type: string minLength: 3 maxLength: 6 pattern: ^[A-Z]*$ enum: - GET - POST - PUT - DELETE - PATCH error_400: type: object title: Bad Request Error description: Request is not well-formed, syntactically incorrect, or violates schema. properties: name: type: string enum: - INVALID_REQUEST message: type: string enum: - Request is not well-formed, syntactically incorrect, or violates schema. details: type: array items: $ref: "#/components/schemas/error_details" debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" error_401: type: object title: Unauthorized Error description: Authentication failed due to missing Authorization header, or invalid authentication credentials. properties: name: type: string enum: - AUTHENTICATION_FAILURE message: type: string enum: - Authentication failed due to missing authorization header, or invalid authentication credentials. details: type: array items: $ref: "#/components/schemas/error_details" debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" error_403: type: object title: Not Authorized Error description: "The client is not authorized to access this resource, although it may have valid credentials. " properties: name: type: string enum: - NOT_AUTHORIZED message: type: string enum: - Authorization failed due to insufficient permissions. details: type: array items: $ref: "#/components/schemas/error_details" debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" error_404: type: object title: Not found Error description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available. properties: name: type: string enum: - RESOURCE_NOT_FOUND message: type: string enum: - The specified resource does not exist. details: type: array items: $ref: "#/components/schemas/error_details" debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" error_409: type: object title: Resource Conflict Error description: The server has detected a conflict while processing this request. properties: name: type: string enum: - RESOURCE_CONFLICT message: type: string enum: - The server has detected a conflict while processing this request. details: type: array items: $ref: "#/components/schemas/error_details" debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" error_415: type: object title: Unsupported Media Type Error description: The server does not support the request payload's media type. properties: name: type: string enum: - UNSUPPORTED_MEDIA_TYPE message: type: string enum: - The server does not support the request payload's media type. details: type: array items: $ref: "#/components/schemas/error_details" debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" error_422: type: object title: Unprocessable Entity Error description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request. properties: name: type: string enum: - UNPROCESSABLE_ENTITY message: type: string enum: - The requested action could not be performed, semantically incorrect, or failed business validation. details: type: array items: $ref: "#/components/schemas/error_details" debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" error_500: type: object title: Internal Server Error description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server. properties: name: type: string enum: - INTERNAL_SERVER_ERROR message: type: string enum: - An internal server error occurred. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" examples: - name: INTERNAL_SERVER_ERROR message: An internal server error occurred. debug_id: 90957fca61718 links: - href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR rel: information_link error_503: type: object title: Service Unavailable Error description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime. properties: name: type: string enum: - SERVICE_UNAVAILABLE message: type: string enum: - Service Unavailable. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. links: description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS). type: array minItems: 0 maxItems: 10000 items: $ref: "#/components/schemas/error_link_description" examples: - name: SERVICE_UNAVAILABLE message: Service Unavailable. debug_id: 90957fca61718 information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE error_details-2: title: Error Details type: object description: The error details. Required for client-side `4XX` errors. properties: field: type: string description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors. value: type: string description: The value of the field that caused the error. location: type: string description: The location of the field that caused the error. Value is `body`, `path`, or `query`. default: body issue: type: string description: The unique, fine-grained application-level error code. description: type: string description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value. required: - issue link_description: type: object title: Link Description description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information. required: - href - rel properties: href: type: string description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. rel: type: string description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). method: type: string description: The HTTP method required to make the related call. enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH error: type: object title: Error description: The error details. properties: name: type: string description: The human-readable, unique name of the error. message: type: string description: The message that describes the error. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. information_link: type: string description: The information link, or URI, that shows detailed information about this error for the developer. readOnly: true details: type: array description: An array of additional details about the error. items: $ref: "#/components/schemas/error_details-2" links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" readOnly: true required: - name - message - debug_id credit_card_token: type: object title: Credit Card Token description: The tokenized credit card details. You can use this instrument to fund a payment. properties: credit_card_id: type: string description: The ID of credit card that is stored in the PayPal vault. minLength: 1 maxLength: 256 payer_id: type: string description: Deprecated. A unique ID that you can assign and track when you store a credit card in the vault or use a vaulted credit card. This ID can help to avoid unintentional use or misuse of credit cards and can be any value, such as a UUID, user name, or email address. **Required** when you use a vaulted credit card and if a `payer_id` was originally provided when you vaulted the credit card. Use external_customer_id instead. minLength: 1 maxLength: 256 external_customer_id: type: string description: The externally-provided ID of the customer. minLength: 1 maxLength: 256 last4: type: string readOnly: true description: The last four digits of the stored credit card number. minLength: 4 maxLength: 4 type: type: string readOnly: true description: The credit card type. Value is `visa`, `mastercard`, `discover`, or `amex`. Do not use these lowercase values for display. minLength: 1 maxLength: 256 expire_month: type: integer readOnly: true description: The expiration month with no leading zero. Value is from `1` to `12`. minimum: 1 maximum: 12 expire_year: type: string readOnly: true description: The four-digit expiration year. pattern: ^[0-9]{4}$ minLength: 4 maxLength: 4 required: - credit_card_id funding_instrument: type: object title: Funding Instrument description: The funding instrument details. An instance of this schema is valid if and only if it validates against exactly one of these supported properties. properties: credit_card_token: description: The tokenized credit card details. You can use this instrument to fund a payment. $ref: "#/components/schemas/credit_card_token" country_code: type: string description: The [two-character ISO 3166-1 code](/docs/api/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.
format: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ address: type: object title: Address description: The billing address or shipping address for a payment. properties: line1: type: string description: The first line of the address. For example, number, street, and so on. maxLength: 300 line2: type: string description: The second line of the address. For example, suite or apartment number. maxLength: 300 city: type: string description: The city name. maxLength: 64 country_code: $ref: "#/components/schemas/country_code" postal_code: type: string description: The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). state: type: string description: "The [code](/docs/integration/direct/rest/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/integration/direct/rest/state-codes/#argentina), [Brazil](/docs/integration/direct/rest/state-codes/#brazil), [Canada](/docs/integration/direct/rest/state-codes/#canada), [China](/docs/integration/direct/rest/state-codes/#china), [India](/docs/integration/direct/rest/state-codes/#india), [Italy](/docs/integration/direct/rest/state-codes/#italy), [Japan](/docs/integration/direct/rest/state-codes/#japan), [Mexico](/docs/integration/direct/rest/state-codes/#mexico), [Thailand](/docs/integration/direct/rest/state-codes/#thailand), or [United States](/docs/integration/direct/rest/state-codes/#usa)." maxLength: 300 phone: type: string format: phone description: The phone number, in [E.123 format](https://www.itu.int/rec/T-REC-E.123-200102-I/en). Maximum length is 50 characters. normalization_status: type: string description: The address normalization status. Returned only for payers from Brazil. readOnly: true enum: - UNKNOWN - UNNORMALIZED_USER_PREFERRED - NORMALIZED - UNNORMALIZED type: type: string description: The type of address. For example, `HOME_OR_WORK`, `GIFT`, and so on. required: - line1 - country_code shipping_address: title: Shipping Address description: The shipping address details. allOf: - $ref: "#/components/schemas/address" - properties: recipient_name: type: string description: The name of the recipient at this address. maxLength: 127 payer_info: type: object title: Payer Information description: The payer information. properties: email: type: string format: email description: The payer's email address. Maximum length is 127 characters. salutation: type: string description: The payer's salutation. readOnly: true first_name: type: string description: The payer's first name. readOnly: true middle_name: type: string description: The payer's middle name. readOnly: true last_name: type: string description: The payer's last name. readOnly: true suffix: type: string description: The payer's suffix. readOnly: true payer_id: type: string description: The PayPal-assigned encrypted payer ID. readOnly: true birth_date: type: string format: date-time description: The birth date of the payer, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `1990-04-12`. tax_id: type: string description: The payer's tax ID. Supported for the PayPal payment method only. maxLength: 14 tax_id_type: type: string description: The payer's tax ID type. Supported for the PayPal payment method only. enum: - BR_CPF - BR_CNPJ billing_address: $ref: "#/components/schemas/address" description: The payer's billing address. shipping_address: $ref: "#/components/schemas/shipping_address" description: Deprecated. The shipping address. Use the shipping address for the purchase unit or at the root level of the checkout session. readOnly: true payer: type: object title: Payer description: The payer. The payer funds the payment. properties: payment_method: type: string minLength: 4 maxLength: 17 description: The payment method. enum: - credit_card - paypal - pay_upon_invoice - carrier - alternate_payment - bank status: type: string minLength: 8 maxLength: 10 description: The status of payer's PayPal account. readOnly: true enum: - VERIFIED - UNVERIFIED funding_instruments: type: array description: An array of a single funding instrument for the current payment. Valid only and required for the credit card payment method. The array must include either a `credit_card` or `credit_card_token` object. If the array contains more than one instrument, the payment is declined. items: $ref: "#/components/schemas/funding_instrument" minItems: 1 maxItems: 1 payer_info: $ref: "#/components/schemas/payer_info" token: type: object title: Token description: The tokenized payment source to fund a payment. properties: id: type: string description: The PayPal-generated ID for the token. minLength: 1 maxLength: 255 type: type: string description: The tokenization method that generated the ID. minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_-]+$ enum: - BILLING_AGREEMENT required: - id - type payment_source: type: object title: Payment Source description: The payment source definition. properties: token: $ref: "#/components/schemas/token" payment_pattern: type: string description: Provides context (e.g. frequency of payment (Single, Recurring) along with whether (Customer is Present, Not Present) for the payment being processed. For Card and PayPal Vaulted/Billing Agreement transactions, this helps specify the appropriate indicators to the networks (e.g. Mastercard, Visa) which ensures compliance as well as ensure a better auth-rate. For bank processing, indicates to clearing house whether the transaction is recurring or not depending on the option chosen. title: Payment pattern minLength: 3 maxLength: 255 pattern: ^[A-Z_]+$ enum: - CUSTOMER_PRESENT_ONETIME_PURCHASE - CUSTOMER_NOT_PRESENT_RECURRING - CUSTOMER_PRESENT_RECURRING_FIRST - CUSTOMER_PRESENT_ONETIME_PURCHASE_VAULTED - CUSTOMER_NOT_PRESENT_ONETIME_PURCHASE_VAULTED - MAIL_ORDER_TELEPHONE_ORDER application_context: type: object title: Application Context description: The application context. Set these properties to customize the payment flow experience for your customers. properties: brand_name: type: string description: A label that overrides the business name in the merchant's PayPal account on the PayPal checkout pages. maxLength: 127 locale: type: string description: The locale of pages that the PayPal payment experience displays. Please refer [here](/docs/api/reference/locale-codes/#localize-the-checkout-experience) for list of supported local codes. Defaulted to en_US if not provided or invalid. landing_page: type: string description: The type of landing page to show on the PayPal site for customer checkout. To use the non-PayPal account landing page, set to `Billing`. To use the PayPal account log in landing page, set to `Login`. shipping_preference: type: string description: The shipping preference. default: GET_FROM_FILE enum: - NO_SHIPPING - GET_FROM_FILE - SET_PROVIDED_ADDRESS user_action: type: string description: The user action. Presents the customer with either the Continue or Pay Now checkout flow:
FlowActionDescription
Pay Nowuser_action=commitAfter the customer is redirected to the PayPal payment page, shows the Pay Now button.

Use this option when you know the final amount when checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now.
Continue user_action=continueAfter the customer is redirected to the PayPal payment page, shows the Continue button.

Use this option when you do not know the final amount when you initiate the checkout flow and you want to redirect the customer to the merchant page without processing the payment.
preferred_payment_source: type: object description: The preferred payment source for the payer. Currently supported only for PayPal Billing Agreements. If provided, checkout experience will have this payment source pre-selected for the payer. $ref: "#/components/schemas/payment_source" payment_pattern: $ref: "#/components/schemas/payment_pattern" amount: type: object title: Amount description: The payment amount, with details. properties: currency: type: string description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/). PayPal does not support all currencies. total: type: string description: The total amount charged to the payee by the payer. For refunds, represents the amount that the payee refunds to the original payer. Maximum length is 10 characters, which includes: details: type: object title: Payment Amount Details description: The additional details about the payment amount.
Note: For an order authorization or capture, you cannot include the amount details object.
properties: subtotal: type: string description: The subtotal amount for the items. If the request includes line items, this property is **required**. Maximum length is 10 characters, which includes:
Note: For an order authorization or capture, you cannot include the subtotal parameter.
shipping: type: string description: The shipping fee. Maximum length is 10 characters, which includes:
Note: For an order authorization or capture, you cannot include the shipping parameter.
tax: type: string description: The tax. Maximum length is 10 characters, which includes:
Note: For an order authorization or capture, you cannot include the tax parameter.
handling_fee: type: string description: The handling fee. Maximum length is 10 characters, which includes:Supported for the PayPal payment method only.
Note: For an order authorization or capture, you cannot include the handling_fee parameter.
shipping_discount: type: string description: The shipping fee discount. Maximum length is 10 characters, which includes:Supported for the PayPal payment method only.
Note: For an order authorization or capture, you cannot include the shipping_discount parameter.
insurance: type: string description: The insurance fee. Maximum length is 10 characters, which includes:Supported only for the PayPal payment method.
Note: For an order authorization or capture, you cannot include the insurance parameter.
gift_wrap: type: string description: The gift wrap fee. Maximum length is 10 characters, which includes:
Note: For an order authorization or capture, you cannot include the gift_wrap parameter.
x-hidden: true required: - currency - total payee: type: object title: Payee description: The payee who receives the funds and fulfills the order. properties: email: type: string format: email description: The email address associated with the payee's PayPal account. For an intent of authorize or order, the email address must be associated with a confirmed PayPal business account. For an intent of sale, the email can either: merchant_id: type: string description: The PayPal account ID for the payee. currency_code: description: The [three-character ISO-4217 currency code](/docs/api/reference/currency-codes/) that identifies the currency. type: string format: ppaas_common_currency_code_v2 minLength: 3 maxLength: 3 item: type: object title: Item description: The item details. properties: sku: type: string description: The stock keeping unit (SKU) for the item. maxLength: 127 name: type: string description: The item name. If this value is greater than the maximum allowed length, the API truncates the string. maxLength: 127 description: type: string description: The item description. Supported for only the PayPal payment method. maxLength: 127 quantity: type: string description: The item quantity. Must be a whole number. maxLength: 10 pattern: ^[0-9]{0,10}$ price: type: string description: The item cost. Supports two decimal places. maxLength: 10 pattern: ^[0-9]{0,10}(\.[0-9]{0,2})?$ currency: $ref: "#/components/schemas/currency_code" tax: type: string description: The item tax. Supported only for the PayPal payment method. required: - quantity - price - currency payment_hold_reason: type: object title: Related Resources description: The payment-related financial transactions, which include sales, authorizations, captures, and refunds. To show resource details, use the resource ID. For example, to [show details for a related authorization](/docs/api/payments/v1/#authorization_get), use the ID returned in the `authorization` object. You can also use the [HATEOAS links](/docs/api/hateoas-links/) for a resource to complete operations for that resource. For example, a `sale` object provides a `refund` link that enables you to refund the sale. properties: payment_hold_reason: description: The reason that PayPal holds the recipient fund. Set only if the payment hold status is `HELD`. type: string enum: - PAYMENT_HOLD - SHIPPING_RISK_HOLD currency: type: object title: Currency description: The currency and amount for a transaction. properties: currency: type: string description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/). PayPal does not support all currencies. value: type: string description: The amount. Includes the specified number of digits after decimal separator for the [ISO-4217 currency code](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). required: - currency - value fmf_details: type: object title: FMF Details description: The Fraud Management Filter (FMF) details that are applied to the payment that result in an accept, deny, or pending action. Returned in a payment response only if the merchant has enabled FMF in the profile settings and one of the fraud filters was triggered based on those settings. For more information, see [Fraud Management Filters Summary](/docs/classic/fmf/integration-guide/FMFSummary/). properties: filter_type: type: string description: The filter type. readOnly: true enum: - ACCEPT - PENDING - DENY - REPORT filter_id: type: string description: The filter ID. readOnly: true enum: - AVS_NO_MATCH - AVS_PARTIAL_MATCH - AVS_UNAVAILABLE_OR_UNSUPPORTED - CARD_SECURITY_CODE_MISMATCH - MAXIMUM_TRANSACTION_AMOUNT - UNCONFIRMED_ADDRESS - COUNTRY_MONITOR - LARGE_ORDER_NUMBER - BILLING_OR_SHIPPING_ADDRESS_MISMATCH - RISKY_ZIP_CODE - SUSPECTED_FREIGHT_FORWARDER_CHECK - TOTAL_PURCHASE_PRICE_MINIMUM - IP_ADDRESS_VELOCITY - RISKY_EMAIL_ADDRESS_DOMAIN_CHECK - RISKY_BANK_IDENTIFICATION_NUMBER_CHECK - RISKY_IP_ADDRESS_RANGE - PAYPAL_FRAUD_MODEL name: type: string description: The filter name. readOnly: true description: type: string description: The filter description. readOnly: true required: - filter_type - filter_id processor_response: type: object title: Processor Response description: The processor-provided response codes that describe the submitted payment. Supported only when the `payment_method` is `credit_card`. properties: response_code: type: string description: The PayPal normalized response code, which is generated from the processor's specific response code. maxLength: 4 readOnly: true avs_code: type: string description: The [Address Verification System (AVS)](/docs/nvp-soap-api/AVSResponseCodes/) response code. maxLength: 1 pattern: "[A-z0-9]{1}" readOnly: true cvv_code: type: string description: The [CVV](/docs/nvp-soap-api/AVSResponseCodes/) system response code. maxLength: 1 pattern: "[A-z0-9]{1}" readOnly: true advice_code: type: string description: The merchant advice on how to handle declines for recurring payments. readOnly: true enum: - 01_NEW_ACCOUNT_INFORMATION - 02_TRY_AGAIN_LATER - 02_STOP_SPECIFIC_PAYMENT - 03_DO_NOT_TRY_AGAIN - 03_REVOKE_AUTHORIZATION_FOR_FUTURE_PAYMENT - 21_DO_NOT_TRY_AGAIN_CARD_HOLDER_CANCELLED_RECURRRING_CHARGE - 21_CANCEL_ALL_RECURRING_PAYMENTS eci_submitted: type: string description: The processor-provided authorization response. readOnly: true vpas: type: string description: The processor-provided Visa Payer Authentication Service (VPAS) status. readOnly: true required: - response_code sale: type: object title: Sale description: The sale transaction details. properties: id: type: string readOnly: true description: The ID of the sale transaction. amount: description: The amount to collect. $ref: "#/components/schemas/amount" payment_mode: type: string description: The transaction payment mode. Supported only for PayPal payments. readOnly: true enum: - INSTANT_TRANSFER - MANUAL_BANK_TRANSFER - DELAYED_TRANSFER - ECHECK state: type: string enum: - completed - partially_refunded - pending - refunded - denied description: The state of the sale transaction. readOnly: true reason_code: type: string enum: - CHARGEBACK - GUARANTEE - BUYER_COMPLAINT - REFUND - UNCONFIRMED_SHIPPING_ADDRESS - ECHECK - INTERNATIONAL_WITHDRAWAL - RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION - PAYMENT_REVIEW - REGULATORY_REVIEW - UNILATERAL - VERIFICATION_REQUIRED - TRANSACTION_APPROVED_AWAITING_FUNDING description: A reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments. readOnly: true protection_eligibility: type: string enum: - ELIGIBLE - PARTIALLY_ELIGIBLE - INELIGIBLE description: The merchant protection level in effect for the transaction. Supported only for PayPal payments. readOnly: true protection_eligibility_type: type: string enum: - ITEM_NOT_RECEIVED_ELIGIBLE - UNAUTHORIZED_PAYMENT_ELIGIBLE - ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE description: The merchant protection type in effect for the transaction. Returned only when `protection_eligibility` is `ELIGIBLE` or `PARTIALLY_ELIGIBLE`. Supported only for PayPal payments. readOnly: true clearing_time: type: string format: date-time description: The date and time when the PayPal eCheck transaction is expected to clear, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true payment_hold_status: type: string enum: - HELD description: The recipient fund status. Returned only when the fund status is `held`. readOnly: true payment_hold_reasons: type: array readOnly: true description: An array of reasons that PayPal holds the recipient fund. Set only if the payment hold status is `HELD`. items: $ref: "#/components/schemas/payment_hold_reason" transaction_fee: description: The currency and amount of the transaction fee for this payment. Would not be returned for `pending` transactions where the funds have not been realized in the payee account. readOnly: true $ref: "#/components/schemas/currency" receivable_amount: description: The currency and amount of the net that the merchant receives for this transaction in their receivable currency. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer. $ref: "#/components/schemas/currency" transaction_fee_in_receivable_currency: description: The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example `CNY`. Would not be returned for `pending` transactions where the funds have not been realized in the payee account. readOnly: true $ref: "#/components/schemas/currency" exchange_rate: type: string description: The exchange rate for this transaction. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer. readOnly: true fmf_details: $ref: "#/components/schemas/fmf_details" receipt_id: type: string description: The receipt ID, which is a payment ID number that is returned for guest users to identify the payment. pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$ readOnly: true parent_payment: type: string description: The ID of the payment on which this transaction is based. readOnly: true processor_response: $ref: "#/components/schemas/processor_response" billing_agreement_id: type: string description: The ID of the billing agreement. Used as reference to execute this transaction. readOnly: true create_time: type: string format: date-time description: The date and time of the sale, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string format: date-time description: The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" required: - id - amount - state - parent_payment - create_time authorization: type: object title: Authorization description: The authorization details. properties: id: type: string readOnly: true description: The ID of the authorization. amount: $ref: "#/components/schemas/amount" description: The amount being authorized. payment_mode: type: string description: The payment mode of the authorization. readOnly: true enum: - INSTANT_TRANSFER state: type: string description: The authorized payment state. readOnly: true enum: - pending - authorized - partially_captured - captured - expired - denied - voided reason_code: type: string description: The reason code for the pending transaction state. readOnly: true enum: - AUTHORIZATION pending_reason: type: string description: Deprecated. The reason code for the pending transaction state. Obsolete. Use `reason_code` instead. readOnly: true enum: - AUTHORIZATION protection_eligibility: type: string description: The level of seller protection present for the transaction. Supported for the PayPal payment method only. readOnly: true enum: - ELIGIBLE - PARTIALLY_ELIGIBLE - INELIGIBLE protection_eligibility_type: type: string description: The type of seller protection for the transaction. Returned only when the `protection_eligibility` property is `ELIGIBLE` or `PARTIALLY_ELIGIBLE`. Supported for the PayPal payment method only. readOnly: true enum: - ITEM_NOT_RECEIVED_ELIGIBLE - UNAUTHORIZED_PAYMENT_ELIGIBLE - ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE fmf_details: $ref: "#/components/schemas/fmf_details" parent_payment: type: string readOnly: true description: The ID of the payment on which this transaction is based. processor_response: $ref: "#/components/schemas/processor_response" valid_until: type: string format: date-time description: The date and time when the authorization expires, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true create_time: type: string format: date-time description: The date and time when the authorization was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string format: date-time description: The date and time when the authorization was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true receipt_id: type: string description: The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users. pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$ readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" required: - amount order: type: object title: Order description: The order transaction details. properties: id: type: string readOnly: true description: The ID of the order transaction. amount: description: The amount to collect.
Note: For an order authorization, you cannot include amount details.
$ref: "#/components/schemas/amount" payment_mode: type: string description: The transaction payment mode. readOnly: true enum: - INSTANT_TRANSFER - MANUAL_BANK_TRANSFER - DELAYED_TRANSFER - ECHECK state: type: string description: The state of the order transaction. readOnly: true enum: - PENDING - AUTHORIZED - CAPTURED - COMPLETED - VOIDED reason_code: type: string description: The reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments. readOnly: true enum: - PAYER_SHIPPING_UNCONFIRMED - MULTI_CURRENCY - RISK_REVIEW - REGULATORY_REVIEW - VERIFICATION_REQUIRED - ORDER - OTHER pending_reason: type: string enum: - payer_shipping_unconfirmed - multi_currency - risk_review - regulatory_review - verification_required - order - other description: Deprecated. The reason code for the pending transaction state. Obsolete. Use `reason_code` instead. readOnly: true protection_eligibility: type: string description: The level of seller protection in effect for the transaction. readOnly: true enum: - ELIGIBLE - PARTIALLY_ELIGIBLE - INELIGIBLE protection_eligibility_type: type: string description: The kind of seller protection in effect for the transaction. Returned only when the `protection_eligibility` property is `ELIGIBLE` or `PARTIALLY_ELIGIBLE`. Supported only for PayPal payments. readOnly: true enum: - ITEM_NOT_RECEIVED_ELIGIBLE - UNAUTHORIZED_PAYMENT_ELIGIBLE - ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE parent_payment: type: string readOnly: true description: The ID of the payment on which this transaction is based. fmf_details: $ref: "#/components/schemas/fmf_details" create_time: type: string format: date-time description: The date and time when the resource was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string format: date-time description: The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" required: - amount capture: type: object title: Capture description: The capture transaction details. properties: id: type: string description: The ID of the capture transaction. readOnly: true amount: description: The amount to capture. If the amount matches the originally authorized amount, the state of the authorization changes to `captured`. Otherwise, the state changes to `partially_captured`. $ref: "#/components/schemas/amount" is_final_capture: type: boolean description: Indicates whether to release all remaining held funds. default: false state: type: string description: The state of the capture. readOnly: true enum: - pending - completed - refunded - partially_refunded - denied reason_code: type: string description: The reason code that describes why the transaction state is pending or reversed. readOnly: true enum: - CHARGEBACK - GUARANTEE - BUYER_COMPLAINT - REFUND - UNCONFIRMED_SHIPPING_ADDRESS - ECHECK - INTERNATIONAL_WITHDRAWAL - RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION - PAYMENT_REVIEW - REGULATORY_REVIEW - UNILATERAL - VERIFICATION_REQUIRED - TRANSACTION_APPROVED_AWAITING_FUNDING - NONE parent_payment: type: string readOnly: true description: The ID of the payment on which this transaction is based. invoice_number: type: string description: The invoice number to track this payment. maxLength: 127 transaction_fee: description: The currency and amount of the transaction fee for this payment. Would not be returned for `pending` transactions where the funds have not been realized in the payee account. readOnly: true $ref: "#/components/schemas/currency" transaction_fee_in_receivable_currency: description: The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example `CNY`. Would not be returned for `pending` transactions where the funds have not been realized in the payee account. readOnly: true $ref: "#/components/schemas/currency" receivable_amount: description: The net amount and currency that the merchant receives for this transaction in the receivable currency. $ref: "#/components/schemas/currency" readOnly: true exchange_rate: type: string description: The exchange rate applied for this transaction. Returned when there is a currency conversion from the transaction currency to the receivable currency. readOnly: true note_to_payer: type: string description: A free-form field that clients can use to send a note to the payer. maxLength: 255 create_time: type: string format: date-time description: The date and time of the capture, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string format: date-time description: The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" refund: type: object title: Refund description: The refund details. properties: id: type: string readOnly: true description: The ID of the refund transaction. Maximum length is 17 characters. amount: $ref: "#/components/schemas/amount" description: The refund amount. Includes both the amount refunded to the payer and amount of the fee refunded to the payee. state: type: string description: The state of the refund. readOnly: true enum: - pending - completed - cancelled - failed reason: type: string description: The reason that the transaction is being refunded. invoice_number: type: string description: The invoice or tracking ID number. maxLength: 127 sale_id: type: string readOnly: true description: The ID of the sale transaction being refunded. capture_id: type: string readOnly: true description: The ID of the sale transaction being refunded. parent_payment: type: string readOnly: true description: The ID of the payment on which this transaction is based. description: type: string description: The refund description. Value must be single-byte alphanumeric characters. create_time: type: string format: date-time description: The date and time when the refund was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string format: date-time description: The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" related_resources: type: object title: Related Resources description: The payment-related financial transactions, which include sales, authorizations, captures, and refunds. To show resource details, use the resource ID. For example, to [show details for a related authorization](/docs/api/payments/v1/#authorization_get), use the ID returned in the `authorization` object. You can also use the [HATEOAS links](/docs/api/hateoas-links/) for a resource to complete operations for that resource. For example, a `sale` object provides a `refund` link that enables you to refund the sale. properties: sale: $ref: "#/components/schemas/sale" authorization: $ref: "#/components/schemas/authorization" order: $ref: "#/components/schemas/order" capture: $ref: "#/components/schemas/capture" refund: $ref: "#/components/schemas/refund" transaction: type: object title: Transaction description: An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment. properties: amount: $ref: "#/components/schemas/amount" description: The amount to collect. payee: $ref: "#/components/schemas/payee" description: type: string description: The purchase description. maxLength: 127 note_to_payee: type: string description: The note to the recipient of the funds in this transaction. maxLength: 255 custom: type: string description: The free-form field for the client's use. maxLength: 127 invoice_number: type: string description: The invoice number to track this payment. maxLength: 127 soft_descriptor: type: string description: The soft descriptor to use to charge this funding source. If greater than the maximum allowed length, the API truncates the string. maxLength: 22 payment_options: type: object title: Payment Options description: The payment options for this transaction. properties: allowed_payment_method: type: string description: The payment method for this transaction. This field does not apply to the credit card payment method. default: UNRESTRICTED enum: - UNRESTRICTED - INSTANT_FUNDING_SOURCE - IMMEDIATE_PAY item_list: type: object title: Item List description: An array of items that are being purchased. properties: items: type: array description: An array of items that are being purchased. items: $ref: "#/components/schemas/item" shipping_address: $ref: "#/components/schemas/shipping_address" shipping_method: type: string description: The shipping method used for this payment, such as USPS Parcel. shipping_phone_number: type: string description: The shipping phone number, in its canonical international format as defined by the [E.164](https://en.wikipedia.org/wiki/E.164) numbering plan. Enables merchants to share payer’s contact number with PayPal for the current payment. The final contact number for the payer who is associated with the transaction might be the same as or different from the `shipping_phone_number` based on the payer’s action on PayPal. notify_url: type: string format: uri description: The URL to send payment notifications. maxLength: 2048 related_resources: type: array description: An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment. readOnly: true items: $ref: "#/components/schemas/related_resources" payment: type: object title: Payment description: The payment details. properties: id: type: string description: The ID of the payment. readOnly: true intent: type: string description: The payment intent. Value is: enum: - sale - authorize - order payer: description: The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit. $ref: "#/components/schemas/payer" application_context: description: Use the application context resource to customize payment flow experience for your buyers. $ref: "#/components/schemas/application_context" transactions: type: array description: An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment. For update and execute payment calls, the **`transactions`** object accepts the **`amount`** object only. items: $ref: "#/components/schemas/transaction" state: type: string description: The state of the payment, authorization, or order transaction. Value is: enum: - created - approved - failed - partially_completed - in_progress readOnly: true experience_profile_id: type: string description: Deprecated. The PayPal-generated ID for the merchant's payment experience profile. For information, see [create web experience profile](/docs/api/payment-experience/v1/#web-profiles_create). Use application_context instead. note_to_payer: type: string description: A free-form field that clients can use to send a note to the payer. maxLength: 165 redirect_urls: type: object description: A set of redirect URLs that you provide for PayPal-based payments. title: Redirect URLs additionalProperties: false properties: return_url: type: string format: uri description: The URL where the payer is redirected after he or she approves the payment. **Required for PayPal account payments**. cancel_url: type: string format: uri description: The URL where the payer is redirected after he or she cancels the payment. **Required for PayPal account payments**. failure_reason: type: string description: The reason code for a payment failure. enum: - UNABLE_TO_COMPLETE_TRANSACTION - INVALID_PAYMENT_METHOD - PAYER_CANNOT_PAY - CANNOT_PAY_THIS_PAYEE - REDIRECT_REQUIRED - PAYEE_FILTER_RESTRICTIONS readOnly: true create_time: type: string format: date-time description: The date and time when the payment was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string format: date-time description: The date and time when the payment was updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" required: - intent - payer payment_history: type: object title: "Payment History " description: An array of merchant payments that are complete. Payments that you just created with the [create payment](/docs/api/payments/v1/#payment_create) call do not appear in the list. properties: payments: type: array description: An array of payments that are complete. Payments that you just created with the [create payment](/docs/api/payments/v1/#payment_create) call do not appear in the list. items: $ref: "#/components/schemas/payment" count: type: integer description: The number of items returned in each range of results. Note that the last results range might have fewer items than the requested number of items. maximum: 20 next_id: type: string description: The ID of the element to use to get the next range of results. readOnly: true patch: type: object title: Patch description: The JSON patch object to apply partial updates to resources. properties: op: type: string description: The operation. enum: - add - remove - replace - move - copy - test path: type: string description: The JSON Pointer to the target document location at which to complete the operation. value: title: Patch Value description: The value to apply. The remove operation does not require a value. from: type: string description: The JSON Pointer to the target document location from which to move the value. Required for the move operation. required: - op patch_request: type: array title: Patch Request description: An array of JSON patch objects to apply partial updates to resources. items: $ref: "#/components/schemas/patch" cart_base: type: object title: Cart Base description: The cart. properties: reference_id: type: string description: The merchant-provided ID for the purchase unit. maxLength: 256 amount: $ref: "#/components/schemas/amount" description: The amount to collect. payee: $ref: "#/components/schemas/payee" description: type: string description: The purchase description. maxLength: 127 note_to_payee: type: string description: The note to the recipient of the funds in this transaction. maxLength: 255 custom: type: string description: The free-form field for the client's use. maxLength: 127 invoice_number: type: string description: The invoice number to track this payment. maxLength: 127 soft_descriptor: type: string description: The payment descriptor on account transactions on the customer's credit card statement, that PayPal sends to processors. The maximum length of the soft descriptor information that you can pass in the API field is 22 characters, in the following format:
22 -
            len(PAYPAL * (8)) - len(Descriptor in Payment Receiving
            Preferences of Merchant account + 1)
The PAYPAL prefix uses 8 characters.

The soft descriptor supports the following ASCII characters:For Wallet payments marketplace integrations:
For unbranded payments (Direct Card) marketplace integrations, use a combination of the seller name and phone number. maxLength: 22 payment_options: type: object title: Payment Options description: The payment options for this transaction. properties: allowed_payment_method: type: string description: The payment method for this transaction. This field does not apply to the credit card payment method. default: UNRESTRICTED enum: - UNRESTRICTED - INSTANT_FUNDING_SOURCE - IMMEDIATE_PAY item_list: type: object title: Item List description: An array of items that are being purchased. properties: items: type: array description: An array of items that are being purchased. items: $ref: "#/components/schemas/item" shipping_address: $ref: "#/components/schemas/shipping_address" shipping_phone_number: type: string description: The shipping phone number, in its canonical international format as defined by the [E.164](https://en.wikipedia.org/wiki/E.164) numbering plan. Enables merchants to share payer’s contact number with PayPal for the current payment. The final contact number for the payer who is associated with the transaction might be the same as or different from the `shipping_phone_number` based on the payer’s action on PayPal. minLength: 1 maxLength: 50 notify_url: type: string format: uri description: The send payment notifications URL. maxLength: 2048 order_url: type: string format: uri description: The payment-related URL on the merchant site. maxLength: 2048 required: - amount payment_execution: type: object title: Payment Execution description: Executes a PayPal account-based payment with the `payer_id` obtained from the web approval URL. properties: payer_id: type: string description: The ID of the payer that PayPal passes in the `return_url`. transactions: type: array description: An array of transaction details. Includes the amount and item details. For update and execute payment calls, the `transactions` object accepts only the `amount` object. items: $ref: "#/components/schemas/cart_base" refund_request: type: object title: Refund Request description: The refund request. properties: amount: description: The refund amount. Includes both the amount to refund to the payer and the fee amount to refund to the payee. $ref: "#/components/schemas/amount" description: type: string description: The refund description. Value is a string of single-byte alphanumeric characters. maxLength: 255 reason: type: string description: The refund reason description. maxLength: 30 invoice_number: type: string description: The invoice number that tracks this payment. Value is a string of single-byte alphanumeric characters. maxLength: 127 refund-2: type: object title: Refund description: The refund transaction details. properties: id: type: string readOnly: true description: The ID of the refund transaction. maxLength: 17 amount: description: The refund amount. Includes both the amount refunded to the payer and the fee refunded to the payee. $ref: "#/components/schemas/amount" state: type: string enum: - pending - completed - cancelled - failed description: The state of the refund. readOnly: true reason: type: string description: The reason that the transaction is being refunded. invoice_number: type: string description: Your own invoice or tracking ID number. Value is a string of single-byte alphanumeric characters. maxLength: 127 sale_id: type: string readOnly: true description: The ID of the sale transaction being refunded. capture_id: type: string readOnly: true description: The ID of the sale transaction being refunded. parent_payment: type: string readOnly: true description: The ID of the payment on which this transaction is based. description: type: string description: The refund description. create_time: type: string format: date-time description: The date and time when the refund was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string format: date-time description: The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: "#/components/schemas/link_description" detailed_refund: type: object title: Detailed Refund description: The refund transaction details. allOf: - $ref: "#/components/schemas/refund-2" - properties: custom: type: string description: The note to the payer in this transaction. maxLength: 127 invoice_number: type: string description: The invoice number to track this payment. maxLength: 127 refund_from_transaction_fee: description: The currency and amount of the transaction fee that is refunded to original the recipient of payment. $ref: "#/components/schemas/currency" refund_from_received_amount: description: The currency and amount of the refund that is subtracted from the original payment recipient's PayPal balance. $ref: "#/components/schemas/currency" total_refunded_amount: description: The currency and amount of the total refund from the original purchase. For example, if a payer makes $100 purchase and the payer was refunded $20 a week ago and $30 in this transaction, the gross refund amount is $30 for this transaction and the total refunded amount is $50. $ref: "#/components/schemas/currency" parameters: paypal_partner_attribution_id: name: PayPal-Partner-Attribution-Id in: header required: false schema: type: string maxLength: 32 count: name: count in: query description: The number of items to list in the response. required: false schema: type: integer maximum: 20 default: 10 start_id: name: start_id in: query description: The ID of the starting resource in the response. When results are paged, you can use the `next_id` value as the `start_id` to continue with the next set of results. required: false schema: type: string start_index: name: start_index in: query description: The start index of the payments to list. Typically, you use the `start_index` to jump to a specific position in the resource history based on its cart. For example, to start at the second item in a list of results, specify `?start_index=2`. required: false schema: type: integer start_time: name: start_time in: query description: The start date and time for the range to show in the response, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `start_time=2016-03-06T11:00:00Z`. required: false schema: type: string end_time: name: end_time in: query description: The end date and time for the range to show in the response, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `end_time=2016-03-06T11:00:00Z`. required: false schema: type: string payee_id: name: payee_id in: query description: Filters the payments in the response by a PayPal-assigned merchant ID that identifies the payee. required: false schema: type: string sort_by: name: sort_by in: query description: Sorts the payments in the response by a create time. required: false schema: type: string enum: - create_time sort_order: name: sort_order in: query description: Sorts the payments in the response in descending order. required: false schema: type: string enum: - desc payment_id: name: payment_id in: path description: The ID of the payment to execute. required: true schema: type: string paypal_request_id: name: PayPal-Request-Id description: The server stores keys for 30 days. in: header required: false schema: type: string maxLength: 78 sale_id: name: sale_id in: path description: The ID of the sale transaction to refund. required: true schema: type: string authorization_id: name: authorization_id in: path description: The ID of the authorization to re-authorize. required: true schema: type: string order_id: name: order_id in: path description: The ID of the order to authorize. required: true schema: type: string capture_id: name: capture_id in: path description: The ID of the captured payment to refund. required: true schema: type: string refund_id: name: refund_id in: path description: The ID of the refund for which to show details. required: true schema: type: string x-hidden: true x-errors: - name: AGREEMENT_ALREADY_CANCELLED message: The requested agreement is already canceled. description: The agreement that was used to make the payment is already canceled. - name: AMOUNT_MISMATCH message: The totals of the cart item amounts do not match sale amounts. description: The amount total does not match the item amount totals. - name: AUTH_SETTLE_NOT_ALLOWED message: Authorization and Capture feature is not enabled for the merchant. description: Make sure that the recipient of the funds is a verified business account. - name: AUTHORIZATION_ALREADY_COMPLETED message: Capture refused - this authorization has already been completed. description: The capture on the authorization failed because it was already completed by one or more previous captures on this authorization. - name: AUTHORIZATION_AMOUNT_LIMIT_EXCEEDED message: Authorization amount exceeds allowed order limit. description: The authorization amount exceeds the allowed order limit. - name: AUTHORIZATION_CANNOT_BE_VOIDED message: Authorization is in [x] state and hence cannot be voided. description: You cannot void this authorization because it is in a state, such as `captured` or `expired`, that cannot be voided. - name: AUTHORIZATION_EXPIRED message: Authorization has expired. description: The authorization related to this request has expired. You must reauthorize the transaction. - name: AUTHORIZATION_ID_DOES_NOT_EXIST message: The requested authorization ID does not exist. description: The authorization ID in the request does not exist in the PayPal system. - name: AUTHORIZATION_VOIDED message: Authorization has been voided. description: This authorization was already voided. You can [show authorization details](/docs/api/payments/v1/#authorization_get) for a voided authorization. - name: BA_TOKEN_CREATION_FAILED message: Billing agreement token creation failed. description: The billing agreement token creation failed. - name: BANK_ACCOUNT_VALIDATION_FAILED message: Bank account validation failed. description: The validation of the bank account failed. - name: BILLING_AGREEMENT_CREATION_FAILED message: Billing agreement creation failed. description: The billing agreement creation failed. - name: BUYER_NOT_SET message: Buyer is not yet set for this purchase. description: The customer cannot make this purchase. - name: CANNOT_PAY_SELF message: Payer cannot pay him- or herself. description: The customer cannot pay him- or herself. - name: PLATFORM_FEE_PAYEE_CANNOT_BE_SAME_AS_PAYER message: The payer cannot pay themselves. The recipient account of the platform fees must be different from the payer account. description: The customer cannot pay platform fee for themselves. - name: CANNOT_REAUTH_CHILD_AUTHORIZATION message: Can only reauthorize the original authorization, not a reauthorization. description: Reauthorization only works on an original authorization ID. - name: CANNOT_REAUTH_INSIDE_HONOR_PERIOD message: Reauthorization is not allowed within the honor period. description: You can only reauthorize a payment after the three-day honor period concludes. - name: CAPTURE_AMOUNT_LIMIT_EXCEEDED message: Capture amount specified exceeded allowable limit. description: You can only capture up to the original authorization amount. - name: CARD_TOKEN_PAYER_MISMATCH message: "`payer_id` does not match ID for this token." description: The `payer_id` must match the one that was provided when the credit card was stored in the vault. - name: COMPLIANCE_VIOLATION message: Transaction is declined due to compliance violation. description: The transaction is declined due to a compliance violation. - name: CREDIT_CARD_CVV_CHECK_FAILED message: The credit card CVV check failed. description: The CVV provided for the credit card was not valid. Resend the payment with a valid CVV for the credit card. - name: CREDIT_CARD_REFUSED message: Credit card was refused. description: The credit card used for the payment was refused. Resend the request with another credit card. - name: CREDIT_PAYMENT_NOT_ALLOWED message: Buyer cannot use credit to complete the payment. description: You cannot use credit to complete this payment. Ask the customer to retry the transaction with alternate funding instrument. - name: CURRENCY_MISMATCH message: Currency provided in the request must match the currency of the parent order or authorization. description: The currency that was used to capture an authorization must match the original currency of the authorization. - name: CURRENCY_NOT_ALLOWED message: Currency is not supported. description: The currency is not currently supported. - name: DOMESTIC_TRANSACTION_REQUIRED message: This transaction requires the payee and payer to be resident in the same country, a domestic transaction is required to create this payment. description: The payer and payee do not reside in the same country. - name: DUPLICATE_REQUEST_ID message: The value of PayPal-Request-Id header has already been used. description: Resend the request with a unique `PayPal-Request-Id` header value. - name: DUPLICATE_TRANSACTION message: Duplicate invoice Id detected. description: Resend the request with a unique `invoice_number` value. - name: ERROR_AUTH message: Unauthorized payment. description: You do not have the proper permissions to complete this request. - name: EXPIRED_CREDIT_CARD_TOKEN message: Credit card token is expired. description: Use the Vault API to store the credit card again. - name: FEATURE_UNSUPPORTED_FOR_PAYEE message: This feature is unsupported. description: This feature is not supported for the payee. - name: FULL_REFUND_NOT_ALLOWED_AFTER_PARTIAL_REFUND message: Full refund refused - partial refund has already been done on this payment. description: You cannot refund the full payment amount after you have partially refunded a payment. - name: IMMEDIATE_PAY_NOT_SUPPORTED message: Immediate pay is not supported for the specified payment intent. description: For this payment intent, immediate payment is not supported. - name: INSTRUMENT_DECLINED message: The instrument presented was either declined by the processor or bank, or it can't be used for this payment. description: If the customer's funding source has insufficient funds, restart the payment and prompt the customer to choose another payment method that is available on your site. - name: INSUFFICIENT_FUNDS message: Buyer cannot pay - insufficient funds. description: The customer must add a valid funding instrument, such as a credit card or bank account, to their PayPal account. - name: INTERNAL_SERVICE_ERROR message: An internal service error has occurred. description: Resend the request at another time. If this error persists, contact [PayPal Merchant Technical Support](https://www.paypal-support.com). - name: INVALID_ACCOUNT_NUMBER message: Account number does not exist. description: Provide a valid account number and resend the request. - name: INVALID_CITY_STATE_ZIP message: The combination of city, state, and zip in the address is invalid. description: The address contains an invalid combination of a city, state, and zip code. - name: INVALID_EXPERIENCE_PROFILE_ID message: The requested experience profile ID was not found. description: To get the profile ID for a merchant, [list web experience profiles](/docs/api/payment-experience/v1/#web-profiles_get-list). - name: INVALID_FACILITATOR_CONFIGURATION message: This transaction cannot be processed due to an invalid facilitator configuration. description: To process this transaction type, you must have the right account configuration. - name: INVALID_PAYER_ID message: Payer ID is invalid. description: The specified `payer_id` is not valid. Resend the request with a valid `payer_id`. - name: INVALID_RESOURCE_ID message: The requested resource ID was not found. description: Provide a valid resource ID and resend the request. - name: MALFORMED_REQUEST message: JSON request is malformed. description: Review the JSON request. - name: MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED message: You have exceeded the maximum number of payment attempts. description: The maximum number of payment attempts was reached. - name: MAXIMUM_ALLOWED_AUTHORIZATION_REACHED_FOR_ORDER message: You have reached the configured maximum number of authorizations allowed for an order. description: You cannot create any more authorizations for this order. - name: MERCHANT_NOT_ENABLED_FOR_CHANNEL_INITIATED_BILLING message: Merchant is not enabled for channel-initiated billing. description: The merchant cannot use channel-initiated billing. - name: MERCHANT_NOT_ENABLED_FOR_REFERENCE_TRANSACTION message: Merchant is not enabled for reference transaction. description: The merchant cannot make reference transactions. - name: NEED_CREDIT_CARD message: Need credit card to complete the payment. description: To complete this payment, a credit card is required. - name: NEED_CREDIT_CARD_OR_BANK_ACCOUNT message: Need bank or credit card to complete the payment. description: To complete this payment, a bank card or credit card is required. - name: NOT_IMPLEMENTED message: Not implemented. description: This API capability is not implemented. - name: ORDER_ALREADY_COMPLETED message: Order has already been voided, expired, or completed. description: This order was already voided, completed, or expired. - name: ORDER_CANNOT_BE_VOIDED message: You can only void orders that are either in the `PENDING` or `AUTHORIZED` state, or those in the `CAPTURED` state that are not fully captured. description: Due to the state of the order, you cannot void it. - name: ORDER_IS_EXPIRED message: Order has expired. description: The order has expired. - name: ORDER_VOIDED message: Order has been voided. description: The order was already voided. For more information, you can [show order details](/docs/api/payments/v1/#orders_get). - name: PAYEE_ACCOUNT_INVALID message: Payee account is invalid. description: The payee account is not valid. - name: PAYEE_ACCOUNT_LOCKED_OR_CLOSED message: Payee account is locked or closed. description: The recipient account is locked or closed and cannot receive payments. - name: PAYEE_ACCOUNT_NO_CONFIRMED_EMAIL message: Refused - payee account does not have a confirmed email. description: For this transaction to proceed, the payment recipient must have a confirmed email. - name: PAYEE_ACCOUNT_RESTRICTED message: Refused - payee account is restricted. description: The account receiving this payment is restricted and cannot receive payments at this time. - name: PAYEE_BLOCKED_TRANSACTION message: The Fraud settings for this seller are such that this payment cannot be executed. description: The fraud filter configuration for the seller blocks this payment. - name: PAYEE_COUNTRY_NOT_ENABLED message: Payee country is not enabled for this feature. description: The payee country is not enabled for billing product. - name: PAYER_ACCOUNT_LOCKED_OR_CLOSED message: The payer account cannot be used for this transaction. description: The payer account is locked or closed. - name: PAYER_ACCOUNT_RESTRICTED message: The payer account is restricted. description: The payer account cannot be used for this transaction. - name: PAYER_ACTION_REQUIRED message: Transaction cannot complete successfully, instruct the buyer to return to PP. description: The customer must return to PayPal to before the transaction can complete. - name: PAYER_CANNOT_PAY message: Payer cannot pay for this transaction. description: Payer cannot pay for this transaction. Please contact the payer to find other ways to pay for this transaction. - name: PAYER_COUNTRY_NOT_ENABLED message: Payer country is not enabled for this feature. description: The payer country is not enabled for billing product. - name: PAYER_EMPTY_BILLING_ADDRESS message: Billing address is empty. description: The billing address is required for credit card transactions without a PayPal account. - name: PAYER_ID_MISSING_FOR_CARD_TOKEN message: "`payer_id` is required for payments made with this token." description: A `payer_id` is required when one was used to store the credit card in the vault. - name: PAYMENT_ALREADY_DONE message: Payment has been done already for this cart. description: You have completed the payment for this request already. Look up the transaction to get the details. - name: PAYMENT_APPROVAL_EXPIRED message: Payment approval has expired. description: Inform customers that the transaction has expired and that they must restart the transaction. Offer customers a link to restart the payment flow from payment creation and redirect the customer to PayPal. - name: PAYMENT_CANNOT_BE_INITIATED message: Payment cannot be processed. description: PayPal cannot start processing the payment due to an issue with the specified information. - name: PAYMENT_DENIED message: PayPal has declined to process this transaction. description: PayPal declined the payment due to one or more customer issues. - name: PAYMENT_EXPIRED message: The payment is expired. description: The payment expired because too much time has passed between payment creation or approval and execution of that payment. Restart the payment request starting from payment creation. - name: PAYMENT_METHOD_UNUSABLE message: Payer cannot pay with this payment method. description: The specified payment method is not usable. For example, PayPal business rules do not allow the payment method or the payment method information was incorrect in the request. - name: PAYMENT_NOT_APPROVED_FOR_EXECUTION message: Payer has not approved payment. description: The customer must approve all payments that use the PayPal payment method. - name: PAYMENT_REQUEST_ID_INVALID message: PayPal request ID is invalid. Please try a different one. description: Try a different PayPal request ID. - name: PAYMENT_STATE_INVALID message: This request is invalid due to the current state of the payment. description: The payment state does not allow this kind of request. - name: PERMISSION_DENIED message: No permission for the requested operation. description: You do not have the proper permissions to complete this request. - name: PHONE_NUMBER_REQUIRED message: This transaction requires the payer to provide a valid phone number. description: The customer must provide a phone number to PayPal to proceed with the payment. - name: REAUTH_NOT_SUPPORTED_FOR_ORDER message: Re-authorization is not allowed for this type of authorization. description: You cannot re-authorize an order. - name: REDIRECT_PAYER_FOR_ALTERNATE_FUNDING message: Transaction failed. Redirect the payer to select another funding source. description: The transaction failed so try another funding instrument. - name: REFUND_EXCEEDED_TRANSACTION_AMOUNT message: Refund refused - the requested refund amount would exceed the amount of transaction being refunded. description: The requested refund must be less than or equal to the original transaction amount. To see the original transaction amount, [show the refund details](/docs/api/payments/v1/#refund_get). - name: REFUND_FAILED_INSUFFICIENT_FUNDS message: Refund failed due to insufficient funds in your PayPal account. description: You do not have sufficient funds in your PayPal account to process this refund. - name: REFUND_TIME_LIMIT_EXCEEDED message: This transaction is too old to refund. description: For information about refund time limits, see [PayPal Customer Support](https://www.paypal.com/us/selfhelp/home). After the time limit expires, you must send a payment instead of issuing a refund. - name: REQUESTED_OPERATION_REFUSED_DUE_TO_SELLER_OPT_OUT message: You cannot perform this operation as payee has opted out on PayPal.com. description: The third-party-initiated operations are blocked because the payee has opted out on paypal.com. - name: REQUIRED_SCOPE_MISSING message: Access token does not have required scope. description: You must get user consent with the correct scope for this type of request. - name: SENDING_LIMIT_EXCEEDED message: The transaction exceeds the buyer's sending limit. description: The customer cannot make any more transactions. - name: SHIPPING_ADDRESS_INVALID message: Provided shipping address is invalid. description: The specified shipping address is not valid. - name: TOO_MANY_REAUTHORIZATIONS message: Maximum number of reauthorizations for this authorization has been reached. description: You can only reauthorize a payment once. - name: TOO_MANY_SETTLEMENTS message: Maximum number of allowable settlements has been reached. No more settlement for the authorization. description: The maximum number of settlements was reached. - name: TRANSACTION_ALREADY_REFUNDED message: Refund transaction refused - this transaction has already been refunded. description: You can only refund a transaction up to the original amount. While you can do multiple partial refunds up to the original amount, you can only do a full refund once. - name: TRANSACTION_LIMIT_EXCEEDED message: Total payment amount exceeded transaction limit. description: The transaction limit was exceeded. For information about the PayPal transaction limits, see [PayPal Customer Support](https://www.paypal.com/us/selfhelp/home). - name: TRANSACTION_RECEIVING_LIMIT_EXCEEDED message: The transaction exceeds the receiver’s receiving limit. description: The amount exceeds the maximum amount for a single transaction. - name: TRANSACTION_REFUSED message: This request was refused. description: The possible reasons for this failure are: - name: TRANSACTION_REFUSED_BY_PAYPAL_RISK message: PayPal risk refused this transaction. description: PayPal risk assessment refused this transaction. - name: TRANSACTION_REFUSED_PAYEE_PREFERENCE message: Merchant profile preference is set to automatically deny certain transactions. description: The merchant account preferences are set to deny this kind of transaction. - name: UNAUTHORIZED_PAYMENT message: Unauthorized payment. description: This payment was not authorized. - name: UNSUPPORTED_PAYEE_COUNTRY message: Payee country is not supported for this transaction. description: The merchant does not accept payments from this country. - name: UNSUPPORTED_PAYEE_CURRENCY message: The currency is not accepted by payee. description: The merchant does not accept payments in this currency. - name: VALIDATION_ERROR message: Invalid request - see details. description: A validation error occurred with your request. - name: BILLING_AGREEMENT_ID_MISMATCH message: Billing Agreement ID must match the one that was provided during payment creation. description: Billing Agreement ID must match the one that was provided during payment creation. - name: INVALID_PICKUP_ADDRESS message: Invalid shipping address. description: "If the 'shipping_option.type' is set as 'PICKUP' then the 'shipping_address.recipient_name' should start with 'S2S' meaning Ship To Store. Example: 'S2S My Store'." - name: INVALID_PAYPAL_PAYMENT_TOKEN message: Payment token is invalid. A payment token is typically valid for 3 hours since the time it was issued. Please check the token and try again. description: Will be returned only for [Google Pay Integration](/docs/archive/checkout/how-to/googlepay-integration) for the [Create payment](https://developer.paypal.com/docs/api/payments/v1/#payment_create) call. - name: PREVIOUS_REQUEST_IN_PROGRESS message: 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. 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.