Payment Method Tokens API

Version notice: This API uses /v2/vault endpoints. Vault v3 endpoints are now available in the United States. Payment tokens created with Vault v2 are fully compatible with Vault v3. You can upgrade to v3 at any time.

Payment tokens (resource group)

List all payment tokens

GET/v2/vault/payment-tokens
Returns all payment tokens for a customer.

Query parameters

  • page

    integer

    Minimum value: 1.

    Description: A non-negative, non-zero integer representing the page of the results.

  • page_size

    integer

    Minimum value: 1.

    Description: A non-negative, non-zero integer indicating the maximum number of results to return at one time.

  • source

    enum

    The possible values are:

    • CARD. A payment token that represent a card.
    • PAYPAL. A payment token that represents a PayPal Wallet.

    Minimum length: 1.

    Maximum length: 1024.

    Description: Filters the records for a specific payment token source.

    Pattern: ^[a-zA-Z-]+$.

  • total_required

    boolean

    Description: A boolean indicating total number of items (total_items) and pages (total_pages) are expected to be returned in the response.

  • customer_id

    string

    required

    Minimum length: 1.

    Maximum length: 22.

    Description: A unique identifier representing a specific customer in your system of record.

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

Header parameters

  • Paypal-Application-Context

    string

    Description: An identity object that identifies Applications. This is used to convey application identity metadata.

  • Authorization

    string

    required

    Description: Contains the credentials to authenticate a user agent with a server.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v2/vault/payment-tokens?customer_id=customer_4029352050 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

Successful execution.
  • customer_id

    string

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

  • links

    array (contains the link_description object)

    Read only.

    Description: An array of related HATEOAS links.

  • payment_tokens

    array (contains the min_vault_resource object)

  • total_items

    string

    Minimum length: 1.

    Maximum length: 255.

    Description: Total number of items.

    Pattern: ^[0-9]+$.

  • total_pages

    string

    Minimum length: 1.

    Maximum length: 255.

    Description: Total number of pages.

    Pattern: ^[0-9]+$.

Sample Response

{
  "customer_id": "customer_4029352050",
  "payment_tokens": [
    {
      "id": "8kk845",
      "status": "CREATED",
      "source": {
        "card": {
          "brand": "VISA",
          "last_digits": "1111",
          "verification_status": "NOT_VERIFIED"
        }
      },
      "links": [
        {
          "rel": "self",
          "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
          "method": "GET"
        },
        {
          "rel": "delete",
          "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
          "method": "DELETE"
        }
      ]
    },
    {
      "id": "6km842",
      "status": "CREATED",
      "source": {
        "card": {
          "brand": "VISA",
          "last_digits": "1234",
          "verification_status": "NOT_VERIFIED"
        }
      },
      "links": [
        {
          "rel": "self",
          "href": "https://api-m.paypal.com/v2/vault/payment-tokens/6km842",
          "method": "GET"
        },
        {
          "rel": "delete",
          "href": "https://api-m.paypal.com/v2/vault/payment-tokens/6km842",
          "method": "DELETE"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false",
      "method": "GET"
    },
    {
      "rel": "first",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false",
      "method": "GET"
    },
    {
      "rel": "last",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false",
      "method": "GET"
    }
  ]
}

Add payment token to vault

POST/v2/vault/payment-tokens
Creates a Payment Token from the given source and adds it to the Vault of the associated customer id.

Header parameters

  • PayPal-Client-Metadata-Id

    string

  • Paypal-Application-Context

    string

    Description: An identity object that identifies Applications. This is used to convey application identity metadata.

  • Authorization

    string

    required

    Description: Contains the credentials to authenticate a user agent with a server.

  • Content-Type

    string

    required

    Description: Specifies the request format.

  • PayPal-Request-Id

    string

    required

    Description: The server stores keys for 3 hours.

Request body

  • source

    object

    required

    Description: The payment method to vault with the instrument details.

  • application_context

    object

    Description: Customizes the Vault creation flow experience for your customers.

  • customer_id

    string

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

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/vault/payment-tokens \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-ID: b5efbe82-bbad-4bb0-aeeb-bfef5b442e49" \
-d '{
  "source": {
    "card": {
      "number": "4111111111111111",
      "expiry": "2020-02",
      "name": "John Doe",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_1": "CA",
        "admin_area_2": "San Jose",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  },
  "application_context": {
    "brand_name": "YourBrandName",
    "locale": "en-US",
    "return_url": "https://example.com/returnUrl",
    "cancel_url": "https://example.com/cancelUrl"
  }
}'

Response

A successful creation of resource.
  • customer_id

    string

    Minimum length: 1.

    Maximum length: 22.

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

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

  • id

    string

    Minimum length: 1.

    Maximum length: 255.

    Description: The PayPal-generated ID for the token.

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

  • links

    array (contains the link_description object)

    Read only.

    Description: An array of related HATEOAS links.

  • source

    object

    Description: Minimal Source Response which will contain information of one of the payment methods vaulted. These types can be one of CARD or PAYPAL.

  • status

    enum

    The possible values are:

    • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
    • CREATED. The payment token has been vaulted.

    Default: CREATED.

    Minimum length: 1.

    Maximum length: 255.

    Description: The status of the payment token.

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

Sample Response

{
  "id": "8kk845",
  "customer_id": "customer_4029352050",
  "status": "CREATED",
  "source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "verification_status": "NOT_VERIFIED"
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
      "method": "GET"
    },
    {
      "rel": "delete",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
      "method": "DELETE"
    }
  ]
}

Delete payment token

DELETE/v2/vault/payment-tokens/{id}
Delete the payment token associated with the payment token id.

Header parameters

  • Paypal-Application-Context

    string

    Description: An identity object that identifies Applications. This is used to convey application identity metadata.

  • Authorization

    string

    required

    Description: Contains the credentials to authenticate a user agent with a server.

Path parameters

  • id

    string

    required

    Description: ID of the payment token.

Sample Request

curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/vault/payment-tokens/8kk845 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

The server has successfully executed the method, but there is no entity body to return.

    Sample Response

    204 No Content

    Show a payment token

    GET/v2/vault/payment-tokens/{id}
    Returns a payment associated with the payment token id.

    Header parameters

    • Paypal-Application-Context

      string

      Description: An identity object that identifies Applications. This is used to convey application identity metadata.

    • Authorization

      string

      required

      Description: Contains the credentials to authenticate a user agent with a server.

    Path parameters

    • id

      string

      required

      Description: ID of the payment token.

    Sample Request

    curl -v -X GET https://api-m.sandbox.paypal.com/v2/vault/payment-tokens/8kk845 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

    Response

    Successful execution.
    • customer_id

      string

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

    • id

      string

      Description: The PayPal-generated ID for the token.

    • links

      array (contains the link_description object)

      Read only.

      Description: An array of related HATEOAS links.

    • source

      object

      Description: A payment token response which will contain information of one of the payment methods saved. These types can be one of Card or PayPal.

    • status

      enum

      The possible values are:

      • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
      • CREATED. The payment token has been vaulted.

      Description: The status of the payment token.

    Sample Response

    {
  "id": "8kk845",
  "customer_id": "customer_4029352050",
  "status": "CREATED",
  "source": {
    "card": {
      "last_digits": "1111",
      "verification_status": "NOT_VERIFIED",
      "expiry": "2024-12",
      "brand": "VISA",
      "billing_address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "Building 17",
        "admin_area_2": "San Jose",
        "admin_area_1": "CA",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
      "method": "GET"
    },
    {
      "rel": "delete",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
      "method": "DELETE"
    }
  ]
}

    Approval tokens (resource group)

    Show approval token

    GET/v2/vault/approval-tokens/{id}
    Returns the approval session based on the approval token identifier. The approval token has a lifespan of 3 hours. Once approved, use the /confirm-payment-token API to create a Payment Token that can be used for Payments.

    Header parameters

    • Paypal-Application-Context

      string

      Description: An identity object that identifies Applications. This is used to convey application identity metadata.

    • Authorization

      string

      required

      Description: Contains the credentials to authenticate a user agent with a server.

    Path parameters

    • id

      string

      required

      Description: Temporary ID of the approval token. This token will have a lifespan of 3 hours.

    Sample Request

    curl -v -X GET https://api-m.sandbox.paypal.com/v2/vault/approval-tokens/5C991763VB2781612 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

    Response

    Ok. Successful execution.
    • customer_id

      string

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

    • id

      string

      Minimum length: 15.

      Maximum length: 1024.

      Description: The temporary PayPal-generated ID for the token.

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

    • links

      array (contains the link_description object)

      Read only.

      Description: An array of related HATEOAS links.

    • source

      object

      Description: Payment Method Response which will contain information of one of the payment methods vaulted. These types can be one of CARD, PAYPAL, BANK, etc.

    • status

      enum

      The possible values are:

      • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
      • APPROVED. The approval token has been approved by the buyer. The approval token can be confirmed to a payment token using the /confirm-payment-token controller action.
      • CREATED. The payment token has been vaulted.

      Default: CUSTOMER_ACTION_REQUIRED.

      Minimum length: 1.

      Maximum length: 255.

      Description: The status of the approval token. This status reflects whether the customer has taken an action such that it can be confirmed.

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

    Sample Response

    {
  "id": "5C991763VB2781612",
  "status": "CUSTOMER_ACTION_REQUIRED",
  "customer_id": "4029352050",
  "source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "verification_status": "NOT_VERIFIED"
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v2/vault/approval-tokens/5C991763VB2781612",
      "method": "GET"
    },
    {
      "href": "https://paypal.com/webapps/helios?action=authenticate&validate_session_id=82cf4a87-5c40-0a27-1a09-4ffbb0d05fdc",
      "rel": "approve",
      "method": "GET"
    },
    {
      "rel": "confirm",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/5C991763VB2781612/confirm-payment-token",
      "method": "POST"
    }
  ]
}

    Create payment token from approval token

    POST/v2/vault/approval-tokens/{id}/confirm-payment-token
    Executes the payment token creation on an approval token, which must first be acted upon by the customer. The resulting token can be used for payments.

    Header parameters

    • PayPal-Client-Metadata-Id

      string

    • Paypal-Application-Context

      string

      Description: An identity object that identifies Applications. This is used to convey application identity metadata.

    • Prefer

      string

      Description: 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

      Description: Contains the credentials to authenticate a user agent with a server.

    • PayPal-Request-Id

      string

      required

      Description: The server stores keys for 3 hours.

    • Content-Type

      string

      Description: Specifies the request format.

    Path parameters

    • id

      string

      required

      Description: Temporary id of the approval token. This token will have a lifespan of 3 hours.

    Sample Request

    curl -v -X POST https://api-m.sandbox.paypal.com/v2/vault/approval-tokens/5C991763VB2781612/confirm-payment-token \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-ID: b5efbe82-bbad-4bb0-aeeb-bfef5b442e49"

    Response

    Created. Payer approval has been confirmed and the minimal token resource is returned.
    • customer_id

      string

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

    • id

      string

      Description: The PayPal-generated ID for the token.

    • links

      array (contains the link_description object)

      Read only.

      Description: An array of related HATEOAS links.

    • source

      object

      Description: Payment Method Response which will contain information of one of the payment methods vaulted. These types can be one of CARD, PAYPAL, BANK, etc.

    • status

      enum

      The possible values are:

      • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
      • CREATED. The payment token has been vaulted.

      Description: The status of the payment token.

    Sample Response

    {
  "id": "8kk845",
  "customer_id": "4029352050",
  "status": "CREATED",
  "source": {
    "card": {
      "brand": "VISA",
      "last_digits": "1111",
      "verification_status": "VERIFIED",
      "verification_method": "SCA_WHEN_REQUIRED",
      "verification": {
        "authorization": {
          "network_transaction_id": "20286098380002303",
          "verification_time": "2020-10-07T22:44:41.000Z",
          "amount": {
            "value": "0.00",
            "currency_code": "USD"
          },
          "processor_response": {
            "avs_code": "M",
            "cvv_code": "P"
          }
        },
        "authentication": {
          "three_d_secure": {
            "type": "THREE_DS_AUTHENTICATION",
            "eci_flag": "FULLY_AUTHENTICATED_TRANSACTION",
            "card_brand": "VISA",
            "enrolled": "Y",
            "pares_status": "Y",
            "three_ds_version": "2",
            "authentication_type": "DYNAMIC",
            "three_ds_server_transaction_id": "3d-secure-txn-id"
          }
        }
      }
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
      "method": "GET"
    },
    {
      "rel": "delete",
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/8kk845",
      "method": "DELETE"
    }
  ]
}

    Common object definitions

    3ds_card_brand

    • 3ds_card_brand

      enum

      The possible values are:

      • AMERICAN_EXPRESS. Card Brand Amex.
      • DISCOVER. Card Brand DISCOVER.
      • JCB. Card Brand JCB.
      • MAESTRO. Card Brand MAESTRO.
      • MASTERCARD. Card Brand MASTERCARD.
      • SOLO. Card Brand SOLO.
      • VISA. Card Brand VISA.
      • ELECTRON. Card Brand ELECTRON.
      • ELO. Card Brand ELO.

      Minimum length: 1.

      Maximum length: 255.

      Description: Card brand that the transaction was processed for authentication.

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

    3ds_result

    • type

      string

      Description: The type of authentication used on the financial instrument.

    • access_control_server_transaction_id

      string

      Minimum length: 1.

      Maximum length: 36.

      Description: Unique transaction identifier assigned by the Access Control Server (ACS) to identify a single transaction.

    • authentication_type

      string

      Minimum length: 1.

      Maximum length: 255.

      Description: Indicates the type of authentication that will be used to challenge the card holder.

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

    • card_brand

      string

      Minimum length: 1.

      Maximum length: 255.

      Description: Card brand that the transaction was processed for authentication.

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

    • cavv

      string

      Minimum length: 1.

      Maximum length: 40.

      Description: This is the cardholder authentication value. The CAVV is unique to the cardholder and to the transaction that was authenticated.

    • cavv_algorithm

      string

      Minimum length: 1.

      Maximum length: 255.

      Description: Indicates the algorithm used to generate the CAVV value.

      Pattern: ^[A-Z_]+$.

    • directory_server_transaction_id

      string

      Minimum length: 1.

      Maximum length: 36.

      Description: Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.

    • eci_flag

      string

      Minimum length: 1.

      Maximum length: 255.

      Description: Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.

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

    • enrolled

      string

      Minimum length: 1.

      Maximum length: 255.

      Description: Status of Authentication eligibility.

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

    • merchant_name

      string

      Minimum length: 1.

      Maximum length: 25.

      Description: The merchant name that was sent in the authentication request.

    • pares_status

      string

      Minimum length: 1.

      Maximum length: 255.

      Description: Transactions status result identifier. The outcome of the issuer's authentication.

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

    • paypal_acquiring_bin

      string

      Minimum length: 1.

      Maximum length: 6.

      Description: The PayPal acquiring BIN to be used for authorization.

      Pattern: ^[0-9]+$.

    • paypal_acquiring_mid

      string

      Minimum length: 1.

      Maximum length: 25.

      Description: The PayPal acquiring MID to be used for authorization.

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

    • signature_verification_status

      string

      Minimum length: 1.

      Maximum length: 50.

      Description: Transaction Signature status identifier.

      Pattern: ^[A-Z]+$.

    • three_ds_server_transaction_id

      string

      Minimum length: 1.

      Maximum length: 36.

      Description: Unique transaction identifier assigned by the 3DS Server to identify a single transaction.

    • three_ds_version

      string

      Minimum length: 1.

      Maximum length: 10.

      Description: The 3DS version that was used to process the transaction.

    • ucaf_indicator

      string

      Minimum length: 1.

      Maximum length: 255.

      Description: Universal Cardholder Authentication Field (UCAF) Indicator value provided by the issuer.

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

    • xid

      string

      Minimum length: 1.

      Maximum length: 40.

      Description: Transaction identifier resulting from authentication processing.

    3ds_result

    • type

      string

      Description: The type of authentication used on the financial instrument.

    • authentication_type

      string

      Description: Indicates the type of authentication that will be used to challenge the card holder.

    • card_brand

      string

      Description: Card brand that the transaction was processed for authentication.

    • eci_flag

      string

      Description: Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.

    • enrolled

      string

      Description: Status of Authentication eligibility.

    • pares_status

      string

      Description: Transactions status result identifier. The outcome of the issuer's authentication.

    • three_ds_server_transaction_id

      string

      Minimum length: 1.

      Maximum length: 36.

      Description: Unique transaction identifier assigned by the 3DS Server to identify a single transaction.

    • three_ds_version

      string

      Minimum length: 1.

      Maximum length: 10.

      Description: The 3DS version that was used to process the transaction.

    account_id

    • account_id

      string

      Minimum length: 13.

      Maximum length: 13.

      Description: The account identifier for a PayPal account.

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

    address_details

    • building_name

      string

      Maximum length: 100.

      Description: 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.

    • delivery_service

      string

      Maximum length: 100.

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

    • street_name

      string

      Maximum length: 100.

      Description: The street name. Just Drury in Drury Lane.

    • street_number

      string

      Maximum length: 100.

      Description: The street number.

    • street_type

      string

      Maximum length: 100.

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

    • sub_building

      string

      Maximum length: 100.

      Description: 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.

    address_portable

    • country_code

      string

      required

      Minimum length: 2.

      Maximum length: 2.

      Description: 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.

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

    • address_details

      object

      Description: 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

      Maximum length: 300.

      Description: 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.

    • address_line_2

      string

      Maximum length: 300.

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

    • address_line_3

      string

      Maximum length: 100.

      Description: 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.

    • admin_area_1

      string

      Maximum length: 300.

      Description: 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.

    • admin_area_2

      string

      Maximum length: 120.

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

    • admin_area_3

      string

      Maximum length: 100.

      Description: 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.

    • admin_area_4

      string

      Maximum length: 100.

      Description: 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.

    • postal_code

      string

      Maximum length: 60.

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

    address_portable

    • country_code

      string

      required

      Description: 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

      Maximum length: 300.

      Description: 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.

    • address_line_2

      string

      Maximum length: 300.

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

    • admin_area_1

      string

      Maximum length: 300.

      Description: 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.

    • admin_area_2

      string

      Maximum length: 120.

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

    • postal_code

      string

      Maximum length: 60.

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

    address_portable

    • country_code

      string

      required

      Description: 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

      Maximum length: 300.

      Description: 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.

    • address_line_2

      string

      Maximum length: 300.

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

    • admin_area_1

      string

      Maximum length: 300.

      Description: 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.

    • admin_area_2

      string

      Maximum length: 120.

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

    • postal_code

      string

      Maximum length: 60.

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

    address_portable_postal_code_validation

    • address_portable_postal_code_validation

    amount_breakdown

    • discount

      object

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

    • handling

      object

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

    • insurance

      object

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

    • item_total

      object

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

    • shipping

      object

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

    • shipping_discount

      object

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

    • tax_total

      object

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

    amount_with_breakdown

    • currency_code

      string

      Minimum length: 3.

      Maximum length: 3.

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

    • value

      string

      Maximum length: 32.

      Description: 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.

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

    • breakdown

      object

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

    application_context

    • brand_name

      string

      Minimum length: 1.

      Maximum length: 300.

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

      Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

    • cancel_url

      string

      Minimum length: 10.

      Maximum length: 4000.

      Description: The URL where the customer is redirected after customer cancels or leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS.

      Pattern: ^[a-zA-Z0-9_'\-., :;\!?"\/]*$.

    • locale

      string

      Minimum length: 2.

      Maximum length: 10.

      Description: The BCP 47-formatted locale of pages that the PayPal vaulting 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.

      Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.

    • payment_method_preference

      object

      Description: The customer and merchant payment preferences.

    • permit_multiple_payment_tokens

      boolean

      Description: Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source.

    • return_url

      string

      Minimum length: 10.

      Maximum length: 4000.

      Description: The URL where the customer is redirected after customer approves leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS.

      Pattern: ^[a-zA-Z0-9_'\-., :;\!?"\/]*$.

    • shipping_preference

      enum

      The possible values are:

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

      Minimum length: 1.

      Maximum length: 255.

      Description: The shipping preference. This only applies to PayPal payment source.

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

    • vault_on_approval

      boolean

      Description: Indicates to vault upon successful customer authentication and approval. When indicated as true, the /confirm-payment-token API does not need to be called. Please listen to either webhooks or poll on the approval token to retrieve the vaulted payment token.

    application_context.payment_method

    • payee_preferred

      enum

      The possible values are:

      • UNRESTRICTED. Accepts any type of payment from the customer.
      • IMMEDIATE_PAYMENT_REQUIRED. Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status.

      Description: The merchant-preferred payment methods.

    • payer_selected

      enum

      The possible values are:

      • PAYPAL_CREDIT. PayPal Credit.
      • PAYPAL. PayPal.

      Minimum length: 1.

      Description: The customer-selected payment method on the merchant site.

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

    approval_token_resource

    • customer_id

      string

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

    • id

      string

      Minimum length: 15.

      Maximum length: 1024.

      Description: The temporary PayPal-generated ID for the token.

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

    • links

      array (contains the link_description object)

      Read only.

      Description: An array of related HATEOAS links.

    • source

      object

      Description: Payment Method Response which will contain information of one of the payment methods vaulted. These types can be one of CARD, PAYPAL, BANK, etc.

    • status

      enum

      The possible values are:

      • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
      • APPROVED. The approval token has been approved by the buyer. The approval token can be confirmed to a payment token using the /confirm-payment-token controller action.
      • CREATED. The payment token has been vaulted.

      Minimum length: 1.

      Maximum length: 255.

      Description: The status of the approval token. This status reflects whether the customer has taken an action such that it can be confirmed.

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

    approval_token_status

    • approval_token_status

      enum

      The possible values are:

      • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
      • APPROVED. The approval token has been approved by the buyer. The approval token can be confirmed to a payment token using the /confirm-payment-token controller action.
      • CREATED. The payment token has been vaulted.

      Minimum length: 1.

      Maximum length: 255.

      Description: The status of the approval token.

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

    authentication_details

    • three_d_secure

      object

      Description: Card 3DS Authentication Results.

    authentication_result_type

    • type

      enum

      The possible values are:

      • THREE_DS_AUTHENTICATION. The card was authenticated using 3D Secure (3DS) authentication scheme.

      Description: The type of authentication used on the financial instrument.

    authentication_type

    • authentication_type

      enum

      The possible values are:

      • STATIC. Indicates fixed password.
      • DYNAMIC. Indicates one-time password. Could be single-step or multi-step.
      • OUT_OF_BAND. Indicates biometric over the phone.
      • DECOUPLED. Indicates decoupled authentication.

      Minimum length: 1.

      Maximum length: 255.

      Description: Indicates the type of authentication that was used to challenge the card holder.

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

    authorization_details

    • amount

      object

      Description: The transaction amount along with breakdown details. If not passed, we will treat as if a minimum authorization in the country the transaction is taken place.

    • network_transaction_id

      string

      Minimum length: 1.

      Maximum length: 1024.

      Description: Transaction Identifier as given by the network to indicate a previously executed CIT authorization. Only present when authorization is successful for a verification.

      Pattern: ^[0-9]+$.

    • processor_response

      object

      Description: The processor information.

    • verification_time

      string

      Read only.

      Minimum length: 20.

      Maximum length: 64.

      Description: The date and time when the instrument was verified.

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

    authorization_details.amount_with_breakdown

    • currency_code

      string

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

    • value

      string

      Maximum length: 32.

      Description: 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.

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

      authorization_details.processor_response

      • avs_code

        enum

        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.

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

      • cvv_code

        enum

        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.

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

      card

      • expiry

        string

        required

        Minimum length: 7.

        Maximum length: 7.

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

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

      • number

        string

        required

        Minimum length: 13.

        Maximum length: 19.

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

      • attributes

        object

        Description: Additional attributes associated with the use of this card.

      • authentication_results

        array (contains the 3ds_result object)

        Description: A list of authentication results.

      • billing_address

        object

        Description: 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.

      • card_type

        enum

        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.

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

      • id

        string

        Read only.

        Description: The PayPal-generated ID for the card.

      • last_digits

        string

        Read only.

        Description: The last digits of the payment card.

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

      • name

        string

        Maximum length: 300.

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

      • security_code

        string

        Description: The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.

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

      card

      • expiry

        string

        required

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

      • number

        string

        required

        Minimum length: 13.

        Maximum length: 19.

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

      • billing_address

        object

        Description: 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.

      • name

        string

        Maximum length: 300.

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

      • security_code

        string

        Description: The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.

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

      card.address_portable

      • country_code

        string

        required

        Description: 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

        Maximum length: 300.

        Description: 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.

      • address_line_2

        string

        Maximum length: 300.

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

      • admin_area_1

        string

        Maximum length: 300.

        Description: 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.

      • admin_area_2

        string

        Maximum length: 120.

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

      • postal_code

        string

        Maximum length: 60.

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

      card.address_portable

      • country_code

        string

        required

        Description: 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

        Maximum length: 300.

        Description: 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.

      • address_line_2

        string

        Maximum length: 300.

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

      • admin_area_1

        string

        Maximum length: 300.

        Description: 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.

      • admin_area_2

        string

        Maximum length: 120.

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

      • postal_code

        string

        Maximum length: 60.

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

      card_attributes

      • customer

        object

        Description: The details about a customer in merchant's or partner's system of records.

      • vault

        Description: Instruction to vault the card based on the specified strategy.

      • verification

        object

        Description: Instruction to optionally verify the card based on the specified strategy

      card_brand

      • card_brand

        enum

        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.

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

        Pattern: ^[A-Z_]+$.

      card_request

      • billing_address

        object

        Description: 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

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

      • name

        string

        Maximum length: 300.

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

      • number

        string

        Minimum length: 13.

        Maximum length: 19.

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

      • security_code

        string

        Description: The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.

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

      • verification_method

        string

        Description: The API caller can opt in to verify the payment token through PayPal offered verification services (e.g. Smart Dollar Auth, 3DS).

      card_response

      • bin

        string

        Minimum length: 6.

        Maximum length: 8.

        Description: An acronym for Bank Identification Number (BIN), also known as IIN (Issuer Identification Number). It Is a standardized global numbering scheme (6 to 8 digits) used to identify a bank / institution that issued the card.

        Pattern: ^[0-9]{6,8}$.

      • brand

        enum

        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.

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

        Pattern: ^[A-Z_]+$.

      • id

        string

        Read only.

        Description: The PayPal-generated ID for the card.

      • issuer

        enum

        The possible values are:

        • PAYPAL. A PayPal credit card.

        Read only.

        Description: The issuer of the card instrument.

      • last_digits

        string

        Read only.

        Description: The last digits of the payment card.

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

      • last_n_chars

        string

        Read only.

        Minimum length: 2.

        Description: The last digits of the payment card.

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

      • type

        enum

        The possible values are:

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

        Read only.

        Description: The payment card type.

      card_response

      • brand

        string

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

      • last_digits

        Description: The last digits of the payment card.

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

      • billing_address

        object

        Description: 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

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

      • verification

        object

        Description: Card Verification details including the authorization details and 3D SECURE details.

      • verification_status

        string

        Description: Card Verification status.

      card_response

      • brand

        string

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

      • last_digits

        Description: The last digits of the payment card.

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

      • billing_address

        object

        Description: 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

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

      • verification

        object

        Description: Card Verification details including the authorization details and 3D SECURE details.

      • verification_method

        string

        Description: The verification method of the card.

      • verification_status

        string

        Description: Card Verification status.

      card_response

      • brand

        enum

        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.

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

      • last_digits

        Read only.

        Description: The last digits of the payment card.

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

      card_response

      • brand

        enum

        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.

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

      • last_digits

        Read only.

        Description: The last digits of the payment card.

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

      card_response

      • brand

        enum

        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.

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

      • last_digits

        Read only.

        Description: The last digits of the payment card.

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

      card_threeds_response

      • type

        string

        Description: The type of authentication used on the financial instrument.

      • authentication_type

        string

        Description: Indicates the type of authentication that will be used to challenge the card holder.

      • card_brand

        string

        Description: Card brand that the transaction was processed for authentication.

      • eci_flag

        string

        Description: Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.

      • enrolled

        string

        Description: Status of Authentication eligibility.

      • pares_status

        string

        Description: Transactions status result identifier. The outcome of the issuer's authentication.

      • three_ds_server_transaction_id

        string

        Minimum length: 1.

        Maximum length: 36.

        Description: Unique transaction identifier assigned by the 3DS Server to identify a single transaction.

      • three_ds_version

        string

        Minimum length: 1.

        Maximum length: 10.

        Description: The 3DS version that was used to process the transaction.

      card_verification

      • method

        enum

        The possible values are:

        • 3D_SECURE. The contingency surfaced as an additional security layer that helps prevent unauthorized card-not-present transactions and protects the merchant from exposure to fraud.
        • AVS_CVV. Places a temporary hold on the card to ensure its validity. This process protects the merchant from exposure to fraud. This verification method will confirm that the address information or CVV included matches what the issuing bank has on file for the associated card, ensuring that only authorized card users are able to make purchases from you.

        Minimum length: 1.

        Maximum length: 255.

      card_verification_details

      • authentication

        object

        Description: Card authentication details.

      • authorization

        object

        Description: Card authorization details.

      card_verification_details

      • authorization

        object

        Description: Card authorization details.

      card_verification_details

      • authorization

        object

        Description: Card authorization details.

      card_verification_method

      • card_verification_method

        enum

        The possible values are:

        • SCA_WHEN_REQUIRED. This is the default. When an authorization or transaction is attempted this option will return a contingency and HATEOAS link only when local regulations require strong customer authentication, (e.g. 3DS in countries and use cases where it is mandated). The API caller should redirect the payer to the link so that they can authenticate themselves. In all cases, when an authorization is requested the AVS/CVV results will be returned in the response.

        Minimum length: 1.

        Maximum length: 255.

        Description: The verification method of the card.

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

      card_verification_status

      • card_verification_status

        enum

        The possible values are:

        • VERIFIED. Card has been verified
        • NOT_VERIFIED. Card has not been verified

        Minimum length: 1.

        Maximum length: 255.

        Description: Verification status of Card.

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

      cavv_algorithm

      • cavv_algorithm

        enum

        The possible values are:

        • CVV_WITH_ATN. Refers to the Visa CAVV generation specification that includes a unique identifier built into the value.
        • MASTERCARD_SPA_ALGORITHM. Refers to Secure Payment Algorithm used to generate Mastercard's Accountholder Authentication Value (AAV).

        Minimum length: 1.

        Maximum length: 255.

        Description: Indicates the algorithm used to generate the CAVV/AAV value.

        Pattern: ^[A-Z_]+$.

      country_code

      • country_code

        string

        Minimum length: 2.

        Maximum length: 2.

        Description: 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.

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

      currency_code

      customer

      • id

        string

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

      date_no_time

      • date_no_time

        string

        Minimum length: 10.

        Maximum length: 10.

        Description: 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.

        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

        Minimum length: 20.

        Maximum length: 64.

        Description: 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.

        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

        Minimum length: 7.

        Maximum length: 7.

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

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

      eci_flag

      • eci_flag

        enum

        The possible values are:

        • MASTERCARD_NON_3D_SECURE_TRANSACTION. Mastercard non-3-D Secure transaction.
        • MASTERCARD_ATTEMPTED_AUTHENTICATION_TRANSACTION. Mastercard attempted authentication transaction.
        • MASTERCARD_FULLY_AUTHENTICATED_TRANSACTION. Mastercard fully authenticated transaction.
        • FULLY_AUTHENTICATED_TRANSACTION. VISA, AMEX, JCB, DINERS CLUB fully authenticated transaction.
        • ATTEMPTED_AUTHENTICATION_TRANSACTION. VISA, AMEX, JCB, DINERS CLUB attempted authentication transaction.
        • NON_3D_SECURE_TRANSACTION. VISA, AMEX, JCB, DINERS CLUB non-3-D Secure transaction.

        Minimum length: 1.

        Maximum length: 255.

        Description: Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the Gateway/Processor.

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

      email

      • email

        string

        Maximum length: 254.

        Description: The internationalized email address.

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

        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])+)\]).

      enrolled

      • enrolled

        enum

        The possible values are:

        • Y. Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl.
        • N. No. The bank is not participating in 3-D Secure protocol.
        • U. Unavailable. The DS or ACS is not available for authentication at the time of the request.
        • B. Bypass. The merchant authentication rule is triggered to bypass authentication.

        Minimum length: 1.

        Maximum length: 255.

        Description: Status of Authentication eligibility.

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

      error

      • debug_id

        string

        required

        Description: The PayPal internal ID. Used for correlation purposes.

      • message

        string

        required

        Description: The message that describes the error.

      • name

        string

        required

        Description: The human-readable, unique name of the error.

      • details

        array (contains the error_details object)

        Description: An array of additional details about the error.

      • information_link

        string

        Read only.

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

      • links

        array (contains the link_description object)

        Read only.

        Description: An array of request-related HATEOAS links.

      error_details

      • issue

        string

        required

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

      • description

        string

        Description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

      • field

        string

        Description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.

      • location

        string

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

      • value

        string

        Description: The value of the field that caused the error.

      id

      • id

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The PayPal-generated ID for the token.

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

      language

      merchant_partner_customer_id

      • merchant_partner_customer_id

        string

        Minimum length: 1.

        Maximum length: 22.

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

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

      min_card_response

      • brand

        string

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

      • last_digits

        Description: The last digits of the payment card.

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

      • verification

        object

        Description: Card Verification details including the authorization details and 3D SECURE details.

      • verification_method

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The verification method of the card.

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

      • verification_status

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: Verification status of Card.

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

      min_payment_token

      • customer_id

        string

        Minimum length: 1.

        Maximum length: 22.

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

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

      • id

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The PayPal-generated ID for the token.

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

      • links

        array (contains the link_description object)

        Read only.

        Description: An array of related HATEOAS links.

      • source

        object

        Description: Minimal Source Response which will contain information of one of the payment methods vaulted. These types can be one of CARD or PAYPAL.

      • status

        enum

        The possible values are:

        • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
        • CREATED. The payment token has been vaulted.

        Minimum length: 1.

        Maximum length: 255.

        Description: The status of the payment token.

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

      min_paypal_wallet_response

      • description

        string

        Minimum length: 1.

        Maximum length: 128.

        Description: The description displayed to payer on PayPal.com.

        Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

      • payer

        object

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

      min_paypal_wallet_response.payer

      • email_address

        string

        Description: The email address of the payer.

      • name

        object

        Description: The name of the payer. Supports only the given_name and surname properties.

      • payer_id

        string

        Read only.

        Description: The PayPal-assigned ID for the payer.

      min_source_response

      • card

        object

        Description: Minimal representation of a Card Payment Token.

      • paypal

        object

        Description: Minimal representation of a PayPal Payment Token.

      min_vault_resource

      • id

        string

        Description: The PayPal-generated ID for the token.

      • links

        array (contains the link_description object)

        Read only.

        Description: An array of related HATEOAS links.

      • source

        object

        Description: Minimal Source Response which will contain information of one of the payment methods vaulted. These types can be one of CARD or PAYPAL.

      • status

        enum

        The possible values are:

        • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
        • CREATED. The payment token has been vaulted.

        Description: The status of the payment token.

      money

      • currency_code

        string

        required

        Minimum length: 3.

        Maximum length: 3.

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

      • value

        string

        required

        Maximum length: 32.

        Description: 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.

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

      name

      • alternate_full_name

        string

        Maximum length: 300.

        Description: 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.

      • full_name

        string

        Maximum length: 300.

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

      • given_name

        string

        Maximum length: 140.

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

      • middle_name

        string

        Maximum length: 140.

        Description: 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.

      • prefix

        string

        Maximum length: 140.

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

      • suffix

        string

        Maximum length: 140.

        Description: The suffix for the party's name.

      • surname

        string

        Maximum length: 140.

        Description: 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.

      name_validation

      • name_validation

      pares_status

      • pares_status

        enum

        The possible values are:

        • Y. Successful authentication.
        • N. Failed authentication / account not verified / transaction denied.
        • U. Unable to complete authentication.
        • A. Successful attempts transaction.
        • C. Challenge required for authentication.
        • R. Authentication rejected (merchant must not submit for authorization).
        • D. Challenge required; decoupled authentication confirmed.
        • I. Informational anly; 3DS requestor challenge preference acknowledged.

        Minimum length: 1.

        Maximum length: 255.

        Description: Transactions status result identifier. The outcome of the issuer's authentication.

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

      payee_payment_method_preference

      • payee_payment_method_preference

        enum

        The possible values are:

        • UNRESTRICTED. Accepts any type of payment from the customer.
        • IMMEDIATE_PAYMENT_REQUIRED. Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status.

        Minimum length: 1.

        Maximum length: 255.

        Description: The merchant-preferred payment methods.

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

      payer

      • address

        object

        Description: The address of the payer. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. Also referred to as the billing address of the customer.

      • birth_date

        string

        Minimum length: 10.

        Maximum length: 10.

        Description: The birth date of the payer in YYYY-MM-DD format.

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

      • email_address

        string

        Maximum length: 254.

        Description: The email address of the payer.

        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])+)\]).

      • name

        object

        Description: The name of the payer. Supports only the given_name and surname properties.

      • payer_id

        string

        Read only.

        Minimum length: 13.

        Maximum length: 13.

        Description: The PayPal-assigned ID for the payer.

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

      • phone

        object

        Description: The phone number of the customer. Available only when you enable the Contact Telephone Number option in the Profile & Settings for the merchant's PayPal account. The phone.phone_number supports only national_number.

      • tax_info

        object

        Description: The tax information of the payer. Required only for Brazilian payer's. Both tax_id and tax_id_type are required.

      payer

      • address

        object

        Description: The address of the payer. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. Also referred to as the billing address of the customer.

      • email_address

        string

        Description: The email address of the payer.

      • name

        object

        Description: The name of the payer. Supports only the given_name and surname properties.

      • payer_id

        string

        Read only.

        Description: The PayPal-assigned ID for the payer.

      • phone

        object

        Description: The phone number of the customer. Available only when you enable the Contact Telephone Number option in the Profile & Settings for the merchant's PayPal account. The phone.phone_number supports only national_number.

      payer.address_portable

      • country_code

        string

        required

        Description: 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

        Maximum length: 300.

        Description: 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.

      • address_line_2

        string

        Maximum length: 300.

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

      • admin_area_1

        string

        Maximum length: 300.

        Description: 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.

      • admin_area_2

        string

        Maximum length: 120.

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

      • postal_code

        string

        Maximum length: 60.

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

      payer.name

      • given_name

        string

        Maximum length: 140.

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

      • surname

        string

        Maximum length: 140.

        Description: 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.

      payer.name

      • given_name

        string

        Maximum length: 140.

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

      • surname

        string

        Maximum length: 140.

        Description: 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.

      payment_method

      • payee_preferred

        enum

        The possible values are:

        • UNRESTRICTED. Accepts any type of payment from the customer.
        • IMMEDIATE_PAYMENT_REQUIRED. Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status.

        Description: The merchant-preferred payment methods.

      • payer_selected

        enum

        The possible values are:

        • PAYPAL_CREDIT. PayPal Credit.
        • PAYPAL. PayPal.

        Minimum length: 1.

        Description: The customer-selected payment method on the merchant site.

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

      • standard_entry_class_code

        enum

        The possible values are:

        • TEL. The API caller (merchant/partner) accepts authorization and payment information from a consumer over the telephone.
        • WEB. The API caller (merchant/partner) accepts Debit transactions from a consumer on their website.
        • CCD. Cash concentration and disbursement for corporate debit transaction. Used to disburse or consolidate funds. Entries are usually Optional high-dollar, low-volume, and time-critical. (e.g. intra-company transfers or invoice payments to suppliers).
        • PPD. Prearranged payment and deposit entries. Used for debit payments authorized by a consumer account holder, and usually initiated by a company. These are usually recurring debits (such as insurance premiums).

        Minimum length: 3.

        Maximum length: 255.

        Description: NACHA (the regulatory body governing the ACH network) requires that API callers (merchants, partners) obtain the consumer’s explicit authorization before initiating a transaction. To stay compliant, you’ll need to make sure that you retain a compliant authorization for each transaction that you originate to the ACH Network using this API. ACH transactions are categorized (using SEC codes) by how you capture authorization from the Receiver (the person whose bank account is being debited or credited). PayPal supports the following SEC codes.

      payment_token_resource

      • customer_id

        string

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

      • id

        string

        Description: The PayPal-generated ID for the token.

      • links

        array (contains the link_description object)

        Read only.

        Description: An array of related HATEOAS links.

      • source

        object

        Description: A payment token response which will contain information of one of the payment methods saved. These types can be one of Card or PayPal.

      • status

        enum

        The possible values are:

        • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
        • CREATED. The payment token has been vaulted.

        Description: The status of the payment token.

      payment_token_resource

      • customer_id

        string

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

      • id

        string

        Description: The PayPal-generated ID for the token.

      • links

        array (contains the link_description object)

        Read only.

        Description: An array of related HATEOAS links.

      • source

        object

        Description: Payment Method Response which will contain information of one of the payment methods vaulted. These types can be one of CARD, PAYPAL, BANK, etc.

      • status

        enum

        The possible values are:

        • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
        • CREATED. The payment token has been vaulted.

        Description: The status of the payment token.

      payment_token_status

      • payment_token_status

        enum

        The possible values are:

        • CUSTOMER_ACTION_REQUIRED. Before the payment method can be saved, the customer has to complete an action specific to the payment method.
        • CREATED. The payment token has been vaulted.

        Minimum length: 1.

        Maximum length: 255.

        Description: The status of payment token.

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

      paypal_wallet

      • customer_type

        enum

        The possible values are:

        • CONSUMER. The customer vaulting the PayPal payment token is a consumer on the merchant / platform.
        • BUSINESS. The customer vaulting the PayPal payment token is a business on merchant / platform.

        Minimum length: 1.

        Maximum length: 255.

        Description: The customer type associated with the PayPal payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer.

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

      • description

        string

        Minimum length: 1.

        Maximum length: 128.

        Description: The description displayed to PayPal consumer on the approval flow for PayPal, as well as on the PayPal payment token management experience on PayPal.com.

        Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

      • payment_method_preference

        enum

        The possible values are:

        • UNRESTRICTED. Accepts any type of payment from the customer.
        • IMMEDIATE_PAYMENT_REQUIRED. Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status.

        Minimum length: 1.

        Maximum length: 255.

        Description: The merchant-preferred payment methods.

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

      • product_label

        string

        Minimum length: 1.

        Maximum length: 25.

        Description: Merchant defined identifier uniquely identify merchant’s business and the usage of the PayPal payment token for the business. Please contact your PayPal Technical Account Manager to define the product_label for your business and how it can help your business. For details on product_label and different types of usages of a PayPal Payment Token, please refer to documentation. For a business with different type of usage of the payment method, a new product_label needs to be defined and a new PayPal Payment Token will be created. For including multiple businesses of same charge pattern, an existing product_label with the same charge pattern can be leveraged. Business can decide to use custom name for the product_label. If no product_label is specified, default policies will apply for PayPal payment method, irrespective of the nature of the business.

        Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

      • shipping

        object

        Description: The shipping address for the Payer.

      • usage_type

        enum

        The possible values are:

        • MERCHANT. The PayPal Payment Token will be used for future transaction directly with a merchant.
        • PLATFORM. The PayPal Payment Token will be used for future transaction on a platform. A platform is typically a marketplace or a channel that a payer can purchase goods and services from multiple merchants.

        Minimum length: 1.

        Maximum length: 255.

        Description: The usage type associated with the PayPal payment token.

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

      paypal_wallet.shipping_detail

      • address

        object

        Description: The address of the person to whom to ship the items. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

      • name

        object

        Description: The name of the person to whom to ship the items. Supports only the full_name property.

      paypal_wallet_request

      • customer_type

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The customer type associated with the PayPal payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer.

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

      • description

        string

        Minimum length: 1.

        Maximum length: 128.

        Description: The description displayed to PayPal consumer on the approval flow for PayPal, as well as on the PayPal payment token management experience on PayPal.com.

        Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

      • payment_method_preference

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The merchant-preferred payment methods.

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

      • product_label

        string

        Minimum length: 1.

        Maximum length: 25.

        Description: Merchant defined identifier uniquely identify merchant’s business and the usage of the PayPal payment token for the business. Please contact your PayPal Technical Account Manager to define the product_label for your business and how it can help your business. For details on product_label and different types of usages of a PayPal Payment Token, please refer to documentation. For a business with different type of usage of the payment method, a new product_label needs to be defined and a new PayPal Payment Token will be created. For including multiple businesses of same charge pattern, an existing product_label with the same charge pattern can be leveraged. Business can decide to use custom name for the product_label. If no product_label is specified, default policies will apply for PayPal payment method, irrespective of the nature of the business.

        Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

      • shipping

        object

        Description: The shipping address for the Payer.

      • usage_type

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The usage type associated with the PayPal payment token.

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

      paypal_wallet_response

      • customer_type

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The customer type associated with the PayPal payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer.

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

      • description

        string

        Minimum length: 1.

        Maximum length: 128.

        Description: The description displayed to PayPal consumer on the approval flow for PayPal, as well as on the PayPal payment token management experience on PayPal.com.

        Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

      • payment_method_preference

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The merchant-preferred payment methods.

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

      • product_label

        string

        Minimum length: 1.

        Maximum length: 25.

        Description: Merchant defined identifier uniquely identify merchant’s business and the usage of the PayPal payment token for the business. Please contact your PayPal Technical Account Manager to define the product_label for your business and how it can help your business. For details on product_label and different types of usages of a PayPal Payment Token, please refer to documentation. For a business with different type of usage of the payment method, a new product_label needs to be defined and a new PayPal Payment Token will be created. For including multiple businesses of same charge pattern, an existing product_label with the same charge pattern can be leveraged. Business can decide to use custom name for the product_label. If no product_label is specified, default policies will apply for PayPal payment method, irrespective of the nature of the business.

        Pattern: ^[a-zA-Z0-9_'\-., :;\!?"]*$.

      • shipping

        object

        Description: The shipping address for the Payer.

      • usage_type

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: The usage type associated with the PayPal payment token.

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

      • payer

        object

        Description: The PayPal payer account associated with the wallet.

      phone

      • country_code

        string

        required

        Minimum length: 1.

        Maximum length: 3.

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

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

      • national_number

        string

        required

        Minimum length: 1.

        Maximum length: 14.

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

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

      • extension_number

        string

        Minimum length: 1.

        Maximum length: 15.

        Description: The extension number.

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

      phone_type

      • phone_type

        enum

        Possible values: FAX,HOME,MOBILE,OTHER,PAGER.

        Description: The phone type.

      phone_with_type

      • phone_number

        object

        required

        Description: The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.

      • phone_type

        enum

        Possible values: FAX,HOME,MOBILE,OTHER,PAGER.

        Description: The phone type.

      phone_with_type.phone

      • national_number

        string

        required

        Minimum length: 1.

        Maximum length: 14.

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

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

      processor_response

      • avs_code

        enum

        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.

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

      • cvv_code

        enum

        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.

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

      • payment_advice_code

        enum

        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.

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

      • response_code

        enum

        The possible values are:

        • 0000. APPROVED.
        • 0100. REFERRAL.
        • 0800. BAD_RESPONSE_REVERSAL_REQUIRED.
        • 1000. PARTIAL_AUTHORIZATION.
        • 1300. INVALID_DATA_FORMAT.
        • 1310. INVALID_AMOUNT.
        • 1312. INVALID_TRANSACTION_CARD_ISSUER_ACQUIRER.
        • 1317. INVALID_CAPTURE_DATE.
        • 1320. INVALID_CURRENCY_CODE.
        • 1330. INVALID_ACCOUNT.
        • 1335. INVALID_ACCOUNT_RECURRING.
        • 1340. INVALID_TERMINAL.
        • 1350. INVALID_MERCHANT.
        • 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.
        • 0500. DO_NOT_HONOR.
        • 5100. GENERIC_DECLINE.
        • 5110. CVV2_FAILURE.
        • 5120. INSUFFICIENT_FUNDS.
        • 5130. INVALID_PIN.
        • 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.
        • 5800. REVERSAL_REJECTED.
        • 5900. INVALID_ISSUE.
        • 5910. ISSUER_NOT_AVAILABLE_NOT_RETRIABLE.
        • 5920. ISSUER_NOT_AVAILABLE_RETRIABLE.
        • 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.
        • 5930. CARD_NOT_ACTIVATED.
        • PPMD. PPMD.
        • PPCE. CE_REGISTRATION_INCOMPLETE.
        • PPNT. NETWORK_ERROR.
        • PPCT. CARD_TYPE_UNSUPPORTED.
        • PPTT. TRANSACTION_TYPE_UNSUPPORTED.
        • PPCU. CURRENCY_USED_INVALID.
        • PPQC. QUASI_CASH_UNSUPPORTED.
        • PPVE. VALIDATION_ERROR.
        • PPVT. VIRTUAL_TERMINAL_UNSUPPORTED.
        • PPDC. DCC_UNSUPPORTED.
        • PPER. INTERNAL_SYSTEM_ERROR.
        • PPIM. ID_MISMATCH.
        • PPH1. H1_ERROR.
        • PPSD. STATUS_DESCRIPTION.
        • PPAG. ADULT_GAMING_UNSUPPORTED.
        • PPLS. LARGE_STATUS_CODE.
        • PPCO. COUNTRY.
        • PPAD. BILLING_ADDRESS.
        • PPAU. MCC_CODE.
        • PPUC. CURRENCY_CODE_UNSUPPORTED.
        • PPUR. UNSUPPORTED_REVERSAL.
        • PPVC. VALIDATE_CURRENCY.
        • PPS0. BANKAUTH_ROW_MISMATCH.
        • PPS1. BANKAUTH_ROW_SETTLED.
        • PPS2. BANKAUTH_ROW_VOIDED.
        • PPS3. BANKAUTH_EXPIRED.
        • PPS4. CURRENCY_MISMATCH.
        • PPS5. CREDITCARD_MISMATCH.
        • PPS6. AMOUNT_MISMATCH.
        • PPRF. INVALID_PARENT_TRANSACTION_STATUS.
        • PPEX. EXPIRY_DATE.
        • PPAX. AMOUNT_EXCEEDED.
        • PPDV. AUTH_MESSAGE.
        • PPDI. DINERS_REJECT.
        • PPAR. AUTH_RESULT.
        • PPBG. BAD_GAMING.
        • PPGR. GAMING_REFUND_ERROR.
        • PPCR. CREDIT_ERROR.
        • PPAI. AMOUNT_INCOMPATIBLE.
        • PPIF. IDEMPOTENCY_FAILURE.
        • PPMC. BLOCKED_Mastercard.
        • PPAE. AMEX_DISABLED.
        • PPFV. FIELD_VALIDATION_FAILED.
        • PPII. INVALID_INPUT_FAILURE.
        • PPPM. INVALID_PAYMENT_METHOD.
        • PPUA. USER_NOT_AUTHORIZED.
        • PPFI. INVALID_FUNDING_INSTRUMENT.
        • PPEF. EXPIRED_FUNDING_INSTRUMENT.
        • PPFR. RESTRICTED_FUNDING_INSTRUMENT.
        • PPEL. EXCEEDS_FREQUENCY_LIMIT.
        • PCVV. CVV_FAILURE.
        • PPTV. INVALID_VERIFICATION_TOKEN.
        • PPTE. VERIFICATION_TOKEN_EXPIRED.
        • PPPI. INVALID_PRODUCT.
        • PPIT. INVALID_TRACE_ID.
        • PPTF. INVALID_TRACE_REFERENCE.
        • PPFE. FUNDING_SOURCE_ALREADY_EXISTS.
        • PPTR. VERIFICATION_TOKEN_REVOKED.
        • PPTI. INVALID_TRANSACTION_ID.
        • PPD3. SECURE_ERROR_3DS.
        • PPPH. NO_PHONE_FOR_DCC_TRANSACTION.
        • PPAV. ARC_AVS.
        • PPC2. ARC_CVV.
        • PPLR. LATE_REVERSAL.
        • PPNC. NOT_SUPPORTED_NRC.
        • PPRR. MERCHANT_NOT_REGISTERED.
        • PPSC. ARC_SCORE.
        • PPSE. AMEX_DENIED.
        • PPUE. UNSUPPORT_ENTITY.
        • PPUI. UNSUPPORT_INSTALLMENT.
        • PPUP. UNSUPPORT_POS_FLAG.
        • PPRE. UNSUPPORT_REFUND_ON_PENDING_BC.

        Read only.

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

      shipping_detail

      • address

        object

        Description: The address of the person to whom to ship the items. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

      • name

        object

        Description: The name of the person to whom to ship the items. Supports only the full_name property.

      • options

        array (contains the shipping_option object)

        Description: An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.

      shipping_detail.address_portable

      • country_code

        string

        required

        Description: 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

        Maximum length: 300.

        Description: 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.

      • address_line_2

        string

        Maximum length: 300.

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

      • admin_area_1

        string

        Maximum length: 300.

        Description: 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.

      • admin_area_2

        string

        Maximum length: 120.

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

      • postal_code

        string

        Maximum length: 60.

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

      shipping_detail.address_portable

      • country_code

        string

        required

        Description: 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

        Maximum length: 300.

        Description: 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.

      • address_line_2

        string

        Maximum length: 300.

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

      • admin_area_1

        string

        Maximum length: 300.

        Description: 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.

      • admin_area_2

        string

        Maximum length: 120.

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

      • postal_code

        string

        Maximum length: 60.

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

      shipping_detail.name

      • full_name

        string

        Maximum length: 300.

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

      shipping_detail.name

      • full_name

        string

        Maximum length: 300.

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

      shipping_option

      • id

        string

        required

        Maximum length: 127.

        Description: A unique ID that identifies a payer-selected shipping option.

      • label

        string

        required

        Maximum length: 127.

        Description: A description that the payer sees, which helps them choose an appropriate shipping option. For example, Free Shipping, USPS Priority Shipping, Expédition prioritaire USPS, or USPS yōuxiān fā huò. Localize this description to the payer's locale.

      • selected

        boolean

        required

        Description: If the API request sets selected = true, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the shipping.options in the PayPal Checkout experience. As part of the response if a shipping.option contains selected=true, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only one shipping.option can be set to selected=true.

      • amount

        object

        Description: The shipping cost for the selected option.

      • type

        enum

        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.

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

      shipping_type

      • shipping_type

        enum

        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.

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

      signature_verification_status

      • signature_verification_status

        enum

        The possible values are:

        • YES. Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted.
        • NO. Indicates that the PARes could not be validated.

        Minimum length: 1.

        Maximum length: 50.

        Description: Transaction signature status identifier.

        Pattern: ^[A-Z]+$.

      source_request

      • card

        Description: Creates a token representing a card and gives an option to verify the card prior to saving in the Vault.

      • paypal

        object

        Description: A Resource representing a Request to Vault PayPal Wallet.

      source_response

      • card

        object

        Description: Full representation of a Card Payment Token.

      • paypal

        object

        Description: Full representation of a PayPal Payment Token.

      source_response

      • card

        object

        Description: The payment card to use to fund a payment. Card can be a credit or debit card.

      • paypal

        object

        Description: Full representation of a PayPal Payment Token.

      tax_info

      • tax_id

        string

        required

        Maximum length: 14.

        Description: The customer's tax ID. Supported for the PayPal payment method only. Typically, the tax ID is 11 characters long for individuals and 14 characters long for businesses.

      • tax_id_type

        enum

        required

        The possible values are:

        • BR_CPF. The individual tax ID type.
        • BR_CNPJ. The business tax ID type.

        Description: The customer's tax ID type. Supported for the PayPal payment method only.

      token_request

      • source

        object

        required

        Description: The payment method to vault with the instrument details.

      • application_context

        object

        Description: Customizes the Vault creation flow experience for your customers.

      • customer_id

        string

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

      ucaf_indicator

      • ucaf_indicator

        enum

        The possible values are:

        • NON_SECURECODE_TRANSACTION. Non-SecureCode transaction, bypassed by the merchant.
        • MERCHANT_ONLY_SECURECODE_TRANSACTION. Merchant-Only SecureCode transaction.
        • FULLY_AUTHENTICATED_SECURECODE. Fully authenticated SecureCode.

        Minimum length: 1.

        Maximum length: 255.

        Description: Universal Cardholder Authentication Field (UCAF) Indicator value provided by the issuer.

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

      vault

      • customer_id

        string

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

      • links

        array (contains the link_description object)

        Read only.

        Description: An array of related HATEOAS links.

      • payment_tokens

        array (contains the min_vault_resource object)

      • total_items

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: Total number of items.

        Pattern: ^[0-9]+$.

      • total_pages

        string

        Minimum length: 1.

        Maximum length: 255.

        Description: Total number of pages.

        Pattern: ^[0-9]+$.

      Additional API information

      ReferencePayPal.comPrivacyCookiesSupportLegalContact