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.

Request samples 
curl -v -X get https://api-m.sandbox.paypal.com//v2/payments/authorizations/0VF52814937998046 \
 \
-d '{}'
Response samples
application/json
{}

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 (Money)

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

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.

Request samples
application/json
{ }
Response samples
application/json
{}

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.

Request samples
application/json
{ }
Response samples
application/json
{}

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

Response samples
application/json
{
  • "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.

Request samples 
curl -v -X get https://api-m.sandbox.paypal.com//v2/payments/captures/74L756601X447022Y \
 \
-d '{}'
Response samples
application/json
{}

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.

Request samples
application/json
{ }
Response samples
application/json
{
  • "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.

Request samples
application/json
{ }
Response samples
application/json
{
  • "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.

Request samples 
curl -v -X get https://api-m.sandbox.paypal.com//v2/payments/refunds/1JU08902781691411 \
 \
-d '{}'
Response samples
application/json
{
  • "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": {}
        }
      ],
    • "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"
}

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"
      }
    }
}

authorization

The authorized payment transaction.

status
string (Authorization Status)

The status for the authorized payment.

Enum: "CREATED" "CAPTURED" "DENIED" "PARTIALLY_CAPTURED" "VOIDED" "PENDING"
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: "CREATED" "CAPTURED" "DENIED" "PARTIALLY_CAPTURED" "VOIDED" "PENDING"
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: "CREATED" "CAPTURED" "DENIED" "PARTIALLY_CAPTURED" "VOIDED" "PENDING"
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: "PENDING_REVIEW" "DECLINED_BY_RISK_FRAUD_FILTERS"
{
  • "reason": "PENDING_REVIEW"
}

capture

A captured payment.

status
string (Capture Status)

The status of the captured payment.

Enum: "COMPLETED" "DECLINED" "PARTIALLY_REFUNDED" "PENDING" "REFUNDED" "FAILED"
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: "INSTANT" "DELAYED"
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 (Money)

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

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"
    },
  • "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: "COMPLETED" "DECLINED" "PARTIALLY_REFUNDED" "PENDING" "REFUNDED" "FAILED"
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: "BUYER_COMPLAINT" "CHARGEBACK" "ECHECK" "INTERNATIONAL_WITHDRAWAL" "OTHER" "PENDING_REVIEW" "RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION" "REFUNDED" "TRANSACTION_APPROVED_AWAITING_FUNDING" "UNILATERAL" "VERIFICATION_REQUIRED" "DECLINED_BY_RISK_FRAUD_FILTERS"
{
  • "reason": "BUYER_COMPLAINT"
}

Captured Payment

A captured payment.

status
string (Capture Status)

The status of the captured payment.

Enum: "COMPLETED" "DECLINED" "PARTIALLY_REFUNDED" "PENDING" "REFUNDED" "FAILED"
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: "INSTANT" "DELAYED"
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_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: "VISA" "MASTERCARD" "DISCOVER" "AMEX" "SOLO" "JCB" "STAR" "DELTA" "SWITCH" "MAESTRO" "CB_NATIONALE" "CONFIGOGA" "CONFIDIS" "ELECTRON" "CETELEM" "CHINA_UNION_PAY" "DINERS" "ELO" "HIPER" "HIPERCARD" "RUPAY" "GE" "SYNCHRONY" "EFTPOS" "CARTE_BANCAIRE" "STAR_ACCESS" "PULSE" "NYCE" "ACCEL" "UNKNOWN"
"VISA"

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: "CREDIT" "PAYLATER" "PAY_IN_3" "PAY_IN_4"
{
  • "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: "CREDIT" "PAYLATER" "PAY_IN_3" "PAY_IN_4"
"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.

id
string [ 1 .. 36 ] characters ^[0-9a-zA-Z_-]+$

The unique ID for a customer in merchant's or partner's system of records.

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"
    },
  • "id": "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: "INSTANT" "DELAYED"
"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_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"
      },
    • "id": "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",
    • "include_account_details": "false",
    • "include_vault_tokens": "false",
    • "payment_source_constraint": {
      • "constraint_type": "INCLUDE",
      • "payment_sources": [
        • "PAYPAL"
        ]
      }
    }
}

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: "GET" "POST" "PUT" "DELETE" "HEAD" "CONNECT" "OPTIONS" "PATCH"
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"
}

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: "VISA" "MASTERCARD" "DISCOVER" "AMEX" "SOLO" "JCB" "STAR" "DELTA" "SWITCH" "MAESTRO" "CB_NATIONALE" "CONFIGOGA" "CONFIDIS" "ELECTRON" "CETELEM" "CHINA_UNION_PAY" "DINERS" "ELO" "HIPER" "HIPERCARD" "RUPAY" "GE" "SYNCHRONY" "EFTPOS" "CARTE_BANCAIRE" "STAR_ACCESS" "PULSE" "NYCE" "ACCEL" "UNKNOWN"
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"
}

payer_base

The customer who approves and pays for the order. The customer is also known as the payer.

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.

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

The account identifier for a PayPal account.

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

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.

{
  • "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"
    }
}

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: "INSTANT" "DELAYED"
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: "PAYPAL" "VENMO" "PAYPAL_CREDIT" "PAYPAL_PAY_LATER"
"PAYPAL"

payment_token

Vaulted instrument for a payment-method.

id
string (id) [ 7 .. 36 ] characters ^[0-9a-zA-Z_-]+$

The PayPal-generated ID for the vault token.

object (The vaulted payment method details)

The vaulted payment method details.

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

An array of related HATEOAS links.

{
  • "id": "strings",
  • "payment_source": {
    • "paypal": {
      • "email_address": "string",
      • "payer_id": "string"
      },
    • "venmo": {
      • "user_name": "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"
        }
      }
    ]
}

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 along with applicable vault tokens, if requested.

object (Payment Methods)

List of payment methods.

Array of objects (payment_token) [ 1 .. 64 ] items

Payment tokens for vaulted instruments, if available. This object will be included only if include_vault_tokens is set to true in the request.

{
  • "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"
      }
    },
  • "payment_tokens": [
    • {
      • "id": "strings",
      • "payment_source": {
        • "paypal": {
          • "email_address": "string",
          • "payer_id": "string"
          },
        • "venmo": {
          • "user_name": "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"
            }
          }
        ]
      }
    ]
}

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: "ONE_TIME_PAYMENT" "RECURRING_PAYMENT" "VAULT_WITH_PAYMENT" "VAULT_WITHOUT_PAYMENT"
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.

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",
  • "include_account_details": "false",
  • "include_vault_tokens": "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: "A" "B" "C" "D" "E" "F" "G" "I" "M" "N" "P" "R" "S" "U" "W" "X" "Y" "Z" "Null" "0" "1" "2" "3" "4"
cvv_code
string

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

Enum: "E" "I" "M" "N" "P" "S" "U" "X" "All others" "0" "1" "2" "3" "4"
response_code
string

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

Enum: "0000" "00N7" "0100" "0390" "0500" "0580" "0800" "0880" "0890" "0960" "0R00" "1000" "10BR" "1300" "1310" "1312" "1317" "1320" "1330" "1335" "1340" "1350" "1352" "1360" "1370" "1380" "1382" "1384" "1390" "1393" "5100" "5110" "5120" "5130" "5135" "5140" "5150" "5160" "5170" "5180" "5190" "5200" "5210" "5400" "5500" "5650" "5700" "5710" "5800" "5900" "5910" "5920" "5930" "5950" "6300" "7600" "7700" "7710" "7800" "7900" "8000" "8010" "8020" "8030" "8100" "8110" "8220" "9100" "9500" "9510" "9520" "9530" "9540" "9600" "PCNR" "PCVV" "PP06" "PPRN" "PPAD" "PPAB" "PPAE" "PPAG" "PPAI" "PPAR" "PPAU" "PPAV" "PPAX" "PPBG" "PPC2" "PPCE" "PPCO" "PPCR" "PPCT" "PPCU" "PPD3" "PPDC" "PPDI" "PPDV" "PPDT" "PPEF" "PPEL" "PPER" "PPEX" "PPFE" "PPFI" "PPFR" "PPFV" "PPGR" "PPH1" "PPIF" "PPII" "PPIM" "PPIT" "PPLR" "PPLS" "PPMB" "PPMC" "PPMD" "PPNC" "PPNL" "PPNM" "PPNT" "PPPH" "PPPI" "PPPM" "PPQC" "PPRE" "PPRF" "PPRR" "PPS0" "PPS1" "PPS2" "PPS3" "PPS4" "PPS5" "PPS6" "PPSC" "PPSD" "PPSE" "PPTE" "PPTF" "PPTI" "PPTR" "PPTT" "PPTV" "PPUA" "PPUC" "PPUE" "PPUI" "PPUP" "PPUR" "PPVC" "PPVE" "PPVT"
payment_advice_code
string

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

Enum: "01" "02" "03" "04" "21" "22" "24" "25" "26" "27" "28" "29" "30" "40" "43"
{
  • "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: "CANCELLED" "FAILED" "PENDING" "COMPLETED"
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.

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"
    },
  • "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: "CANCELLED" "FAILED" "PENDING" "COMPLETED"
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: "ECHECK"
{
  • "reason": "ECHECK"
}

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: "CREDIT" "PAYLATER" "PAY_IN_3" "PAY_IN_4"
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: "CREDIT" "PAYLATER" "PAY_IN_3" "PAY_IN_4"
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: "ELIGIBLE" "PARTIALLY_ELIGIBLE" "NOT_ELIGIBLE"
dispute_categories
Array of strings (dispute_category) [ 0 .. 32767 ] items

An array of conditions that are covered for the transaction.

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

venmo_payment_token

Payment Token info for Venmo payment source.

user_name
string [ 1 .. 50 ] characters ^[-a-zA-Z0-9_]*$

The Venmo username, as chosen by the user.

{
  • "user_name": "string"
}