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.
Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer.
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. |
Idempotent response for a successful creation of payment token.
A successful creation of payment token.
Request is not well-formed, syntactically incorrect, or violates schema.
Authorization failed due to insufficient permissions.
Request contains reference to resources that do not exist.
The requested action could not be performed, semantically incorrect, or failed business validation.
An internal server error has occurred.
{- "payment_source": {
- "token": {
- "id": "4BD1763VB2781894",
- "type": "SETUP_TOKEN"
}
}
}
{- "id": "8kk8451t",
- "customer": {
- "id": "BygeLlrpZF",
- "merchant_customer_id": "customer@merchant.com"
}, - "payment_source": {
- "card": {
- "name": "John Doe",
- "brand": "VISA",
- "last_digits": "1111",
- "expiry": "2027-02",
- "billing_address": {
- "id": "kk",
- "address_line_1": "2211 N First Street",
- "address_line_2": "Building 17",
- "admin_area_2": "San Jose",
- "admin_area_1": "CA",
- "postal_code": "95131",
- "country_code": "US"
}
}
}, - "links": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "delete",
- "method": "DELETE",
- "encType": "application/json"
}
]
}
Returns all payment tokens for a customer.
Successful execution.
Request is not well-formed, syntactically incorrect, or violates schema.
Authorization failed due to insufficient permissions.
An internal server error has occurred.
{ }
{- "customer": {
- "id": "BygeLlrpZF",
- "merchant_customer_id": "customer@merchant.com"
}, - "payment_tokens": [
- {
- "id": "8kk8451t",
- "customer": {
- "id": "BygeLlrpZF"
}, - "payment_source": {
- "card": {
- "name": "John Doe",
- "brand": "VISA",
- "last_digits": "1111",
- "expiry": "2027-02",
- "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": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "delete",
- "method": "DELETE",
- "encType": "application/json"
}
]
}, - {
- "id": "fgh6561t",
- "customer": {
- "id": "BygeLlrpZF"
}, - "payment_source": {
- "paypal": {
- "description": "Description for PayPal to be shown to PayPal payer",
- "email_address": "john.doe@example.com",
- "account_id": "VYYFH3WJ4JPJQ",
- "shipping": {
- "name": {
- "full_name": "John Doe"
}, - "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"
}
}, - "usage_pattern": "IMMEDIATE",
- "usage_type": "MERCHANT",
- "customer_type": "CONSUMER",
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "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": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "delete",
- "method": "DELETE",
- "encType": "application/json"
}
]
}, - {
- "id": "hg654s1t",
- "customer": {
- "id": "BygeLlrpZF"
}, - "payment_source": {
- "venmo": {
- "description": "Description for Venmo to be shown to Venmo payer",
- "shipping": {
- "name": {
- "full_name": "John Doe"
}, - "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"
}
}, - "usage_pattern": "IMMEDIATE",
- "usage_type": "MERCHANT",
- "customer_type": "CONSUMER",
- "email_address": "john.doe@example.com",
- "user_name": "johndoe",
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "account_id": "VYYFH3WJ4JPJQ",
- "address": {
- "address_line_1": "PayPal",
- "address_line_2": "2211 North 1st Street",
- "admin_area_1": "CA",
- "admin_area_2": "San Jose",
- "postal_code": "96112",
- "country_code": "US"
}
}
}, - "links": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "delete",
- "method": "DELETE",
- "encType": "application/json"
}
]
}, - {
- "id": "8kk8457",
- "payment_source": {
- "apple_pay": {
- "card": {
- "name": "John Doe",
- "last_digits": "1111",
- "type": "CREDIT",
- "brand": "VISA",
- "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"
}
}
}
}, - "links": [
- {
- "rel": "delete",
- "method": "DELETE"
}
]
}, - {
- "id": "8kk8458",
- "payment_source": {
- "bank": {
- "ach_debit": {
- "last_digits": "9991",
- "routing_number": "307075259",
- "account_type": "CHECKING",
- "ownership_type": "PERSONAL",
- "account_holder_name": "John Doe",
- "billing_address": {
- "country_code": "US"
}, - "verification": {
- "external": {
- "status": "VERIFIED"
}
}
}
}
}, - "links": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "delete",
- "method": "DELETE",
- "encType": "application/json"
}
]
}, - {
- "id": "8kk82r8",
- "customer": {
- "id": "BygeLlrpZF",
- "merchant_customer_id": "customer@merchant.com"
}, - "payment_source": {
- "bank": {
- "ach_debit": {
- "last_digits": "9992",
- "routing_number": "307075260",
- "account_type": "CHECKING",
- "ownership_type": "PERSONAL",
- "account_holder_name": "John Doe",
- "billing_address": {
- "country_code": "US"
}, - "verification": {
- "paypal": {
- "method": "INSTANT_ACCOUNT_VERIFICATION",
- "status": "VERIFIED"
}
}
}
}
}, - "links": [
- {
- "rel": "delete",
- "method": "DELETE"
}
]
}, - {
- "id": "8kk8459",
- "payment_source": {
- "bank": {
- "sepa_debit": {
- "iban_last_chars": "5034",
- "account_holder_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"
}, - "authorization_details": {
- "status": "AUTHORIZED"
}
}
}
}, - "links": [
- {
- "rel": "view-mandate",
- "method": "GET"
}, - {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "delete",
- "method": "DELETE",
- "encType": "application/json"
}
]
}
], - "links": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "first",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "last",
- "method": "GET",
- "encType": "application/json"
}
]
}
Returns a readable representation of vaulted payment source associated with the payment token id.
Successful execution.
Authorization failed due to insufficient permissions.
The specified resource does not exist.
An internal server error has occurred.
{- "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": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "delete",
- "method": "DELETE",
- "encType": "application/json"
}
]
}
Delete the payment token associated with the payment token id.
The server has successfully executed the method, but there is no entity body to return.
Request is not well-formed, syntactically incorrect, or violates schema.
Authorization failed due to insufficient permissions.
An internal server error has occurred.
{ }
Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.
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. |
Idempotent response for a successful creation of setup token.
A successful creation of setup token.
Request is not well-formed, syntactically incorrect, or violates schema.
Authorization failed due to insufficient permissions.
The requested action could not be performed, semantically incorrect, or failed business validation.
An internal server error has occurred.
{- "payment_source": {
- "card": { }
}
}
{- "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": [
- {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "confirm",
- "method": "POST",
- "encType": "application/json"
}
]
}
Returns a readable representation of temporarily vaulted payment source associated with the setup token id.
Found requested setup-token, returned a payment method associated with the token.
Authorization failed due to insufficient permissions.
The specified resource does not exist.
An internal server error has occurred.
{- "id": "5C991763VB2771612",
- "customer": {
- "id": "BygeLlrpZF",
- "merchant_customer_id": "customer@merchant.com"
}, - "status": "APPROVED",
- "payment_source": {
- "paypal": {
- "description": "Description for PayPal to be shown to PayPal payer",
- "shipping": {
- "name": {
- "full_name": "John Doe"
}, - "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"
}
}, - "usage_pattern": "IMMEDIATE",
- "usage_type": "MERCHANT",
- "customer_type": "CONSUMER",
- "email_address": "john.doe@example.com",
- "name": {
- "given_name": "John",
- "surname": "Doe"
}, - "account_id": "VYYFH3WJ4JPJQ",
- "address": {
- "address_line_1": "PayPal",
- "address_line_2": "2211 North 1st Street",
- "admin_area_1": "CA",
- "admin_area_2": "San Jose",
- "postal_code": "96112",
- "country_code": "US"
}
}
}, - "links": [
- {
- "rel": "approve",
- "method": "GET",
- "encType": "application/json"
}, - {
- "rel": "confirm",
- "method": "POST",
- "encType": "application/json"
}, - {
- "rel": "self",
- "method": "GET",
- "encType": "application/json"
}
]
}
Message:
Expiration year outside of acceptable range.
Description: The requested action could not be performed, semantically incorrect, or failed business validation.
Message:
Credit card number is invalid.
Description: The request is not well-formed, is syntactically incorrect, or violates schema.
Message:
Exactly one payment source is required.
Description: The request is not well-formed, is syntactically incorrect, or violates schema.
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.
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.
Message:
The integer value of a field is too small.
Description: The request is not well-formed, is syntactically incorrect, or violates schema.
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.
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.
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.
Message:
The value of a field is too long.
Description: The request is not well-formed, is syntactically incorrect, or violates schema.
Message:
The request JSON is not well formed.
Description: The request is not well-formed, is syntactically incorrect, or violates schema.
Message:
A required field / parameter is missing.
Description: The request is not well-formed, is syntactically incorrect, or violates schema.
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.
Message:
Specified operation not supported on any fields.
Description: The requested action could not be performed, semantically incorrect, or failed business validation.
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.
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.
Message:
You do not have permission to access or perform operations on this resource.
Description: Authorization failed due to insufficient permissions.
Message:
The specified resource does not exist.
Description: The requested resource ID was not found
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.
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.
Message:
The specified token id does not exist.
Description: The requested resource ID was not found.
The level of customer registration for the PayPal account.
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"
A legal agreement with associated attributes against the account.
major_version | integer [ 0 .. 99 ] Major version number accepted by the user. | ||||
minor_version | integer [ 0 .. 99 ] Minor version number accepted by the user. | ||||
type required | string (legal_agreement_type) [ 1 .. 64 ] characters ^[A-Z_]+$ Type of legal document that is recorded in the context of Connect Profile.
|
{- "major_version": 99,
- "minor_version": 99,
- "type": "ACCELERATED_CHECKOUT_USER_AGREEMENT"
}
The date and time stamps that are common to authorized payment, captured payment, and refund transactions.
create_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 transaction occurred, in Internet date and time format. |
update_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 transaction was last updated, in Internet date and time format. |
{- "create_time": "stringstringstringst",
- "update_time": "stringstringstringst"
}
Address request details.
address_line_1 | string <= 300 characters The first line of the address, such as number and street, for example, |
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_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,
|
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 |
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"
}
}
The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
object (Money) The subtotal for all items. Required if the request includes | |
object (Money) The shipping fee for all items within a given | |
object (Money) The handling fee for all items within a given | |
object (Money) The total tax for all items. Required if the request includes | |
object (Money) The insurance fee for all items within a given | |
object (Money) The shipping discount for all items within a given | |
object (Money) The discount for all items within a given |
{- "item_total": {
- "currency_code": "str",
- "value": "string"
}, - "shipping": {
- "currency_code": "str",
- "value": "string"
}, - "handling": {
- "currency_code": "str",
- "value": "string"
}, - "tax_total": {
- "currency_code": "str",
- "value": "string"
}, - "insurance": {
- "currency_code": "str",
- "value": "string"
}, - "shipping_discount": {
- "currency_code": "str",
- "value": "string"
}, - "discount": {
- "currency_code": "str",
- "value": "string"
}
}
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
brand | string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the |
{- "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"
}
}
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"
}
}
}
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",
- "authentication_id": "string"
}
}
Authorization details.
status | string (The authorization status) [ 1 .. 100 ] characters ^[0-9A-Z_]+$ Instrument authorization status.
|
{- "status": "AUTHORIZED"
}
A unique identifier for the financial instrument authorization sub-resource within the PayPal System.
A unique identifier for the financial instrument authorization sub-resource within the PayPal System.
"string"
The details of Bank mandate authorization
status | string (The authorization status) [ 1 .. 100 ] characters ^[0-9A-Z_]+$ The authorization status of the wallet instrument.
| ||||||||||||||
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. | ||||||||||||||
type | string [ 1 .. 255 ] characters ^[A-Z_]+$ Represents the type of mandate.
| ||||||||||||||
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. |
{- "status": "AUTHORIZED",
- "authorization_codes": [
- "string"
], - "type": "ONE_OFF",
- "time_authorized": "string"
}
Full representation of a Bank Payment Token.
object (sepa_debit_response) SEPA Debit Response. |
{- "sepa_debit": {
- "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"
}, - "authorization_details": {
- "status": "AUTHORIZED"
}
}
}
The billing cycle providing details of the billing frequency, amount, duration and if the billing cycle is a free, discounted or regular billing cycle. The sequence of the billing cycle will be in the following order - free trial billing cycle(s), discounted trial billing cycle(s), regular billing cycle(s).
tenure_type required | string [ 1 .. 24 ] characters ^[A-Z_]+$ The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle.
| ||||||
total_cycles | integer <int32> [ 0 .. 999 ] Default: 1 The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between | ||||||
sequence | integer <int32> [ 1 .. 3 ] Default: 1 The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a | ||||||
object (pricing_scheme) The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme. | |||||||
start_date | 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 start date for the billing cycle, in YYYY-MM-DD. This field should be not be provided if the billing cycle starts at the time of checkout. When this field is not provided, the billing cycle amount will be included in any data validations confirming that the total provided by the merchant match the sum of individual items due at the time of checkout. Only one billing cycle (with sequence equal to 1) can have a no start date. |
{- "tenure_type": "REGULAR",
- "total_cycles": 1,
- "sequence": 1,
- "pricing_scheme": {
- "pricing_model": "FIXED",
- "price": {
- "currency_code": "str",
- "value": "string"
}, - "reload_threshold_amount": {
- "currency_code": "str",
- "value": "string"
}
}, - "start_date": "string"
}
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)$ The two-character ISO-3166-1 country code of the bank. |
{- "bin": "string",
- "issuing_bank": "string",
- "products": [
- "string"
], - "bin_country_code": "string"
}
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
brand | string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the |
{- "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"
}
}
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the |
{- "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"
}
}
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.
|
{- "method": "SCA_ALWAYS"
}
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"
}
}
The card network or brand. Applies to credit, debit, gift, and payment cards.
The card network or brand. Applies to credit, debit, gift, and payment cards.
Enum Value | 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"
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 | |
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"
}
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the |
{- "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"
}
}
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Portable Postal Address (Medium-Grained)) The billing address for this card. Supports only the | |||||||||||||||||||||||||||||||||||||||||||||||||||||
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": {
- "brand_name": "string",
- "locale": "string",
- "vault_instruction": "ON_CREATE_PAYMENT_TOKENS"
}, - "verification_method": "string"
}
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized | boolean Default: "false" Indicates if the card has being tokenized. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
|
{- "name": "string",
- "last_digits": "stri",
- "tokenized": "false",
- "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"
}, - "three_d_secure": null
}, - "network_transaction_reference": {
- "id": "stringstr",
- "date": "stri",
- "network": "VISA",
- "time": "stringstringstringst"
}, - "authentication_result": {
- "three_d_secure": {
- "authentication_status": "Y",
- "enrollment_status": "Y",
- "authentication_id": "string"
}
}, - "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"
}
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized | boolean Default: "false" Indicates if the card has being tokenized. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
|
{- "name": "string",
- "last_digits": "stri",
- "tokenized": "false",
- "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"
}, - "three_d_secure": null
}, - "network_transaction_reference": {
- "id": "stringstr",
- "date": "stri",
- "network": "VISA",
- "time": "stringstringstringst"
}, - "authentication_result": {
- "three_d_secure": {
- "authentication_status": "Y",
- "enrollment_status": "Y",
- "authentication_id": "string"
}
}, - "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"
}
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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized | boolean Default: "false" Indicates if the card has being tokenized. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||
verification_status | string (card_verification_status) [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Card Verification status. | ||||||||||||||||||||||||||||||||||||||||||||||||||||