PayPal payment method tokens

Payment Method Tokens API Version v3 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.

Create payment token for a given payment source post /v3/vault/payment-tokens Try it Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer.

Security Oauth2 Request header Parameters PayPal-Request-Id
string [ 1 .. 10000 ] characters The server stores keys for 3 hours.

Request Body schema: application/json application/json required Payment Token creation with a financial instrument and an optional customer_id.

payment_source required object The payment method to vault with the instrument details.

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

Responses 200Idempotent response for a successful creation of payment token. 201A successful creation of payment token. 400Request is not well-formed, syntactically incorrect, or violates schema. 403Authorization failed due to insufficient permissions. 404Request contains reference to resources that do not exist. 422The requested action could not be performed, semantically incorrect, or failed business validation. 500An internal server error has occurred. Request samples Payload cURL

application/json application/json

Sample 1 - 201 - Create Payment Token - PayPal Wallet from Setup Token Sample 1 - 201 - Create Payment Token - PayPal Wallet from Setup Token CopyExpand allCollapse all { "payment_source": { "token": { "id": "4BD1763VB2781894", "type": "SETUP_TOKEN" } } } Response samples 200 201 400 403 404

2 more 2 more application/json

Sample 1 - 201 - Create Payment Token - PayPal Wallet from Setup Token Sample 1 - 201 - Create Payment Token - PayPal Wallet from Setup Token CopyExpand allCollapse all { "id": "8kk8451t", "customer": { "id": "BygeLlrpZF", "merchant_customer_id": "customer@merchant.com" }, "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", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t", "method": "GET", "encType": "application/json" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t", "method": "DELETE", "encType": "application/json" } ] } List all payment tokens get /v3/vault/payment-tokens Try it Returns all payment tokens for a customer.

Security Oauth2 Request query Parameters customer_id required string [ 7 .. 36 ] characters A unique identifier representing a specific customer in merchant's/partner's system or records.

page_size
integer [ 1 .. 5 ] Default: 5 A non-negative, non-zero integer indicating the maximum number of results to return at one time.

page
integer [ 1 .. 10 ] 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.

Request Body schema: application/json application/json any Responses 200Successful execution. 400Request is not well-formed, syntactically incorrect, or violates schema. 403Authorization failed due to insufficient permissions. 500An internal server error has occurred. Request samples Payload cURL

application/json application/json Copy { } Response samples 200 400 403 500 application/json

Sample 1 - 200 - List Payment Tokens - Retrieve All Tokens for Customer Id Sample 1 - 200 - List Payment Tokens - Retrieve All Tokens for Customer Id CopyExpand allCollapse all { "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", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t", "method": "GET", "encType": "application/json" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t", "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", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/fgh6561t", "method": "GET", "encType": "application/json" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/fgh6561t", "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", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t", "method": "GET", "encType": "application/json" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t", "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": "self", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk845", "method": "GET" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk845", "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", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8458", "method": "GET", "encType": "application/json" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8458", "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": "self", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8458", "method": "GET" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8458", "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", "href": "https://msmaster.qa.paypal.com/directdebit/mandate/view?id=8kk8459&auth_code=C21_A.AAdol4tFtU0Q60ilyOPiTmmDax_YC1T00fAlBH_Uef_orr3TtzkcyKO4IuSxBlWmFHUzEvhiOXxV5WqE1bWNwmDyvsliIg", "method": "GET" }, { "rel": "self", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8459", "method": "GET", "encType": "application/json" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8459", "method": "DELETE", "encType": "application/json" } ] } ], "links": [ { "rel": "self", "href": "https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=BygeLlrpZF&page=1&page_size=5&total_required=false", "method": "GET", "encType": "application/json" }, { "rel": "first", "href": "https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=BygeLlrpZF&page=1&page_size=5&total_required=false", "method": "GET", "encType": "application/json" }, { "rel": "last", "href": "https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=BygeLlrpZF&page=1&page_size=5&total_required=false", "method": "GET", "encType": "application/json" } ] } Retrieve a payment token get /v3/vault/payment-tokens/{id} Try it Returns a readable representation of vaulted payment source associated with the payment token id.

Security Oauth2 Request path Parameters id required string [ 1 .. 36 ] characters ID of the payment token.

Responses 200Successful execution. 403Authorization failed due to insufficient permissions. 404The specified resource does not exist. 500An internal server error has occurred. Request samples cURL

Sample 1 - 200 - Retrieve Payment Token - Card Token Sample 1 - 200 - Retrieve Payment Token - Card Token Copy curl -v -X GET https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/8kk8451t \ -H 'Authorization: Bearer FULL_scoped_access_token'
Response samples 200 403 404 500 application/json

Sample 1 - 200 - Retrieve Payment Token - Card Token Sample 1 - 200 - Retrieve Payment Token - Card Token CopyExpand allCollapse all { "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", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t", "method": "GET", "encType": "application/json" }, { "rel": "delete", "href": "https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t", "method": "DELETE", "encType": "application/json" } ] } Delete payment token delete /v3/vault/payment-tokens/{id} Try it Delete the payment token associated with the payment token id.

Security Oauth2 Request path Parameters id required string [ 1 .. 36 ] characters ID of the payment token.

Responses 204The server has successfully executed the method, but there is no entity body to return. 400Request is not well-formed, syntactically incorrect, or violates schema. 403Authorization failed due to insufficient permissions. 500An internal server error has occurred. Request samples cURL

Sample 1 - 204 - Delete Payment Token Sample 1 - 204 - Delete Payment Token Copy curl -v -X DELETE https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/8kk8451t \ -H 'Authorization: Bearer FULL_scoped_access_token'
Response samples 204 400 403 500 application/json

Sample 1 - 204 - Delete Payment Token Sample 1 - 204 - Delete Payment Token Copy { } Create a setup token post /v3/vault/setup-tokens Try it Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.

Security Oauth2 Request header Parameters PayPal-Request-Id
string [ 1 .. 10000 ] characters The server stores keys for 3 hours.

Request Body schema: application/json application/json required Setup Token creation with a instrument type optional financial instrument details and customer_id.

payment_source required object The payment method to vault with the instrument details.

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

Responses 200Idempotent response for a successful creation of setup token. 201A successful creation of setup token. 400Request is not well-formed, syntactically incorrect, or violates schema. 403Authorization failed due to insufficient permissions. 422The requested action could not be performed, semantically incorrect, or failed business validation. 500An internal server error has occurred. Request samples Payload cURL

application/json application/json

Sample 1 - 201 - Create Setup Token - Card with Full Request Sample 1 - 201 - Create Setup Token - Card with Full Request CopyExpand allCollapse all { "customer": { "id": "BygeLlrpZF", "merchant_customer_id": "customer@merchant.com" }, "payment_source": { "card": { "number": "4111111111111111", "expiry": "2027-02", "name": "John Doe", "security_code": "321", "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" } } } } Response samples 200 201 400 403 422

1 more 1 more application/json

Sample 1 - 201 - Create Setup Token - Card with Full Request Sample 1 - 201 - Create Setup Token - Card with Full Request CopyExpand allCollapse all { "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" } } }, "links": [ { "rel": "self", "href": "https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2781612", "method": "GET", "encType": "application/json" }, { "rel": "confirm", "href": "https://api-m.paypal.com/v3/vault/payment-token", "method": "POST", "encType": "application/json" } ] } Retrieve a setup token get /v3/vault/setup-tokens/{id} Try it Returns a readable representation of temporarily vaulted payment source associated with the setup token id.

Security Oauth2 Request path Parameters id required string [ 7 .. 36 ] characters ID of the setup token.

Responses 200Found requested setup-token, returned a payment method associated with the token. 400Request is not well-formed, syntactically incorrect, or violates schema 403Authorization failed due to insufficient permissions. 404The specified resource does not exist. 500An internal server error has occurred. Request samples cURL

Sample 1 - 200 - Retrieve Setup Token - Card with 3DS Contingency 3DS VERIFIED Sample 1 - 200 - Retrieve Setup Token - Card with 3DS Contingency 3DS VERIFIED Copy curl -v -X GET https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2781612 \ -H 'Authorization: Bearer LOW_scoped_access_token' \ -H 'PayPal-Request-ID: b5efbe82-bbad-4bb0-aeeb-bfef5b442e49'
Response samples 200 400 403 404 500 application/json

Sample 1 - 200 - Retrieve Setup Token - Card with 3DS Contingency 3DS VERIFIED Sample 1 - 200 - Retrieve Setup Token - Card with 3DS Contingency 3DS VERIFIED CopyExpand allCollapse all { "id": "5C991763VB2771612", "customer": { "id": "BygeLlrpZF", "merchant_customer_id": "customer@merchant.com" }, "status": "APPROVED", "payment_source": { "card": { "brand": "VISA", "last_digits": "1111", "verification_status": "VERIFIED", "network_transaction_reference": { "id": "20286098380002303", "date": "1020", "network": "VISA", "time": "2020-10-20T22:44:41.000Z" }, "verification": { "amount": { "value": "0.00", "currency_code": "USD" }, "processor_response": { "avs_code": "M", "cvv_code": "P" }, "three_d_secure": { "type": "THREE_DS_AUTHENTICATION", "eci_flag": "FULLY_AUTHENTICATED_TRANSACTION", "card_brand": "VISA", "enrolled": "Y", "pares_status": "Y", "three_ds_version": "2", "authentication_type": "DYNAMIC", "three_ds_server_transaction_id": "3d-secure-txn-id" } }, "authentication_result": { "three_d_secure": { "authentication_status": "Y", "enrollment_status": "Y" } } } }, "links": [ { "href": "https://api-m.paypal.com/v3/vault/payment-token", "rel": "confirm", "method": "POST", "encType": "application/json" }, { "href": "https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2771612", "rel": "self", "method": "GET", "encType": "application/json" } ] } 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 3ds_result any (3ds_result) Copy null Account Registration Type The level of customer registration for the PayPal account.

string [ 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. Copy "ANONYMOUS" activity_timestamps The date and time stamps that are common to authorized payment, captured payment, and refund transactions.

create_time string [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...Show pattern The date and time when the transaction occurred, in Internet date and time format.

update_time string [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...Show pattern The date and time when the transaction was last updated, in Internet date and time format.

Copy { "create_time": "stringstringstringst", "update_time": "stringstringstringst" } 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 = 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 The resource ID of the address.

Copy { "address_line_1": "string", "address_line_2": "string", "admin_area_2": "string", "admin_area_1": "string", "postal_code": "string", "country_code": "st", "id": "string" } 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 = 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 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 The phone number that can go on the mailing label with the address to track the shipping. Phone number is in E.164 format.

name
object The name of the party.

phone_number
object Phone number associated to the address.

CopyExpand allCollapse all { "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" } } amount_breakdown The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.

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

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

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

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

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

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

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

CopyExpand allCollapse all { "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" } } 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 The card holder's name as it appears on the card.

last_digits string [ 2 .. 4 ] characters The last digits of the payment card.

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

Enum Value 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 [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. billing_address object The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

CopyExpand allCollapse all { "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.

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

CopyExpand allCollapse all { "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.

three_d_secure
object Results of 3D Secure Authentication.

CopyExpand allCollapse all { "three_d_secure": { "authentication_status": "Y", "enrollment_status": "Y", "authentication_id": "string" } } Authorization details Authorization details.

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

Enum Value 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. Copy { "status": "AUTHORIZED" } authorization_id A unique identifier for the financial instrument authorization sub-resource within the PayPal System.

string [ 1 .. 255 ] characters ^[A-Za-z0-9-_.+/=]* A unique identifier for the financial instrument authorization sub-resource within the PayPal System.

Copy "string" bank_authorization_details The details of Bank mandate authorization

status
string [ 1 .. 100 ] characters ^[0-9A-Z_]+$ The authorization status of the wallet instrument.

Enum Value 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. authorization_codes Array of strings [ 1 .. 50 ] items An array of the PayPal generated authorization codes. These codes can be based on the issuer specification.

type
string [ 1 .. 255 ] characters Represents the type of mandate.

Enum Value Description ONE_OFF Mandate of type ONE_OFF. RECURRENT Mandate of type RECURRENT. time_authorized string [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...Show pattern The date and time when the instrument was authorized, in Internet date and time format.

CopyExpand allCollapse all { "status": "AUTHORIZED", "authorization_codes": [ "string" ], "type": "ONE_OFF", "time_authorized": "string" } billing_cycle 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 The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle.

Enum Value Description REGULAR A regular billing cycle to identify recurring charges for the billing agreement. TRIAL A trial billing cycle to identify free or discounted charge for the billing agreement. Free trails will not have a price object in pricing scheme where as a discounted trial would have a discounted price compared to regular billing cycle. total_cycles
integer [ 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 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).

sequence
integer [ 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 sequence of 1 while a regular billing cycle has a sequence of 2, so that trial cycle runs before the regular cycle.

pricing_scheme
object The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.

start_date
string = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...Show pattern 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.

CopyExpand allCollapse all { "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" } bin_details Bank Identification Number (BIN) details used to fund a payment.

bin string [ 1 .. 25 ] characters 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 = 2 characters ^([A-Z]{2}|C2)$ The two-character ISO-3166-1 country code of the bank.

CopyExpand allCollapse all { "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 The card holder's name as it appears on the card.

number
string [ 13 .. 19 ] characters The primary account number (PAN) for the payment card.

last_digits string [ 2 .. 4 ] characters The last digits of the payment card.

expiry
string = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format.

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

Enum Value 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 [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. billing_address object The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

CopyExpand allCollapse all { "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 The card holder's name as it appears on the card.

number required string [ 13 .. 19 ] characters The primary account number (PAN) for the payment card.

security_code
string [ 3 .. 4 ] characters 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 = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format.

brand
string [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. billing_address object The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

CopyExpand allCollapse all { "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 Default: "SCA_WHEN_REQUIRED" The method used for card verification.

Enum Value 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. Copy { "method": "SCA_ALWAYS" } card_attributes Additional attributes associated with the use of this card.

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

vault
object Instruction to vault the card based on the specified strategy.

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

CopyExpand allCollapse all { "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 [ 1 .. 255 ] characters ^[A-Z_]+$ 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. Copy "VISA" card_customer The details about a customer in PayPal's system of record.

id
string [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer generated by PayPal.

email_address
string [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:.[a-zA-...Show pattern 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.

phone
object 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 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.

CopyExpand allCollapse all { "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 The card holder's name as it appears on the card.

number
string [ 13 .. 19 ] characters The primary account number (PAN) for the payment card.

security_code
string [ 3 .. 4 ] characters 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 = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format.

brand
string [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. billing_address object The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

CopyExpand allCollapse all { "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 The card holder's name as it appears on the card.

number
string [ 13 .. 19 ] characters The primary account number (PAN) for the payment card.

security_code
string [ 3 .. 4 ] characters 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 = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format.

brand
string [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. billing_address object The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

experience_context
object Customizes the Vault creation flow experience for your customers.

verification_method string [ 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).

Enum Value Description SCA_WHEN_REQUIRED 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. 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. CopyExpand allCollapse all { "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", "return_url": "http://example.com", "cancel_url": "http://example.com", "locale": "string", "vault_instruction": "ON_CREATE_PAYMENT_TOKENS" }, "verification_method": "SCA_WHEN_REQUIRED" } card_response Full representation of a Card Payment Token including network token.

name
string [ 2 .. 300 ] characters The card holder's name as it appears on the card.

last_digits string [ 2 .. 4 ] characters The last digits of the payment card.

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

network_transaction_reference
object Previous network transaction reference including id in response.

authentication_result
object Results of Authentication such as 3D Secure.

brand
string [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. expiry
string = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format.

billing_address object The billing address for this card.

verification_status string [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Card Verification status.

Enum Value Description VERIFIED Card has been verified FAILED Card verification has failed bin_details object Bank Identification Number (BIN) details used to fund a payment.

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

Enum Value Description CREDIT A credit card. DEBIT A debit card. PREPAID A Prepaid card. STORE A store card. UNKNOWN Card type cannot be determined. CopyExpand allCollapse all { "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" }, "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" }, "verification_status": "VERIFIED", "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 The card holder's name as it appears on the card.

last_digits string [ 2 .. 4 ] characters The last digits of the payment card.

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

network_transaction_reference
object Previous network transaction reference including id in response.

authentication_result
object Results of Authentication such as 3D Secure.

brand
string [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. expiry
string = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format.

billing_address object The billing address for this card.

verification_status string [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Card Verification status.

Enum Value Description VERIFIED Card has been verified FAILED Card verification has failed bin_details object Bank Identification Number (BIN) details used to fund a payment.

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

Enum Value Description CREDIT A credit card. DEBIT A debit card. PREPAID A Prepaid card. STORE A store card. UNKNOWN Card type cannot be determined. CopyExpand allCollapse all { "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" }, "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" }, "verification_status": "VERIFIED", "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 The card holder's name as it appears on the card.

last_digits string [ 2 .. 4 ] characters The last digits of the payment card.

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

network_transaction_reference
object Previous network transaction reference including id in response.

authentication_result
object Results of Authentication such as 3D Secure.

brand
string [ 1 .. 255 ] characters ^[A-Z_]+$ The card brand or network. Typically used in the response.

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. expiry
string = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$ The card expiration year and month, in Internet date format.

billing_address object The billing address for this card.

verification_status string [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Card Verification status.

Enum Value Description VERIFIED Card has been verified FAILED Card verification has failed bin_details object Bank Identification Number (BIN) details used to fund a payment.

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

Enum Value Description CREDIT A credit card. DEBIT A debit card. PREPAID A Prepaid card. STORE A store card. UNKNOWN Card type cannot be determined. CopyExpand allCollapse all { "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" }, "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" }, "verification_status": "VERIFIED", "bin_details": { "bin": "string", "issuing_bank": "string", "products": [ "string" ], "bin_country_code": "string" }, "type": "CREDIT" } card_supplementary_data Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout.

level_2 object The level 2 card processing data collections. If your merchant account has been configured for Level 2 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 2 data for your business.

level_3 object The level 3 card processing data collections, If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf. Please contact your PayPal Technical Account Manager to define level 3 data for your business.

CopyExpand allCollapse all { "level_2": { "invoice_id": "string", "tax_total": { "currency_code": "str", "value": "string" } }, "level_3": { "ships_from_postal_code": "string", "line_items": [ { "name": "string", "quantity": "string", "description": "string", "sku": "string", "url": "http://example.com", "image_url": "http://example.com", "upc": { "type": "UPC-A", "code": "string" }, "commodity_code": "string", "unit_of_measure": "string", "unit_amount": { "currency_code": "str", "value": "string" }, "tax": { "currency_code": "str", "value": "string" }, "discount_amount": { "currency_code": "str", "value": "string" }, "total_amount": { "currency_code": "str", "value": "string" } } ], "shipping_amount": { "currency_code": "str", "value": "string" }, "duty_amount": { "currency_code": "str", "value": "string" }, "discount_amount": { "currency_code": "str", "value": "string" }, "shipping_address": { "address_line_1": "string", "address_line_2": "string", "admin_area_2": "string", "admin_area_1": "string", "postal_code": "string", "country_code": "st" } } } card_type Type of card. i.e Credit, Debit and so on.

string [ 1 .. 255 ] characters ^[A-Z_]+$ Type of card. i.e Credit, Debit and so on.

Enum Value Description CREDIT A credit card. DEBIT A debit card. PREPAID A Prepaid card. STORE A store card. UNKNOWN Card type cannot be determined. Copy "CREDIT" card_verification_details Card Verification details including the authorization details and 3D SECURE details.

network_transaction_id
string [ 1 .. 1024 ] characters DEPRECATED. This field is DEPRECATED. Please find the network transaction id data in the 'id' field under the 'network_transaction_reference' object instead of the 'verification' object.

date
string = 4 characters DEPRECATED. This field is DEPRECATED. Please find the date data in the 'date' field under the 'network_transaction_reference' object instead of the 'verification' object.

network string [ 1 .. 255 ] characters ^[A-Z_]+$ DEPRECATED. This field is DEPRECATED. Please find the network data in the 'network' field under the 'network_transaction_reference' object instead of the 'verification' object.

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. time
string [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...Show pattern DEPRECATED. This field is DEPRECATED. Please find the time data in the 'time' field under the 'network_transaction_reference' object instead of the 'verification' object.

amount
object The amount used for card verification.

processor_response
object The processor information.

three_d_secure
any DEPRECATED. This field is DEPRECATED. Please find the 3D secure authentication data in the 'three_d_secure' object under the 'authentication_result' object instead of the 'verification' object.

CopyExpand allCollapse all { "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 } card_verification_method The verification method of the card.

string [ 1 .. 255 ] characters ^[0-9A-Z_]+$ The verification method of the card.

Enum Value Description SCA_WHEN_REQUIRED 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. 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. Copy "SCA_WHEN_REQUIRED" card_verification_status Verification status of Card.

string [ 1 .. 255 ] characters ^[0-9A-Z_]+$ Verification status of Card.

Enum Value Description VERIFIED Card has been verified FAILED Card verification has failed Copy "VERIFIED" 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 (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. Copy "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 (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. Copy "st" currency_code The three-character ISO-4217 currency code that identifies the currency.

string (currency_code) = 3 characters The three-character ISO-4217 currency code that identifies the currency.

Copy "str" customer This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details.

merchant_customer_id
string [ 1 .. 64 ] characters 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 [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer in merchant's or partner's system of records.

Copy { "merchant_customer_id": "string", "id": "string" } customer The details about a customer in PayPal's system of record.

id
string [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer generated by PayPal.

email_address
string [ 3 .. 254 ] characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:.[a-zA-...Show pattern 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.

phone
object 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.

CopyExpand allCollapse all { "id": "string", "email_address": "string", "phone": { "phone_type": "FAX", "phone_number": { "national_number": "string" } } } customer This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details.

merchant_customer_id
string [ 1 .. 64 ] characters 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 [ 1 .. 22 ] characters ^[0-9a-zA-Z_-]+$ The unique ID for a customer in merchant's or partner's system of records.

Copy { "merchant_customer_id": "string", "id": "string" } customer This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details.