Payment Method Tokens (3)

The Payment Method Tokens API saves payment methods so payers don't have to enter details for future transactions. Payers can check out faster or pay without being present after they agree to save a payment method.

The API associates a payment method with a temporary setup token. Pass the setup token to the API to exchange the setup token for a permanent token.

The permanent token represents a payment method that's saved to the vault. This token can be used repeatedly for checkout or recurring transactions such as subscriptions.

The Payment Method Tokens API is available in the US only.

Create payment token for a given payment source

post/v3/vault/payment-tokens

Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer.

SecurityOauth2
Request
header Parameters
Content-Type
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

Specifies the request format.

Authorization
required
string

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

PayPal-Request-Id
required
string

The server stores keys for 3 hours.

Request Body schema: application/json

Payment Token creation with a financial instrument and an optional customer_id.

required
object (Payment source request)

The payment method to vault with the instrument details.

object (customer)

Customer in merchant's or partner's system of records.

Responses
201

A successful creation of payment token.

Request samples
application/json
{
  • "payment_source": {
    • "token": {
      • "id": "5C991763VB2781612",
      • "type": "SETUP_TOKEN"
      }
    }
}
Response samples
application/json
{
  • "id": "8kk8451t",
  • "customer": {
    • "id": "BygeLlrpZF",
    • "merchant_customer_id": "customer@merchant.com"
    },
  • "payment_source": {
    • "card": {
      • "brand": "VISA",
      • "last_digits": "1111",
      • "expiry": "2027-02",
      • "name": "John Doe",
      • "billing_address": {
        • "address_line_1": "2211 N First Street",
        • "address_line_2": "17.3.160",
        • "admin_area_2": "San Jose",
        • "admin_area_1": "CA",
        • "postal_code": "95131",
        • "country_code": "US"
        }
      }
    },
  • "links": []
}

List all payment tokens

get/v3/vault/payment-tokens

Returns all payment tokens for a customer.

SecurityOauth2
Request
query Parameters
customer_id
required
string [ 7 .. 36 ] characters ^[0-9a-zA-Z_-]+$

A unique identifier representing a specific customer in merchant's/partner's system or records.

page_size
integer >= 1
Default: 5

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

page
integer >= 1
Default: 1

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

total_required
boolean
Default: false

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

header Parameters
Authorization
required
string

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

Content-Type
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

Specifies the request format.

Responses
200

Successful execution.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=BygeLlrpZF \
-H 'Authorization: Bearer FULL_scoped_access_token'
Response samples
application/json
{}

Retrieve a payment token

get/v3/vault/payment-tokens/{id}

Returns a readable representation of vaulted payment source associated with the payment token id.

SecurityOauth2
Request
path Parameters
id
required
string <= 36 characters ^[0-9a-zA-Z_-]+$

ID of the payment token.

header Parameters
Authorization
required
string

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

Content-Type
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

Specifies the request format.

Responses
200

Successful execution.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/8kk8451t \
-H 'Authorization: Bearer FULL_scoped_access_token'
Response samples
application/json
{
  • "id": "8kk8451t",
  • "customer": {
    • "id": "BygeLlrpZF",
    • "merchant_customer_id": "customer@merchant.com"
    },
  • "payment_source": {
    • "card": {
      • "last_digits": "1111",
      • "expiry": "2027-02",
      • "brand": "VISA",
      • "name": "John Doe",
      • "billing_address": {
        • "id": "kk",
        • "address_line_1": "2211 N First Street",
        • "address_line_2": "17.3.160",
        • "admin_area_2": "San Jose",
        • "admin_area_1": "CA",
        • "postal_code": "95131",
        • "country_code": "US"
        }
      }
    },
  • "links": []
}

Delete payment token

delete/v3/vault/payment-tokens/{id}

Delete the payment token associated with the payment token id.

SecurityOauth2
Request
path Parameters
id
required
string <= 36 characters ^[0-9a-zA-Z_-]+$

ID of the payment token.

header Parameters
Content-Type
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

Specifies the request format.

Authorization
required
string

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

Responses
204

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

Request samples 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/8kk8451t \
-H 'Authorization: Bearer FULL_scoped_access_token'

Create a setup token

post/v3/vault/setup-tokens

Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.

SecurityOauth2
Request
header Parameters
Content-Type
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

Specifies the request format.

Authorization
required
string

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

PayPal-Request-Id
required
string

The server stores keys for 3 hours.

Request Body schema: application/json

Setup Token creation with a instrument type optional financial instrument details and customer_id.

required
object

The payment method to vault with the instrument details.

object (customer)

Customer in merchant's or partner's system of records.

Responses
201

A successful creation of setup token.

Request samples
application/json
{
  • "payment_source": {
    • "card": {
      • "number": "4111111111111111",
      • "expiry": "2027-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"
        },
      • "experience_context": {}
      }
    },
  • "customer": {
    • "id": "BygeLlrpZF",
    • "merchant_customer_id": "customer@merchant.com"
    }
}
Response samples
application/json
{
  • "id": "5C991763VB2781612",
  • "customer": {
    • "id": "BygeLlrpZF",
    • "merchant_customer_id": "customer@merchant.com"
    },
  • "status": "APPROVED",
  • "payment_source": {
    • "card": {
      • "last_digits": "1111",
      • "expiry": "2027-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"
        },
      • "bin_details": {
        • "bin": "411111",
        • "issuing_bank": "Advantage One Federal Credit Union",
        • "products": [
          • "CREDIT"
          ],
        • "bin_country_code": "US"
        }
      }
    },
  • "links": []
}

Retrieve a setup token

get/v3/vault/setup-tokens/{id}

Returns a readable representation of temporarily vaulted payment source associated with the setup token id.

SecurityOauth2
Request
path Parameters
id
required
string [ 7 .. 36 ] characters ^[0-9a-zA-Z_-]+$

ID of the setup token.

header Parameters
Authorization
required
string

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

Content-Type
string [ 1 .. 255 ] characters ^[A-Za-z0-9/+-]+$

Specifies the request format.

Responses
200

Found requested setup-token, returned a payment method associated with the token.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612 \
-H 'Authorization: Bearer LOW_scoped_access_token' \
-H 'Content-Type: application/json' \
-H 'PayPal-Request-ID: b5efbe82-bbad-4bb0-aeeb-bfef5b442e49'
Response samples
application/json
{
  • "id": "5C991763VB2781612",
  • "customer": {
    • "id": "BygeLlrpZF",
    • "merchant_customer_id": "customer@merchant.com"
    },
  • "status": "APPROVED",
  • "payment_source": {
    • "card": {
      • "last_digits": "1111",
      • "expiry": "2027-02",
      • "name": "John Doe",
      • "billing_address": {
        • "address_line_1": "2211 N First Street",
        • "address_line_2": "17.3.160",
        • "admin_area_2": "San Jose",
        • "admin_area_1": "CA",
        • "postal_code": "95131",
        • "country_code": "US"
        }
      }
    },
  • "links": []
}

Errors

CARD_EXPIRATION_YEAR_IS_INVALID

Message:
Expiration year outside of acceptable range.

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

CREDIT_CARD_NUMBER_IS_INVALID

Message:
Credit card number is invalid.

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

EXACTLY_ONE_FIELD_REQUIRED

Message:
Exactly one payment source is required.

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

INTERNAL_SERVER_ERROR

Message:
A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.

Description: An internal server error occurred.

INVALID_EXPIRY_DATE

Message:
Expiry date is invalid. Expiry date should be a date in future and within the threshold for the payment source.

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

INVALID_INTEGER_MIN_VALUE

Message:
The integer value of a field is too small.

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

INVALID_PARAMETER_SYNTAX

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

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

INVALID_SECURITY_CODE

Message:
The security code provided does not conform to the card number provided.

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

INVALID_STRING_LENGTH

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

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

INVALID_STRING_MAX_LENGTH

Message:
The value of a field is too long.

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

MALFORMED_REQUEST_JSON

Message:
The request JSON is not well formed.

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

MISSING_REQUIRED_PARAMETER

Message:
A required field / parameter is missing.

Description: The request is not well-formed, is syntactically incorrect, or violates schema.

NOT_ENABLED_TO_VAULT_PAYMENT_SOURCE

Message:
The API caller or the merchant on whose behalf the API call is initiated is not allowed to vault the given source. Please contact PayPal customer support for assistance.

Description: Authorization failed due to insufficient permissions.

OPERATION_NOT_SUPPORTED

Message:
Specified operation not supported on any fields.

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

PAYER_ACTION_REQUIRED

Message:
Please make sure setup up token is approved. Please complete the approval flow Payer Approval.

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

PAYPAL_REQUEST_ID_PREVIOUSLY_USED

Message:
The PayPal-Request-ID has already been used for another request.

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

PERMISSION_DENIED

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

Description: Authorization failed due to insufficient permissions.

RESOURCE_NOT_FOUND

Message:
The specified resource does not exist.

Description: The requested resource ID was not found

SETUP_TOKEN_ALREADY_TOKENIZED

Message:
The setup token has been used previously to generate a payment token.

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

SETUP_TOKEN_NOT_TOKENIZED

Message:
The payment source represented by this setup token is not vaulted.

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

TOKEN_NOT_FOUND

Message:
The specified token id does not exist.

Description: The requested resource ID was not found.

Definitions

Account Registration Type

The level of customer registration for the PayPal account.

string (Account Registration Type) [ 1 .. 255 ] characters ^[A-Z0-9_]+$

The level of customer registration for the PayPal account.

Value: Description
ANONYMOUS

Anonymous account. The user does not even know that they have used PayPal. Typically used for the counterparty in a DCC or VT scenario where a merchant is directly charging a credit card.

"ANONYMOUS"

Address request details.

Address request details.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

id
string [ 1 .. 36 ] characters ^[0-9A-Za-z-_]+$

The resource ID of the address.

company
string [ 1 .. 100 ] characters ^.*$

The name of the company or business associated to the address.

phone
string [ 1 .. 16 ] characters ^\+[1-9]\d{1,14}$

The phone number that can go on the mailing label with the address to track the shipping. Phone number is in E.164 format.

object (Name)

The name of the party.

object (Phone)

Phone number associated to the address.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st",
  • "id": "string",
  • "company": "string",
  • "phone": "string",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone_number": {
    • "country_code": "str",
    • "national_number": "string",
    • "extension_number": "string"
    }
}

apple_pay_card

The payment card to be used to fund a payment. Can be a credit or debit card.

name
string [ 1 .. 300 ] characters ^.{1,300}$

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

last_digits
string [ 2 .. 4 ] characters ^[0-9]{2,4}$

The last digits of the payment card.

type
string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

The payment card type.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

object (Portable Postal Address (Medium-Grained))

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",
  • "last_digits": "stri",
  • "type": "CREDIT",
  • "brand": "VISA",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

apple_pay_payment_token_response

A resource representing a response for Apple Pay.

object (apple_pay_card)

Card data for the card linked to the apple pay token.

{
  • "card": {
    • "name": "string",
    • "last_digits": "stri",
    • "type": "CREDIT",
    • "brand": "VISA",
    • "billing_address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    }
}

authentication_response

Results of Authentication such as 3D Secure.

object (three_d_secure_authentication_response)

Results of 3D Secure Authentication.

{
  • "three_d_secure": {
    • "authentication_status": "Y",
    • "enrollment_status": "Y"
    }
}

Authorization details

Authorization details.

authorization_codes
Array of strings [ 1 .. 50 ] items ^[-._0-9a-zA-Z]+$

An array of the PayPal generated authorization codes. These codes can be based on the issuer specification.

status
string (The authorization status) [ 1 .. 100 ] characters ^[0-9A-Z_]+$

Instrument authorization status.

Enum: Description
AUTHORIZED

The authorization status is authorized.

BLOCKED

The authorization status is blocked.

FAILED

The authorization status is failed.

NOT_APPLICABLE

Authorization not applicable.

NOT_SUPPORTED

Authorization not supported.

UNAUTHORIZED

The authorization status is unauthorized.

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

The date and time when the instrument was authorized, in Internet date and time format.

{
  • "authorization_codes": [
    • "string"
    ],
  • "status": "AUTHORIZED",
  • "time_authorized": "stringstringstringst"
}

authorization_id

A unique identifier for the financial instrument authorization sub-resource within the PayPal System.

string (authorization_id) [ 1 .. 255 ] characters ^[A-Za-z0-9-_.+/=]*

A unique identifier for the financial instrument authorization sub-resource within the PayPal System.

"string"

bank_authorization_details

The details of Bank mandate authorization

authorization_codes
Array of strings [ 1 .. 50 ] items ^[-._0-9a-zA-Z]+$

An array of the PayPal generated authorization codes. These codes can be based on the issuer specification.

status
string (The authorization status) [ 1 .. 100 ] characters ^[0-9A-Z_]+$

Instrument authorization status.

Enum: Description
AUTHORIZED

The authorization status is authorized.

BLOCKED

The authorization status is blocked.

FAILED

The authorization status is failed.

NOT_APPLICABLE

Authorization not applicable.

NOT_SUPPORTED

Authorization not supported.

UNAUTHORIZED

The authorization status is unauthorized.

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

The date and time when the instrument was authorized, in Internet date and time format.

type
string [ 1 .. 255 ] characters ^[A-Z_]+$

Represents the type of mandate.

{
  • "authorization_codes": [
    • "string"
    ],
  • "status": "AUTHORIZED",
  • "time_authorized": "stringstringstringst",
  • "type": "string"
}

bank_response

Full representation of a Bank Payment Token.

object (bank_response)

Full representation of a Bank Payment Token.

{ }

bin_details

Bank Identification Number (BIN) details used to fund a payment.

bin
string [ 1 .. 25 ] characters ^[0-9]+$

The Bank Identification Number (BIN) signifies the number that is being used to identify the granular level details (except the PII information) of the card.

issuing_bank
string [ 1 .. 64 ] characters

The issuer of the card instrument.

products
Array of strings [ 1 .. 256 ] items

The type of card product assigned to the BIN by the issuer. These values are defined by the issuer and may change over time. Some examples include: PREPAID_GIFT, CONSUMER, CORPORATE.

bin_country_code
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$
{
  • "bin": "string",
  • "issuing_bank": "string",
  • "products": [
    • "string"
    ],
  • "bin_country_code": "string"
}

card

The payment card to use to fund a payment. Can be a credit or debit card.

name
string [ 1 .. 300 ] characters ^.{1,300}$

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

number
string [ 13 .. 19 ] characters ^[0-9]{13,19}$

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

last_digits
string [ 2 .. 4 ] characters ^[0-9]{2,4}$

The last digits of the payment card.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

type
string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

The payment card type.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

object (Portable Postal Address (Medium-Grained))

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",
  • "number": "stringstrings",
  • "last_digits": "stri",
  • "expiry": "string",
  • "type": "CREDIT",
  • "brand": "VISA",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

card

The payment card to use to fund a payment. Can be a credit or debit card.

name
string [ 1 .. 300 ] characters ^.{1,300}$

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

number
required
string [ 13 .. 19 ] characters ^[0-9]{13,19}$

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

security_code
string [ 3 .. 4 ] characters ^[0-9]{3,4}$

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

expiry
required
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

object (Portable Postal Address (Medium-Grained))

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",
  • "number": "stringstrings",
  • "security_code": "stri",
  • "expiry": "string",
  • "brand": "VISA",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

Card Verification

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

method
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "SCA_WHEN_REQUIRED"

The method used for card verification.

Enum: Description
SCA_ALWAYS

Selecting this option will attempt to force a strong customer authentication for the authorization/transaction. In countries where SCA has been defined and implemented it will result in a contingency and HATEOAS link being returned. The API caller should redirect the payer to that link so that they can authenticate themselves against their issuing bank or other entity. As noted, the HATEOAS link is only available in all regions where strong authentication is supported, (e.g. in European countries where 3DS is live). Merchants can use this setting as an additional layer of security if they choose to. In all cases, when an authorization is requested the AVS/CVV results will be returned in the response.

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.

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.

{
  • "method": "SCA_ALWAYS"
}

card_attributes

Additional attributes associated with the use of this card.

object (card_customer)

The details about a customer in PayPal's system of record.

object (vault_instruction_base)

Instruction to vault the card based on the specified strategy.

object (Card Verification)

Instruction to optionally verify the card based on the specified strategy.

{
  • "customer": {
    • "id": "string",
    • "email_address": "string",
    • "phone": {
      • "phone_type": "FAX",
      • "phone_number": {
        • "national_number": "string"
        }
      },
    • "merchant_customer_id": "string"
    },
  • "vault": {
    • "store_in_vault": "ON_SUCCESS"
    },
  • "verification": {
    • "method": "SCA_ALWAYS"
    }
}

card_brand

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

string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

"VISA"

card_customer

The details about a customer in PayPal's system of record.

id
string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$

The unique ID for a customer generated by PayPal.

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

Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer.

object (phone_with_type)

The phone number of the buyer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number.

merchant_customer_id
string [ 1 .. 64 ] characters ^[0-9a-zA-Z-_.^*$@#]+$

Merchants and partners may already have a data-store where their customer information is persisted. Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer.

{
  • "id": "string",
  • "email_address": "string",
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    },
  • "merchant_customer_id": "string"
}

card_request

A Resource representing a request to vault a Card.

name
string [ 1 .. 300 ] characters ^.{1,300}$

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

number
string [ 13 .. 19 ] characters ^[0-9]{13,19}$

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

security_code
string [ 3 .. 4 ] characters ^[0-9]{3,4}$

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

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

object (Portable Postal Address (Medium-Grained))

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",
  • "number": "stringstrings",
  • "security_code": "stri",
  • "expiry": "string",
  • "brand": "VISA",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

card_request

A Resource representing a request to vault a Card.

name
string [ 1 .. 300 ] characters ^.{1,300}$

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

number
string [ 13 .. 19 ] characters ^[0-9]{13,19}$

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

security_code
string [ 3 .. 4 ] characters ^[0-9]{3,4}$

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

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

object (Portable Postal Address (Medium-Grained))

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.

object (experience_context)

Customizes the Vault creation flow experience for your customers.

verification_method
string (card_verification_method) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

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

{
  • "name": "string",
  • "number": "stringstrings",
  • "security_code": "stri",
  • "expiry": "string",
  • "brand": "VISA",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    },
  • "experience_context": {},
  • "verification_method": "string"
}

card_response

Full representation of a Card Payment Token including network token.

name
string [ 2 .. 300 ] characters ^[A-Za-z ]+$

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

last_digits
string [ 2 .. 4 ] characters [0-9]{2,}

The last digits of the payment card.

object (card_verification_details)

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

object (network_transaction_reference_response)

Previous network transaction reference including id in response.

object (authentication_response)

Results of Authentication such as 3D Secure.

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

object (Address request details.)

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.

verification_status
string (card_verification_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Card Verification status.

object (bin_details)

Bank Identification Number (BIN) details used to fund a payment.

type
string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

The payment card type.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

{
  • "name": "string",
  • "last_digits": "stri",
  • "verification": {
    • "network_transaction_id": "string",
    • "date": "stri",
    • "network": "VISA",
    • "time": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "processor_response": {
      • "avs_code": "A",
      • "cvv_code": "E"
      }
    },
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA",
    • "time": "stringstringstringst"
    },
  • "authentication_result": {
    • "three_d_secure": {
      • "authentication_status": "Y",
      • "enrollment_status": "Y"
      }
    },
  • "brand": "VISA",
  • "expiry": "strings",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "id": "string",
    • "company": "string",
    • "phone": "string",
    • "name": {
      • "given_name": "string",
      • "surname": "string"
      },
    • "phone_number": {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string"
      }
    },
  • "verification_status": "string",
  • "bin_details": {
    • "bin": "string",
    • "issuing_bank": "string",
    • "products": [
      • "string"
      ],
    • "bin_country_code": "string"
    },
  • "type": "CREDIT"
}

card_response

Full representation of a Card Payment Token including network token.

name
string [ 2 .. 300 ] characters ^[A-Za-z ]+$

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

last_digits
string [ 2 .. 4 ] characters [0-9]{2,}

The last digits of the payment card.

object (card_verification_details)

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

object (network_transaction_reference_response)

Previous network transaction reference including id in response.

object (authentication_response)

Results of Authentication such as 3D Secure.

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

object (Address request details.)

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.

verification_status
string (card_verification_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Card Verification status.

object (bin_details)

Bank Identification Number (BIN) details used to fund a payment.

type
string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

The payment card type.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

{
  • "name": "string",
  • "last_digits": "stri",
  • "verification": {
    • "network_transaction_id": "string",
    • "date": "stri",
    • "network": "VISA",
    • "time": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "processor_response": {
      • "avs_code": "A",
      • "cvv_code": "E"
      }
    },
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA",
    • "time": "stringstringstringst"
    },
  • "authentication_result": {
    • "three_d_secure": {
      • "authentication_status": "Y",
      • "enrollment_status": "Y"
      }
    },
  • "brand": "VISA",
  • "expiry": "strings",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "id": "string",
    • "company": "string",
    • "phone": "string",
    • "name": {
      • "given_name": "string",
      • "surname": "string"
      },
    • "phone_number": {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string"
      }
    },
  • "verification_status": "string",
  • "bin_details": {
    • "bin": "string",
    • "issuing_bank": "string",
    • "products": [
      • "string"
      ],
    • "bin_country_code": "string"
    },
  • "type": "CREDIT"
}

card_response_entity

Full representation of a Card Payment Token.

name
string [ 2 .. 300 ] characters ^[A-Za-z ]+$

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

last_digits
string [ 2 .. 4 ] characters [0-9]{2,}

The last digits of the payment card.

object (card_verification_details)

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

object (network_transaction_reference_response)

Previous network transaction reference including id in response.

object (authentication_response)

Results of Authentication such as 3D Secure.

brand
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

object (Address request details.)

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.

verification_status
string (card_verification_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Card Verification status.

object (bin_details)

Bank Identification Number (BIN) details used to fund a payment.

type
string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

The payment card type.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

{
  • "name": "string",
  • "last_digits": "stri",
  • "verification": {
    • "network_transaction_id": "string",
    • "date": "stri",
    • "network": "VISA",
    • "time": "string",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "processor_response": {
      • "avs_code": "A",
      • "cvv_code": "E"
      }
    },
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA",
    • "time": "stringstringstringst"
    },
  • "authentication_result": {
    • "three_d_secure": {
      • "authentication_status": "Y",
      • "enrollment_status": "Y"
      }
    },
  • "brand": "VISA",
  • "expiry": "strings",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "id": "string",
    • "company": "string",
    • "phone": "string",
    • "name": {
      • "given_name": "string",
      • "surname": "string"
      },
    • "phone_number": {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string"
      }
    },
  • "verification_status": "string",
  • "bin_details": {
    • "bin": "string",
    • "issuing_bank": "string",
    • "products": [
      • "string"
      ],
    • "bin_country_code": "string"
    },
  • "type": "CREDIT"
}

card_type

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

string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

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

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

"CREDIT"

card_verification_details

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

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

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

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

The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date".

network
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

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

The date and time when the instrument was verified.

object (Money)

The amount used for card verification.

object (processor_response)

The processor information.

{
  • "network_transaction_id": "string",
  • "date": "stri",
  • "network": "VISA",
  • "time": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "processor_response": {
    • "avs_code": "A",
    • "cvv_code": "E"
    }
}

card_verification_method

The verification method of the card.

string (card_verification_method) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The verification method of the card.

"string"

card_verification_status

Verification status of Card.

string (card_verification_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Verification status of Card.

"string"

country_code

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

"st"

country_code

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

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

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

"st"

currency_code

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

string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

"str"

customer

Customer in merchant's or partner's system of records.

merchant_customer_id
string [ 1 .. 64 ] characters ^[0-9a-zA-Z-_.^*$@#]+$

Merchants and partners may already have a data-store where their customer information is persisted. Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer.

id
string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$

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

{
  • "merchant_customer_id": "string",
  • "id": "string"
}

customer

The details about a customer in PayPal's system of record.

id
string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$

The unique ID for a customer generated by PayPal.

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

Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer.

object (phone_with_type)

The phone number of the buyer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number.

{
  • "id": "string",
  • "email_address": "string",
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    }
}

date_no_time

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.

string <ppaas_date_notime_v2> (date_no_time) = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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.

"stringstri"

date_time

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

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

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

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

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

"stringstringstringst"

date_year_month

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

string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

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

"strings"

digital_wallet

Resource consolidating common request and response attributes for vaulting a Digital Wallet.

description
string [ 1 .. 128 ] characters ^.*$

The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com.

permit_multiple_payment_tokens
boolean
Default: false

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.

usage_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The usage type associated with a digital wallet payment token.

customer_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

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

object (shipping_detail)

The shipping address for the Payer.

{
  • "description": "string",
  • "permit_multiple_payment_tokens": false,
  • "usage_type": "string",
  • "customer_type": "string",
  • "shipping": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    }
}

email

The internationalized email address.

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

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

The internationalized email address.

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

"string"

enrolled

Status of Authentication eligibility.

string (enrolled) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Status of Authentication eligibility.

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

"Y"

Error

The error details.

name
required
string

The human-readable, unique name of the error.

message
required
string

The message that describes the error.

debug_id
required
string

The PayPal internal ID. Used for correlation purposes.

Array of objects (Error Details)

An array of additional details about the error.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}

Error Details

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

field
string

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

value
string

The value of the field that caused the error.

location
string
Default: "body"

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

issue
required
string

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

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

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

description
string

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

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "description": "string"
}

experience_context

Customizes the Vault creation flow experience for your customers.

brand_name
string [ 1 .. 300 ] characters ^.*$

The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode.

return_url
string <uri> [ 1 .. 4000 ] characters

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.

cancel_url
string <uri> [ 1 .. 4000 ] characters

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.

locale
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

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.

vault_instruction
string (Vault Instruction) [ 1 .. 255 ] characters ^[A-Z_]+$
Default: "ON_CREATE_PAYMENT_TOKENS"

Vault Instruction on action to be performed after a successful payer approval.

{}

experience_context

Customizes the Vault creation flow experience for your customers.

brand_name
string [ 1 .. 300 ] characters ^.*$

The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode.

return_url
string <uri> [ 1 .. 4000 ] characters

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.

cancel_url
string <uri> [ 1 .. 4000 ] characters

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.

shipping_preference
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "GET_FROM_FILE"

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

locale
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

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.

vault_instruction
string (Vault Instruction) [ 1 .. 255 ] characters ^[A-Z_]+$
Default: "ON_CREATE_PAYMENT_TOKENS"

Vault Instruction on action to be performed after a successful payer approval.

{
  • "brand_name": "string",
  • "return_url": "http://example.com",
  • "cancel_url": "http://example.com",
  • "shipping_preference": "GET_FROM_FILE",
  • "locale": "string",
  • "vault_instruction": "ON_CREATE_PAYMENT_TOKENS"
}

experience_context

Customizes the Vault creation flow experience for your customers.

brand_name
string [ 1 .. 300 ] characters ^.*$

The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode.

shipping_preference
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "GET_FROM_FILE"

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

vault_instruction
string (Vault Instruction) [ 1 .. 255 ] characters ^[A-Z_]+$
Default: "ON_CREATE_PAYMENT_TOKENS"

Vault Instruction on action to be performed after a successful payer approval.

{
  • "brand_name": "string",
  • "shipping_preference": "GET_FROM_FILE",
  • "vault_instruction": "ON_CREATE_PAYMENT_TOKENS"
}

iban_last_chars

The last characters of the IBAN used to pay.

string (iban_last_chars) [ 4 .. 34 ] characters [a-zA-Z0-9]{4}

The last characters of the IBAN used to pay.

"string"

id

The PayPal-generated ID for the vault token.

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

The PayPal-generated ID for the vault token.

"string"

instrument_id

The identifier of the instrument.

string (instrument_id) [ 1 .. 256 ] characters ^[A-Za-z0-9-_.+=]+$

The identifier of the instrument.

"string"

language

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

"string"

language

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

"string"

liability_shift

Liability shift indicator. The outcome of the issuer's authentication.

string (liability_shift) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Liability shift indicator. The outcome of the issuer's authentication.

Enum: Description
NO

Liability is with the merchant.

POSSIBLE

Liability may shift to the card issuer.

UNKNOWN

The authentication system is not available.

"NO"

merchant_partner_customer_id

The unique ID for a customer generated by PayPal.

string (merchant_partner_customer_id) [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$

The unique ID for a customer generated by PayPal.

"string"

Money

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

currency_code
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

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

The value, which might be:

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

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

Name

The name of the party.

given_name
string <= 140 characters

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

surname
string <= 140 characters

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.

{
  • "given_name": "string",
  • "surname": "string"
}

Name

The name of the party.

full_name
string <= 300 characters

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

{
  • "full_name": "string"
}

Name

The name of the party.

given_name
string <= 140 characters

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

surname
string <= 140 characters

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.

{
  • "given_name": "string",
  • "surname": "string"
}

Name

The name of the party.

given_name
string <= 140 characters

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

surname
string <= 140 characters

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.

{
  • "given_name": "string",
  • "surname": "string"
}

Name

The name of the party.

full_name
string <= 300 characters

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

{
  • "full_name": "string"
}

network_transaction_reference

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

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

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

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

The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date.

network
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

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

network_transaction_reference_entity

Previous network transaction reference including id and network.

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

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

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

The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date.

network
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

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

The date and time when the instrument was verified.

{
  • "id": "stringstr",
  • "date": "stri",
  • "network": "VISA",
  • "time": "stringstringstringst"
}

network_transaction_reference_response

Previous network transaction reference including id in response.

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

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

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

The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date.

network
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

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

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

DINERS

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

ELO

The Brazilian Elo card payment network.

HIPER

The Hiper - Ingenico ePayment network.

HIPERCARD

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

RUPAY

The RuPay payment network.

GE

The GE Credit Union 3Point card payment network.

SYNCHRONY

The Synchrony Financial (SYF) payment network.

EFTPOS

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

UNKNOWN

UNKNOWN payment network.

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

The date and time when the instrument was verified.

{
  • "id": "stringstr",
  • "date": "stri",
  • "network": "VISA",
  • "time": "stringstringstringst"
}

ordinal

Ordinal number for sorting.

integer (ordinal) [ 1 .. 99 ]

Ordinal number for sorting.

1

pares_status

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

string (pares_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

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

Enum: Description
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 only; 3DS requestor challenge preference acknowledged.

"Y"

Patch

The JSON patch object to apply partial updates to resources.

op
required
string

The operation.

Enum: Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.

replace

Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.

move

Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.

copy

Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

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

value
any (Patch Value)

The value to apply. The remove, copy, and move operations do not require a value. Since JSON Patch allows any type for value, the type property is not specified.

from
string

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

{
  • "op": "add",
  • "path": "string",
  • "value": null,
  • "from": "string"
}

Patch

The JSON patch object to apply partial updates to resources.

op
required
string

The operation.

Enum: Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.

replace

Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.

move

Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.

copy

Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

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

value
any (Patch Value)

The value to apply. The remove, copy, and move operations do not require a value. Since JSON Patch allows any type for value, the type property is not specified.

from
string

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

{
  • "op": "add",
  • "path": "string",
  • "value": null,
  • "from": "string"
}

payer

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

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

The email address of the payer.

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

The PayPal-assigned ID for the payer.

object (Name)

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

object (phone_with_type)

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.

object (Portable Postal Address (Medium-Grained))

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",
  • "payer_id": "string",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

payer

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

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

The email address of the payer.

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

The PayPal-assigned ID for the payer.

object (Name)

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

object (phone_with_type)

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.

object (Portable Postal Address (Medium-Grained))

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",
  • "payer_id": "string",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

payer_base

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

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

The email address of the payer.

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

The PayPal-assigned ID for the payer.

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

payment_token_response

Full representation of a saved payment token.

object (Payment token response payment source)

The vaulted payment method details.

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

An array of related HATEOAS links.

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

The PayPal-generated ID for the vault token.

object (customer)

Customer in merchant's or partner's system of records.

{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "last_digits": "stri",
      • "verification": {
        • "network_transaction_id": "string",
        • "date": "stri",
        • "network": "VISA",
        • "time": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "processor_response": {
          • "avs_code": "A",
          • "cvv_code": "E"
          }
        },
      • "network_transaction_reference": {
        • "id": "stringstr",
        • "date": "stri",
        • "network": "VISA",
        • "time": "stringstringstringst"
        },
      • "authentication_result": {
        • "three_d_secure": {
          • "authentication_status": "Y",
          • "enrollment_status": "Y"
          }
        },
      • "brand": "VISA",
      • "expiry": "strings",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st",
        • "id": "string",
        • "company": "string",
        • "phone": "string",
        • "name": {
          • "given_name": "string",
          • "surname": "string"
          },
        • "phone_number": {
          • "country_code": "str",
          • "national_number": "string",
          • "extension_number": "string"
          }
        },
      • "verification_status": "string",
      • "bin_details": {
        • "bin": "string",
        • "issuing_bank": "string",
        • "products": [
          • "string"
          ],
        • "bin_country_code": "string"
        },
      • "type": "CREDIT"
      },
    • "paypal": {
      • "email_address": "string",
      • "payer_id": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "account_id": "stringstrings",
      • "phone_number": {
        • "country_code": "str",
        • "national_number": "string",
        • "extension_number": "string"
        }
      },
    • "venmo": {
      • "email_address": "string",
      • "payer_id": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "user_name": "string"
      },
    • "apple_pay": {
      • "card": {
        • "name": "string",
        • "last_digits": "stri",
        • "type": "CREDIT",
        • "brand": "VISA",
        • "billing_address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st"
          }
        }
      },
    • "bank": { }
    },
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "id": "string",
  • "customer": {
    • "merchant_customer_id": "string",
    • "id": "string"
    }
}

payment_token_status

The status of the payment token.

string (payment_token_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "CREATED"

The status of the payment token.

"CREATED"

PayPal Account Identifier

The account identifier for a PayPal account.

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

The account identifier for a PayPal account.

"stringstrings"

paypal_wallet_request

A resource representing a request to vault PayPal Wallet.

description
string [ 1 .. 128 ] characters ^.*$

The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com.

permit_multiple_payment_tokens
boolean
Default: false

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.

usage_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The usage type associated with a digital wallet payment token.

customer_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

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

object (shipping_detail)

The shipping address for the Payer.

object (experience_context)

Customizes the Vault creation flow experience for your customers.

{
  • "description": "string",
  • "permit_multiple_payment_tokens": false,
  • "usage_type": "string",
  • "customer_type": "string",
  • "shipping": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "experience_context": {
    • "brand_name": "string",
    • "return_url": "http://example.com",
    • "cancel_url": "http://example.com",
    • "shipping_preference": "GET_FROM_FILE",
    • "locale": "string",
    • "vault_instruction": "ON_CREATE_PAYMENT_TOKENS"
    }
}

paypal_wallet_response

Full representation of a PayPal Payment Token.

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

The email address of the payer.

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

The PayPal-assigned ID for the payer.

object (Name)

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

object (phone_with_type)

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.

object (Portable Postal Address (Medium-Grained))

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.

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

The account identifier for a PayPal account.

object (Phone)

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

{
  • "email_address": "string",
  • "payer_id": "string",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    },
  • "account_id": "stringstrings",
  • "phone_number": {
    • "country_code": "str",
    • "national_number": "string",
    • "extension_number": "string"
    }
}

Phone

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

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

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

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

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

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

The extension number.

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

Phone

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

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

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

{
  • "national_number": "string"
}

Phone Type

The phone type.

string (Phone Type)

The phone type.

Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"
"FAX"

phone_with_type

The phone information.

phone_type
string (Phone Type)

The phone type.

Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"
required
object (Phone)

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

{
  • "phone_type": "FAX",
  • "phone_number": {
    • "national_number": "string"
    }
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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

address_line_2
string <= 300 characters

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

admin_area_2
string <= 120 characters

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

admin_area_1
string <= 300 characters

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

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

postal_code
string <= 60 characters

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

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

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

processor_response

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

avs_code
string

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

Enum: Description
0

For Maestro, all address information matches.

1

For Maestro, none of the address information matches.

2

For Maestro, part of the address information matches.

3

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

4

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

A

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

B

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

C

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

D

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

E

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

F

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

G

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

I

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

M

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

N

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

P

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

R

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

S

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

U

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

W

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

X

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

Y

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

Z

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

Null

For Maestro, no AVS response was obtained.

cvv_code
string

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

Enum: Description
0

For Maestro, the CVV2 matched.

1

For Maestro, the CVV2 did not match.

2

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

3

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

4

For Maestro, the service is not available.

E

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

I

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

M

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

N

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

P

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

S

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

U

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

X

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

All others

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

{
  • "avs_code": "A",
  • "cvv_code": "E"
}

sepa_debit_experience_context

Customizes the payer experience during the approval process for the SEPA Debit payment.

locale
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

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

return_url
required
string <uri> (url)

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

cancel_url
required
string <uri> (url)

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

{
  • "locale": "string",
  • "return_url": "string",
  • "cancel_url": "string"
}

setup_token_request

Setup Token Request where the source defines the type of instrument to be stored.

required
object

The payment method to vault with the instrument details.

object (customer)

Customer in merchant's or partner's system of records.

{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "stri",
      • "expiry": "string",
      • "brand": "VISA",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "experience_context": {},
      • "verification_method": "string"
      },
    • "paypal": {
      • "description": "string",
      • "permit_multiple_payment_tokens": false,
      • "usage_type": "string",
      • "customer_type": "string",
      • "shipping": {
        • "type": "SHIPPING",
        • "name": {
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st"
          }
        },
      • "experience_context": {
        • "brand_name": "string",
        • "return_url": "http://example.com",
        • "cancel_url": "http://example.com",
        • "shipping_preference": "GET_FROM_FILE",
        • "locale": "string",
        • "vault_instruction": "ON_CREATE_PAYMENT_TOKENS"
        }
      },
    • "venmo": {
      • "description": "string",
      • "permit_multiple_payment_tokens": false,
      • "usage_type": "string",
      • "customer_type": "string",
      • "shipping": {
        • "type": "SHIPPING",
        • "name": {
          • "full_name": "string"
          },
        • "address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st"
          }
        },
      • "experience_context": {
        • "brand_name": "string",
        • "shipping_preference": "GET_FROM_FILE",
        • "vault_instruction": "ON_CREATE_PAYMENT_TOKENS"
        }
      },
    • "token": {
      • "id": "string",
      • "type": "SETUP_TOKEN"
      }
    },
  • "customer": {
    • "merchant_customer_id": "string",
    • "id": "string"
    }
}

setup_token_response

Minimal representation of a cached setup token.

object

The setup payment method details.

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

An array of related HATEOAS links.

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

The PayPal-generated ID for the vault token.

ordinal
integer (ordinal) [ 1 .. 99 ]

The ordinal number of customers' payment source for sorting.

object (customer)

Customer in merchant's or partner's system of records.

status
string (payment_token_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "CREATED"

The status of the payment token.

{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "last_digits": "stri",
      • "verification": {
        • "network_transaction_id": "string",
        • "date": "stri",
        • "network": "VISA",
        • "time": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "processor_response": {
          • "avs_code": "A",
          • "cvv_code": "E"
          }
        },
      • "network_transaction_reference": {
        • "id": "stringstr",
        • "date": "stri",
        • "network": "VISA",
        • "time": "stringstringstringst"
        },
      • "authentication_result": {
        • "three_d_secure": {
          • "authentication_status": "Y",
          • "enrollment_status": "Y"
          }
        },
      • "brand": "VISA",
      • "expiry": "strings",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st",
        • "id": "string",
        • "company": "string",
        • "phone": "string",
        • "name": {
          • "given_name": "string",
          • "surname": "string"
          },
        • "phone_number": {
          • "country_code": "str",
          • "national_number": "string",
          • "extension_number": "string"
          }
        },
      • "verification_status": "string",
      • "bin_details": {
        • "bin": "string",
        • "issuing_bank": "string",
        • "products": [
          • "string"
          ],
        • "bin_country_code": "string"
        },
      • "type": "CREDIT"
      },
    • "paypal": {
      • "email_address": "string",
      • "payer_id": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "account_id": "stringstrings",
      • "phone_number": {
        • "country_code": "str",
        • "national_number": "string",
        • "extension_number": "string"
        }
      },
    • "venmo": {
      • "email_address": "string",
      • "payer_id": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "user_name": "string"
      }
    },
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "id": "string",
  • "ordinal": 1,
  • "customer": {
    • "merchant_customer_id": "string",
    • "id": "string"
    },
  • "status": "CREATED"
}

setup_token_response

Minimal representation of a cached setup token.

object

The setup payment method details.

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

An array of related HATEOAS links.

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

The PayPal-generated ID for the vault token.

ordinal
integer (ordinal) [ 1 .. 99 ]

The ordinal number of customers' payment source for sorting.

object (customer)

Customer in merchant's or partner's system of records.

status
string (payment_token_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "CREATED"

The status of the payment token.

{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "last_digits": "stri",
      • "verification": {
        • "network_transaction_id": "string",
        • "date": "stri",
        • "network": "VISA",
        • "time": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "processor_response": {
          • "avs_code": "A",
          • "cvv_code": "E"
          }
        },
      • "network_transaction_reference": {
        • "id": "stringstr",
        • "date": "stri",
        • "network": "VISA",
        • "time": "stringstringstringst"
        },
      • "authentication_result": {
        • "three_d_secure": {
          • "authentication_status": "Y",
          • "enrollment_status": "Y"
          }
        },
      • "brand": "VISA",
      • "expiry": "strings",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st",
        • "id": "string",
        • "company": "string",
        • "phone": "string",
        • "name": {
          • "given_name": "string",
          • "surname": "string"
          },
        • "phone_number": {
          • "country_code": "str",
          • "national_number": "string",
          • "extension_number": "string"
          }
        },
      • "verification_status": "string",
      • "bin_details": {
        • "bin": "string",
        • "issuing_bank": "string",
        • "products": [
          • "string"
          ],
        • "bin_country_code": "string"
        },
      • "type": "CREDIT"
      },
    • "paypal": {
      • "email_address": "string",
      • "payer_id": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "account_id": "stringstrings",
      • "phone_number": {
        • "country_code": "str",
        • "national_number": "string",
        • "extension_number": "string"
        }
      },
    • "venmo": {
      • "email_address": "string",
      • "payer_id": "string",
      • "name": {
        • "given_name": "string",
        • "surname": "string"
        },
      • "phone": {
        • "phone_type": "FAX",
        • "phone_number": {
          • "national_number": "string"
          }
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "user_name": "string"
      }
    },
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "id": "string",
  • "ordinal": 1,
  • "customer": {
    • "merchant_customer_id": "string",
    • "id": "string"
    },
  • "status": "CREATED"
}

shipping_detail

The shipping details.

type
string (Fullfillment Type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either type or options may be present, but not both.

Enum: Description
SHIPPING

The payer intends to receive the items at a specified address.

PICKUP_IN_PERSON

DEPRECATED. Please use "PICKUP_FROM_PERSON" instead.

PICKUP_IN_STORE

The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, "Buy Online, Pick-up in Store". Seller protection is provided with this option.

PICKUP_FROM_PERSON

The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment.

object (Name)

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

object (Portable Postal Address (Medium-Grained))

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.

{
  • "type": "SHIPPING",
  • "name": {
    • "full_name": "string"
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

shipping_option

The options that the payee or merchant offers to the payer to ship or pick up their items.

id
required
string <= 127 characters

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

label
required
string <= 127 characters

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
required
boolean

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.

type
string (shipping_type)

A classification for the method of purchase fulfillment.

Enum: Description
SHIPPING

The payer intends to receive the items at a specified address.

PICKUP

DEPRECATED. To ensure that seller protection is correctly assigned, please use 'PICKUP_IN_STORE' or 'PICKUP_FROM_PERSON' instead. Currently, this field indicates that the payer intends to pick up the items at a specified address (ie. a store address).

PICKUP_IN_STORE

The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, "Buy Online, Pick-up in Store". Seller protection is provided with this option.

PICKUP_FROM_PERSON

The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment.

object (Money)

The shipping cost for the selected option.

{
  • "id": "string",
  • "label": "string",
  • "selected": true,
  • "type": "SHIPPING",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

shipping_type

A classification for the method of purchase fulfillment.

string (shipping_type)

A classification for the method of purchase fulfillment.

Enum: Description
SHIPPING

The payer intends to receive the items at a specified address.

PICKUP

DEPRECATED. To ensure that seller protection is correctly assigned, please use 'PICKUP_IN_STORE' or 'PICKUP_FROM_PERSON' instead. Currently, this field indicates that the payer intends to pick up the items at a specified address (ie. a store address).

PICKUP_IN_STORE

The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, "Buy Online, Pick-up in Store". Seller protection is provided with this option.

PICKUP_FROM_PERSON

The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment.

"SHIPPING"

store_in_vault_instruction

Defines how and when the payment source gets vaulted.

string (store_in_vault_instruction) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Defines how and when the payment source gets vaulted.

Value: Description
ON_SUCCESS

Defines that the payment_source will be vaulted only when at least one authorization or capture using that payment_source is successful.

"ON_SUCCESS"

tax_info

The tax ID of the customer. The customer is also known as the payer. Both tax_id and tax_id_type are required.

tax_id
required
string [ 1 .. 14 ] characters ([a-zA-Z0-9])

The customer's tax ID value.

tax_id_type
required
string [ 1 .. 14 ] characters ^[A-Z0-9_]+$

The customer's tax ID type.

Enum: Description
BR_CPF

The individual tax ID type, typically is 11 characters long.

BR_CNPJ

The business tax ID type, typically is 14 characters long.

{
  • "tax_id": "string",
  • "tax_id_type": "BR_CPF"
}

The authorization state

The authorization state of the wallet instrument during transaction.

string (The authorization state) [ 1 .. 100 ] characters ^[0-9A-Z_]+$

The authorization state of the wallet instrument during transaction.

Enum: Description
NOT_STARTED

The authorization state is not started.

PENDING

The authorization state is pending.

CREATED

The authorization state is created.

CANCELLED

The authorization state is cancelled.

REVOKED

The authorization state is revoked.

REFUSED

The authorization state is refused.

CANCELLATION_REQUESTED

The authorization state is in process on cancellation.

CANCELLATION_REFUSED

The authorization state is refused to cancel.

LODGED

The authorization state is lodged.

"NOT_STARTED"

The authorization status

The authorization status of the wallet instrument.

string (The authorization status) [ 1 .. 100 ] characters ^[0-9A-Z_]+$

The authorization status of the wallet instrument.

Enum: Description
AUTHORIZED

The authorization status is authorized.

BLOCKED

The authorization status is blocked.

FAILED

The authorization status is failed.

NOT_APPLICABLE

Authorization not applicable.

NOT_SUPPORTED

Authorization not supported.

UNAUTHORIZED

The authorization status is unauthorized.

"AUTHORIZED"

three_d_secure_authentication_response

Results of 3D Secure Authentication.

authentication_status
string (pares_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The outcome of the issuer's authentication.

Enum: Description
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 only; 3DS requestor challenge preference acknowledged.

enrollment_status
string (enrolled) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Status of authentication eligibility.

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

{
  • "authentication_status": "Y",
  • "enrollment_status": "Y"
}

token_id_request

The Tokenized Payment Source representing a Request to Vault a Token.

id
required
string [ 1 .. 255 ] characters ^[0-9A-Za-z_-]+$

The PayPal-generated ID for the token.

type
required
string [ 1 .. 255 ] characters ^[0-9A-Z_-]+$

The tokenization method that generated the ID.

Enum: Description
SETUP_TOKEN

The setup token, which is a temporary reference to payment source.

BILLING_AGREEMENT

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

{
  • "id": "string",
  • "type": "SETUP_TOKEN"
}

token_request

Payment Token Request where the source defines the type of instrument to be stored.

required
object (Payment source request)

The payment method to vault with the instrument details.

object (customer)

Customer in merchant's or partner's system of records.

{
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "stri",
      • "expiry": "string",
      • "brand": "VISA",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        }
      },
    • "token": {
      • "id": "string",
      • "type": "SETUP_TOKEN"
      }
    },
  • "customer": {
    • "merchant_customer_id": "string",
    • "id": "string"
    }
}

url

Describes the URL.

string <uri> (url)

Describes the URL.

"http://example.com"

Vault Instruction

Vault Instruction on action to be performed after a successful payer approval.

string (Vault Instruction) [ 1 .. 255 ] characters ^[A-Z_]+$
Default: "ON_CREATE_PAYMENT_TOKENS"

Vault Instruction on action to be performed after a successful payer approval.

"ON_CREATE_PAYMENT_TOKENS"

vault payment tokens

Collection of payment tokens saved for a given customer.

total_items
integer [ 1 .. 50 ]

Total number of items.

total_pages
integer [ 1 .. 10 ]

Total number of pages.

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

An array of related HATEOAS links.

object (customer)

Customer in merchant's or partner's system of records.

{
  • "total_items": 1,
  • "total_pages": 1,
  • "payment_tokens": [
    • {
      • "payment_source": {
        • "card": {
          • "name": "string",
          • "last_digits": "stri",
          • "verification": {
            • "network_transaction_id": "string",
            • "date": "stri",
            • "network": "VISA",
            • "time": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "processor_response": {
              • "avs_code": "A",
              • "cvv_code": "E"
              }
            },
          • "network_transaction_reference": {
            • "id": "stringstr",
            • "date": "stri",
            • "network": "VISA",
            • "time": "stringstringstringst"
            },
          • "authentication_result": {
            • "three_d_secure": {
              • "authentication_status": "Y",
              • "enrollment_status": "Y"
              }
            },
          • "brand": "VISA",
          • "expiry": "strings",
          • "billing_address": {
            • "address_line_1": "string",
            • "address_line_2": "string",
            • "admin_area_2": "string",
            • "admin_area_1": "string",
            • "postal_code": "string",
            • "country_code": "st",
            • "id": "string",
            • "company": "string",
            • "phone": "string",
            • "name": {
              • "given_name": "string",
              • "surname": "string"
              },
            • "phone_number": {
              • "country_code": "str",
              • "national_number": "string",
              • "extension_number": "string"
              }
            },
          • "verification_status": "string",
          • "bin_details": {
            • "bin": "string",
            • "issuing_bank": "string",
            • "products": [
              • "string"
              ],
            • "bin_country_code": "string"
            },
          • "type": "CREDIT"
          },
        • "paypal": {
          • "email_address": "string",
          • "payer_id": "string",
          • "name": {
            • "given_name": "string",
            • "surname": "string"
            },
          • "phone": {
            • "phone_type": "FAX",
            • "phone_number": {
              • "national_number": "string"
              }
            },
          • "address": {
            • "address_line_1": "string",
            • "address_line_2": "string",
            • "admin_area_2": "string",
            • "admin_area_1": "string",
            • "postal_code": "string",
            • "country_code": "st"
            },
          • "account_id": "stringstrings",
          • "phone_number": {
            • "country_code": "str",
            • "national_number": "string",
            • "extension_number": "string"
            }
          },
        • "venmo": {
          • "email_address": "string",
          • "payer_id": "string",
          • "name": {
            • "given_name": "string",
            • "surname": "string"
            },
          • "phone": {
            • "phone_type": "FAX",
            • "phone_number": {
              • "national_number": "string"
              }
            },
          • "address": {
            • "address_line_1": "string",
            • "address_line_2": "string",
            • "admin_area_2": "string",
            • "admin_area_1": "string",
            • "postal_code": "string",
            • "country_code": "st"
            },
          • "user_name": "string"
          },
        • "apple_pay": {
          • "card": {
            • "name": "string",
            • "last_digits": "stri",
            • "type": "CREDIT",
            • "brand": "VISA",
            • "billing_address": {
              • "address_line_1": "string",
              • "address_line_2": "string",
              • "admin_area_2": "string",
              • "admin_area_1": "string",
              • "postal_code": "string",
              • "country_code": "st"
              }
            }
          },
        • "bank": { }
        },
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "id": "string",
      • "customer": {
        • "merchant_customer_id": "string",
        • "id": "string"
        }
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "customer": {
    • "merchant_customer_id": "string",
    • "id": "string"
    }
}

vault_instruction_base

Basic vault instruction specification that can be extended by specific payment sources that supports vaulting.

store_in_vault
string (store_in_vault_instruction) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Defines how and when the payment source gets vaulted.

Value: Description
ON_SUCCESS

Defines that the payment_source will be vaulted only when at least one authorization or capture using that payment_source is successful.

{
  • "store_in_vault": "ON_SUCCESS"
}

vault_sepa_debit_response

An API resource used in the response of securely storing a SEPA Debit.

iban_last_chars
string (iban_last_chars) [ 4 .. 34 ] characters [a-zA-Z0-9]{4}

The last 4 characters of the SEPA IBAN number.

object (Portable Postal Address (Medium-Grained))

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

{
  • "iban_last_chars": "string",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

venmo_request

A resource representing a request to vault Venmo.

description
string [ 1 .. 128 ] characters ^.*$

The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com.

permit_multiple_payment_tokens
boolean
Default: false

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.

usage_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The usage type associated with a digital wallet payment token.

customer_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

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

object (shipping_detail)

The shipping address for the Payer.

object (experience_context)

Customizes the Vault creation flow experience for your customers.

{
  • "description": "string",
  • "permit_multiple_payment_tokens": false,
  • "usage_type": "string",
  • "customer_type": "string",
  • "shipping": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "experience_context": {
    • "brand_name": "string",
    • "shipping_preference": "GET_FROM_FILE",
    • "vault_instruction": "ON_CREATE_PAYMENT_TOKENS"
    }
}

venmo_response

Full representation of a Venmo Payment Token.

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

The email address of the payer.

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

The PayPal-assigned ID for the payer.

object (Name)

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

object (phone_with_type)

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.

object (Portable Postal Address (Medium-Grained))

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.

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

The Venmo username, as chosen by the user.

{
  • "email_address": "string",
  • "payer_id": "string",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    },
  • "user_name": "string"
}