Payments API

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.

Authorizations (resource group)

Use the /authorizations resource to show details for, capture payment for, reauthorize, and void authorized payments.

Show details for authorized payment

GET/v2/payments/authorizations/{authorization_id}
Shows details for an authorized payment, by ID.

Header parameters

  • Authorization

    string

    required

    To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

  • Content-Type

    string

    required

    Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

  • authorization_id

    string

    required

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

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

    object

    An object that provides supplementary/additional data related to a payment transaction.

    Read only.

Sample Response

{
  "id": "0VF52814937998046",
  "status": "CREATED",
  "amount": {
    "value": "10.99",
    "currency_code": "USD"
  },
  "invoice_id": "INVOICE-123",
  "seller_protection": {
    "status": "ELIGIBLE",
    "dispute_categories": [
      "ITEM_NOT_RECEIVED",
      "UNAUTHORIZED_TRANSACTION"
    ]
  },
  "expiration_time": "2017-10-10T23:23:45Z",
  "create_time": "2017-09-11T23:23:45Z",
  "update_time": "2017-09-11T23:23:45Z",
  "links": [
    {
      "rel": "self",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046"
    },
    {
      "rel": "capture",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/capture"
    },
    {
      "rel": "void",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/void"
    },
    {
      "rel": "reauthorize",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/reauthorize"
    }
  ]
}

Capture authorized payment

POST/v2/payments/authorizations/{authorization_id}/capture
Captures an authorized payment, by ID.

Header parameters

  • PayPal-Request-Id

    string

    The server stores keys for 45 days.

  • Prefer

    string

    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

    required

    To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

  • Content-Type

    string

    required

    Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

  • authorization_id

    string

    required

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

Request body

  • amount

    object

    The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.

  • final_capture

    boolean

    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.

  • invoice_id

    string

    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.

    Maximum length: 127.

  • note_to_payer

    string

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

    Maximum length: 255.

  • payment_instruction

    object

    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

    The payment descriptor on the payer's account statement.

    Maximum length: 22.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440010" \
-d '{
  "amount": {
    "value": "10.99",
    "currency_code": "USD"
  },
  "invoice_id": "INVOICE-123",
  "final_capture": true,
  "note_to_payer": "If the ordered color is not available, we will substitute with a different color free of charge.",
  "soft_descriptor": "Bob's Custom Sweaters"
}'

Response

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

    object

    An object that provides supplementary/additional data related to a payment transaction.

    Read only.

Sample Response

{
  "id": "2GG279541U471931P",
  "status": "COMPLETED",
  "links": [
    {
      "rel": "self",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
    },
    {
      "rel": "refund",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P/refund"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046"
    }
  ]
}

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 once for up to 115% of the original authorized amount, not to exceed an increase of $75 USD.

Supports only the amount request parameter.
Note: This request is currently not supported for Partner use cases.

Header parameters

  • PayPal-Request-Id

    string

    The server stores keys for 45 days.

  • Prefer

    string

    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

    required

    To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

  • Content-Type

    string

    required

    Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

  • authorization_id

    string

    required

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

Request body

  • amount

    object

    The amount to reauthorize for an authorized payment.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/reauthorize \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440040" \
-d '{
  "amount": {
    "value": "10.99",
    "currency_code": "USD"
  }
}'

Response

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

    object

    An object that provides supplementary/additional data related to a payment transaction.

    Read only.

Sample Response

{
  "id": "8AA831015G517922L",
  "status": "CREATED",
  "links": [
    {
      "rel": "self",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L"
    },
    {
      "rel": "capture",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/capture"
    },
    {
      "rel": "void",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/void"
    },
    {
      "rel": "reauthorize",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/reauthorize"
    }
  ]
}

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.

Header parameters

  • PayPal-Auth-Assertion

    string

    An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.

    Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.

  • Authorization

    string

    required

    To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

  • Content-Type

    string

    required

    Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Path parameters

  • authorization_id

    string

    required

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

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/void \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

    Sample Response

    204 No Content

    Captures (resource group)

    Use the /captures resource to show details for and refund a captured payment.

    Show captured payment details

    GET/v2/payments/captures/{capture_id}
    Shows details for a captured payment, by ID.

    Header parameters

    • Authorization

      string

      required

      To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

    • Content-Type

      string

      required

      Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

    Path parameters

    • capture_id

      string

      required

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

    Sample Request

    curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Access-Token"

    Response

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

      object

      An object that provides supplementary/additional data related to a payment transaction.

      Read only.

    Sample Response

    {
      "id": "2GG279541U471931P",
      "status": "COMPLETED",
      "status_details": {},
      "amount": {
        "total": "10.99",
        "currency": "USD"
      },
      "final_capture": true,
      "seller_protection": {
        "status": "ELIGIBLE",
        "dispute_categories": [
          "ITEM_NOT_RECEIVED",
          "UNAUTHORIZED_TRANSACTION"
        ]
      },
      "seller_receivable_breakdown": {
        "gross_amount": {
          "total": "10.99",
          "currency": "USD"
        },
        "paypal_fee": {
          "value": "0.33",
          "currency": "USD"
        },
        "net_amount": {
          "value": "10.66",
          "currency": "USD"
        },
        "receivable_amount": {
          "currency_code": "CNY",
          "value": "59.26"
        },
        "paypal_fee_in_receivable_currency": {
          "currency_code": "CNY",
          "value": "1.13"
        },
        "exchange_rate": {
          "source_currency": "USD",
          "target_currency": "CNY",
          "value": "5.9483297432325"
        }
      },
      "invoice_id": "INVOICE-123",
      "create_time": "2017-09-11T23:24:01Z",
      "update_time": "2017-09-11T23:24:01Z",
      "links": [
        {
          "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P/refund",
          "rel": "refund",
          "method": "POST"
        },
        {
          "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046",
          "rel": "up",
          "method": "GET"
        }
      ]
    }

    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.

    Header parameters

    • PayPal-Auth-Assertion

      string

      An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.

      Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.

    • PayPal-Request-Id

      string

      The server stores keys for 45 days.

    • Prefer

      string

      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

      required

      To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

    • Content-Type

      string

      required

      Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

    Path parameters

    • capture_id

      string

      required

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

    Request body

    • amount

      object

      The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to captured amount - previous refunds is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured.

    • invoice_id

      string

      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.

      Minimum length: 1.

      Maximum length: 127.

    • note_to_payer

      string

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

      Minimum length: 1.

      Maximum length: 255.

    • payment_instruction

      object

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

    Sample Request

    curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P/refund \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Access-Token" \
    -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440020" \
    -d '{
      "amount": {
        "value": "10.00",
        "currency_code": "USD"
      },
      "invoice_id": "INVOICE-123",
      "note_to_payer": "DefectiveProduct",
      "payment_instruction": {
        "platform_fees": [
          {
            "amount": {
              "currency_code": "USD",
              "value": "1.00"
            }
          }
        ]
      }
    }'

    Response

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

      object

      The amount that the payee refunded to the payer.

      Read only.

    • create_time

      string

      The date and time when the transaction occurred, in Internet date and time format.

      Read only.

    • id

      string

      The PayPal-generated ID for the refund.

      Read only.

    • invoice_id

      string

      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.

      Read only.

    • links

      array (contains the link_description object)

      An array of related HATEOAS links.

      Read only.

    • note_to_payer

      string

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

      Read only.

    • seller_payable_breakdown

      object

      The breakdown of the refund.

      Read only.

    • status

      enum

      The status of the refund.

      The possible values are:

      • CANCELLED. The refund was cancelled.
      • FAILED. The refund could not be processed.
      • PENDING. The refund is pending. For more information, see status_details.reason.
      • COMPLETED. The funds for this transaction were debited to the customer's account.

      Read only.

    • status_details

      object

      The details of the refund status.

      Read only.

    • update_time

      string

      The date and time when the transaction was last updated, in Internet date and time format.

      Read only.

    Sample Response

    {
      "id": "1JU08902781691411",
      "amount": {
        "value": "10.00",
        "currency_code": "USD"
      },
      "status": "COMPLETED",
      "note": "Defective product",
      "seller_payable_breakdown": {
        "gross_amount": {
          "value": "10.00",
          "currency_code": "USD"
        },
        "paypal_fee": {
          "value": "0",
          "currency_code": "USD"
        },
        "platform_fees": [
          {
            "amount": {
              "currency_code": "USD",
              "value": "1.00"
            }
          }
        ],
        "net_amount": {
          "value": "9.00",
          "currency_code": "USD"
        },
        "total_refunded_amount": {
          "value": "10.00",
          "currency_code": "USD"
        }
      },
      "invoice_id": "INVOICE-123",
      "create_time": "2022-04-23T23:24:19Z",
      "update_time": "2022-04-23T23:24:19Z",
      "links": [
        {
          "rel": "self",
          "method": "GET",
          "href": "https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411"
        },
        {
          "rel": "up",
          "method": "GET",
          "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
        }
      ]
    }

    Refunds (resource group)

    Use the /refunds resource to show refund details.

    Show refund details

    GET/v2/payments/refunds/{refund_id}
    Shows details for a refund, by ID.

    Header parameters

    • Authorization

      string

      required

      To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

    • Content-Type

      string

      required

      Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

    Path parameters

    • refund_id

      string

      required

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

    Sample Request

    curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/refunds/1JU08902781691411 \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Access-Token"

    Response

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

      object

      The amount that the payee refunded to the payer.

      Read only.

    • create_time

      string

      The date and time when the transaction occurred, in Internet date and time format.

      Read only.

    • id

      string

      The PayPal-generated ID for the refund.

      Read only.

    • invoice_id

      string

      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.

      Read only.

    • links

      array (contains the link_description object)

      An array of related HATEOAS links.

      Read only.

    • note_to_payer

      string

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

      Read only.

    • seller_payable_breakdown

      object

      The breakdown of the refund.

      Read only.

    • status

      enum

      The status of the refund.

      The possible values are:

      • CANCELLED. The refund was cancelled.
      • FAILED. The refund could not be processed.
      • PENDING. The refund is pending. For more information, see status_details.reason.
      • COMPLETED. The funds for this transaction were debited to the customer's account.

      Read only.

    • status_details

      object

      The details of the refund status.

      Read only.

    • update_time

      string

      The date and time when the transaction was last updated, in Internet date and time format.

      Read only.

    Sample Response

    {
      "id": "1JU08902781691411",
      "amount": {
        "value": "10.99",
        "currency_code": "USD"
      },
      "status": "COMPLETED",
      "note_to_payer": "Defective product",
      "seller_payable_breakdown": {
        "gross_amount": {
          "value": "10.99",
          "currency_code": "USD"
        },
        "paypal_fee": {
          "value": "0",
          "currency_code": "USD"
        },
        "net_amount": {
          "value": "10.99",
          "currency_code": "USD"
        },
        "total_refunded_amount": {
          "value": "10.99",
          "currency_code": "USD"
        }
      },
      "invoice_id": "INVOICE-123",
      "create_time": "2018-09-11T23:24:19Z",
      "update_time": "2018-09-11T23:24:19Z",
      "links": [
        {
          "rel": "self",
          "method": "GET",
          "href": "https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411"
        },
        {
          "rel": "up",
          "method": "GET",
          "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
        }
      ]
    }

    Common object definitions

    account_id

    • account_id

      string

      The account identifier for a PayPal account.

      Minimum length: 13.

      Maximum length: 13.

      Pattern: ^[2-9A-HJ-NP-Z]{13}$.

    activity_timestamps

    address-country_code

    • address-country_code

      string

      The 2-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.

      Minimum length: 2.

      Maximum length: 2.

      Pattern: ^([A-Z]{2}|C2)$.

    address_details

    • building_name

      string

      A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.

      Maximum length: 100.

    • delivery_service

      string

      The delivery service. Post office box, bag number, or post office name.

      Maximum length: 100.

    • street_name

      string

      The street name. Just Drury in Drury Lane.

      Maximum length: 100.

    • street_number

      string

      The street number.

      Maximum length: 100.

    • street_type

      string

      The street type. For example, avenue, boulevard, road, or expressway.

      Maximum length: 100.

    • sub_building

      string

      The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.

      Maximum length: 100.

    address_portable

    • country_code

      string

      required

      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.

      Minimum length: 2.

      Maximum length: 2.

      Pattern: ^([A-Z]{2}|C2)$.

    • address_details

      object

      The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
      For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.

    • address_line_1

      string

      The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

      Maximum length: 300.

    • address_line_2

      string

      The second line of the address. For example, suite or apartment number.

      Maximum length: 300.

    • address_line_3

      string

      The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.

      Maximum length: 100.

    • admin_area_1

      string

      The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:

      • UK. A county.
      • US. A state.
      • Canada. A province.
      • Japan. A prefecture.
      • Switzerland. A kanton.

      Maximum length: 300.

    • admin_area_2

      string

      A city, town, or village. Smaller than admin_area_level_1.

      Maximum length: 120.

    • admin_area_3

      string

      A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:

      • Brazil. Suburb, bairro, or neighborhood.
      • India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.

      Maximum length: 100.

    • admin_area_4

      string

      The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:

      • The postal sorting code for Guernsey and many French territories, such as French Guiana.
      • The fine-grained administrative levels in China.

      Maximum length: 100.

    • postal_code

      string

      The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

      Maximum length: 60.

    address_portable

    • country_code

      string

      required

      The 2-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.

      Minimum length: 2.

      Maximum length: 2.

      Pattern: ^([A-Z]{2}|C2)$.

    • address_details

      object

      The non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.

    • address_line_1

      string

      The first line of the address, such as number and street, for example, 173 Drury Lane. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.

      Maximum length: 300.

    • address_line_2

      string

      The second line of the address, for example, a suite or apartment number.

      Maximum length: 300.

    • address_line_3

      string

      The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.

      Maximum length: 100.

    • admin_area_1

      string

      The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, CA and not California. Value, by country, is:

      • UK. A county.
      • US. A state.
      • Canada. A province.
      • Japan. A prefecture.
      • Switzerland. A kanton.

      Maximum length: 300.

    • admin_area_2

      string

      A city, town, or village. Smaller than admin_area_level_1.

      Maximum length: 120.

    • admin_area_3

      string

      The sub-locality, suburb, neighborhood, or district. This is smaller than admin_area_level_2. Value is:

      • Brazil. Suburb, bairro, or neighborhood.
      • India. Sub-locality or district. Street name information isn't always available, but a sub-locality or district can be a very small area.

      Maximum length: 100.

    • admin_area_4

      string

      The neighborhood, ward, or district. This is smaller than admin_area_level_3 or sub_locality. Value is:

      • The postal sorting code that is used in Guernsey and many French territories, such as French Guiana.
      • The fine-grained administrative levels in China.

      Maximum length: 100.

    • postal_code

      string

      The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

      Maximum length: 60.

    address_portable_postal_code_validation

    • address_portable_postal_code_validation

    address_portable_postal_code_validation

    • address_portable_postal_code_validation

    amount_breakdown

    • discount

      object

      The discount for all items within a given purchase_unit. discount.value can not be a negative number.

    • handling

      object

      The handling fee for all items within a given purchase_unit. handling.value can not be a negative number.

    • insurance

      object

      The insurance fee for all items within a given purchase_unit. insurance.value can not be a negative number.

    • item_total

      object

      The subtotal for all items. Required if the request includes purchase_units[].items[].unit_amount. Must equal the sum of (items[].unit_amount * items[].quantity) for all items. item_total.value can not be a negative number.

    • shipping

      object

      The shipping fee for all items within a given purchase_unit. shipping.value can not be a negative number.

    • shipping_discount

      object

      The shipping discount for all items within a given purchase_unit. shipping_discount.value can not be a negative number.

    • tax_total

      object

      The total tax for all items. Required if the request includes purchase_units.items.tax. Must equal the sum of (items[].tax * items[].quantity) for all items. tax_total.value can not be a negative number.

    apple_pay_decrypted_token_data

    • device_manufacturer_id

      string

      required

      Apple Pay Hex-encoded device manufacturer identifier.

      Minimum length: 1.

      Maximum length: 2000.

    • payment_data

      object

      required

      Apple Pay payment data object which contains the cryptogram, eci_indicator and other data.

    • payment_data_type

      enum

      required

      Indicates the type of payment data passed, in case of Non China the payment data is 3DSECURE and for China it is EMV.

      The possible values are:

      • 3DSECURE. The card was authenticated using 3D Secure (3DS) authentication scheme. While using this value make sure to populate cryptogram and eci_indicator as part of payment data..
      • EMV. The card was authenticated using EMV method, which is applicable for China. While using this value make sure to pass emv_data and pin as part of payment data.

      Minimum length: 1.

      Maximum length: 16.

      Pattern: ^[0-9A-Z_]+$.

    • tokenized_card

      object

      required

      Apple Pay tokenized credit card used to pay.

    • transaction_amount

      object

      required

      The transaction amount for the payment that the payer has approved on apple platform.

    apple_pay_decrypted_token_data.card

    • billing_address

      object

      required

      The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

    • brand

      enum

      The card brand or network. Typically used in the response.

      The possible values are:

      • VISA. Visa card.
      • MASTERCARD. Mastecard card.
      • DISCOVER. Discover card.
      • AMEX. American Express card.
      • SOLO. Solo debit card.
      • JCB. Japan Credit Bureau card.
      • STAR. Military Star card.
      • DELTA. Delta Airlines card.
      • SWITCH. Switch credit card.
      • MAESTRO. Maestro credit card.
      • CB_NATIONALE. Carte Bancaire (CB) credit card.
      • CONFIGOGA. Configoga credit card.
      • CONFIDIS. Confidis credit card.
      • ELECTRON. Visa Electron credit card.
      • CETELEM. Cetelem credit card.
      • CHINA_UNION_PAY. China union pay credit card.
    • card_type

      enum

      The card brand or network. Typically used in the response.

      The possible values are:

      • VISA. Visa card.
      • MASTERCARD. Mastecard card.
      • DISCOVER. Discover card.
      • AMEX. American Express card.
      • SOLO. Solo debit card.
      • JCB. Japan Credit Bureau card.
      • STAR. Military Star card.
      • DELTA. Delta Airlines card.
      • SWITCH. Switch credit card.
      • MAESTRO. Maestro credit card.
      • CB_NATIONALE. Carte Bancaire (CB) credit card.
      • CONFIGOGA. Configoga credit card.
      • CONFIDIS. Confidis credit card.
      • ELECTRON. Visa Electron credit card.
      • CETELEM. Cetelem credit card.
      • CHINA_UNION_PAY. China union pay credit card.

      Read only.

    • expiry

      string

      The card expiration year and month, in Internet date format.

    • name

      string

      The card holder's name as it appears on the card.

      Minimum length: 1.

      Maximum length: 300.

      Pattern: ^.{1,300}$.

    • number

      string

      The primary account number (PAN) for the payment card.

      Minimum length: 13.

      Maximum length: 19.

      Pattern: ^[0-9]{13,19}$.

    • type

      enum

      The payment card type.

      The possible values are:

      • CREDIT. A credit card.
      • DEBIT. A debit card.
      • PREPAID. A Prepaid card.
      • STORE. A store card.
      • UNKNOWN. Card type cannot be determined.

    apple_pay_payment_data

    • cryptogram

      string

      Online payment cryptogram, as defined by 3D Secure.

      Minimum length: 1.

      Maximum length: 2000.

    • eci_indicator

      string

      ECI indicator, as defined by 3- Secure.

      Minimum length: 1.

      Maximum length: 256.

    • emv_data

      string

      Encoded Apple Pay EMV Payment Structure used for payments in China.

      Minimum length: 1.

      Maximum length: 2000.

    • pin

      string

      Bank Key encrypted Apple Pay PIN.

      Minimum length: 1.

      Maximum length: 2000.

    asset_source

    • id

      string

      required

      Instrument Id for the asset.

      Minimum length: 1.

      Maximum length: 18.

      Pattern: ^([a-zA-Z]){2}-([0-9]){18}.

    • symbol

      enum

      required

      The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.

      The possible values are:

      • BTC. The ticker symbol for Bitcoin. https://en.wikipedia.org/wiki/Bitcoin.
      • ETH. The ticker symbol for Ethereum. https://en.wikipedia.org/wiki/Ethereum.
      • BCH. The ticker symbol for Bitcoin Cash. https://en.wikipedia.org/wiki/Bitcoin_Cash.
      • LTC. The ticker symbol for Litecoin. https://en.wikipedia.org/wiki/Litecoin.

      Minimum length: 1.

      Maximum length: 10.

      Pattern: ^[0-9A-Za-z]{1,10}$.

    authorization

      • supplementary_data

        object

        An object that provides supplementary/additional data related to a payment transaction.

      authorization

      • status

        string

        The status for the authorized payment.

      • status_details

        object

        The details of the authorized order pending status.

      • amount

        object

        The amount for this authorized payment.

      • custom_id

        string

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

        Maximum length: 127.

      • expiration_time

        string

        The date and time when the authorized payment expires, in Internet date and time format.

        Minimum length: 20.

        Maximum length: 64.

        Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

      • id

        string

        The PayPal-generated ID for the authorized payment.

      • invoice_id

        string

        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.

      • links

        array (contains the link_description object)

        An array of related HATEOAS links.

      • seller_protection

        object

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

      authorization_status

      • status

        enum

        The status for the authorized payment.

        The possible values are:

        • CREATED. The authorized payment is created. No captured payments have been made for this authorized payment.
        • CAPTURED. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.
        • DENIED. PayPal cannot authorize funds for this authorized payment.
        • EXPIRED. The authorized payment has expired.
        • PARTIALLY_CAPTURED. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.
        • VOIDED. The authorized payment was voided. No more captured payments can be made against this authorized payment.
        • PENDING. The created authorization is in pending state. For more information, see status.details.

        Read only.

      • status_details

        object

        The details of the authorized order pending status.

        Read only.

      authorization_status_details

      • reason

        enum

        The reason why the authorized status is PENDING.

        The possible values are:

        • PENDING_REVIEW. Authorization is pending manual review.

        Minimum length: 1.

        Maximum length: 24.

        Pattern: ^[A-Z_]+$.

      bancontact_request

      • country_code

        string

        required

        The two-character ISO 3166-1 country code.

      • name

        string

        required

        The name of the account holder associated with this payment method.

      bic

      • bic

        string

        The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.

        Minimum length: 8.

        Maximum length: 11.

      blik_request

      • country_code

        string

        required

        The two-character ISO 3166-1 country code.

      • name

        string

        required

        The name of the account holder associated with this payment method.

      • email

        string

        The email address of the account holder associated with this payment method.

      capture

        • supplementary_data

          object

          An object that provides supplementary/additional data related to a payment transaction.

        capture

        • status

          string

          The status of the captured payment.

        • status_details

          object

          The details of the captured payment status.

        • amount

          object

          The amount for this captured payment.

        • custom_id

          string

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

          Maximum length: 127.

        • disbursement_mode

          string

          The funds that are held on behalf of the merchant.

        • final_capture

          boolean

          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.

        • id

          string

          The PayPal-generated ID for the captured payment.

        • invoice_id

          string

          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.

        • links

          array (contains the link_description object)

          An array of related HATEOAS links.

        • processor_response

          object

          An object that provides additional processor information for a direct credit card transaction.

        • seller_protection

          object

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

        • seller_receivable_breakdown

          object

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

        capture_request

        • invoice_id

          string

          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.

          Minimum length: 1.

          Maximum length: 127.

          Pattern: ^.{1,127}$.

        • note_to_payer

          string

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

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^.{1,255}$.

        • amount

          object

          The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.

        • final_capture

          boolean

          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.

        • invoice_id

          string

          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.

          Maximum length: 127.

        • note_to_payer

          string

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

          Maximum length: 255.

        • payment_instruction

          object

          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

          The payment descriptor on the payer's account statement.

          Maximum length: 22.

        capture_status

        • status

          enum

          The status of the captured payment.

          The possible values are:

          • COMPLETED. The funds for this captured payment were credited to the payee's PayPal account.
          • DECLINED. The funds could not be captured.
          • PARTIALLY_REFUNDED. An amount less than this captured payment's amount was partially refunded to the payer.
          • PENDING. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.
          • REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
          • FAILED. There was an error while capturing payment.

          Read only.

        • status_details

          object

          The details of the captured payment status.

          Read only.

        capture_status_details

        • reason

          enum

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

          The possible values are:

          • BUYER_COMPLAINT. The payer initiated a dispute for this captured payment with PayPal.
          • CHARGEBACK. The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.
          • ECHECK. The payer paid by an eCheck that has not yet cleared.
          • INTERNATIONAL_WITHDRAWAL. Visit your online account. In your **Account Overview**, accept and deny this payment.
          • OTHER. No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.
          • PENDING_REVIEW. The captured payment is pending manual review.
          • RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION. The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.
          • REFUNDED. The captured funds were refunded.
          • TRANSACTION_APPROVED_AWAITING_FUNDING. The payer must send the funds for this captured payment. This code generally appears for manual EFTs.
          • UNILATERAL. The payee does not have a PayPal account.
          • VERIFICATION_REQUIRED. The payee's PayPal account is not verified.

          Minimum length: 1.

          Maximum length: 64.

          Pattern: ^[A-Z_]+$.

        card

        • billing_address

          object

          The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

        • brand

          enum

          The card brand or network. Typically used in the response.

          The possible values are:

          • VISA. Visa card.
          • MASTERCARD. Mastecard card.
          • DISCOVER. Discover card.
          • AMEX. American Express card.
          • SOLO. Solo debit card.
          • JCB. Japan Credit Bureau card.
          • STAR. Military Star card.
          • DELTA. Delta Airlines card.
          • SWITCH. Switch credit card.
          • MAESTRO. Maestro credit card.
          • CB_NATIONALE. Carte Bancaire (CB) credit card.
          • CONFIGOGA. Configoga credit card.
          • CONFIDIS. Confidis credit card.
          • ELECTRON. Visa Electron credit card.
          • CETELEM. Cetelem credit card.
          • CHINA_UNION_PAY. China union pay credit card.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[A-Z_]+$.

        • card_type

          enum

          The card brand or network. Typically used in the response.

          The possible values are:

          • VISA. Visa card.
          • MASTERCARD. Mastecard card.
          • DISCOVER. Discover card.
          • AMEX. American Express card.
          • SOLO. Solo debit card.
          • JCB. Japan Credit Bureau card.
          • STAR. Military Star card.
          • DELTA. Delta Airlines card.
          • SWITCH. Switch credit card.
          • MAESTRO. Maestro credit card.
          • CB_NATIONALE. Carte Bancaire (CB) credit card.
          • CONFIGOGA. Configoga credit card.
          • CONFIDIS. Confidis credit card.
          • ELECTRON. Visa Electron credit card.
          • CETELEM. Cetelem credit card.
          • CHINA_UNION_PAY. China union pay credit card.

          Read only.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[A-Z_]+$.

        • expiry

          string

          The card expiration year and month, in Internet date format.

          Minimum length: 7.

          Maximum length: 7.

          Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.

        • The PayPal-generated ID for the card.

          Read only.

          Minimum length: 1.

          Maximum length: 256.

          Pattern: ^[A-Za-z0-9-_.+=]+$.

        • last_digits

          string

          The last digits of the payment card.

          Read only.

          Minimum length: 2.

          Maximum length: 4.

          Pattern: ^[0-9]{2,4}$.

        • name

          string

          The card holder's name as it appears on the card.

          Minimum length: 1.

          Maximum length: 300.

          Pattern: ^.{1,300}$.

        • number

          string

          The primary account number (PAN) for the payment card.

          Minimum length: 13.

          Maximum length: 19.

          Pattern: ^[0-9]{13,19}$.

        • security_code

          string

          The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when payment_initiator=MERCHANT.

          Minimum length: 3.

          Maximum length: 4.

          Pattern: ^[0-9]{3,4}$.

        • type

          enum

          The payment card type.

          The possible values are:

          • CREDIT. A credit card.
          • DEBIT. A debit card.
          • PREPAID. A Prepaid card.
          • STORE. A store card.
          • UNKNOWN. Card type cannot be determined.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[A-Z_]+$.

        card

        • billing_address

          object

          The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

        • expiry

          string

          The card expiration year and month, in Internet date format.

        • name

          The card holder's name as it appears on the card.

          Minimum length: 1.

          Maximum length: 300.

          Pattern: ^.{1,300}$.

        • number

          The primary account number (PAN) for the payment card.

          Minimum length: 13.

          Maximum length: 19.

          Pattern: ^[0-9]{13,19}$.

        • security_code

          The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when payment_initiator=MERCHANT.

          Minimum length: 3.

          Maximum length: 4.

          Pattern: ^[0-9]{3,4}$.

        card

        • billing_address

          object

          The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

        • brand

          enum

          The card brand or network. Typically used in the response.

          The possible values are:

          • VISA. Visa card.
          • MASTERCARD. Mastecard card.
          • DISCOVER. Discover card.
          • AMEX. American Express card.
          • SOLO. Solo debit card.
          • JCB. Japan Credit Bureau card.
          • STAR. Military Star card.
          • DELTA. Delta Airlines card.
          • SWITCH. Switch credit card.
          • MAESTRO. Maestro credit card.
          • CB_NATIONALE. Carte Bancaire (CB) credit card.
          • CONFIGOGA. Configoga credit card.
          • CONFIDIS. Confidis credit card.
          • ELECTRON. Visa Electron credit card.
          • CETELEM. Cetelem credit card.
          • CHINA_UNION_PAY. China union pay credit card.
        • card_type

          enum

          The card brand or network. Typically used in the response.

          The possible values are:

          • VISA. Visa card.
          • MASTERCARD. Mastecard card.
          • DISCOVER. Discover card.
          • AMEX. American Express card.
          • SOLO. Solo debit card.
          • JCB. Japan Credit Bureau card.
          • STAR. Military Star card.
          • DELTA. Delta Airlines card.
          • SWITCH. Switch credit card.
          • MAESTRO. Maestro credit card.
          • CB_NATIONALE. Carte Bancaire (CB) credit card.
          • CONFIGOGA. Configoga credit card.
          • CONFIDIS. Confidis credit card.
          • ELECTRON. Visa Electron credit card.
          • CETELEM. Cetelem credit card.
          • CHINA_UNION_PAY. China union pay credit card.

          Read only.

        • expiry

          string

          The card expiration year and month, in Internet date format.

        • name

          string

          The card holder's name as it appears on the card.

          Minimum length: 1.

          Maximum length: 300.

          Pattern: ^.{1,300}$.

        • number

          string

          The primary account number (PAN) for the payment card.

          Minimum length: 13.

          Maximum length: 19.

          Pattern: ^[0-9]{13,19}$.

        • type

          enum

          The payment card type.

          The possible values are:

          • CREDIT. A credit card.
          • DEBIT. A debit card.
          • PREPAID. A Prepaid card.
          • STORE. A store card.
          • UNKNOWN. Card type cannot be determined.

        card.address_portable

        • country_code

          string

          required

          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.

        • address_line_1

          string

          The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

          Maximum length: 300.

        • address_line_2

          string

          The second line of the address. For example, suite or apartment number.

          Maximum length: 300.

        • admin_area_1

          string

          The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:

          • UK. A county.
          • US. A state.
          • Canada. A province.
          • Japan. A prefecture.
          • Switzerland. A kanton.

          Maximum length: 300.

        • admin_area_2

          string

          A city, town, or village. Smaller than admin_area_level_1.

          Maximum length: 120.

        • postal_code

          string

          The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

          Maximum length: 60.

        card.address_portable

        • country_code

          string

          required

          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.

        • address_line_1

          string

          The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

          Maximum length: 300.

        • address_line_2

          string

          The second line of the address. For example, suite or apartment number.

          Maximum length: 300.

        • admin_area_1

          string

          The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:

          • UK. A county.
          • US. A state.
          • Canada. A province.
          • Japan. A prefecture.
          • Switzerland. A kanton.

          Maximum length: 300.

        • admin_area_2

          string

          A city, town, or village. Smaller than admin_area_level_1.

          Maximum length: 120.

        • postal_code

          string

          The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

          Maximum length: 60.

        card_brand

        • card_brand

          enum

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

          The possible values are:

          • VISA. Visa card.
          • MASTERCARD. Mastecard card.
          • DISCOVER. Discover card.
          • AMEX. American Express card.
          • SOLO. Solo debit card.
          • JCB. Japan Credit Bureau card.
          • STAR. Military Star card.
          • DELTA. Delta Airlines card.
          • SWITCH. Switch credit card.
          • MAESTRO. Maestro credit card.
          • CB_NATIONALE. Carte Bancaire (CB) credit card.
          • CONFIGOGA. Configoga credit card.
          • CONFIDIS. Confidis credit card.
          • ELECTRON. Visa Electron credit card.
          • CETELEM. Cetelem credit card.
          • CHINA_UNION_PAY. China union pay credit card.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[A-Z_]+$.

        card_request

        • billing_address

          object

          The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

        • expiry

          string

          The card expiration year and month, in Internet date format.

        • name

          The card holder's name as it appears on the card.

          Minimum length: 1.

          Maximum length: 300.

          Pattern: ^.{1,300}$.

        • number

          The primary account number (PAN) for the payment card.

          Minimum length: 13.

          Maximum length: 19.

          Pattern: ^[0-9]{13,19}$.

        • security_code

          The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when payment_initiator=MERCHANT.

          Minimum length: 3.

          Maximum length: 4.

          Pattern: ^[0-9]{3,4}$.

        • stored_credential

          object

          Provides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
          Parameter compatibility:

          • payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
          • usage=FIRST is compatible only with payment_initiator=CUSTOMER.
          • previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
          • Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.

        • vault_id

          string

          The PayPal-generated ID for the saved card payment source. Typically stored on the merchant's server.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9a-zA-Z_-]+$.

        card_stored_credential

        • payment_initiator

          enum

          required

          The person or party who initiated or triggered the payment.

          The possible values are:

          • CUSTOMER. Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website.
          • MERCHANT. Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Z_]+$.

        • payment_type

          enum

          required

          Indicates the type of the stored payment_source payment.

          The possible values are:

          • ONE_TIME. One Time payment such as online purchase or donation. (e.g. Checkout with one-click).
          • RECURRING. Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments).
          • UNSCHEDULED. Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments).

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Z_]+$.

        • previous_network_transaction_reference

          object

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

        • usage

          enum

          Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

          The possible values are:

          • FIRST. Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment.
          • SUBSEQUENT. Indicates a payment using a stored payment_source which has been successfully used previously for a payment.
          • DERIVED. Indicates that PayPal will derive the value of `FIRST` or `SUBSEQUENT` based on data available to PayPal.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Z_]+$.

        card_type

        • card_type

          enum

          Type of card. i.e Credit, Debit and so on.

          The possible values are:

          • CREDIT. A credit card.
          • DEBIT. A debit card.
          • PREPAID. A Prepaid card.
          • STORE. A store card.
          • UNKNOWN. Card type cannot be determined.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[A-Z_]+$.

        country_code

        • country_code

          string

          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.

          Minimum length: 2.

          Maximum length: 2.

          Pattern: ^([A-Z]{2}|C2)$.

        country_code

        • country_code

          string

          The 2-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.

          Minimum length: 2.

          Maximum length: 2.

          Pattern: ^([A-Z]{2}|C2)$.

        cryptocurrency_symbol

        • cryptocurrency_symbol

          enum

          The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.

          The possible values are:

          • BTC. The ticker symbol for Bitcoin. https://en.wikipedia.org/wiki/Bitcoin.
          • ETH. The ticker symbol for Ethereum. https://en.wikipedia.org/wiki/Ethereum.
          • BCH. The ticker symbol for Bitcoin Cash. https://en.wikipedia.org/wiki/Bitcoin_Cash.
          • LTC. The ticker symbol for Litecoin. https://en.wikipedia.org/wiki/Litecoin.

          Minimum length: 1.

          Maximum length: 10.

          Pattern: ^[0-9A-Za-z]{1,10}$.

        currency_code

        currency_code

        customer_service_instructions

        • customer_service_instructions

          string

          The contact address for the merchant's customer service.

          Maximum length: 256.

        date_no_time

        • date_no_time

          string

          The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

          Minimum length: 10.

          Maximum length: 10.

          Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

        date_no_time

        • date_no_time

          string

          The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

          Minimum length: 10.

          Maximum length: 10.

          Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$.

        date_time

        • date_time

          string

          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.

          Minimum length: 20.

          Maximum length: 64.

          Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

        date_year_month

        • date_year_month

          string

          The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.

          Minimum length: 7.

          Maximum length: 7.

          Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.

        disbursement_mode

        • disbursement_mode

          enum

          The funds that are held on behalf of the merchant.

          The possible values are:

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

          Minimum length: 1.

          Maximum length: 16.

          Pattern: ^[A-Z_]+$.

        dispute_category

        • dispute_category

          enum

          The condition that is covered for the transaction.

          The possible values are:

          • ITEM_NOT_RECEIVED. The payer paid for an item that they did not receive.
          • UNAUTHORIZED_TRANSACTION. The payer did not authorize the payment.

        email

        • email

          string

          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.

          Maximum length: 254.

          Pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).

        email_address

        • email_address

          string

          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.

          Minimum length: 3.

          Maximum length: 254.

          Pattern: ^.+@[^"\-].+$.

        email_address

        • email_address

          string

          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.

          Minimum length: 3.

          Maximum length: 254.

          Pattern: ^.+@[^"\-].+$.

        eps_request

        • country_code

          string

          required

          The two-character ISO 3166-1 country code.

        • name

          string

          required

          The name of the account holder associated with this payment method.

        error

        • debug_id

          string

          required

          The PayPal internal ID. Used for correlation purposes.

        • message

          string

          required

          The message that describes the error.

        • name

          string

          required

          The human-readable, unique name of the error.

        • details

          array (contains the error_details object)

          An array of additional details about the error.

        • information_link

          string

          The information link, or URI, that shows detailed information about this error for the developer.

          Read only.

        • links

          array (contains the link_description object)

          An array of request-related HATEOAS links.

          Read only.

        error_details

        • issue

          string

          required

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

        • description

          string

          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

          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.

        • location

          string

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

        • value

          string

          The value of the field that caused the error.

        exchange_rate

        • source_currency

          string

          The source currency from which to convert an amount.

        • target_currency

          string

          The target currency to which to convert an amount.

        • value

          string

          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.

        experience_context_base

        • brand_name

          string

          The label that overrides the business name in the PayPal account on the PayPal site.

          Minimum length: 1.

          Maximum length: 127.

        • cancel_url

          string

          The URL where the customer is redirected after the customer cancels the payment.

        • locale

          string

          The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.

        • return_url

          string

          The URL where the customer is redirected after the customer approves the payment.

        • shipping_preference

          enum

          The location from which the shipping address is derived.

          The possible values are:

          • GET_FROM_FILE. Get the customer-provided shipping address on the PayPal site.
          • NO_SHIPPING. Redacts the shipping address from the PayPal site. Recommended for digital goods.
          • SET_PROVIDED_ADDRESS. Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages.

          Minimum length: 1.

          Maximum length: 24.

          Pattern: ^[A-Z_]+$.

        financial_instrument-common-instrument_id

        • financial_instrument-common-instrument_id

          string

          The identifier of the instrument.

          Minimum length: 1.

          Maximum length: 256.

          Pattern: ^[A-Za-z0-9-_.+=]+$.

        financial_instrument-common-url

        • financial_instrument-common-url

          string

          Describes the URL.

        giropay_request

        • country_code

          string

          required

          The two-character ISO 3166-1 country code.

        • name

          string

          required

          The name of the account holder associated with this payment method.

        ideal_request

        • country_code

          string

          required

          The two-character ISO 3166-1 country code.

        • name

          string

          required

          The name of the account holder associated with this payment method.

        • The bank identification code (BIC).

          Minimum length: 8.

          Maximum length: 11.

        language

        merchant_partner_customer_id

        • merchant_partner_customer_id

          string

          The unique ID for a customer generated by PayPal.

          Minimum length: 1.

          Maximum length: 22.

          Pattern: ^[0-9a-zA-Z_-]+$.

        money

        • currency_code

          string

          required

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

          Minimum length: 3.

          Maximum length: 3.

        • value

          string

          required

          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.

          Maximum length: 32.

          Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

        money

        • currency_code

          string

          required

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

          Minimum length: 3.

          Maximum length: 3.

        • value

          string

          required

          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.

          Maximum length: 32.

          Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

        mybank_request

        • country_code

          string

          required

          The two-character ISO 3166-1 country code.

        • name

          string

          required

          The name of the account holder associated with this payment method.

        name

        • full_name

          string

          When the party is a person, the party's full name.

          Maximum length: 300.

        • given_name

          string

          When the party is a person, the party's given, or first, name.

          Maximum length: 140.

        • middle_name

          string

          When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.

          Maximum length: 140.

        • prefix

          string

          The prefix, or title, to the party's name.

          Maximum length: 140.

        • suffix

          string

          The suffix for the party's name.

          Maximum length: 140.

        • surname

          string

          When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

          Maximum length: 140.

        name

        • alternate_full_name

          string

          DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.

          Maximum length: 300.

        • full_name

          string

          When the party is a person, the party's full name.

          Maximum length: 300.

        • given_name

          string

          When the party is a person, the party's given, or first, name.

          Maximum length: 140.

        • middle_name

          string

          When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.

          Maximum length: 140.

        • prefix

          string

          The prefix, or title, to the party's name.

          Maximum length: 140.

        • suffix

          string

          The suffix for the party's name.

          Maximum length: 140.

        • surname

          string

          When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

          Maximum length: 140.

        name

        • name

          string

          The full name representation like Mr J Smith.

          Minimum length: 3.

          Maximum length: 300.

        name_validation

        • name_validation

        name_validation

        • name_validation

        net_amount_breakdown

        • converted_amount

          object

          The converted payable amount.

          Read only.

        • exchange_rate

          object

          The exchange rate that determines the amount that was debited from the merchant's PayPal account.

          Read only.

        • payable_amount

          object

          The net amount debited from the merchant's PayPal account.

          Read only.

        network_transaction_reference

        • id

          string

          required

          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.

          Minimum length: 9.

          Maximum length: 15.

          Pattern: ^[a-zA-Z0-9]+$.

        • network

          enum

          required

          Name of the card network through which the transaction was routed.

          The possible values are:

          • VISA. Visa card.
          • MASTERCARD. Mastecard card.
          • DISCOVER. Discover card.
          • AMEX. American Express card.
          • SOLO. Solo debit card.
          • JCB. Japan Credit Bureau card.
          • STAR. Military Star card.
          • DELTA. Delta Airlines card.
          • SWITCH. Switch credit card.
          • MAESTRO. Maestro credit card.
          • CB_NATIONALE. Carte Bancaire (CB) credit card.
          • CONFIGOGA. Configoga credit card.
          • CONFIDIS. Confidis credit card.
          • ELECTRON. Visa Electron credit card.
          • CETELEM. Cetelem credit card.
          • CHINA_UNION_PAY. China union pay credit card.
        • date

          string

          The date that the transaction was authorized by the scheme. For MasterCard, this is the "BankNet reference date" field in response.

          Minimum length: 4.

          Maximum length: 4.

          Pattern: ^[0-9]+$.

        nrp-nrr_attributes

        • invoice_id

          string

          The API caller-provided external invoice number for the order. It appears in the payer's transaction history.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Za-z-]+$.

        • pos_details

          object

          The API caller-provided information about the store. It is supported only for Point of Sale transactions.

        nrp-nrr_experience_context

        • note

          string

          Custom memo about the transaction.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Za-z ]+$.

        • refund_source_preference

          enum

          Indicates merchant's preference of the payment methods to fund the transaction.

          The possible values are:

          • ANY. The merchant does not have a preference. Use any available funding source.
          • INSTANT. Use the merchant's balance as the funding source.
          • ECHECK. The merchant prefers using the eCheck funding source. If the merchant's PayPal balance can cover the refund amount, use the PayPal balance.

          Minimum length: 1.

          Maximum length: 20.

          Pattern: ^[A-Z]+$.

        p24_request

        • country_code

          string

          required

          The two-character ISO 3166-1 country code.

        • email

          string

          required

          The email address of the account holder associated with this payment method.

        • name

          string

          required

          The name of the account holder associated with this payment method.

        patch

        • op

          enum

          required

          The operation.

          The possible values are:

          • add. Depending on the target location reference, completes one of these functions:
            • The target location is an array index. Inserts a new value into the array at the specified index.
            • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
            • The target location is an object parameter that does exist. Replaces that parameter's value.
            The value parameter defines the value to add. For more information, see 4.1. add.
          • remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
          • replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
          • move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
          • copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.
          • test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
            TypeConsidered equal if both values
            stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
            numbersAre numerically equal.
            arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
            objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
            literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
            For more information, see 4.6. test.
        • from

          string

          The JSON Pointer to the target document location from which to move the value. Required for the move operation.

        • path

          string

          The JSON Pointer to the target document location at which to complete the operation.

        • value

          number,integer,string,boolean,null,array,object

          The value to apply. The remove operation does not require a value.

        patch_request

        • patch_request

          array (contains the patch object)

          An array of JSON patch objects to apply partial updates to resources.

        pay_upon_invoice_experience_context

        • brand_name

          string

          The label that overrides the business name in the PayPal account on the PayPal site.

          Minimum length: 1.

          Maximum length: 127.

        • cancel_url

          string

          The URL where the customer is redirected after the customer cancels the payment.

        • locale

          string

          The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.

        • return_url

          string

          The URL where the customer is redirected after the customer approves the payment.

        • shipping_preference

          string

          The location from which the shipping address is derived.

          Minimum length: 1.

          Maximum length: 24.

          Pattern: ^[A-Z_]+$.

        • customer_service_instructions

          array (contains the customer_service_instructions object)

          The payee's customer service contact instructions provided to the payer.

        • logo_url

          string

          The URL to the logo of the payment method.

        payee_base

        • email_address

          string

          The email address of merchant.

        • merchant_id

          string

          The encrypted PayPal account ID of the merchant.

          Minimum length: 13.

          Maximum length: 13.

          Pattern: ^[2-9A-HJ-NP-Z]{13}$.

        payment_initiator

        • payment_initiator

          enum

          The person or party who initiated or triggered the payment.

          The possible values are:

          • CUSTOMER. Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website.
          • MERCHANT. Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Z_]+$.

        payment_instruction

        • disbursement_mode

          enum

          The funds that are held payee by the marketplace/platform. This field is only applicable to merchants that been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability.

          The possible values are:

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

          Minimum length: 1.

          Maximum length: 16.

          Pattern: ^[A-Z_]+$.

        • payee_pricing_tier_id

          string

          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.

          Minimum length: 1.

          Maximum length: 20.

        • payee_receivable_fx_rate_id

          string

          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.

          Minimum length: 1.

          Maximum length: 4000.

        • platform_fees

          array (contains the platform_fee object)

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

        payment_instruction

        • platform_fees

          array (contains the platform_fee object)

          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.

        phone

        • country_code

          string

          required

          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).

          Minimum length: 1.

          Maximum length: 3.

          Pattern: ^[0-9]{1,3}?$.

        • national_number

          string

          required

          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).

          Minimum length: 1.

          Maximum length: 14.

          Pattern: ^[0-9]{1,14}?$.

        • extension_number

          string

          The extension number.

          Minimum length: 1.

          Maximum length: 15.

          Pattern: ^[0-9]{1,15}?$.

        phone

        • country_code

          string

          required

          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).

          Minimum length: 1.

          Maximum length: 3.

          Pattern: ^[0-9]{1,3}?$.

        • national_number

          string

          required

          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).

          Minimum length: 1.

          Maximum length: 14.

          Pattern: ^[0-9]{1,14}?$.

        • extension_number

          string

          The extension number.

          Minimum length: 1.

          Maximum length: 15.

          Pattern: ^[0-9]{1,15}?$.

        platform_fee

        • amount

          object

          required

          The fee for this transaction.

        • payee

          object

          The recipient of the fee for this transaction. If you omit this value, the default is the API caller.

        platform_fee

        • amount

          object

          required

          The fee for this transaction.

        point_of_sale

        • store_id

          string

          The API caller-provided external store identification number.

          Minimum length: 1.

          Maximum length: 50.

          Pattern: ^[A-Za-z0-9-]{1,50}$.

        • terminal_id

          string

          The API caller-provided external terminal identification number.

          Minimum length: 1.

          Maximum length: 50.

          Pattern: ^[A-Za-z0-9-]{1,50}$.

        processor_response

        • avs_code

          enum

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

          The possible values are:

          • A. For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct.
          • B. For Visa, Mastercard, or Discover transactions, the address matches. International A.
          • C. For Visa, Mastercard, or Discover transactions, no values match. International N.
          • D. For Visa, Mastercard, or Discover transactions, the address and postal code match. International X.
          • E. For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match.
          • F. For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches.
          • G. For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches.
          • I. For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable.
          • M. For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match.
          • N. For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect.
          • P. For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only.
          • R. For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable.
          • S. For Visa, Mastercard, Discover, or American Express, the service is not supported.
          • U. For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available.
          • W. For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.
          • X. For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.
          • Y. For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct.
          • Z. For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct.
          • Null. For Maestro, no AVS response was obtained.
          • 0. For Maestro, all address information matches.
          • 1. For Maestro, none of the address information matches.
          • 2. For Maestro, part of the address information matches.
          • 3. For Maestro, the merchant did not provide AVS information. It was not processed.
          • 4. For Maestro, the address was not checked or the acquirer had no response. The service is not available.

          Read only.

        • cvv_code

          enum

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

          The possible values are:

          • E. For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response.
          • I. For Visa, Mastercard, Discover, or American Express, invalid or null.
          • M. For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches.
          • N. For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match.
          • P. For Visa, Mastercard, Discover, or American Express, it was not processed.
          • S. For Visa, Mastercard, Discover, or American Express, the service is not supported.
          • U. For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified.
          • X. For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available.
          • All others. For Visa, Mastercard, Discover, or American Express, error.
          • 0. For Maestro, the CVV2 matched.
          • 1. For Maestro, the CVV2 did not match.
          • 2. For Maestro, the merchant has not implemented CVV2 code handling.
          • 3. For Maestro, the merchant has indicated that CVV2 is not present on card.
          • 4. For Maestro, the service is not available.

          Read only.

        • payment_advice_code

          enum

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

          The possible values are:

          • 01. For Mastercard, expired card account upgrade or portfolio sale conversion. Obtain new account information before next billing cycle.
          • 02. For Mastercard, over credit limit or insufficient funds. Retry the transaction 72 hours later. For Visa, the card holder wants to stop only one specific payment in the recurring payment relationship. The merchant must NOT resubmit the same transaction. The merchant can continue the billing process in the subsequent billing period.
          • 03. For Mastercard, account closed as fraudulent. Obtain another type of payment from customer due to account being closed or fraud. Possible reason: Account closed as fraudulent. For Visa, the card holder wants to stop all recurring payment transactions for a specific merchant. Stop recurring payment requests.
          • 21. For Mastercard, the card holder has been unsuccessful at canceling recurring payment through merchant. Stop recurring payment requests. For Visa, all recurring payments were canceled for the card number requested. Stop recurring payment requests.

          Read only.

        • response_code

          enum

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

          The possible values are:

          • 0000. APPROVED.
          • 00N7. CVV2_FAILURE_POSSIBLE_RETRY_WITH_CVV.
          • 0100. REFERRAL.
          • 0390. ACCOUNT_NOT_FOUND.
          • 0500. DO_NOT_HONOR.
          • 0580. UNAUTHORIZED_TRANSACTION.
          • 0800. BAD_RESPONSE_REVERSAL_REQUIRED.
          • 0880. CRYPTOGRAPHIC_FAILURE.
          • 0R00. CANCELLED_PAYMENT.
          • 1000. PARTIAL_AUTHORIZATION.
          • 10BR. ISSUER_REJECTED.
          • 1300. INVALID_DATA_FORMAT.
          • 1310. INVALID_AMOUNT.
          • 1312. INVALID_TRANSACTION_CARD_ISSUER_ACQUIRER.
          • 1317. INVALID_CAPTURE_DATE.
          • 1320. INVALID_CURRENCY_CODE.
          • 1330. INVALID_ACCOUNT.
          • 1335. INVALID_ACCOUNT_RECURRING.
          • 1340. INVALID_TERMINAL.
          • 1350. INVALID_MERCHANT.
          • 1360. BAD_PROCESSING_CODE.
          • 1370. INVALID_MCC.
          • 1380. INVALID_EXPIRATION.
          • 1382. INVALID_CARD_VERIFICATION_VALUE.
          • 1384. INVALID_LIFE_CYCLE_OF_TRANSACTION.
          • 1390. INVALID_ORDER.
          • 1393. TRANSACTION_CANNOT_BE_COMPLETED.
          • 5100. GENERIC_DECLINE.
          • 5110. CVV2_FAILURE.
          • 5120. INSUFFICIENT_FUNDS.
          • 5130. INVALID_PIN.
          • 5135. DECLINED_PIN_TRY_EXCEEDED.
          • 5140. CARD_CLOSED.
          • 5150. PICKUP_CARD_SPECIAL_CONDITIONS. Try using another card. Do not retry the same card.
          • 5160. UNAUTHORIZED_USER.
          • 5170. AVS_FAILURE.
          • 5180. INVALID_OR_RESTRICTED_CARD. Try using another card. Do not retry the same card.
          • 5190. SOFT_AVS.
          • 5200. DUPLICATE_TRANSACTION.
          • 5210. INVALID_TRANSACTION.
          • 5400. EXPIRED_CARD.
          • 5500. INCORRECT_PIN_REENTER.
          • 5650. DECLINED_SCA_REQUIRED.
          • 5700. TRANSACTION_NOT_PERMITTED. Outside of scope of accepted business.
          • 5710. TX_ATTEMPTS_EXCEED_LIMIT.
          • 5800. REVERSAL_REJECTED.
          • 5900. INVALID_ISSUE.
          • 5910. ISSUER_NOT_AVAILABLE_NOT_RETRIABLE.
          • 5920. ISSUER_NOT_AVAILABLE_RETRIABLE.
          • 5930. CARD_NOT_ACTIVATED.
          • 6300. ACCOUNT_NOT_ON_FILE.
          • 7600. APPROVED_NON_CAPTURE.
          • 7700. ERROR_3DS.
          • 7710. AUTHENTICATION_FAILED.
          • 7800. BIN_ERROR.
          • 7900. PIN_ERROR.
          • 8000. PROCESSOR_SYSTEM_ERROR.
          • 8010. HOST_KEY_ERROR.
          • 8020. CONFIGURATION_ERROR.
          • 8030. UNSUPPORTED_OPERATION.
          • 8100. FATAL_COMMUNICATION_ERROR.
          • 8110. RETRIABLE_COMMUNICATION_ERROR.
          • 8220. SYSTEM_UNAVAILABLE.
          • 9100. DECLINED_PLEASE_RETRY. Retry.
          • 9500. SUSPECTED_FRAUD. Try using another card. Do not retry the same card.
          • 9510. SECURITY_VIOLATION.
          • 9520. LOST_OR_STOLEN. Try using another card. Do not retry the same card.
          • 9530. HOLD_CALL_CENTER. The merchant must call the number on the back of the card. POS scenario.
          • 9540. REFUSED_CARD.
          • 9600. UNRECOGNIZED_RESPONSE_CODE.
          • PCNR. CONTINGENCIES_NOT_RESOLVED.
          • PCVV. CVV_FAILURE.
          • PPAD. BILLING_ADDRESS.
          • PPAE. AMEX_DISABLED.
          • PPAG. ADULT_GAMING_UNSUPPORTED.
          • PPAI. AMOUNT_INCOMPATIBLE.
          • PPAR. AUTH_RESULT.
          • PPAU. MCC_CODE.
          • PPAV. ARC_AVS.
          • PPAX. AMOUNT_EXCEEDED.
          • PPBG. BAD_GAMING.
          • PPC2. ARC_CVV.
          • PPCE. CE_REGISTRATION_INCOMPLETE.
          • PPCO. COUNTRY.
          • PPCR. CREDIT_ERROR.
          • PPCT. CARD_TYPE_UNSUPPORTED.
          • PPCU. CURRENCY_USED_INVALID.
          • PPD3. SECURE_ERROR_3DS.
          • PPDC. DCC_UNSUPPORTED.
          • PPDI. DINERS_REJECT.
          • PPDV. AUTH_MESSAGE.
          • PPEF. EXPIRED_FUNDING_INSTRUMENT.
          • PPEL. EXCEEDS_FREQUENCY_LIMIT.
          • PPER. INTERNAL_SYSTEM_ERROR.
          • PPEX. EXPIRY_DATE.
          • PPFE. FUNDING_SOURCE_ALREADY_EXISTS.
          • PPFI. INVALID_FUNDING_INSTRUMENT.
          • PPFR. RESTRICTED_FUNDING_INSTRUMENT.
          • PPFV. FIELD_VALIDATION_FAILED.
          • PPGR. GAMING_REFUND_ERROR.
          • PPH1. H1_ERROR.
          • PPIF. IDEMPOTENCY_FAILURE.
          • PPII. INVALID_INPUT_FAILURE.
          • PPIM. ID_MISMATCH.
          • PPIT. INVALID_TRACE_ID.
          • PPLR. LATE_REVERSAL.
          • PPLS. LARGE_STATUS_CODE.
          • PPMB. MISSING_BUSINESS_RULE_OR_DATA.
          • PPMC. BLOCKED_Mastercard.
          • PPMD. PPMD.
          • PPNC. NOT_SUPPORTED_NRC.
          • PPNL. EXCEEDS_NETWORK_FREQUENCY_LIMIT.
          • PPNT. NETWORK_ERROR.
          • PPPH. NO_PHONE_FOR_DCC_TRANSACTION.
          • PPPI. INVALID_PRODUCT.
          • PPPM. INVALID_PAYMENT_METHOD.
          • PPQC. QUASI_CASH_UNSUPPORTED.
          • PPRE. UNSUPPORT_REFUND_ON_PENDING_BC.
          • PPRF. INVALID_PARENT_TRANSACTION_STATUS.
          • PPRR. MERCHANT_NOT_REGISTERED.
          • PPS0. BANKAUTH_ROW_MISMATCH.
          • PPS1. BANKAUTH_ROW_SETTLED.
          • PPS2. BANKAUTH_ROW_VOIDED.
          • PPS3. BANKAUTH_EXPIRED.
          • PPS4. CURRENCY_MISMATCH.
          • PPS5. CREDITCARD_MISMATCH.
          • PPS6. AMOUNT_MISMATCH.
          • PPSC. ARC_SCORE.
          • PPSD. STATUS_DESCRIPTION.
          • PPSE. AMEX_DENIED.
          • PPTE. VERIFICATION_TOKEN_EXPIRED.
          • PPTF. INVALID_TRACE_REFERENCE.
          • PPTI. INVALID_TRANSACTION_ID.
          • PPTR. VERIFICATION_TOKEN_REVOKED.
          • PPTT. TRANSACTION_TYPE_UNSUPPORTED.
          • PPTV. INVALID_VERIFICATION_TOKEN.
          • PPUA. USER_NOT_AUTHORIZED.
          • PPUC. CURRENCY_CODE_UNSUPPORTED.
          • PPUE. UNSUPPORT_ENTITY.
          • PPUI. UNSUPPORT_INSTALLMENT.
          • PPUP. UNSUPPORT_POS_FLAG.
          • PPUR. UNSUPPORTED_REVERSAL.
          • PPVC. VALIDATE_CURRENCY.
          • PPVE. VALIDATION_ERROR.
          • PPVT. VIRTUAL_TERMINAL_UNSUPPORTED.

          Read only.

        reauthorize_request

        • amount

          object

          The amount to reauthorize for an authorized payment.

        refund

        • status

          string

          The status of the refund.

        • status_details

          object

          The details of the refund status.

        • amount

          object

          The amount that the payee refunded to the payer.

        • id

          string

          The PayPal-generated ID for the refund.

        • invoice_id

          string

          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.

        • links

          array (contains the link_description object)

          An array of related HATEOAS links.

        • note_to_payer

          string

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

        • seller_payable_breakdown

          object

          The breakdown of the refund.

        refund_request

        • amount

          object

          The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to captured amount - previous refunds is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured.

        • invoice_id

          string

          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.

          Minimum length: 1.

          Maximum length: 127.

        • note_to_payer

          string

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

          Minimum length: 1.

          Maximum length: 255.

        • payment_instruction

          object

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

        refund_status

        • status

          enum

          The status of the refund.

          The possible values are:

          • CANCELLED. The refund was cancelled.
          • FAILED. The refund could not be processed.
          • PENDING. The refund is pending. For more information, see status_details.reason.
          • COMPLETED. The funds for this transaction were debited to the customer's account.

          Read only.

        • status_details

          object

          The details of the refund status.

          Read only.

        refund_status_details

        • reason

          enum

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

          The possible values are:

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

        seller_payable_breakdown

        • gross_amount

          object

          The amount that the payee refunded to the payer.

          Read only.

        • net_amount

          object

          The net amount that the payee's account is debited in the transaction currency. The net amount is calculated as gross_amount minus paypal_fee minus platform_fees.

          Read only.

        • net_amount_breakdown

          array (contains the net_amount_breakdown object)

          An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds.

          Read only.

        • net_amount_in_receivable_currency

          object

          The net amount that the payee's account is debited in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.

          Read only.

        • paypal_fee

          object

          The PayPal fee that was refunded to the payer in the currency of the transaction. This fee might not match the PayPal fee that the payee paid when the payment was captured.

          Read only.

        • paypal_fee_in_receivable_currency

          object

          The PayPal fee that was refunded to the payer in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.

          Read only.

        • platform_fees

          array (contains the platform_fee object)

          An array of platform or partner fees, commissions, or brokerage fees for the refund.

        • total_refunded_amount

          object

          The total amount refunded from the original capture to date. For example, if a payer makes a $100 purchase and was refunded $20 a week ago and was refunded $30 in this refund, the gross_amount is $30 for this refund and the total_refunded_amount is $50.

        seller_protection

        • dispute_categories

          array (contains the dispute_category object)

          An array of conditions that are covered for the transaction.

          Read only.

        • status

          enum

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

          The possible values are:

          • ELIGIBLE. Your PayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment.
          • PARTIALLY_ELIGIBLE. Your PayPal balance remains intact if the customer claims that they did not receive an item.
          • NOT_ELIGIBLE. This transaction is not eligible for seller protection.

          Read only.

        seller_receivable_breakdown

        • gross_amount

          object

          required

          The amount for this captured payment in the currency of the transaction.

        • exchange_rate

          object

          The exchange rate that determines the amount that is credited to the payee's PayPal account. Returned when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds.

          Read only.

        • net_amount

          object

          The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee minus the platform_fees.

        • paypal_fee

          object

          The applicable fee for this captured payment in the currency of the transaction.

        • paypal_fee_in_receivable_currency

          object

          The applicable fee for this captured payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'.

        • platform_fees

          array (contains the platform_fee object)

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

        • receivable_amount

          object

          The net amount that is credited to the payee's PayPal account. Returned only when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. The amount is computed as net_amount times exchange_rate.

        shipping_type

        • shipping_type

          enum

          The method by which the payer wants to get their items.

          The possible values are:

          • SHIPPING. The payer intends to receive the items at a specified address.
          • PICKUP. The payer intends to pick up the items at a specified address. For example, a store address.

        sofort_request

        • country_code

          string

          required

          The two-character ISO 3166-1 country code.

        • name

          string

          required

          The name of the account holder associated with this payment method.

        stored_payment_source_payment_type

        • stored_payment_source_payment_type

          enum

          Indicates the type of the stored payment_source payment.

          The possible values are:

          • ONE_TIME. One Time payment such as online purchase or donation. (e.g. Checkout with one-click).
          • RECURRING. Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments).
          • UNSCHEDULED. Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments).

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Z_]+$.

        stored_payment_source_usage_type

        • stored_payment_source_usage_type

          enum

          Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

          The possible values are:

          • FIRST. Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment.
          • SUBSEQUENT. Indicates a payment using a stored payment_source which has been successfully used previously for a payment.
          • DERIVED. Indicates that PayPal will derive the value of `FIRST` or `SUBSEQUENT` based on data available to PayPal.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Z_]+$.

        supplementary_data

        • related_ids

          object

          Identifiers related to a specific resource.

          Read only.

        supplementary_purchase_data

        • invoice_id

          string

          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.

          Minimum length: 1.

          Maximum length: 127.

          Pattern: ^.{1,127}$.

        • note_to_payer

          string

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

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^.{1,255}$.

        tax_info

        • tax_id

          string

          required

          The customer's tax ID value.

          Minimum length: 1.

          Maximum length: 14.

        • tax_id_type

          enum

          required

          The customer's tax ID type.

          The possible values are:

          • BR_CPF. The individual tax ID type, typically is 11 characters long.
          • BR_CNPJ. The business tax ID type, typically is 14 characters long.

          Minimum length: 1.

          Maximum length: 14.

        time_duration

        • time_duration

          string

          The ISO-8601-formatted length of time in years, months, weeks, days, hours, minutes, and seconds.

          Note: The format is PyYmMdDThHmMsS. When an amount is zero, you can omit it. Because week cannot co-exist with other time components in ISO-8601 duration, specify P7D. Make provisions to incorporate the effects of daylight savings time.

          For more information, see durations.

          Pattern: ^P([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T([0-9]+H)?([0-9]+M)?([0-9]+S)?)?$.

        token

        • id

          string

          required

          The PayPal-generated ID for the token.

          Minimum length: 1.

          Maximum length: 255.

        • type

          enum

          required

          The tokenization method that generated the ID.

          The possible values are:

          • BILLING_AGREEMENT. The PayPal billing agreement ID. References an approved recurring payment for goods or services.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9A-Z_-]+$.

        trustly_request

        • country_code

          string

          required

          The two-character ISO 3166-1 country code.

        • name

          string

          required

          The name of the account holder associated with this payment method.

        vault_id

        • vault_id

          string

          The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future transactions.

          Minimum length: 1.

          Maximum length: 255.

          Pattern: ^[0-9a-zA-Z_-]+$.

        Additional API information

        Error messages

        In addition to the common HTTP status codes that the REST APIs return, the Payments API can return the following errors.

        • AUTH_CAPTURE_CURRENCY_MISMATCH

          Currency of capture must be the same as currency of authorization.


          Verify the currency of the capture and try the request again.

        • AUTHENTICATION_FAILURE

          Authentication failed due to missing authorization header, or invalid authentication credentials.


          Account validations failed for the user.

        • AUTHORIZATION_ALREADY_CAPTURED

          Authorization has already been captured.


          If final_capture is set to to true, additional captures are not possible against the authorization.

        • AUTHORIZATION_DENIED

          A denied authorization cannot be captured.


          You cannot capture a denied authorization.

        • AUTHORIZATION_EXPIRED

          An expired authorization cannot be captured.


          You cannot capture an expired authorization.

        • AUTHORIZATION_VOIDED

          A voided authorization cannot be captured or reauthorized.


          You cannot capture or reauthorize a voided authorization.

        • CANNOT_BE_ZERO_OR_NEGATIVE

          Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported.


          Specify a different value and try the request again.

        • CANNOT_BE_VOIDED

          A reauthorization cannot be voided. Please void the original parent authorization.


          You cannot void a reauthorized payment. You must void the original parent authorized payment.

        • REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK

          The requested action could not be performed, semantically incorrect, or failed business validation.


          Refunds not allowed on this capture due to a chargeback on the card or bank. Please contact the payee to resolve the chargeback.

        • TRANSACTION_DISPUTED

          Partial refunds cannot be offered at this time because there is an open case on this transaction. Visit the PayPal Resolution Center to review this case.


          Refund for an amount less than the remaining transaction amount cannot be processed at this time because of an open dispute on the capture. Please visit the PayPal Resolution Center to view the details.

        • CAPTURE_FULLY_REFUNDED

          The capture has already been fully refunded.


          You cannot capture additional refunds against this capture.

        • CARD_BRAND_NOT_SUPPORTED

          Refund cannot be issued to this card. The card brand card_brand is not supported. Please try again with another card.

        • CARD_BILLING_ADDRESS_COUNTRY_NOT_SUPPORTED

          Specified country is not currently supported for payment processing.

        • CARD_EXPIRED

          The card is expired.

        • CARD_ISSUER_COUNTRY_NOT_SUPPORTED

          Card is issued by a financial institution for a country (e.g. Cuba, Iran, North Korea, Syria) that is not current supported for payment processing.

        • CURRENCY_NOT_SUPPORTED_FOR_CARD_BRAND

          Currency not supported for card specified. Card is card_brand. Only currency_code is supported for this brand of card.

        • CURRENCY_NOT_SUPPORTED_FOR_COUNTRY

          Currency code not supported for card payments in your country.

        • DECIMAL_PRECISION

          The value of the field should not be more than two decimal places.


          If the currency supports decimals, only two decimal place precision is supported.

        • DECIMALS_NOT_SUPPORTED

          Currency does not support decimals.


          Currency does not support decimals. Please refer to https://developer.paypal.com/docs/api/reference/currency-codes/ for more information.

        • DUPLICATE_INVOICE_ID

          Requested invoice number has been previously captured. Possible duplicate transaction.


          Payment for this invoice was already captured.

        • INSTRUMENT_DECLINED

          The instrument presented was either declined by the processor or bank, or it can't be used for this payment.

        • INVALID_ACCOUNT_STATUS

          Account validations failed for the user.


          The user account could not be validated.

        • INVALID_CARD_NUMBER

          The card number is invalid.

        • INTERNAL_SERVER_ERROR

          An internal server error has occurred.


          Try your request again later.

        • RATE_LIMIT_REACHED

          Too many requests. Blocked due to rate limiting.

          The rate limit was reached.

        • INVALID_CURRENCY_CODE

          Currency code should be a three-character ISO-4217 currency code.


          Currency code is invalid or is not currently supported. Please refer https://developer.paypal.com/docs/api/reference/currency-codes/ for list of supported currency codes.

        • INVALID_INVOICE_ID

          Specified invoice_id does not exist.


          Please check the invoice_id and try again.

        • INVALID_PARAMETER_SYNTAX

          The value of the field does not conform to the expected format.


          Verify the specification for supported pattern and try the request again.

        • INVALID_PARAMETER_VALUE

          The value of a field is invalid.


          Verify the specification for the allowed values and try the request again.

        • INVALID_PAYEE_ACCOUNT

          Payee account is invalid.


          Verify the payee account information and try the request again.

        • INVALID_PLATFORM_FEES_AMOUNT

          The platform_fees amount cannot be greater than the capture amount.


          Verify the platform_fees amount and try the request again.

        • INVALID_RESOURCE_ID

          Specified resource ID does not exist. Please check the resource ID and try again.


          Verify the resource ID and try the request again.

        • INVALID_STRING_LENGTH

          The value of a field is either too short or too long.


          Verify the specification for the supported min and max values and try the request again.

        • INVALID_STRING_MAX_LENGTH

          The value of a field is too long.


          The parameter string is too long.

        • MAX_CAPTURE_AMOUNT_EXCEEDED

          Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the order amount. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer.


          Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.

        • MAX_CAPTURE_COUNT_EXCEEDED

          Maximum number of allowable captures has been reached. No additional captures are possible for this authorization. Please contact customer service or your account manager to change the number of captures that be made for a given authorization.


          You cannot make additional captures.

        • MAX_NUMBER_OF_REFUNDS_EXCEEDED

          You have exceeded the number of refunds that can be processed per capture.


          Please contact customer support or your account manager to review the number of refunds that can be processed per capture.

        • MAX_REFUND_LIMIT_EXCEEDED

          Refund amount exceeds allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.

        • MAX_REFUND_LIMIT_EXCEEDED

          Refund amount exceeds allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.

        • MISSING_REQUIRED_PARAMETER

          A required field / parameter is missing.


          Verify the specification for required fields and try the request again.

        • MULTIPLE_AUTHORIZATIONS_FOUND

          Cannot void multiple authorizations.


          Specified invoice_id is associated with more than one authorization.

        • NOT_AUTHORIZED

          You do not have permission to access or perform operations on this resource.


          To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

        • PARTIAL_REFUND_NOT_ALLOWED

          You cannot do a refund for an amount less than the original capture amount.


          Specify an amount equal to the capture amount or omit the amount object from the request. Then, try the request again.

        • PAYEE_ACCOUNT_LOCKED_OR_CLOSED

          Transaction could not complete because payee account is locked or closed.


          To get more information about the status of the account, call Customer Support.

        • PAYEE_ACCOUNT_RESTRICTED

          Payee account is restricted.


          To get more information about the status of the account, call Customer Support.

        • PAYER_ACCOUNT_LOCKED_OR_CLOSED

          The payer account cannot be used for this transaction.


          Contact the payer for an alternate payment method.

        • PAYER_ACCOUNT_RESTRICTED

          Payer account is restricted.


          To get more information about the status of the account, call Customer Support.

        • PAYER_CANNOT_PAY

          Payer cannot pay for this transaction.


          Please contact the payer to find other ways to pay for this transaction.

        • PENDING_CAPTURE

          Cannot initiate a refund as the capture is pending.


          Capture is typically pending when the payer has funded the transaction by using an e-check or bank account.

        • PERMISSION_DENIED

          You do not have permission to access or perform operations on this resource.


          To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

        • PERMISSION_NOT_GRANTED

          Payee of the authorization has not granted permission to perform capture on the authorization.


          To make API calls on behalf of a merchant, ensure that you have sufficient permissions to capture the authorization.

        • PREVIOUSLY_CAPTURED

          Authorization has been previously captured and hence cannot be voided.


          This authorized payment was already captured. You cannot capture it again.

        • PREVIOUSLY_VOIDED

          Authorization has been previously voided and hence cannot be voided again.


          This authorized payment was already voided. You cannot void it again.

        • REFUND_AMOUNT_EXCEEDED

          The refund amount must be less than or equal to the capture amount that has not yet been refunded.


          Verify the refund amount and try the request again.

        • REFUND_AMOUNT_TOO_LOW

          The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account.


          The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account.

        • REFUND_CAPTURE_CURRENCY_MISMATCH

          Refund must be in the same currency as the capture.


          Verify the currency of the refund and try the request again.

        • REFUND_FAILED_INSUFFICIENT_FUNDS

          Refund cannot be processed due to insufficient funds.


          Verify that either you have sufficient funds in your PayPal account or the bank account that is linked to your PayPal account is verified and has sufficient funds.

        • REFUND_NOT_ALLOWED

          Capture cannot be refunded.


          You cannot refund this capture.

        • REFUND_TIME_LIMIT_EXCEEDED

          You are over the time limit to perform a refund on this capture.


          The refund cannot be issued at this time.

        • TRANSACTION_REFUSED

          PayPal's internal controls prevent authorization from being captured.


          For more information about this transaction, contact customer support.

        • REFUND_NOT_SUPPORTED_FOR_PAYMENT_SOURCE

          Refund was refused by the payment source.


          Refunds are not supported for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means.

        • REFUND_TIME_EXCEEDED_FOR_PAYMENT_SOURCE

          Refund was refused by the payment source.


          The time limit set by the payer's selected payment source to refund this transaction has expired. Contact the payer directly to arrange a refund via alternative means.

        • REFUND_FAILED_BY_PAYMENT_SOURCE

          Refund was refused by the payment source.


          We're unable to process refunds for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means.

        • PREVIOUS_REQUEST_IN_PROGRESS

          A previous request on this resource is currently in progress. Please wait for sometime and try again. It is best to space out the initial and the subsequent request(s) to avoid receiving this error.


          This scenario only occurs when making multiple API requests on the same resource within a very short duration. To resolve this, API callers need to make subsequent requests with a delay.

        • REAUTHORIZATION_NOT_SUPPORTED

          A reauthorize cannot be attempted on an authorization_id that is the result of a prior reauthorization or on an authorization made on an Order saved using the v2/orders/id/save API.

        • AUTH_CURRENCY_MISMATCH

          The currency specified during reauthorization should be the same as the currency specified in the original authorization. Please check the currency of the authorization for which you are trying to reauthorize and try again.

        • SHIPPING_ADDRESS_INVALID

          Address field does not match the corresponding validation regex.

        • UPDATE_AUTHORIZATION_NOT_SUPPORTED

          Update authorization is not allowed for this type of authorization.

        • REFUND_TRANSACTION_REFUSED

          PayPal's internal controls or user account settings prevent refund from being processed.

        • MAX_PAYER_AMOUNT_LIMIT_EXCEEDED

          Refund amount exceeds the allowed cumulative limit that the payer can refund.

        • MAX_PAYEE_AMOUNT_LIMIT_EXCEEDED

          Refund amount exceeds the allowed cumulative limit that the payee can receive.

        • PAYER_REFUND_AMOUNT_LIMIT_EXCEEDED

          Refund amount exceeds per transaction limit that the payer can refund.

        • PAYEE_REFUND_AMOUNT_LIMIT_EXCEEDED

          Refund amount exceeds per transaction limit that the payee can receive.

        • DUPLICATE_REFUND

          Requested invoice_id has been previously refunded. Possible duplicate transaction.

        • CANNOT_REFUND_SELF

          The payer and payee for the refund cannot be same.

        • REFUND_FUNDS_NOT_AVAILABLE

          There is no valid funding instrument linked to the account from which refund can be processed.

        • REFUND_REFUSED_BY_PROCESSOR

          The funding instrument linked to the account has been declined by either the processor or PayPal internal system.

        • PLATFORM_FEE_NOT_ENABLED

          The API Caller account is not setup to be able to process refunds with 'platform_fees'. Please contact your Account Manager. This feature is useful when you want to contribute a portion of the 'platform_fees' you had capture as part of the refund being processed.

        • REFUND_IS_RESTRICTED

          This refund can only be processed by the API caller that had 'captured' the transaction. If you facilitate your transactions via a platform/partner, please initiate a refund through them.

        • PLATFORM_FEE_EXCEEDED

          Platform fee amount specified exceeds the amount that is available for refund. You can only refund up to the available platform fee amount. This error is also returned when no platform_fee was specified or was zero when the payment was captured.

        • CURRENCY_MISMATCH

          All amounts specified should be in the same currency. Please ensure that the currency for the 'amount' and that of 'platform_fees.amount' is the same.

        • CANNOT_BE_NEGATIVE

          Must be greater than or equal to 0.