--- title: "Create a setup token" method: POST path: "/v3/vault/setup-tokens" tags: ["setup-tokens"] --- # Create a setup token `POST /v3/vault/setup-tokens` Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer. ## Headers - `PayPal-Request-Id` string ## Request body - SetupTokenRequest — Setup Token Request where the `source` defines the type of instrument to be stored. - `customer` Customer — This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details. - `id` string — The unique ID for a customer generated by PayPal. - `merchant_customer_id` string — 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. - `payment_source` object, required — The payment method to vault with the instrument details. - `card` DefinitionsCard — A Resource representing a request to vault a Card. - `name` string — The card holder's name as it appears on the card. - `number` string — The primary account number (PAN) for the payment card. - `expiry` string — The year and month, in ISO-8601 `YYYY-MM` date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). - `security_code` string — The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when `payment_initiator=MERCHANT`. - `brand` 'VISA' | 'MASTERCARD' | 'DISCOVER' | 'AMEX' | 'SOLO' | 'JCB' | 'STAR' | 'DELTA' | 'SWITCH' | 'MAESTRO' | 'CB_NATIONALE' | 'CONFIGOGA' | 'CONFIDIS' | 'ELECTRON' | 'CETELEM' | 'CHINA_UNION_PAY' | 'DINERS' | 'ELO' | 'HIPER' | 'HIPERCARD' | 'RUPAY' | 'GE' | 'SYNCHRONY' | 'EFTPOS' | 'UNKNOWN' — The card network or brand. Applies to credit, debit, gift, and payment cards. - `billing_address` CardBillingAddress — The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). - `address_line_1` string — The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. - `address_line_2` string — The second line of the address, for example, a suite or apartment number. - `admin_area_2` string — A city, town, or village. Smaller than `admin_area_level_1`. - `admin_area_1` string — The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: - `postal_code` string — The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
- `verification_method` 'SCA_WHEN_REQUIRED' | 'SCA_ALWAYS' — The verification method of the card. - `experience_context` CardExperienceContext — Customizes the Vault creation flow experience for your customers. - `brand_name` string — The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode. - `locale` string, ppaas_common_language_v3 — The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/api/rest/reference/country-codes/) or [M49 region code](https://unstats.un.org/unsd/methodology/m49/). - `return_url` string, uri — The URL where the customer is redirected after customer approves leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. - `cancel_url` string, uri — The URL where the customer is redirected after customer cancels or leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. - `vault_instruction` 'ON_CREATE_PAYMENT_TOKENS' | 'ON_PAYER_APPROVAL' — Vault Instruction on action to be performed after a successful payer approval. - `network_transaction_reference` unknown - `paypal` PaypalWalletRequest — Resource consolidating common request and response attributes for vaulting a Digital Wallet. - `description` string — The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com. - `usage_pattern` 'IMMEDIATE' | 'DEFERRED' | 'RECURRING_PREPAID' | 'RECURRING_POSTPAID' | 'THRESHOLD_PREPAID' | 'THRESHOLD_POSTPAID' | 'UNSCHEDULED_POSTPAID' | 'UNSCHEDULED_PREPAID' | 'SUBSCRIPTION_PREPAID' | 'SUBSCRIPTION_POSTPAID' | 'INSTALLMENT_POSTPAID' | 'INSTALLMENT_PREPAID' — Expected business/charge model for the billing agreement. - `shipping` Shipping — The shipping details. - `name` ShippingName — The name of the party. - `full_name` string — When the party is a person, the party's full name. - `phone_number` ShippingPhoneNumber — The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). - `country_code` string, required — The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `national_number` string, required — The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `type` 'SHIPPING' | 'PICKUP_IN_PERSON' | 'PICKUP_IN_STORE' | 'PICKUP_FROM_PERSON' — A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both. - `address` ShippingAddress — The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). - `address_line_1` string — The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. - `address_line_2` string — The second line of the address, for example, a suite or apartment number. - `admin_area_2` string — A city, town, or village. Smaller than `admin_area_level_1`. - `admin_area_1` string — The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: - `postal_code` string — The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
- `permit_multiple_payment_tokens` boolean — Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source. - `usage_type` 'MERCHANT' | 'PLATFORM' — The usage type associated with a digital wallet payment token. - `customer_type` 'CONSUMER' | 'BUSINESS' — The customer type associated with a digital wallet payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer. - `billing_plan` Plan — The merchant level Recurring Billing plan metadata for the Billing Agreement. - `billing_cycles` BillingCycle[], required — An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle. - `tenure_type` 'REGULAR' | 'TRIAL', required — The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle. - `pricing_scheme` PricingScheme — The pricing scheme details. - `price` Money — The currency and amount for a financial transaction, such as a balance or payment due. - … - `pricing_model` 'FIXED' | 'VARIABLE' | 'AUTO_RELOAD', required — The pricing model for the billing cycle. - `reload_threshold_amount` Money — The currency and amount for a financial transaction, such as a balance or payment due. - … - `frequency` unknown - `total_cycles` integer — 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 — 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. - `start_date` string, ppaas_date_notime_v2 — The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years. - `product` unknown - `one_time_charges` OneTimeCharges, required — The one-time charge info at the time of checkout. - `setup_fee` Money — The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, ppaas_common_currency_code_v2, required — The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. - `value` string, required — The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). - `shipping_amount` Money — The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, ppaas_common_currency_code_v2, required — The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. - `value` string, required — The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). - `taxes` Money — The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, ppaas_common_currency_code_v2, required — The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. - `value` string, required — The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). - `product_price` Money — The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, ppaas_common_currency_code_v2, required — The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. - `value` string, required — The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). - `subtotal` Money — The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, ppaas_common_currency_code_v2, required — The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. - `value` string, required — The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). - `total_amount` Money, required — The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, ppaas_common_currency_code_v2, required — The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. - `value` string, required — The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). - `name` string — Name of the recurring plan. - `experience_context` ExperienceContext — Customizes the Vault creation flow experience for your customers. - `brand_name` string — The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode. - `locale` string, ppaas_common_language_v3 — The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/api/rest/reference/country-codes/) or [M49 region code](https://unstats.un.org/unsd/methodology/m49/). - `return_url` string, uri — The URL where the customer is redirected after customer approves leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. - `cancel_url` string, uri — The URL where the customer is redirected after customer cancels or leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS. - `shipping_preference` 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS' — The shipping preference. This only applies to PayPal payment source. - `vault_instruction` 'ON_CREATE_PAYMENT_TOKENS' | 'ON_PAYER_APPROVAL' — Vault Instruction on action to be performed after a successful payer approval. - `venmo` VenmoRequest — A resource representing a request to vault Venmo. - `description` string — The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com. - `usage_pattern` 'IMMEDIATE' | 'DEFERRED' | 'RECURRING_PREPAID' | 'RECURRING_POSTPAID' | 'THRESHOLD_PREPAID' | 'THRESHOLD_POSTPAID' | 'UNSCHEDULED_POSTPAID' | 'UNSCHEDULED_PREPAID' | 'SUBSCRIPTION_PREPAID' | 'SUBSCRIPTION_POSTPAID' | 'INSTALLMENT_POSTPAID' | 'INSTALLMENT_PREPAID' — Expected business/charge model for the billing agreement. - `shipping` Shipping — The shipping details. - `name` ShippingName — The name of the party. - `full_name` string — When the party is a person, the party's full name. - `phone_number` ShippingPhoneNumber — The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). - `country_code` string, required — The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `national_number` string, required — The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `type` 'SHIPPING' | 'PICKUP_IN_PERSON' | 'PICKUP_IN_STORE' | 'PICKUP_FROM_PERSON' — A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both. - `address` ShippingAddress — The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). - `address_line_1` string — The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. - `address_line_2` string — The second line of the address, for example, a suite or apartment number. - `admin_area_2` string — A city, town, or village. Smaller than `admin_area_level_1`. - `admin_area_1` string — The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: - `postal_code` string — The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
- `permit_multiple_payment_tokens` boolean — Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source. - `usage_type` 'MERCHANT' | 'PLATFORM' — The usage type associated with a digital wallet payment token. - `customer_type` 'CONSUMER' | 'BUSINESS' — The customer type associated with a digital wallet payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer. - `experience_context` DefinitionsExperienceContext — Customizes the Vault creation flow experience for your customers. - `brand_name` string — The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode. - `shipping_preference` 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS' — The shipping preference. This only applies to PayPal payment source. - `vault_instruction` 'ON_CREATE_PAYMENT_TOKENS' | 'ON_PAYER_APPROVAL' — Vault Instruction on action to be performed after a successful payer approval. - `token` TokenIdRequest — The Tokenized Payment Source representing a Request to Vault a Token. - `id` string, required — The PayPal-generated ID for the token. - `type` 'SETUP_TOKEN', required — The tokenization method that generated the ID. ## Response `200` Idempotent response for a successful creation of setup token. - SetupTokenResponse — Minimal representation of a cached setup token. - `id` string — The PayPal-generated ID for the vault token. - `customer` Customer — This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details. - `id` string — The unique ID for a customer generated by PayPal. - `merchant_customer_id` string — 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. - `status` 'CREATED' | 'PAYER_ACTION_REQUIRED' | 'APPROVED' | 'VAULTED' | 'TOKENIZED' — The status of the payment token. - `payment_source` object — The setup payment method details. - `card` object — Full representation of a Card Payment Token including network token. - `name` string — The card holder's name as it appears on the card. - `last_digits` string — The last digits of the payment card. - `brand` 'VISA' | 'MASTERCARD' | 'DISCOVER' | 'AMEX' | 'SOLO' | 'JCB' | 'STAR' | 'DELTA' | 'SWITCH' | 'MAESTRO' | 'CB_NATIONALE' | 'CONFIGOGA' | 'CONFIDIS' | 'ELECTRON' | 'CETELEM' | 'CHINA_UNION_PAY' | 'DINERS' | 'ELO' | 'HIPER' | 'HIPERCARD' | 'RUPAY' | 'GE' | 'SYNCHRONY' | 'EFTPOS' | 'UNKNOWN' — The card network or brand. Applies to credit, debit, gift, and payment cards. - `expiry` string — The year and month, in ISO-8601 `YYYY-MM` date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). - `billing_address` BillingAddress — Address request details. - `address_line_1` string — The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. - `address_line_2` string — The second line of the address, for example, a suite or apartment number. - `admin_area_2` string — A city, town, or village. Smaller than `admin_area_level_1`. - `admin_area_1` string — The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: - `postal_code` string — The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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 — The resource ID of the address. - `verification_status` 'VERIFIED' | 'FAILED' — Verification status of Card. - `verification` CardVerificationDetails — Card Verification details including the authorization details and 3D SECURE details. - `network_transaction_id` string — 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 — 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` 'VISA' | 'MASTERCARD' | 'DISCOVER' | 'AMEX' | 'SOLO' | 'JCB' | 'STAR' | 'DELTA' | 'SWITCH' | 'MAESTRO' | 'CB_NATIONALE' | 'CONFIGOGA' | 'CONFIDIS' | 'ELECTRON' | 'CETELEM' | 'CHINA_UNION_PAY' | 'DINERS' | 'ELO' | 'HIPER' | 'HIPERCARD' | 'RUPAY' | 'GE' | 'SYNCHRONY' | 'EFTPOS' | 'UNKNOWN' — The card network or brand. Applies to credit, debit, gift, and payment cards. - `time` string, ppaas_date_time_v3 — The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `amount` Money — The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, ppaas_common_currency_code_v2, required — The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. - `value` string, required — The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). - `processor_response` ProcessorResponse — The processor response information for payment requests, such as direct credit card transactions. - `avs_code` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'I' | 'M' | 'N' | 'P' | 'R' | 'S' | 'U' | 'W' | 'X' | 'Y' | 'Z' | 'Null' | '0' | '1' | '2' | '3' | '4' — The address verification code for Visa, Discover, Mastercard, or American Express transactions. - `cvv_code` 'E' | 'I' | 'M' | 'N' | 'P' | 'S' | 'U' | 'X' | 'All others' | '0' | '1' | '2' | '3' | '4' — The card verification value code for for Visa, Discover, Mastercard, or American Express. - `three_d_secure` unknown - `network_transaction_reference` NetworkTransactionReferenceResponse — Previous network transaction reference including id and network. - `id` string, required — Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -. - `date` string — The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date. - `network` 'VISA' | 'MASTERCARD' | 'DISCOVER' | 'AMEX' | 'SOLO' | 'JCB' | 'STAR' | 'DELTA' | 'SWITCH' | 'MAESTRO' | 'CB_NATIONALE' | 'CONFIGOGA' | 'CONFIDIS' | 'ELECTRON' | 'CETELEM' | 'CHINA_UNION_PAY' | 'DINERS' | 'ELO' | 'HIPER' | 'HIPERCARD' | 'RUPAY' | 'GE' | 'SYNCHRONY' | 'EFTPOS' | 'UNKNOWN' — The card network or brand. Applies to credit, debit, gift, and payment cards. - `time` string, ppaas_date_time_v3 — The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `authentication_result` AuthenticationResult — Results of Authentication such as 3D Secure. - `three_d_secure` ThreeDSecureAuthenticationResponse2 — Results of 3D Secure Authentication. - `authentication_status` 'Y' | 'N' | 'U' | 'A' | 'C' | 'R' | 'D' | 'I' — Transactions status result identifier. The outcome of the issuer's authentication. - `enrollment_status` 'Y' | 'N' | 'U' | 'B' — Status of Authentication eligibility. - `authentication_id` string — The externally received 3ds authentication id, to be returned in card detokenization response. - `bin_details` BinDetails — Bank Identification Number (BIN) details used to fund a payment. - `bin` string — 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 — The issuer of the card instrument. - `bin_country_code` string, ppaas_common_country_code_v2 — The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) 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.
- `products` Products[] — 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. - `type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'STORE' | 'UNKNOWN' — Type of card. i.e Credit, Debit and so on. - `paypal` PaypalWalletResponse — Full representation of a PayPal Payment Token. - `description` string — The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com. - `usage_pattern` 'IMMEDIATE' | 'DEFERRED' | 'RECURRING_PREPAID' | 'RECURRING_POSTPAID' | 'THRESHOLD_PREPAID' | 'THRESHOLD_POSTPAID' | 'UNSCHEDULED_POSTPAID' | 'UNSCHEDULED_PREPAID' | 'SUBSCRIPTION_PREPAID' | 'SUBSCRIPTION_POSTPAID' | 'INSTALLMENT_POSTPAID' | 'INSTALLMENT_PREPAID' — Expected business/charge model for the billing agreement. - `shipping` Shipping — The shipping details. - `name` ShippingName — The name of the party. - `full_name` string — When the party is a person, the party's full name. - `phone_number` ShippingPhoneNumber — The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). - `country_code` string, required — The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `national_number` string, required — The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `type` 'SHIPPING' | 'PICKUP_IN_PERSON' | 'PICKUP_IN_STORE' | 'PICKUP_FROM_PERSON' — A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both. - `address` ShippingAddress — The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). - `address_line_1` string — The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. - `address_line_2` string — The second line of the address, for example, a suite or apartment number. - `admin_area_2` string — A city, town, or village. Smaller than `admin_area_level_1`. - `admin_area_1` string — The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: - `postal_code` string — The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
- `permit_multiple_payment_tokens` boolean — Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source. - `usage_type` 'MERCHANT' | 'PLATFORM' — The usage type associated with a digital wallet payment token. - `customer_type` 'CONSUMER' | 'BUSINESS' — The customer type associated with a digital wallet payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer. - `email_address` string, merchant_common_email_address_v2 — The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
- `payer_id` string, ppaas_payer_id_v3 — The account identifier for a PayPal account. - `name` Name — The name of the party. - `prefix` string — The prefix, or title, to the party's name. - `given_name` string — When the party is a person, the party's given, or first, name. - `surname` string — When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname. - `middle_name` string — When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name. - `suffix` string — The suffix for the party's name. - `alternate_full_name` string — DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business. - `full_name` string — When the party is a person, the party's full name. - `phone` PhoneWithType — The phone information. - `phone_type` 'FAX' | 'HOME' | 'MOBILE' | 'OTHER' | 'PAGER' — The phone type. - `phone_number` PhoneNumber, required — The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). - `national_number` string, required — The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `address` Address — A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone. - `line1` string, required — The first line of the address. For example, number or street. - `line2` string — The second line of the address. For example, suite or apartment number. - `city` string, required — The city name. - `state` string — The [code](/docs/api/reference/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/api/reference/state-codes/#argentina), [Brazil](/docs/api/reference/state-codes/#brazil), [Canada](/docs/api/reference/state-codes/#canada), [China](/docs/api/reference/state-codes/#china), [India](/docs/api/reference/state-codes/#india), [Italy](/docs/api/reference/state-codes/#italy), [Japan](/docs/api/reference/state-codes/#japan), [Mexico](/docs/api/reference/state-codes/#mexico), [Thailand](/docs/api/reference/state-codes/#thailand), or [United States](/docs/api/reference/state-codes/#usa). Maximum length is 40 single-byte characters. - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
- `postal_code` string — The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `account_id` string, ppaas_payer_id_v3 — The account identifier for a PayPal account. - `phone_number` Phone — The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). - `country_code` string, required — The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `national_number` string, required — The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `extension_number` string — The extension number. - `venmo` VenmoResponse — Full representation of a Venmo Payment Token. - `description` string — The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com. - `usage_pattern` 'IMMEDIATE' | 'DEFERRED' | 'RECURRING_PREPAID' | 'RECURRING_POSTPAID' | 'THRESHOLD_PREPAID' | 'THRESHOLD_POSTPAID' | 'UNSCHEDULED_POSTPAID' | 'UNSCHEDULED_PREPAID' | 'SUBSCRIPTION_PREPAID' | 'SUBSCRIPTION_POSTPAID' | 'INSTALLMENT_POSTPAID' | 'INSTALLMENT_PREPAID' — Expected business/charge model for the billing agreement. - `shipping` Shipping — The shipping details. - `name` ShippingName — The name of the party. - `full_name` string — When the party is a person, the party's full name. - `phone_number` ShippingPhoneNumber — The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). - `country_code` string, required — The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `national_number` string, required — The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `type` 'SHIPPING' | 'PICKUP_IN_PERSON' | 'PICKUP_IN_STORE' | 'PICKUP_FROM_PERSON' — A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both. - `address` ShippingAddress — The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). - `address_line_1` string — The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address. - `address_line_2` string — The second line of the address, for example, a suite or apartment number. - `admin_area_2` string — A city, town, or village. Smaller than `admin_area_level_1`. - `admin_area_1` string — The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is: - `postal_code` string — The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
- `permit_multiple_payment_tokens` boolean — Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source. - `usage_type` 'MERCHANT' | 'PLATFORM' — The usage type associated with a digital wallet payment token. - `customer_type` 'CONSUMER' | 'BUSINESS' — The customer type associated with a digital wallet payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer. - `email_address` string, merchant_common_email_address_v2 — The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
- `payer_id` string, ppaas_payer_id_v3 — The account identifier for a PayPal account. - `name` Name — The name of the party. - `prefix` string — The prefix, or title, to the party's name. - `given_name` string — When the party is a person, the party's given, or first, name. - `surname` string — When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname. - `middle_name` string — When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name. - `suffix` string — The suffix for the party's name. - `alternate_full_name` string — DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business. - `full_name` string — When the party is a person, the party's full name. - `phone` PhoneWithType — The phone information. - `phone_type` 'FAX' | 'HOME' | 'MOBILE' | 'OTHER' | 'PAGER' — The phone type. - `phone_number` PhoneNumber, required — The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). - `national_number` string, required — The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). - `address` Address — A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone. - `line1` string, required — The first line of the address. For example, number or street. - `line2` string — The second line of the address. For example, suite or apartment number. - `city` string, required — The city name. - `state` string — The [code](/docs/api/reference/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/api/reference/state-codes/#argentina), [Brazil](/docs/api/reference/state-codes/#brazil), [Canada](/docs/api/reference/state-codes/#canada), [China](/docs/api/reference/state-codes/#china), [India](/docs/api/reference/state-codes/#india), [Italy](/docs/api/reference/state-codes/#italy), [Japan](/docs/api/reference/state-codes/#japan), [Mexico](/docs/api/reference/state-codes/#mexico), [Thailand](/docs/api/reference/state-codes/#thailand), or [United States](/docs/api/reference/state-codes/#usa). Maximum length is 40 single-byte characters. - `country_code` string, ppaas_common_country_code_v2, required — The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
- `postal_code` string — The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). - `user_name` string — The Venmo username, as chosen by the user. - `links` LinkDescription[] — An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). - `href` string, required — The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` string, required — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'CONNECT' | 'OPTIONS' | 'PATCH' — The HTTP method required to make the related call. ## Other responses - `201` — A successful creation of setup token. - `400` — Request is not well-formed, syntactically incorrect, or violates schema. - `403` — Authorization failed due to insufficient permissions. - `422` — The requested action could not be performed, semantically incorrect, or failed business validation. - `500` — An internal server error has occurred. --- [API](https://skmtc.net/paypal/apis/payments.md) · [All operations](https://skmtc.net/paypal/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/paypal/payments/versions/672aceee1190/schema)