Payments (2)

API Version v2

Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the Orders API. For more information, see the PayPal Checkout Overview.

Show details for authorized payment

get/v2/payments/authorizations/{authorization_id}

Shows details for an authorized payment, by ID.

SecurityOauth2
Request
path Parameters
authorization_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The ID of the authorized payment for which to show details.

header Parameters
Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
PayPal-Auth-Assertion
string [ 1 .. 10000 ] characters ^.*$

Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.

Examples:
A paypal-auth-assertion header with a randomized value.
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows authorization details.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

default

Default response.

Response samples
application/json

Shows details for an authorized payment, by ID.

{}

Capture authorized payment

post/v2/payments/authorizations/{authorization_id}/capture

Captures an authorized payment, by ID.

SecurityOauth2
Request
path Parameters
authorization_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the authorized payment to capture.

header Parameters
PayPal-Request-Id
string [ 1 .. 10000 ] characters ^.*$

A unique ID identifying the request header for idempotency purposes.

Examples:
A paypal-request-id header with a randomized value.
17e81d06-77ab-11e8-adc0-fa71639ebebc
Prefer
string [ 0 .. 2147483647 ] characters ^[\S\s]*$
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
PayPal-Auth-Assertion
string [ 1 .. 10000 ] characters ^.*$

Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.

Examples:
A paypal-auth-assertion header with a randomized value.
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
Request Body schema: application/json
optional
invoice_id
string [ 0 .. 127 ] characters ^[\S\s]*$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

note_to_payer
string [ 0 .. 255 ] characters ^[\S\s]*$

An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.

object (amount_with_breakdown)

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

final_capture
boolean
Default: false

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

object (payment_instruction)

Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.

soft_descriptor
string [ 0 .. 22 ] characters ^[\S\s]*$

The payment descriptor on the payer's account statement.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows captured payment details.

201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows captured payment details.

400

The request failed because it is not well-formed or is syntactically incorrect or violates schema.

401

Unauthorized.

403

Forbidden.

404

Not Found.

409

The server has detected a conflict while processing this request.

422

The request failed because it is semantically incorrect or failed business validation.

500

Internal Server Error.

default

Default response.

Request samples
application/json

Captures an authorized payment, by ID.

{
  • "amount": {
    • "value": "10.99",
    • "currency_code": "USD"
    },
  • "invoice_id": "INVOICE-123",
  • "final_capture": true,
  • "note_to_payer": "If the ordered color is not available, we will substitute with a different color free of charge.",
  • "soft_descriptor": "Bob's Custom Sweaters"
}
Response samples
application/json

Captures an authorized payment, by ID.

{}

Reauthorize authorized payment

post/v2/payments/authorizations/{authorization_id}/reauthorize

Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires.

If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.

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

You can reauthorize an authorized payment from 4 to 29 days after the 3-day honor period. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.

Supports only the amount request parameter.

SecurityOauth2
Request
path Parameters
authorization_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the authorized payment to reauthorize.

header Parameters
PayPal-Request-Id
string [ 1 .. 10000 ] characters ^.*$

A unique ID identifying the request header for idempotency purposes.

Examples:
A paypal-request-id header with a randomized value.
17e81d06-77ab-11e8-adc0-fa71639ebebc
Prefer
string [ 0 .. 2147483647 ] characters ^[\S\s]*$
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
PayPal-Auth-Assertion
string [ 1 .. 10000 ] characters ^.*$

Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.

Examples:
A paypal-auth-assertion header with a randomized value.
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
Request Body schema: application/json
optional
object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the reauthorized payment details.

201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows the reauthorized payment details.

400

The request failed because it is not well-formed or is syntactically incorrect or violates schema.

401

Unauthorized.

403

Forbidden.

404

Not Found.

422

The request failed because it either is semantically incorrect or failed business validation.

500

Internal Server Error.

default

Default response.

Request samples
application/json

Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.

{
  • "amount": {
    • "value": "10.99",
    • "currency_code": "USD"
    }
}
Response samples
application/json

Reauthorizes an authorized payment, by ID. The honor period for the authorized payment has expired.

{}

Void authorized payment

post/v2/payments/authorizations/{authorization_id}/void

Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.

SecurityOauth2
Request
path Parameters
authorization_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the authorized payment to void.

header Parameters
Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
PayPal-Auth-Assertion
string [ 1 .. 10000 ] characters ^.*$

Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.

Examples:
A paypal-auth-assertion header with a randomized value.
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
PayPal-Request-Id
string [ 1 .. 10000 ] characters ^.*$

A unique ID identifying the request header for idempotency purposes.

Examples:
A paypal-request-id header with a randomized value.
17e81d06-77ab-11e8-adc0-fa71639ebebc
Prefer
string [ 0 .. 2147483647 ] characters ^[\S\s]*$
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows authorization details. This response is returned when the Prefer header is set to return=representation.

204

No Content.

401

Unauthorized.

403

Forbidden.

404

Not Found.

409

The request failed because a previous call for the given resource is in progress.

422

The request failed because it either is semantically incorrect or failed business validation.

500

Internal Server Error.

default

Default response.

Response samples
application/json

Voids an authorized PayPal account payment, by ID. You cannot void an authorized payment that has been fully captured.

{
  • "id": "5C908745JK343851U",
  • "status": "VOIDED",
  • "amount": {
    • "currency_code": "USD",
    • "value": "100.00"
    },
  • "invoice_id": "OrderInvoice-10_10_2024_12_06_00_pm",
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "ITEM_NOT_RECEIVED",
      • "UNAUTHORIZED_TRANSACTION"
      ]
    },
  • "expiration_time": "2024-11-08T09:06:03-08:00",
  • "create_time": "2024-10-10T10:06:03-07:00",
  • "update_time": "2024-10-10T10:06:19-07:00",
  • "links": []
}

Show captured payment details

get/v2/payments/captures/{capture_id}

Shows details for a captured payment, by ID.

SecurityOauth2
Request
path Parameters
capture_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the captured payment for which to show details.

header Parameters
Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows captured payment details.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

default

Default response.

Response samples
application/json

Shows details for a captured payment, by ID.

{
  • "id": "74L756601X447022Y",
  • "amount": {
    • "currency_code": "USD",
    • "value": "100.00"
    },
  • "final_capture": true,
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "ITEM_NOT_RECEIVED",
      • "UNAUTHORIZED_TRANSACTION"
      ]
    },
  • "seller_receivable_breakdown": {
    • "gross_amount": {
      • "currency_code": "USD",
      • "value": "100.00"
      },
    • "paypal_fee": {
      • "currency_code": "USD",
      • "value": "3.98"
      },
    • "net_amount": {
      • "currency_code": "USD",
      • "value": "96.02"
      }
    },
  • "invoice_id": "OrderInvoice-23_10_2024_12_27_32_pm",
  • "status": "COMPLETED",
  • "supplementary_data": {
    • "related_ids": {
      • "order_id": "25M43554V9523650M",
      • "authorization_id": "0T620041CK889853A"
      }
    },
  • "payee": {
    • "email_address": "merchant@example.com",
    • "merchant_id": "YXZY75W2GKDQE"
    },
  • "create_time": "2024-10-23T20:55:19Z",
  • "update_time": "2024-10-23T20:55:19Z",
  • "links": []
}

Refund captured payment

post/v2/payments/captures/{capture_id}/refund

Refunds a captured payment, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an amount object in the JSON request body.

SecurityOauth2
Request
path Parameters
capture_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the captured payment to refund.

header Parameters
PayPal-Request-Id
string [ 1 .. 10000 ] characters ^.*$

A unique ID identifying the request header for idempotency purposes.

Examples:
A paypal-request-id header with a randomized value.
17e81d06-77ab-11e8-adc0-fa71639ebebc
Prefer
string [ 0 .. 2147483647 ] characters ^[\S\s]*$
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
PayPal-Auth-Assertion
string [ 1 .. 10000 ] characters ^.*$

Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.

Examples:
A paypal-auth-assertion header with a randomized value.
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
Request Body schema: application/json
optional
object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

custom_id
string [ 1 .. 127 ] characters ^.*$

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. The pattern is defined by an external party and supports Unicode.

invoice_id
string [ 1 .. 127 ] characters ^.*$

The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode.

note_to_payer
string [ 1 .. 255 ] characters ^.*$

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. The pattern is defined by an external party and supports Unicode.

object (payment_instruction)

Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.

201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows refund details.

400

The request failed because it is not well-formed or is syntactically incorrect or violates schema.

401

Unauthorized.

403

Forbidden.

404

Not Found.

409

The request failed because a previous call for the given resource is in progress.

422

The request failed because it either is semantically incorrect or failed business validation.

500

Internal Server Error.

default

Default response.

Request samples
application/json

Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an amount object.

{
  • "amount": {
    • "value": "1.00",
    • "currency_code": "USD"
    },
  • "invoice_id": "RefundInvoice-123",
  • "custom_id": "RefundCustom-123"
}
Response samples
application/json

Refunds a captured payment, by ID. For a full refund, include an empty payload in the request body. For a partial refund, include an amount object.

{
  • "id": "0K35355239430361V",
  • "amount": {
    • "currency_code": "USD",
    • "value": "1.00"
    },
  • "seller_payable_breakdown": {
    • "gross_amount": {
      • "currency_code": "USD",
      • "value": "1.00"
      },
    • "paypal_fee": {
      • "currency_code": "USD",
      • "value": "0.00"
      },
    • "net_amount": {
      • "currency_code": "USD",
      • "value": "1.00"
      },
    • "total_refunded_amount": {
      • "currency_code": "USD",
      • "value": "11.00"
      }
    },
  • "invoice_id": "RefundInvoice-14_10_2024_4_58_32_pm",
  • "custom_id": "RefundCustom-14_10_2024_4_58_32_pm",
  • "status": "COMPLETED",
  • "create_time": "2024-10-14T14:58:34-07:00",
  • "update_time": "2024-10-14T14:58:34-07:00",
  • "links": []
}

Find a list of eligible payment methods.

post/v2/payments/find-eligible-methods

Get a list of eligible payment methods based on the input parameters provided.

SecurityOauth2
Request
header Parameters
Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
PayPal-Auth-Assertion
string [ 1 .. 10000 ] characters ^.*$

Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.

Examples:
A paypal-auth-assertion header with a randomized value.
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
User-Agent
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

A characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent. API calls made by PayPal SDKs SHOULD be identified using this request header.

Examples:
A user-agent header for Safari on iPad.
Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405
PayPal-Client-Metadata-Id
string (GUID) [ 1 .. 68 ] characters ^[A-Za-z0-9-{}(),]*$

A GUID value originating from Fraudnet and Dyson passed from external API clients via HTTP header. The value is used by Risk decisions to correlate calls which, in turn, might result in lower decline rates..

Examples:
A paypal-client-metadata-id header with a randomized value.
1295065d-6f34-42dc-ac65-fac0c86af250
Request Body schema: application/json
optional
object (Customer)

Customer who is making a purchase from the merchant/partner.

Array of objects (eligibility_purchase_unit_request) [ 1 .. 10 ] items

Array of purchase units.

object (Preferences)

Preferences of merchant/partner consuming the API.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that provides list of eligibile payments.

400

The request failed because it is not well-formed or is syntactically incorrect or violates schema.

401

Unauthorized.

403

Forbidden.

422

The request failed because it either is semantically incorrect or failed business validation.

500

Internal Server Error.

default

Default response.

Request samples
application/json

Eligible Payment Methods - Exclude listed payment methods

{
  • "customer": {
    • "country_code": "US",
    • "channel": {
      • "browser_type": "SAFARI",
      • "device_type": "MOBILE",
      • "client_os": "IOS"
      }
    },
  • "purchase_units": [
    • {
      • "amount": {
        • "currency_code": "USD",
        • "value": "100.00"
        }
      }
    ],
  • "preferences": {
    • "payment_source_constraint": {
      • "constraint_type": "EXCLUDE",
      • "payment_sources": [
        • "PAYPAL"
        ]
      }
    }
}
Response samples
application/json

Eligible Payment Methods - Exclude listed payment methods

{
  • "eligible_methods": {
    • "venmo": {
      • "can_be_vaulted": true
      }
    }
}

Show refund details

get/v2/payments/refunds/{refund_id}

Shows details for a refund, by ID.

SecurityOauth2
Request
path Parameters
refund_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the refund for which to show details.

header Parameters
Authorization
string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Holds authorization information for external API calls.

Examples:
An authorization header with information for the Bearer authorization scheme. The authorization parameter value is randomized for this example.
Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ
PayPal-Auth-Assertion
string [ 1 .. 10000 ] characters ^.*$

Header for an API client-provided JWT assertion that identifies the merchant. Establishing the consent to act-on-behalf of a merchant is a prerequisite for using this header.

Examples:
A paypal-auth-assertion header with a randomized value.
eyJhbGciOiJub25lIn0.eyJlbWFpbCI6Im15QGVtYWlsLmNvbSJ9
Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.

401

Unauthorized.

403

Forbidden.

404

Not Found.

500

Internal Server Error.

default

Default response.

Response samples
application/json

Shows details for a refund, by ID, with platform fees.

{
  • "id": "1JU08902781691411",
  • "amount": {
    • "value": "10.99",
    • "currency_code": "USD"
    },
  • "status": "COMPLETED",
  • "note": "Defective product",
  • "seller_payable_breakdown": {
    • "gross_amount": {
      • "value": "10.99",
      • "currency_code": "USD"
      },
    • "paypal_fee": {
      • "value": "0.33",
      • "currency_code": "USD"
      },
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "USD",
          • "value": "1.00"
          },
        • "payee": {
          • "email_address": "fee@example.com"
          }
        }
      ],
    • "net_amount": {
      • "value": "9.66",
      • "currency_code": "USD"
      },
    • "total_refunded_amount": {
      • "value": "10.99",
      • "currency_code": "USD"
      }
    },
  • "invoice_id": "INVOICE-123",
  • "create_time": "2018-09-11T23:24:19Z",
  • "update_time": "2018-09-11T23:24:19Z",
  • "links": []
}

Definitions

activity_timestamps

The date and time stamps that are common to authorized payment, captured payment, and refund transactions.

create_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

update_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

{
  • "create_time": "string",
  • "update_time": "string"
}

Advanced Cards Config

Configuration details for advanced card payment methods including credit and debit card processing capabilities.

can_be_vaulted
boolean

Indicates if the payment method can be saved for future use.

supports_installments
boolean

Indicates if installment payment option is available.

Array of objects (Card Vendor) [ 1 .. 100 ] items

Payment card vendors configuration.

{
  • "can_be_vaulted": true,
  • "supports_installments": true,
  • "vendors": [
    • {
      • "network": "AMEX",
      • "eligible": true,
      • "can_be_vaulted": true,
      • "branded": true
      }
    ]
}

amount_breakdown

The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (discount_with_breakdown)

The discount amount and currency code. For list of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

{
  • "item_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "handling": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "insurance": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_discount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "discount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

amount_with_breakdown

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

currency_code
required
string (currency_code) = 3 characters ^[\S\s]*$

The three-character ISO-4217 currency code that identifies the currency.

value
required
string [ 0 .. 32 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The value, which might be:

  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.

object (amount_breakdown)

The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.

{
  • "currency_code": "str",
  • "value": "string",
  • "breakdown": {
    • "item_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "handling": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "tax_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "insurance": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping_discount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "discount": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}

Apple Pay Config

Configuration details for Apple Pay payment method.

eligible
required
boolean

Indicates if Apple Pay is eligible.

merchant_country
required
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

supported_networks
required
Array of strings [ 1 .. 100 ] items

Supported card networks.

Items Enum Value Description
MASTERCARD

MasterCard network.

DISCOVER

Discover network.

VISA

Visa network.

AMEX

American Express network.

merchant_capabilities
required
Array of strings [ 1 .. 10 ] items

An array of the payment capabilities that the merchant supports.

Items Enum Value Description
SUPPORTS_CREDIT

Merchant supports credit card payments.

SUPPORTS_DEBIT

Merchant supports debit card payments.

SUPPORTS_3DS

Merchant supports 3D Secure authentication.

token_notification_url
required
string <uri> [ 10 .. 2000 ] characters

Token notification url for recurring payment request.

{
  • "eligible": true,
  • "merchant_country": "string",
  • "supported_networks": [
    • "MASTERCARD"
    ],
  • "merchant_capabilities": [
    • "SUPPORTS_CREDIT"
    ],
  • "token_notification_url": "http://example.com"
}

authorization

The authorized payment transaction.

status
string (Authorization Status)

The status for the authorized payment.

Enum Value Description
CREATED

The authorized payment is created. No captured payments have been made for this authorized payment.

CAPTURED

The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.

DENIED

PayPal cannot authorize funds for this authorized payment.

PARTIALLY_CAPTURED

A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.

VOIDED

The authorized payment was voided. No more captured payments can be made against this authorized payment.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized payment status.

id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the authorized payment.

object (amount_with_breakdown)

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

invoice_id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

custom_id
string [ 0 .. 255 ] characters ^[\S\s]*$

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

object (network_transaction)

Reference values used by the card network to identify a transaction.

object (seller_protection)

The level of protection offered as defined by PayPal Seller Protection for Merchants.

expiration_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

Array of objects (Link Description) [ 0 .. 32767 ] items

An array of related HATEOAS links.

create_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

update_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    },
  • "id": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "handling": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "insurance": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping_discount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "invoice_id": "string",
  • "custom_id": "string",
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA",
    • "acquirer_reference_number": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "ITEM_NOT_RECEIVED"
      ]
    },
  • "expiration_time": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "create_time": "string",
  • "update_time": "string"
}

Authorization

The authorized payment transaction.

status
string (Authorization Status)

The status for the authorized payment.

Enum Value Description
CREATED

The authorized payment is created. No captured payments have been made for this authorized payment.

CAPTURED

The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.

DENIED

PayPal cannot authorize funds for this authorized payment.

PARTIALLY_CAPTURED

A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.

VOIDED

The authorized payment was voided. No more captured payments can be made against this authorized payment.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized payment status.

id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the authorized payment.

object (amount_with_breakdown)

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

invoice_id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

custom_id
string [ 0 .. 255 ] characters ^[\S\s]*$

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

object (network_transaction)

Reference values used by the card network to identify a transaction.

object (seller_protection)

The level of protection offered as defined by PayPal Seller Protection for Merchants.

expiration_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

Array of objects (Link Description) [ 0 .. 32767 ] items

An array of related HATEOAS links.

create_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

update_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

object (Payment Supplementary Data)

The supplementary data.

object (payee_base)

The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    },
  • "id": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "handling": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "insurance": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping_discount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "invoice_id": "string",
  • "custom_id": "string",
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA",
    • "acquirer_reference_number": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "ITEM_NOT_RECEIVED"
      ]
    },
  • "expiration_time": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "create_time": "string",
  • "update_time": "string",
  • "supplementary_data": {
    • "related_ids": {
      • "order_id": "string",
      • "authorization_id": "string",
      • "capture_id": "string"
      }
    },
  • "payee": {
    • "email_address": "string",
    • "merchant_id": "string"
    }
}

authorization_status

The status fields and status details for an authorized payment.

status
string (Authorization Status)

The status for the authorized payment.

Enum Value Description
CREATED

The authorized payment is created. No captured payments have been made for this authorized payment.

CAPTURED

The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.

DENIED

PayPal cannot authorize funds for this authorized payment.

PARTIALLY_CAPTURED

A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.

VOIDED

The authorized payment was voided. No more captured payments can be made against this authorized payment.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized payment status.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    }
}

authorization_status_details

The details of the authorized payment status.

reason
string (Authorization Incomplete Reason)

The reason why the authorized status is PENDING.

Enum Value Description
PENDING_REVIEW

Authorization is pending manual review.

DECLINED_BY_RISK_FRAUD_FILTERS

Risk Filter set by the payee failed for the transaction.

{
  • "reason": "PENDING_REVIEW"
}

Basic Cards Config

Configuration details for basic card payment methods including credit and debit card processing capabilities.

can_be_vaulted
boolean

Indicates if the payment method can be saved for future use.

supports_installments
boolean

Indicates if installment payment option is available.

guest_enabled
boolean

Indicates if guest checkout is enabled for this payment method.

supports_inline_presentation_mode
boolean

Indicates if inline presentation mode is supported for this payment method.

{
  • "can_be_vaulted": true,
  • "supports_installments": true,
  • "guest_enabled": true,
  • "supports_inline_presentation_mode": true
}

Billing Address Parameters

Configuration parameters for billing address collection in Google Pay.

format
string

Billing address format.

Value Description
FULL

Full billing address format.

{
  • "format": "FULL"
}

Buyer Context

The buyer context for the refund transaction.

transaction_id
string [ 1 .. 255 ] characters ^[0-9a-zA-Z_-]+$

The PayPal generated transaction ID associated with the buyer's refund.

transaction_details_url
string <uri> [ 1 .. 2048 ] characters

The URL for the buyer to view the transaction details.

transaction_create_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

transaction_update_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

{
  • "transaction_id": "string",
  • "transaction_details_url": "http://example.com",
  • "transaction_create_time": "string",
  • "transaction_update_time": "string"
}

capture

A captured payment.

status
string (Capture Status)

The status of the captured payment.

Enum Value Description
COMPLETED

The funds for this captured payment were credited to the payee's PayPal account.

DECLINED

The funds could not be captured.

PARTIALLY_REFUNDED

An amount less than this captured payment's amount was partially refunded to the payer.

PENDING

The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.

REFUNDED

An amount greater than or equal to this captured payment's amount was refunded to the payer.

FAILED

There was an error while capturing payment.

object (capture_status_details)

The details of the captured payment status.

id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the captured payment.

object (amount_with_breakdown)

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

invoice_id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

custom_id
string [ 0 .. 255 ] characters ^[\S\s]*$

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

object (network_transaction)

Reference values used by the card network to identify a transaction.

object (seller_protection)

The level of protection offered as defined by PayPal Seller Protection for Merchants.

final_capture
boolean
Default: false

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

object (Seller Receivable Breakdown)

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

disbursement_mode
string (disbursement_mode)
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum Value Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

Array of objects (Link Description) [ 0 .. 32767 ] items

An array of related HATEOAS links.

object (processor_response)

The processor response information for payment requests, such as direct credit card transactions.

create_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

update_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

{
  • "status": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    },
  • "id": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "handling": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "insurance": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping_discount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "invoice_id": "string",
  • "custom_id": "string",
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA",
    • "acquirer_reference_number": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "ITEM_NOT_RECEIVED"
      ]
    },
  • "final_capture": false,
  • "seller_receivable_breakdown": {
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "receivable_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "exchange_rate": {
      • "source_currency": "string",
      • "target_currency": "string",
      • "value": "string"
      },
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "string"
          }
        }
      ]
    },
  • "disbursement_mode": "INSTANT",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "processor_response": {
    • "avs_code": "A",
    • "cvv_code": "E",
    • "response_code": "0000",
    • "payment_advice_code": "01"
    },
  • "create_time": "string",
  • "update_time": "string"
}

Capture Identifier

The capture identification-related fields. Includes the invoice ID, custom ID, note to payer, and soft descriptor.

invoice_id
string [ 1 .. 127 ] characters ^.{1,127}$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

note_to_payer
string [ 1 .. 255 ] characters ^.{1,255}$

An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.

{
  • "invoice_id": "string",
  • "note_to_payer": "string"
}

Capture Request

Captures either a portion or the full authorized amount of an authorized payment.

invoice_id
string [ 0 .. 127 ] characters ^[\S\s]*$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

note_to_payer
string [ 0 .. 255 ] characters ^[\S\s]*$

An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.

object (amount_with_breakdown)

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

final_capture
boolean
Default: false

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

object (payment_instruction)

Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.

soft_descriptor
string [ 0 .. 22 ] characters ^[\S\s]*$

The payment descriptor on the payer's account statement.

{
  • "invoice_id": "string",
  • "note_to_payer": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "handling": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "insurance": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping_discount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "final_capture": false,
  • "payment_instruction": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "string"
          }
        }
      ],
    • "disbursement_mode": "INSTANT",
    • "payee_pricing_tier_id": "string",
    • "payee_receivable_fx_rate_id": "string"
    },
  • "soft_descriptor": "string"
}

capture_status

The status and status details of a captured payment.

status
string (Capture Status)

The status of the captured payment.

Enum Value Description
COMPLETED

The funds for this captured payment were credited to the payee's PayPal account.

DECLINED

The funds could not be captured.

PARTIALLY_REFUNDED

An amount less than this captured payment's amount was partially refunded to the payer.

PENDING

The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.

REFUNDED

An amount greater than or equal to this captured payment's amount was refunded to the payer.

FAILED

There was an error while capturing payment.

object (capture_status_details)

The details of the captured payment status.

{
  • "status": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    }
}

capture_status_details

The details of the captured payment status.

reason
string (Capture Incomplete Reason)

The reason why the captured payment status is PENDING or DENIED.

Enum Value Description
BUYER_COMPLAINT

The payer initiated a dispute for this captured payment with PayPal.

CHARGEBACK

The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.

ECHECK

The payer paid by an eCheck that has not yet cleared.

INTERNATIONAL_WITHDRAWAL

Visit your online account. In your Account Overview, accept and deny this payment.

OTHER

No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.

PENDING_REVIEW

The captured payment is pending manual review.

RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION

The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.

REFUNDED

The captured funds were refunded.

TRANSACTION_APPROVED_AWAITING_FUNDING

The payer must send the funds for this captured payment. This code generally appears for manual EFTs.

UNILATERAL

The payee does not have a PayPal account.

VERIFICATION_REQUIRED

The payee's PayPal account is not verified.

DECLINED_BY_RISK_FRAUD_FILTERS

Risk Filter set by the payee failed for the transaction.

{
  • "reason": "BUYER_COMPLAINT"
}

Captured Payment

A captured payment.

status
string (Capture Status)

The status of the captured payment.

Enum Value Description
COMPLETED

The funds for this captured payment were credited to the payee's PayPal account.

DECLINED

The funds could not be captured.

PARTIALLY_REFUNDED

An amount less than this captured payment's amount was partially refunded to the payer.

PENDING

The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.

REFUNDED

An amount greater than or equal to this captured payment's amount was refunded to the payer.

FAILED

There was an error while capturing payment.

object (capture_status_details)

The details of the captured payment status.

id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the captured payment.

object (amount_with_breakdown)

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

invoice_id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

custom_id
string [ 0 .. 255 ] characters ^[\S\s]*$

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

object (network_transaction)

Reference values used by the card network to identify a transaction.

object (seller_protection)

The level of protection offered as defined by PayPal Seller Protection for Merchants.

final_capture
boolean
Default: false

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

object (Seller Receivable Breakdown)

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

disbursement_mode
string (disbursement_mode)
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum Value Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

Array of objects (Link Description) [ 0 .. 32767 ] items

An array of related HATEOAS links.

object (processor_response)

The processor response information for payment requests, such as direct credit card transactions.

create_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

update_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

object (Payment Supplementary Data)

The supplementary data.

object (payee_base)

The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

{
  • "status": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    },
  • "id": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "handling": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "insurance": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping_discount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "invoice_id": "string",
  • "custom_id": "string",
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA",
    • "acquirer_reference_number": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "ITEM_NOT_RECEIVED"
      ]
    },
  • "final_capture": false,
  • "seller_receivable_breakdown": {
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "receivable_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "exchange_rate": {
      • "source_currency": "string",
      • "target_currency": "string",
      • "value": "string"
      },
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "string"
          }
        }
      ]
    },
  • "disbursement_mode": "INSTANT",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "processor_response": {
    • "avs_code": "A",
    • "cvv_code": "E",
    • "response_code": "0000",
    • "payment_advice_code": "01"
    },
  • "create_time": "string",
  • "update_time": "string",
  • "supplementary_data": {
    • "related_ids": {
      • "order_id": "string",
      • "authorization_id": "string",
      • "capture_id": "string"
      }
    },
  • "payee": {
    • "email_address": "string",
    • "merchant_id": "string"
    }
}

Card Vendor

Configuration for a specific card vendor or network.

network
required
string (card_brand-2)

The card brand.

Enum Value Description
AMEX

The American Express payment network.

CB_NATIONALE

Carte Bleue Nationale (CBN), a major debit card payment system operating in France.

CETELEM

Cetelem, a brand of BNP Paribas Personal Finance, is a French financial institution specializing in financing individuals consumer credit activities.

COFIDIS

Cofidis is a French company, now majority owned by the Crédit Mutuel, based in Villeneuve-d'Ascq, that offers a payment method that allows you to make bank card payments in 3 or 4 times, PayPal payment in 4 times, or one Euro consumer credit.

COFINOGA

Cofinoga, a brand of BNP Paribas Personal Finance, is a credit specialist in France. It offers a card that allows you to pay for credit online purchases.

CHINA_UNION_PAY

China UnionPay (CUP) or UnionPay International (UPI) is a Chinese financial services corporation headquartered in Shanghai, China. It provides bank card services and a major card scheme in mainland China.

DELTA

The Delta Air Lines online payment network.

DISCOVER

The Discover Financial Services (DFS) banking and payment services capability network.

ELECTRON

The Visa Electron debit card payment network. It's offered by issuing banks in every country with the exception of Canada, Australia, Argentina, Ireland, and the United States.

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

The Brazilian Hipercard payment network that's widely accepted in the retail market.

JCB

The Japan Credit Bureau (JCB) card payment network.

MAESTRO

The Maestro debit card payment network owned by Mastercard.

MASTER_CARD

The Mastercard Incorporated payment network.

SOLO

The Hatton National BankFinance's SOLO digital wallet payment network.

STAR

The STAR payment network.

SWITCH

The Switch payment network.

VISA

The Visa Inc. payment network.

GE

The GE Credit Union 3Point card payment network.

RUPAY

The RuPay payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

DINERS

The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services.

GIROCARD

Girocard is an interbank network and debit card service connecting virtually all German ATMs and banks.

CARNET

Carnet is a fuel card.

V_PAY

V Pay is a Single Euro Payments Area (SEPA) debit card for use in Europe, issued by Visa Europe.

eligible
required
boolean

Indicates if the vendor is eligible.

can_be_vaulted
required
boolean

Indicates if the vendor's payment method can be saved for future use.

branded
required
boolean

Indicates if the vendor has branded customization.

{
  • "network": "AMEX",
  • "eligible": true,
  • "can_be_vaulted": true,
  • "branded": true
}

card_brand

The card network or brand. Applies to credit, debit, gift, and payment cards.

string (card_brand)

The card network or brand. Applies to credit, debit, gift, and payment cards.

Enum Value Description
VISA

Visa card.

MASTERCARD

Mastercard card.

DISCOVER

Discover card.

AMEX

American Express card.

SOLO

Solo debit card.

JCB

Japan Credit Bureau card.

STAR

Military Star card.

DELTA

Delta Airlines card.

SWITCH

Switch credit card.

MAESTRO

Maestro credit card.

CB_NATIONALE

Carte Bancaire (CB) credit card.

CONFIGOGA

Configoga credit card.

CONFIDIS

Confidis credit card.

ELECTRON

Visa Electron credit card.

CETELEM

Cetelem credit card.

CHINA_UNION_PAY

China union pay credit card.

DINERS

The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services.

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

The Brazilian Hipercard payment network that's widely accepted in the retail market.

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network.

CARTE_BANCAIRE

The Carte Bancaire payment network.

STAR_ACCESS

The Star Access payment network.

PULSE

The Pulse payment network.

NYCE

The NYCE payment network.

ACCEL

The Accel payment network.

UNKNOWN

UNKNOWN payment network.

"VISA"

card_brand-2

The card brand.

string (card_brand-2)

The card brand.

Enum Value Description
AMEX

The American Express payment network.

CB_NATIONALE

Carte Bleue Nationale (CBN), a major debit card payment system operating in France.

CETELEM

Cetelem, a brand of BNP Paribas Personal Finance, is a French financial institution specializing in financing individuals consumer credit activities.

COFIDIS

Cofidis is a French company, now majority owned by the Crédit Mutuel, based in Villeneuve-d'Ascq, that offers a payment method that allows you to make bank card payments in 3 or 4 times, PayPal payment in 4 times, or one Euro consumer credit.

COFINOGA

Cofinoga, a brand of BNP Paribas Personal Finance, is a credit specialist in France. It offers a card that allows you to pay for credit online purchases.

CHINA_UNION_PAY

China UnionPay (CUP) or UnionPay International (UPI) is a Chinese financial services corporation headquartered in Shanghai, China. It provides bank card services and a major card scheme in mainland China.

DELTA

The Delta Air Lines online payment network.

DISCOVER

The Discover Financial Services (DFS) banking and payment services capability network.

ELECTRON

The Visa Electron debit card payment network. It's offered by issuing banks in every country with the exception of Canada, Australia, Argentina, Ireland, and the United States.

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

The Brazilian Hipercard payment network that's widely accepted in the retail market.

JCB

The Japan Credit Bureau (JCB) card payment network.

MAESTRO

The Maestro debit card payment network owned by Mastercard.

MASTER_CARD

The Mastercard Incorporated payment network.

SOLO

The Hatton National BankFinance's SOLO digital wallet payment network.

STAR

The STAR payment network.

SWITCH

The Switch payment network.

VISA

The Visa Inc. payment network.

GE

The GE Credit Union 3Point card payment network.

RUPAY

The RuPay payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

DINERS

The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services.

GIROCARD

Girocard is an interbank network and debit card service connecting virtually all German ATMs and banks.

CARNET

Carnet is a fuel card.

V_PAY

V Pay is a Single Euro Payments Area (SEPA) debit card for use in Europe, issued by Visa Europe.

"AMEX"

Common response fields

Common response fields for all payment methods.

can_be_vaulted
boolean
Default: false

Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.

country_code
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

product_code
string (Credit Button Eligibility Button Code)

The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.

Enum Value Description
CREDIT

Open ended credit products.

PAYLATER

Pay Later suite of products.

PAY_IN_3

Pay In 3 suite of products.

PAY_IN_4

Pay In 4 suite of products.

{
  • "can_be_vaulted": false,
  • "country_code": "string",
  • "product_code": "CREDIT"
}

country_code-2

The two-character ISO 3166-1 code 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.

string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

"st"

Credit Button Eligibility Button Code

The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.

string (Credit Button Eligibility Button Code)

The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.

Enum Value Description
CREDIT

Open ended credit products.

PAYLATER

Pay Later suite of products.

PAY_IN_3

Pay In 3 suite of products.

PAY_IN_4

Pay In 4 suite of products.

"CREDIT"

currency_code

The three-character ISO-4217 currency code that identifies the currency.

string (currency_code) = 3 characters ^[\S\s]*$

The three-character ISO-4217 currency code that identifies the currency.

"str"

Customer

Customer who is making a purchase from the merchant/partner.

country_code
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

object (Customer Channel)

Channel through which the request is being posted.

email
string (email_address) [ 3 .. 254 ] characters ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za...

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

object (Phone)

The phone number in its canonical international E.164 numbering plan format.

{
  • "country_code": "string",
  • "channel": {
    • "browser_type": "string",
    • "client_os": "string",
    • "device_type": "string"
    },
  • "email": "string",
  • "phone": {
    • "country_code": "str",
    • "national_number": "string",
    • "extension_number": "string"
    }
}

Customer Channel

Channel through which the request is being posted.

browser_type
string [ 1 .. 30 ] characters ^[0-9a-zA-Z_,. -]+$

The browser used by the customer. Example: Safari, Chrome, etc.

client_os
string [ 1 .. 30 ] characters ^[0-9a-zA-Z_,. -]+$

The operating system on the device used by the customer. Example: iOS 16.5, Android 30, etc.

device_type
string [ 1 .. 30 ] characters ^[0-9a-zA-Z_,. -]+$

The type of device used by the customer. Example: Mobile, Desktop, Tablet, etc.

{
  • "browser_type": "string",
  • "client_os": "string",
  • "device_type": "string"
}

date_time

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

"stringstringstringst"

disbursement_mode

The funds that are held on behalf of the merchant.

string (disbursement_mode)
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum Value Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

"INSTANT"

discount_with_breakdown

The discount amount and currency code. For list of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

currency_code
required
string (currency_code) = 3 characters ^[\S\s]*$

The three-character ISO-4217 currency code that identifies the currency.

value
required
string [ 0 .. 32 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The value, which might be:

  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.

{
  • "currency_code": "str",
  • "value": "string"
}

Eligibility Response for ApplePay

Response for ApplePay.

can_be_vaulted
boolean
Default: false

Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.

country_code
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

product_code
string (Credit Button Eligibility Button Code)

The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.

Enum Value Description
CREDIT

Open ended credit products.

PAYLATER

Pay Later suite of products.

PAY_IN_3

Pay In 3 suite of products.

PAY_IN_4

Pay In 4 suite of products.

object (Apple Pay Config)

Configuration details for Apple Pay payment method.

{
  • "can_be_vaulted": false,
  • "country_code": "string",
  • "product_code": "CREDIT",
  • "config": {
    • "eligible": true,
    • "merchant_country": "string",
    • "supported_networks": [
      • "MASTERCARD"
      ],
    • "merchant_capabilities": [
      • "SUPPORTS_CREDIT"
      ],
    • "token_notification_url": "http://example.com"
    }
}

Eligibility Response for GooglePay

Response for GooglePay.

can_be_vaulted
boolean
Default: false

Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.

country_code
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

product_code
string (Credit Button Eligibility Button Code)

The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.

Enum Value Description
CREDIT

Open ended credit products.

PAYLATER

Pay Later suite of products.

PAY_IN_3

Pay In 3 suite of products.

PAY_IN_4

Pay In 4 suite of products.

object (Google Pay Config)

Configuration details for Google Pay payment method.

{
  • "can_be_vaulted": false,
  • "country_code": "string",
  • "product_code": "CREDIT",
  • "config": {
    • "eligible": true,
    • "merchant_country": "string",
    • "api_version": 1,
    • "api_version_minor": 1,
    • "allowed_payment_methods": [
      • {
        • "type": "CARD",
        • "parameters": {
          • "allowed_auth_methods": [
            • "PAN_ONLY"
            ],
          • "supported_networks": [
            • "MASTERCARD"
            ],
          • "billing_address_required": true,
          • "assurance_details_required": true,
          • "billing_address_parameters": {
            • "format": "FULL"
            }
          },
        • "tokenization_specification": {
          • "type": "PAYMENT_GATEWAY",
          • "parameters": {
            • "gateway": "string",
            • "gateway_merchant_id": "string"
            }
          }
        }
      ],
    • "merchant_info": {
      • "merchant_origin": "string",
      • "merchant_id": "string",
      • "googlepay_partner_domain_verification_jwt": "stringstri"
      }
    }
}

eligibility_purchase_unit_request

Purchase unit for payment eligibility.

object (amount_with_breakdown)

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

object (payee)

The merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

{
  • "amount": {
    • "currency_code": "str",
    • "value": "string",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "handling": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "tax_total": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "insurance": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "shipping_discount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "discount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    },
  • "payee": {
    • "email_address": "string",
    • "merchant_id": "string"
    }
}

email

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

string (email) [ 3 .. 254 ] characters ^.*(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-...

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

"string"

email_address

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

string (email_address) [ 3 .. 254 ] characters ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za...

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

"string"

Error

The error details.

name
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The human-readable, unique name of the error.

message
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The message that describes the error.

debug_id
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal internal ID. Used for correlation purposes.

Array of objects (Error Details) [ 0 .. 32767 ] items

An array of additional details about the error.

Array of objects (Link Description) [ 0 .. 32767 ] items

An array of request-related HATEOAS links.

{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET",
          • "title": "string",
          • "mediaType": "string",
          • "encType": "application/json",
          • "schema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            },
          • "targetSchema": {
            • "additionalItems": { },
            • "dependencies": { },
            • "items": { },
            • "definitions": { },
            • "patternProperties": { },
            • "properties": { },
            • "allOf": [
              • { }
              ],
            • "anyOf": [
              • { }
              ],
            • "oneOf": [
              • { }
              ],
            • "not": { },
            • "links": [
              • { }
              ],
            • "fragmentResolution": "string",
            • "media": {
              • "type": "string",
              • "binaryEncoding": "string"
              },
            • "pathStart": "http://example.com"
            }
          }
        ],
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ]
}

Error Details

The error details. Required for client-side 4XX errors.

field
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

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
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The value of the field that caused the error.

location
string [ 0 .. 2147483647 ] characters ^[\S\s]*$
Default: "body"

The location of the field that caused the error. Value is body, path, or query.

issue
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The unique, fine-grained application-level error code.

Array of objects (Link Description) [ 1 .. 4 ] items

An array of request-related HATEOAS links that are either relevant to the issue by providing additional information or offering potential resolutions.

description
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

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.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "description": "string"
}

exchange_rate

The exchange rate that determines the amount to convert from one currency to another currency.

source_currency
string (currency_code) = 3 characters ^[\S\s]*$

The three-character ISO-4217 currency code that identifies the currency.

target_currency
string (currency_code) = 3 characters ^[\S\s]*$

The three-character ISO-4217 currency code that identifies the currency.

value
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point.

{
  • "source_currency": "string",
  • "target_currency": "string",
  • "value": "string"
}

Find Eligible Payment Methods Request

Request to get list of eligible payment methods.

object (Customer)

Customer who is making a purchase from the merchant/partner.

Array of objects (eligibility_purchase_unit_request) [ 1 .. 10 ] items

Array of purchase units.

object (Preferences)

Preferences of merchant/partner consuming the API.

{
  • "customer": {
    • "country_code": "string",
    • "channel": {
      • "browser_type": "string",
      • "client_os": "string",
      • "device_type": "string"
      },
    • "email": "string",
    • "phone": {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string"
      }
    },
  • "purchase_units": [
    • {
      • "amount": {
        • "currency_code": "str",
        • "value": "string",
        • "breakdown": {
          • "item_total": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "shipping": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "handling": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "tax_total": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "insurance": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "shipping_discount": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "discount": {
            • "currency_code": "str",
            • "value": "string"
            }
          }
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "string"
        }
      }
    ],
  • "preferences": {
    • "payment_flow": "ONE_TIME_PAYMENT",
    • "intent": "CAPTURE",
    • "include_account_details": "false",
    • "include_vault_tokens": "false",
    • "vault": "false",
    • "payment_source_constraint": {
      • "constraint_type": "INCLUDE",
      • "payment_sources": [
        • "PAYPAL"
        ]
      }
    }
}

Google Pay Config

Configuration details for Google Pay payment method.

eligible
boolean

Indicates if Google Pay is eligible.

merchant_country
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

api_version
integer [ 1 .. 10 ]

Google Pay API version.

api_version_minor
integer [ 1 .. 10 ]

Google Pay API minor version.

Array of objects (Payment Method) [ 1 .. 10 ] items

Allowed payment methods for Google Pay.

object (Merchant Information)

Merchant-specific information required for Google Pay integration.

{
  • "eligible": true,
  • "merchant_country": "string",
  • "api_version": 1,
  • "api_version_minor": 1,
  • "allowed_payment_methods": [
    • {
      • "type": "CARD",
      • "parameters": {
        • "allowed_auth_methods": [
          • "PAN_ONLY"
          ],
        • "supported_networks": [
          • "MASTERCARD"
          ],
        • "billing_address_required": true,
        • "assurance_details_required": true,
        • "billing_address_parameters": {
          • "format": "FULL"
          }
        },
      • "tokenization_specification": {
        • "type": "PAYMENT_GATEWAY",
        • "parameters": {
          • "gateway": "string",
          • "gateway_merchant_id": "string"
          }
        }
      }
    ],
  • "merchant_info": {
    • "merchant_origin": "string",
    • "merchant_id": "string",
    • "googlepay_partner_domain_verification_jwt": "stringstri"
    }
}

GUID

A Globally Unique Identifier (GUID) value.

string (GUID) [ 1 .. 68 ] characters ^[A-Za-z0-9-{}(),]*$

A Globally Unique Identifier (GUID) value.

"string"

Link Description

The request-related HATEOAS link information.

href
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The complete target URL. To make the related call, combine the method with this URI Template-formatted 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
required
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

method
string

The HTTP method required to make the related call.

Enum Value Description
GET

The HTTP GET method.

POST

The HTTP POST method.

PUT

The HTTP PUT method.

DELETE

The HTTP DELETE method.

HEAD

The HTTP HEAD method.

CONNECT

The HTTP CONNECT method.

OPTIONS

The HTTP OPTIONS method.

PATCH

The HTTP PATCH method.

title
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The link title.

mediaType
string (media_type) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The media type, as defined by RFC 2046. Describes the link target.

encType
string (enc_type) [ 0 .. 2147483647 ] characters ^[\S\s]*$
Default: "application/json"

The media type in which to submit the request data.

object (Link Schema)

The request data or link target.

object (Link Schema)

The request data or link target.

{
  • "href": "string",
  • "rel": "string",
  • "method": "GET",
  • "title": "string",
  • "mediaType": "string",
  • "encType": "application/json",
  • "schema": {
    • "additionalItems": { },
    • "dependencies": { },
    • "items": { },
    • "definitions": { },
    • "patternProperties": { },
    • "properties": { },
    • "allOf": [
      • { }
      ],
    • "anyOf": [
      • { }
      ],
    • "oneOf": [
      • { }
      ],
    • "not": { },
    • "links": [
      • { }
      ],
    • "fragmentResolution": "string",
    • "media": {
      • "type": "string",
      • "binaryEncoding": "string"
      },
    • "pathStart": "http://example.com"
    },
  • "targetSchema": {
    • "additionalItems": { },
    • "dependencies": { },
    • "items": { },
    • "definitions": { },
    • "patternProperties": { },
    • "properties": { },
    • "allOf": [
      • { }
      ],
    • "anyOf": [
      • { }
      ],
    • "oneOf": [
      • { }
      ],
    • "not": { },
    • "links": [
      • { }
      ],
    • "fragmentResolution": "string",
    • "media": {
      • "type": "string",
      • "binaryEncoding": "string"
      },
    • "pathStart": "http://example.com"
    }
}

Link Schema

The request data or link target.

additionalItems
object (additional_items)

Any additional items.

dependencies
object (Dependencies)

Any Dependencies.

items
object (Items)

An item.

definitions
object (Definitions)

Definitions.

patternProperties
object (pattern_properties)

The pattern properties.

properties
object (Properties)

Properties.

allOf
Array of objects (all_of) [ 0 .. 32767 ] items

An array of sub-schemas. The data must validate against all sub-schemas.

anyOf
Array of objects (any_of) [ 0 .. 32767 ] items

An array of sub-schemas. The data must validate against one or more sub-schemas.

oneOf
Array of objects (one_of) [ 0 .. 32767 ] items

An array of sub-schemas. The data must validate against one sub-schema.

not
object (Not)

Not.

links
Array of objects (link) [ 0 .. 32767 ] items

An array of links.

fragmentResolution
string (fragment_resolution) [ 0 .. 2147483647 ] characters ^[\S\s]*$

The fragment resolution.

object (Media)

The media type and context-encoding scheme.

pathStart
string <uri> (path_start) [ 0 .. 2147483647 ] characters

To apply this schema to the instances' URIs, start the URIs with this value.

{
  • "additionalItems": { },
  • "dependencies": { },
  • "items": { },
  • "definitions": { },
  • "patternProperties": { },
  • "properties": { },
  • "allOf": [
    • { }
    ],
  • "anyOf": [
    • { }
    ],
  • "oneOf": [
    • { }
    ],
  • "not": { },
  • "links": [
    • { }
    ],
  • "fragmentResolution": "string",
  • "media": {
    • "type": "string",
    • "binaryEncoding": "string"
    },
  • "pathStart": "http://example.com"
}

Merchant Information

Merchant-specific information required for Google Pay integration.

merchant_origin
string [ 4 .. 253 ] characters ^[a-zA-Z0-9.-]+$

Merchant origin.

merchant_id
string (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

The account identifier for a PayPal account.

googlepay_partner_domain_verification_jwt
string [ 10 .. 2000 ] characters ^[A-Za-z0-9_.-]+$

JWT token used for Google Pay partner domain verification to authenticate the merchant's domain.

{
  • "merchant_origin": "string",
  • "merchant_id": "string",
  • "googlepay_partner_domain_verification_jwt": "stringstri"
}

Money

The currency and amount for a financial transaction, such as a balance or payment due.

currency_code
required
string (currency_code) = 3 characters ^[\S\s]*$

The three-character ISO-4217 currency code that identifies the currency.

value
required
string [ 0 .. 32 ] characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The value, which might be:

  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.

{
  • "currency_code": "str",
  • "value": "string"
}

net_amount_breakdown

The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (exchange_rate)

The exchange rate that determines the amount to convert from one currency to another currency.

{
  • "payable_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "converted_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "exchange_rate": {
    • "source_currency": "string",
    • "target_currency": "string",
    • "value": "string"
    }
}

network_transaction

Reference values used by the card network to identify a transaction.

id
string [ 9 .. 36 ] characters ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$

Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -.

date
string = 4 characters ^[0-9]+$

The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date". For some specific networks, such as MasterCard and Discover, this date field is mandatory when the previous_network_transaction_reference_id is passed.

network
string (card_brand)

The card network or brand. Applies to credit, debit, gift, and payment cards.

Enum Value Description
VISA

Visa card.

MASTERCARD

Mastercard card.

DISCOVER

Discover card.

AMEX

American Express card.

SOLO

Solo debit card.

JCB

Japan Credit Bureau card.

STAR

Military Star card.

DELTA

Delta Airlines card.

SWITCH

Switch credit card.

MAESTRO

Maestro credit card.

CB_NATIONALE

Carte Bancaire (CB) credit card.

CONFIGOGA

Configoga credit card.

CONFIDIS

Confidis credit card.

ELECTRON

Visa Electron credit card.

CETELEM

Cetelem credit card.

CHINA_UNION_PAY

China union pay credit card.

DINERS

The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services.

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

The Brazilian Hipercard payment network that's widely accepted in the retail market.

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network.

CARTE_BANCAIRE

The Carte Bancaire payment network.

STAR_ACCESS

The Star Access payment network.

PULSE

The Pulse payment network.

NYCE

The NYCE payment network.

ACCEL

The Accel payment network.

UNKNOWN

UNKNOWN payment network.

acquirer_reference_number
string [ 1 .. 36 ] characters ^[a-zA-Z0-9]+$

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

{
  • "id": "stringstr",
  • "date": "stri",
  • "network": "VISA",
  • "acquirer_reference_number": "string"
}

payee

The merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

email_address
string (email) [ 3 .. 254 ] characters ^.*(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-...

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

merchant_id
string (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

The account identifier for a PayPal account.

{
  • "email_address": "string",
  • "merchant_id": "string"
}

payee_base

The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

email_address
string (email) [ 3 .. 254 ] characters ^.*(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-...

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

merchant_id
string (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

The account identifier for a PayPal account.

{
  • "email_address": "string",
  • "merchant_id": "string"
}

Payment Method

Configuration for a specific payment method supported by Google Pay.

type
string

Type of payment method.

Value Description
CARD

Card payment method.

object (Payment Method Parameters)

Parameters specific to the payment method configuration.

object (Tokenization Specification)

Specification for payment method tokenization in Google Pay.

{
  • "type": "CARD",
  • "parameters": {
    • "allowed_auth_methods": [
      • "PAN_ONLY"
      ],
    • "supported_networks": [
      • "MASTERCARD"
      ],
    • "billing_address_required": true,
    • "assurance_details_required": true,
    • "billing_address_parameters": {
      • "format": "FULL"
      }
    },
  • "tokenization_specification": {
    • "type": "PAYMENT_GATEWAY",
    • "parameters": {
      • "gateway": "string",
      • "gateway_merchant_id": "string"
      }
    }
}

Payment Method Parameters

Parameters specific to the payment method configuration.

allowed_auth_methods
Array of strings [ 1 .. 100 ] items

Allowed authentication methods.

Items Enum Value Description
PAN_ONLY

Authentication method using only the primary account number.

CRYPTOGRAM_3DS

Authentication method using 3DS cryptogram.

supported_networks
Array of strings [ 1 .. 100 ] items

Allowed card networks.

Items Enum Value Description
MASTERCARD

MasterCard network.

DISCOVER

Discover network.

VISA

Visa network.

AMEX

American Express network.

billing_address_required
boolean

Whether billing address is required.

assurance_details_required
boolean

Whether assurance details are required.

object (Billing Address Parameters)

Configuration parameters for billing address collection in Google Pay.

{
  • "allowed_auth_methods": [
    • "PAN_ONLY"
    ],
  • "supported_networks": [
    • "MASTERCARD"
    ],
  • "billing_address_required": true,
  • "assurance_details_required": true,
  • "billing_address_parameters": {
    • "format": "FULL"
    }
}

Payment Methods

List of payment methods.

object (Response for PayPal)

Response for PayPal.

object (Response for Venmo)

Response for Venmo.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Eligibility Response for ApplePay)

Response for ApplePay.

object (Eligibility Response for GooglePay)

Response for GooglePay.

object (Advanced Cards Config)

Configuration details for advanced card payment methods including credit and debit card processing capabilities.

object (Basic Cards Config)

Configuration details for basic card payment methods including credit and debit card processing capabilities.

object (Response for ACH)

Response for ACH payment method.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

object (Common response fields)

Common response fields for all payment methods.

{
  • "paypal": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT",
    • "eligible_in_paypal_network": true,
    • "recommended": "false",
    • "recommended_priority": 1
    },
  • "venmo": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT",
    • "eligible_in_paypal_network": true,
    • "recommended": "false",
    • "recommended_priority": 1
    },
  • "paypal_credit": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "paypal_pay_later": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "ideal": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "apple_pay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT",
    • "config": {
      • "eligible": true,
      • "merchant_country": "string",
      • "supported_networks": [
        • "MASTERCARD"
        ],
      • "merchant_capabilities": [
        • "SUPPORTS_CREDIT"
        ],
      • "token_notification_url": "http://example.com"
      }
    },
  • "google_pay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT",
    • "config": {
      • "eligible": true,
      • "merchant_country": "string",
      • "api_version": 1,
      • "api_version_minor": 1,
      • "allowed_payment_methods": [
        • {
          • "type": "CARD",
          • "parameters": {
            • "allowed_auth_methods": [
              • "PAN_ONLY"
              ],
            • "supported_networks": [
              • "MASTERCARD"
              ],
            • "billing_address_required": true,
            • "assurance_details_required": true,
            • "billing_address_parameters": {
              • "format": "FULL"
              }
            },
          • "tokenization_specification": {
            • "type": "PAYMENT_GATEWAY",
            • "parameters": {
              • "gateway": "string",
              • "gateway_merchant_id": "string"
              }
            }
          }
        ],
      • "merchant_info": {
        • "merchant_origin": "string",
        • "merchant_id": "string",
        • "googlepay_partner_domain_verification_jwt": "stringstri"
        }
      }
    },
  • "advanced_cards": {
    • "can_be_vaulted": true,
    • "supports_installments": true,
    • "vendors": [
      • {
        • "network": "AMEX",
        • "eligible": true,
        • "can_be_vaulted": true,
        • "branded": true
        }
      ]
    },
  • "basic_cards": {
    • "can_be_vaulted": true,
    • "supports_installments": true,
    • "guest_enabled": true,
    • "supports_inline_presentation_mode": true
    },
  • "ach": {
    • "can_be_vaulted": false
    },
  • "blik": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "p24": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "eps": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "bancontact": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "swish": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "klarna": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "mbway": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "boletobancario": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "twint": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "bizum": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "afterpay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "zip": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "satispay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "trustly": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "mybank": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "alipay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "wechatpay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "grabpay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "oxxo_pay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "multibanco": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "verkkopankki": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "bancomatpay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "payu": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "blik_pay_later": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "floa_pay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "dragonpay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "paysera": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "lithuania_banks": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "latvia_banks": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "thailand_banks": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "estonia_banks": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "alfamart": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "doku": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "indonesia_banks": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "indomaret": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "jenius_pay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "kredivo": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "linkaja": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "ovo": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "paysafecard": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "skrill": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "wero": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "fiuu_cash": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "gopay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "fpx": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "pay_upon_invoice": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "pix_international": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "scalapay": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    },
  • "crypto": {
    • "can_be_vaulted": false,
    • "country_code": "string",
    • "product_code": "CREDIT"
    }
}

Payment Supplementary Data

The supplementary data.

object (Related Identifiers)

Identifiers related to a specific resource.

{
  • "related_ids": {
    • "order_id": "string",
    • "authorization_id": "string",
    • "capture_id": "string"
    }
}

payment_instruction

Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.

Array of objects (platform_fee) [ 0 .. 1 ] items

An array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Complete Payments Platform for Marketplaces and Platforms capability.

disbursement_mode
string (disbursement_mode)
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum Value Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

payee_pricing_tier_id
string [ 1 .. 20 ] characters ^.*$

This field is only enabled for selected merchants/partners to use and provides the ability to trigger a specific pricing rate/plan for a payment transaction. The list of eligible 'payee_pricing_tier_id' would be provided to you by your Account Manager. Specifying values other than the one provided to you by your account manager would result in an error.

payee_receivable_fx_rate_id
string [ 1 .. 4000 ] characters ^.*$

FX identifier generated returned by PayPal to be used for payment processing in order to honor FX rate (for eligible integrations) to be used when amount is settled/received into the payee account.

{
  • "platform_fees": [
    • {
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "string"
        }
      }
    ],
  • "disbursement_mode": "INSTANT",
  • "payee_pricing_tier_id": "string",
  • "payee_receivable_fx_rate_id": "string"
}

payment_instruction

Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.

Array of objects (platform_fee) [ 0 .. 1 ] items

Specifies the amount that the API caller will contribute to the refund being processed. The amount needs to be lower than platform_fees amount originally captured or the amount that is remaining if multiple refunds have been processed. This field is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.

{
  • "platform_fees": [
    • {
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "string"
        }
      }
    ]
}

payment_method

Set of unique payment methods.

string (payment_method)

Set of unique payment methods.

Enum Value Description
PAYPAL

PAYPAL

VENMO

VENMO

PAYPAL_CREDIT

PAYPAL_CREDIT

PAYPAL_PAY_LATER

PAYPAL_PAY_LATER

ACH

ACH

"PAYPAL"

PayPal Account Identifier

The account identifier for a PayPal account.

string (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

The account identifier for a PayPal account.

"stringstrings"

PayPal services member indicator

Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request.

boolean (PayPal services member indicator)

Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request.

true

paypal_response

Eligible payment methods.

object (Payment Methods)

List of payment methods.

object (Supplementary Data)

Contains supplementary data related to the eligibility check.

{
  • "eligible_methods": {
    • "paypal": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT",
      • "eligible_in_paypal_network": true,
      • "recommended": "false",
      • "recommended_priority": 1
      },
    • "venmo": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT",
      • "eligible_in_paypal_network": true,
      • "recommended": "false",
      • "recommended_priority": 1
      },
    • "paypal_credit": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "paypal_pay_later": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "ideal": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "apple_pay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT",
      • "config": {
        • "eligible": true,
        • "merchant_country": "string",
        • "supported_networks": [
          • "MASTERCARD"
          ],
        • "merchant_capabilities": [
          • "SUPPORTS_CREDIT"
          ],
        • "token_notification_url": "http://example.com"
        }
      },
    • "google_pay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT",
      • "config": {
        • "eligible": true,
        • "merchant_country": "string",
        • "api_version": 1,
        • "api_version_minor": 1,
        • "allowed_payment_methods": [
          • {
            • "type": "CARD",
            • "parameters": {
              • "allowed_auth_methods": [
                • null
                ],
              • "supported_networks": [
                • null
                ],
              • "billing_address_required": true,
              • "assurance_details_required": true,
              • "billing_address_parameters": {
                • "format": null
                }
              },
            • "tokenization_specification": {
              • "type": "PAYMENT_GATEWAY",
              • "parameters": {
                • "gateway": null,
                • "gateway_merchant_id": null
                }
              }
            }
          ],
        • "merchant_info": {
          • "merchant_origin": "string",
          • "merchant_id": "string",
          • "googlepay_partner_domain_verification_jwt": "stringstri"
          }
        }
      },
    • "advanced_cards": {
      • "can_be_vaulted": true,
      • "supports_installments": true,
      • "vendors": [
        • {
          • "network": "AMEX",
          • "eligible": true,
          • "can_be_vaulted": true,
          • "branded": true
          }
        ]
      },
    • "basic_cards": {
      • "can_be_vaulted": true,
      • "supports_installments": true,
      • "guest_enabled": true,
      • "supports_inline_presentation_mode": true
      },
    • "ach": {
      • "can_be_vaulted": false
      },
    • "blik": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "p24": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "eps": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "bancontact": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "swish": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "klarna": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "mbway": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "boletobancario": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "twint": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "bizum": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "afterpay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "zip": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "satispay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "trustly": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "mybank": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "alipay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "wechatpay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "grabpay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "oxxo_pay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "multibanco": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "verkkopankki": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "bancomatpay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "payu": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "blik_pay_later": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "floa_pay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "dragonpay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "paysera": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "lithuania_banks": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "latvia_banks": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "thailand_banks": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "estonia_banks": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "alfamart": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "doku": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "indonesia_banks": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "indomaret": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "jenius_pay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "kredivo": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "linkaja": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "ovo": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "paysafecard": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "skrill": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "wero": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "fiuu_cash": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "gopay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "fpx": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "pay_upon_invoice": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "pix_international": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "scalapay": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      },
    • "crypto": {
      • "can_be_vaulted": false,
      • "country_code": "string",
      • "product_code": "CREDIT"
      }
    },
  • "supplementary_data": {
    • "buyer_country_code": "string"
    }
}

Phone

The phone number in its canonical international E.164 numbering plan format.

country_code
required
string (country_calling_code) [ 1 .. 3 ] characters ^[0-9]{1,3}?$

The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

national_number
required
string [ 1 .. 14 ] characters ^[0-9]{1,14}?$

The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).

extension_number
string [ 1 .. 15 ] characters ^[0-9]{1,15}?$

The extension number.

{
  • "country_code": "str",
  • "national_number": "string",
  • "extension_number": "string"
}

platform_fee

The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit.

required
object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (payee_base)

The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

{
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "payee": {
    • "email_address": "string",
    • "merchant_id": "string"
    }
}

Preferences

Preferences of merchant/partner consuming the API.

payment_flow
string (Payment Flow)

This field specifies the payment flow, expected to provide a hint about which payment action the customer is intending to perform.

Enum Value Description
ONE_TIME_PAYMENT

Indicates that a customer is attempting to acquire a product within the context of a purchase. Most often, this will be the standard PayPal Checkout experience.

RECURRING_PAYMENT

Indicates that the customer is in the recurring payment experience.

VAULT_WITH_PAYMENT

Indicates that the customer is entering through checkout and continue to the vaulting experience.

VAULT_WITHOUT_PAYMENT

Indicates that the customer is in the vaulting experience without any purchase.

intent
string

The intent of the payment flow, specifying the purpose of the payment operation.

Enum Value Description
CAPTURE

The intent to capture payment immediately after customer approval.

AUTHORIZE

The intent to authorize a payment for capture later.

ORDER

The intent to create an order for authorized payments that can be captured later in parts or in full.

TOKENIZE

The intent to tokenize payment details without processing a payment.

SUBSCRIPTION

The intent to process a payment as part of a subscription.

UNKNOWN

Used when the intent is not specified or does not match any known values.

include_account_details
boolean
Default: "false"

If this value is set to true, response will include confirmation if the customer has PayPal and/or Venmo accounts if they are eligible payment methods. Value defaults to false.

include_vault_tokens
boolean
Default: "false"

If this value is set to true, response will include vaulted token information if the eligible funding source has any instrument vaulted for the customer. Value defaults to false.

vault
boolean
Default: "false"

This field determines whether the selected payment method is intended to be stored for future use (vaulted) or used as a one-time payment. Value defaults to false.

object (Payment Source Constraint)

Payment source constraint defines the payment methods that needs to be included/excluded for eligibility assessment. If not passed, all payment methods will be assessed for eligibility.

{
  • "payment_flow": "ONE_TIME_PAYMENT",
  • "intent": "CAPTURE",
  • "include_account_details": "false",
  • "include_vault_tokens": "false",
  • "vault": "false",
  • "payment_source_constraint": {
    • "constraint_type": "INCLUDE",
    • "payment_sources": [
      • "PAYPAL"
      ]
    }
}

processor_response

The processor response information for payment requests, such as direct credit card transactions.

avs_code
string

The address verification code for Visa, Discover, Mastercard, or American Express transactions.

Enum Value Description
0

For Maestro, all address information matches.

1

For Maestro, none of the address information matches.

2

For Maestro, part of the address information matches.

3

For Maestro, the merchant did not provide AVS information. It was not processed.

4

For Maestro, the address was not checked or the acquirer had no response. The service is not available.

A

For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct.

B

For Visa, Mastercard, or Discover transactions, the address matches. International A.

C

For Visa, Mastercard, or Discover transactions, no values match. International N.

D

For Visa, Mastercard, or Discover transactions, the address and postal code match. International X.

E

For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match.

F

For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches.

G

For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches.

I

For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable.

M

For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match.

N

For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect.

P

For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only.

R

For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable.

S

For Visa, Mastercard, Discover, or American Express, the service is not supported.

U

For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available.

W

For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.

X

For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.

Y

For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct.

Z

For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct.

Null

For Maestro, no AVS response was obtained.

cvv_code
string

The card verification value code for for Visa, Discover, Mastercard, or American Express.

Enum Value Description
0

For Maestro, the CVV2 matched.

1

For Maestro, the CVV2 did not match.

2

For Maestro, the merchant has not implemented CVV2 code handling.

3

For Maestro, the merchant has indicated that CVV2 is not present on card.

4

For Maestro, the service is not available.

E

For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response.

I

For Visa, Mastercard, Discover, or American Express, invalid or null.

M

For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches.

N

For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match.

P

For Visa, Mastercard, Discover, or American Express, it was not processed.

S

For Visa, Mastercard, Discover, or American Express, the service is not supported.

U

For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified.

X

For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available.

All others

For Visa, Mastercard, Discover, or American Express, error.

response_code
string

Processor response code for the non-PayPal payment processor errors.

Enum Value Description
1000

PARTIAL_AUTHORIZATION.

1300

INVALID_DATA_FORMAT.

1310

INVALID_AMOUNT.

1312

INVALID_TRANSACTION_CARD_ISSUER_ACQUIRER.

1317

INVALID_CAPTURE_DATE.

1320

INVALID_CURRENCY_CODE.

1330

INVALID_ACCOUNT.

1335

INVALID_ACCOUNT_RECURRING.

1340

INVALID_TERMINAL.

1350

INVALID_MERCHANT.

1352

RESTRICTED_OR_INACTIVE_ACCOUNT.

1360

BAD_PROCESSING_CODE.

1370

INVALID_MCC.

1380

INVALID_EXPIRATION.

1382

INVALID_CARD_VERIFICATION_VALUE.

1384

INVALID_LIFE_CYCLE_OF_TRANSACTION.

1390

INVALID_ORDER.

1393

TRANSACTION_CANNOT_BE_COMPLETED.

5100

GENERIC_DECLINE.

5110

CVV2_FAILURE.

5120

INSUFFICIENT_FUNDS.

5130

INVALID_PIN.

5135

DECLINED_PIN_TRY_EXCEEDED.

5140

CARD_CLOSED.

5150

PICKUP_CARD_SPECIAL_CONDITIONS. Try using another card. Do not retry the same card.

5160

UNAUTHORIZED_USER.

5170

AVS_FAILURE.

5180

INVALID_OR_RESTRICTED_CARD. Try using another card. Do not retry the same card.

5190

SOFT_AVS.

5200

DUPLICATE_TRANSACTION.

5210

INVALID_TRANSACTION.

5400

EXPIRED_CARD.

5500

INCORRECT_PIN_REENTER.

5650

DECLINED_SCA_REQUIRED.

5700

TRANSACTION_NOT_PERMITTED. Outside of scope of accepted business.

5710

TX_ATTEMPTS_EXCEED_LIMIT.

5800

REVERSAL_REJECTED.

5900

INVALID_ISSUE.

5910

ISSUER_NOT_AVAILABLE_NOT_RETRIABLE.

5920

ISSUER_NOT_AVAILABLE_RETRIABLE.

5930

CARD_NOT_ACTIVATED.

5950

DECLINED_DUE_TO_UPDATED_ACCOUNT. External decline as an updated card has been issued.

6300

ACCOUNT_NOT_ON_FILE.

7600

APPROVED_NON_CAPTURE.

7700

ERROR_3DS.

7710

AUTHENTICATION_FAILED.

7800

BIN_ERROR.

7900

PIN_ERROR.

8000

PROCESSOR_SYSTEM_ERROR.

8010

HOST_KEY_ERROR.

8020

CONFIGURATION_ERROR.

8030

UNSUPPORTED_OPERATION.

8100

FATAL_COMMUNICATION_ERROR.

8110

RETRIABLE_COMMUNICATION_ERROR.

8220

SYSTEM_UNAVAILABLE.

9100

DECLINED_PLEASE_RETRY. Retry.

9500

SUSPECTED_FRAUD. Try using another card. Do not retry the same card.

9510

SECURITY_VIOLATION.

9520

LOST_OR_STOLEN. Try using another card. Do not retry the same card.

9530

HOLD_CALL_CENTER. The merchant must call the number on the back of the card. POS scenario.

9540

REFUSED_CARD.

9600

UNRECOGNIZED_RESPONSE_CODE.

0000

APPROVED.

00N7

CVV2_FAILURE_POSSIBLE_RETRY_WITH_CVV.

0100

REFERRAL.

0390

ACCOUNT_NOT_FOUND.

0500

DO_NOT_HONOR.

0580

UNAUTHORIZED_TRANSACTION.

0800

BAD_RESPONSE_REVERSAL_REQUIRED.

0880

CRYPTOGRAPHIC_FAILURE.

0890

UNACCEPTABLE_PIN.

0960

SYSTEM_MALFUNCTION.

0R00

CANCELLED_PAYMENT.

10BR

ISSUER_REJECTED.

PCNR

CONTINGENCIES_NOT_RESOLVED.

PCVV

CVV_FAILURE.

PP06

ACCOUNT_CLOSED. A previously open account is now closed

PPRN

REATTEMPT_NOT_PERMITTED.

PPAD

BILLING_ADDRESS.

PPAB

ACCOUNT_BLOCKED_BY_ISSUER.

PPAE

AMEX_DISABLED.

PPAG

ADULT_GAMING_UNSUPPORTED.

PPAI

AMOUNT_INCOMPATIBLE.

PPAR

AUTH_RESULT.

PPAU

MCC_CODE.

PPAV

ARC_AVS.

PPAX

AMOUNT_EXCEEDED.

PPBG

BAD_GAMING.

PPC2

ARC_CVV.

PPCE

CE_REGISTRATION_INCOMPLETE.

PPCO

COUNTRY.

PPCR

CREDIT_ERROR.

PPCT

CARD_TYPE_UNSUPPORTED.

PPCU

CURRENCY_USED_INVALID.

PPD3

SECURE_ERROR_3DS.

PPDC

DCC_UNSUPPORTED.

PPDI

DINERS_REJECT.

PPDV

AUTH_MESSAGE.

PPDT

DECLINE_THRESHOLD_BREACH.

PPEF

EXPIRED_FUNDING_INSTRUMENT.

PPEL

EXCEEDS_FREQUENCY_LIMIT.

PPER

INTERNAL_SYSTEM_ERROR.

PPEX

EXPIRY_DATE.

PPFE

FUNDING_SOURCE_ALREADY_EXISTS.

PPFI

INVALID_FUNDING_INSTRUMENT.

PPFR

RESTRICTED_FUNDING_INSTRUMENT.

PPFV

FIELD_VALIDATION_FAILED.

PPGR

GAMING_REFUND_ERROR.

PPH1

H1_ERROR.

PPIF

IDEMPOTENCY_FAILURE.

PPII

INVALID_INPUT_FAILURE.

PPIM

ID_MISMATCH.

PPIT

INVALID_TRACE_ID.

PPLR

LATE_REVERSAL.

PPLS

LARGE_STATUS_CODE.

PPMB

MISSING_BUSINESS_RULE_OR_DATA.

PPMC

BLOCKED_Mastercard.

PPMD

DEPRECATED The PPMD value has been deprecated.

PPNC

NOT_SUPPORTED_NRC.

PPNL

EXCEEDS_NETWORK_FREQUENCY_LIMIT.

PPNM

NO_MID_FOUND.

PPNT

NETWORK_ERROR.

PPPH

NO_PHONE_FOR_DCC_TRANSACTION.

PPPI

INVALID_PRODUCT.

PPPM

INVALID_PAYMENT_METHOD.

PPQC

QUASI_CASH_UNSUPPORTED.

PPRE

UNSUPPORT_REFUND_ON_PENDING_BC.

PPRF

INVALID_PARENT_TRANSACTION_STATUS.

PPRR

MERCHANT_NOT_REGISTERED.

PPS0

BANKAUTH_ROW_MISMATCH.

PPS1

BANKAUTH_ROW_SETTLED.

PPS2

BANKAUTH_ROW_VOIDED.

PPS3

BANKAUTH_EXPIRED.

PPS4

CURRENCY_MISMATCH.

PPS5

CREDITCARD_MISMATCH.

PPS6

AMOUNT_MISMATCH.

PPSC

ARC_SCORE.

PPSD

STATUS_DESCRIPTION.

PPSE

AMEX_DENIED.

PPTE

VERIFICATION_TOKEN_EXPIRED.

PPTF

INVALID_TRACE_REFERENCE.

PPTI

INVALID_TRANSACTION_ID.

PPTR

VERIFICATION_TOKEN_REVOKED.

PPTT

TRANSACTION_TYPE_UNSUPPORTED.

PPTV

INVALID_VERIFICATION_TOKEN.

PPUA

USER_NOT_AUTHORIZED.

PPUC

CURRENCY_CODE_UNSUPPORTED.

PPUE

UNSUPPORT_ENTITY.

PPUI

UNSUPPORT_INSTALLMENT.

PPUP

UNSUPPORT_POS_FLAG.

PPUR

UNSUPPORTED_REVERSAL.

PPVC

VALIDATE_CURRENCY.

PPVE

VALIDATION_ERROR.

PPVT

VIRTUAL_TERMINAL_UNSUPPORTED.

payment_advice_code
string

The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.

Enum Value Description
21

For Mastercard, the card holder has been unsuccessful at canceling recurring payment through merchant. Stop recurring payment requests. For Visa, all recurring payments were canceled for the card number requested. Stop recurring payment requests.

22

For Mastercard, merchant does not qualify for product code.

24

For Mastercard, retry after 1 hour.

25

For Mastercard, retry after 24 hours.

26

For Mastercard, retry after 2 days.

27

For Mastercard, retry after 4 days.

28

For Mastercard, retry after 6 days.

29

For Mastercard, retry after 8 days.

30

For Mastercard, retry after 10 days .

40

For Mastercard, consumer non-reloadable prepaid card.

43

For Mastercard, consumer multi-use virtual card number.

01

For Mastercard, expired card account upgrade or portfolio sale conversion. Obtain new account information before next billing cycle.

02

For Mastercard, over credit limit or insufficient funds. Retry the transaction 72 hours later. For Visa, the card holder wants to stop only one specific payment in the recurring payment relationship. The merchant must NOT resubmit the same transaction. The merchant can continue the billing process in the subsequent billing period.

03

For Mastercard, account closed as fraudulent. Obtain another type of payment from customer due to account being closed or fraud. Possible reason: Account closed as fraudulent. For Visa, the card holder wants to stop all recurring payment transactions for a specific merchant. Stop recurring payment requests.

04

For Mastercard, token requirements not fulfilled for this token type.

{
  • "avs_code": "A",
  • "cvv_code": "E",
  • "response_code": "0000",
  • "payment_advice_code": "01"
}

Reauthorize Request

Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. You can reauthorize a payment only once from days four to 29.

If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.

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

You can reauthorize an authorized payment once. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.

Supports only the amount request parameter.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

{
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

refund

The refund information.

status
string (Refund Status With Details)

The status of the refund.

Enum Value Description
CANCELLED

The refund was cancelled.

FAILED

The refund could not be processed.

PENDING

The refund is pending. For more information, see status_details.reason.

COMPLETED

The funds for this transaction were debited to the customer's account.

object (refund_status_details)

The details of the refund status.

id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The PayPal-generated ID for the refund.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

invoice_id
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.

custom_id
string [ 1 .. 255 ] characters ^[A-Za-z0-9-_.,]*$

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

acquirer_reference_number
string [ 1 .. 36 ] characters ^[a-zA-Z0-9]+$

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

note_to_payer
string [ 0 .. 2147483647 ] characters ^[\S\s]*$

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

object (Seller Payable Breakdown)

The breakdown of the refund.

object (payee_base)

The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

object (Buyer Context)

The buyer context for the refund transaction.

Array of objects (Link Description) [ 0 .. 32767 ] items

An array of related HATEOAS links.

create_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

update_time
string (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

{
  • "status": "CANCELLED",
  • "status_details": {
    • "reason": "ECHECK"
    },
  • "id": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "invoice_id": "string",
  • "custom_id": "string",
  • "acquirer_reference_number": "string",
  • "note_to_payer": "string",
  • "seller_payable_breakdown": {
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "string"
          }
        }
      ],
    • "net_amount_breakdown": [
      • {
        • "payable_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "converted_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "exchange_rate": {
          • "source_currency": "string",
          • "target_currency": "string",
          • "value": "string"
          }
        }
      ],
    • "total_refunded_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "payer": {
    • "email_address": "string",
    • "merchant_id": "string"
    },
  • "buyer_context": {
    • "transaction_id": "string",
    • "transaction_details_url": "http://example.com",
    • "transaction_create_time": "string",
    • "transaction_update_time": "string"
    },
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET",
      • "title": "string",
      • "mediaType": "string",
      • "encType": "application/json",
      • "schema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        },
      • "targetSchema": {
        • "additionalItems": { },
        • "dependencies": { },
        • "items": { },
        • "definitions": { },
        • "patternProperties": { },
        • "properties": { },
        • "allOf": [
          • { }
          ],
        • "anyOf": [
          • { }
          ],
        • "oneOf": [
          • { }
          ],
        • "not": { },
        • "links": [
          • { }
          ],
        • "fragmentResolution": "string",
        • "media": {
          • "type": "string",
          • "binaryEncoding": "string"
          },
        • "pathStart": "http://example.com"
        }
      }
    ],
  • "create_time": "string",
  • "update_time": "string"
}

Refund Request

Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an amount object in the request body.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

custom_id
string [ 1 .. 127 ] characters ^.*$

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. The pattern is defined by an external party and supports Unicode.

invoice_id
string [ 1 .. 127 ] characters ^.*$

The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode.

note_to_payer
string [ 1 .. 255 ] characters ^.*$

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. The pattern is defined by an external party and supports Unicode.

object (payment_instruction)

Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.

{
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "custom_id": "string",
  • "invoice_id": "string",
  • "note_to_payer": "string",
  • "payment_instruction": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "string"
          }
        }
      ]
    }
}

refund_status

The refund status with details.

status
string (Refund Status With Details)

The status of the refund.

Enum Value Description
CANCELLED

The refund was cancelled.

FAILED

The refund could not be processed.

PENDING

The refund is pending. For more information, see status_details.reason.

COMPLETED

The funds for this transaction were debited to the customer's account.

object (refund_status_details)

The details of the refund status.

{
  • "status": "CANCELLED",
  • "status_details": {
    • "reason": "ECHECK"
    }
}

refund_status_details

The details of the refund status.

reason
string (Refund Incomplete Reason)

The reason why the refund has the PENDING or FAILED status.

Value Description
ECHECK

The customer's account is funded through an eCheck, which has not yet cleared.

{
  • "reason": "ECHECK"
}

Response for ACH

Response for ACH payment method.

can_be_vaulted
boolean
Default: false

Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.

{
  • "can_be_vaulted": false
}

Response for PayPal

Response for PayPal.

can_be_vaulted
boolean
Default: false

Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.

country_code
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

product_code
string (Credit Button Eligibility Button Code)

The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.

Enum Value Description
CREDIT

Open ended credit products.

PAYLATER

Pay Later suite of products.

PAY_IN_3

Pay In 3 suite of products.

PAY_IN_4

Pay In 4 suite of products.

eligible_in_paypal_network
boolean (PayPal services member indicator)

Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request.

recommended
boolean
Default: "false"

Indicates if the payment method is recommended or not. A true value indicates the customer is payment ready and this payment method may be presented upfront.

recommended_priority
integer [ 1 .. 3 ]

This value is included in the response when recommended is true for a payment method. It indicates the priority of recommendation for payment readiness of eligible payment methods with lowest number taking the highest precedence.

{
  • "can_be_vaulted": false,
  • "country_code": "string",
  • "product_code": "CREDIT",
  • "eligible_in_paypal_network": true,
  • "recommended": "false",
  • "recommended_priority": 1
}

Response for Venmo

Response for Venmo.

can_be_vaulted
boolean
Default: false

Indicates if the payment method can be vaulted or not. A true value indicates the payment method can be vaulted using our vaults product. If false, vaulting is not currently supported for this payment method.

country_code
string (country_code-2) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

product_code
string (Credit Button Eligibility Button Code)

The button code corresponding to a particular product or set of products. The values followed are defined by the SDK team.

Enum Value Description
CREDIT

Open ended credit products.

PAYLATER

Pay Later suite of products.

PAY_IN_3

Pay In 3 suite of products.

PAY_IN_4

Pay In 4 suite of products.

eligible_in_paypal_network
boolean (PayPal services member indicator)

Flag that indicates if the customer is in the PayPal network. This value will be included in the response if the include_account_details flag is set to "true" in the API request.

recommended
boolean
Default: "false"

Indicates if the payment method is recommended or not. A true value indicates the customer is payment ready and this payment method may be presented upfront.

recommended_priority
integer [ 1 .. 3 ]

This value is included in the response when recommended is true for a payment method. It indicates the priority of recommendation for payment readiness of eligible payment methods with lowest number taking the highest precedence.

{
  • "can_be_vaulted": false,
  • "country_code": "string",
  • "product_code": "CREDIT",
  • "eligible_in_paypal_network": true,
  • "recommended": "false",
  • "recommended_priority": 1
}

Schema Object for standard headers

Standard headers are generally less restrictive in structure due to historical precedent across browsers, etc. This is a common schema for use in defining most standard headers.

string (Schema Object for standard headers) [ 1 .. 16000 ] characters ^.*$

Standard headers are generally less restrictive in structure due to historical precedent across browsers, etc. This is a common schema for use in defining most standard headers.

"string"

Seller Receivable Breakdown

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

required
object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (exchange_rate)

The exchange rate that determines the amount to convert from one currency to another currency.

Array of objects (platform_fee) [ 0 .. 1 ] items

An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.

{
  • "gross_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "paypal_fee": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "paypal_fee_in_receivable_currency": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "net_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "receivable_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "exchange_rate": {
    • "source_currency": "string",
    • "target_currency": "string",
    • "value": "string"
    },
  • "platform_fees": [
    • {
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "string"
        }
      }
    ]
}

seller_protection

The level of protection offered as defined by PayPal Seller Protection for Merchants.

status
string (Seller Protection Status)

Indicates whether the transaction is eligible for seller protection. For information, see PayPal Seller Protection for Merchants.

Enum Value Description
ELIGIBLE

Your PayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment.

PARTIALLY_ELIGIBLE

Your PayPal balance remains intact if the customer claims that they did not receive an item.

NOT_ELIGIBLE

This transaction is not eligible for seller protection.

dispute_categories
Array of strings (dispute_category) [ 0 .. 32767 ] items

An array of conditions that are covered for the transaction.

Items Enum Value Description
ITEM_NOT_RECEIVED

The payer paid for an item that they did not receive.

UNAUTHORIZED_TRANSACTION

The payer did not authorize the payment.

{
  • "status": "ELIGIBLE",
  • "dispute_categories": [
    • "ITEM_NOT_RECEIVED"
    ]
}

Tokenization Parameters

Parameters for configuring payment tokenization with the gateway.

gateway
string [ 2 .. 255 ] characters ^[a-zA-Z0-9_-]+$

Payment gateway name.

gateway_merchant_id
string (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

The account identifier for a PayPal account.

{
  • "gateway": "string",
  • "gateway_merchant_id": "string"
}

Tokenization Specification

Specification for payment method tokenization in Google Pay.

type
string

Tokenization type.

Value Description
PAYMENT_GATEWAY

Tokenization using a payment gateway.

object (Tokenization Parameters)

Parameters for configuring payment tokenization with the gateway.

{
  • "type": "PAYMENT_GATEWAY",
  • "parameters": {
    • "gateway": "string",
    • "gateway_merchant_id": "string"
    }
}