--- title: "Request a token" method: POST path: "/tokens" tags: ["Tokens"] --- # Request a token `POST /tokens` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/tokens` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Exchange card details for a reference token that can be used later to request a card payment. Tokens are single use and expire after 15 minutes. To create a token, please authenticate using your public key. **Please note:** You should only use the `card` type for testing purposes. ## Request body - union: The source of the payment - object: Card Token Request - `type` 'card', required: The type of card details to be tokenized - `number` string, required: The card number - `expiry_month` integer, required: The expiry month of the card - `expiry_year` integer, required: The expiry year of the card - `name` string: The cardholder's name - `cvv` string: The card verification value/code. 3 digits, except for American Express (4 digits) - `pin` string: The first 2 digits of the card PIN - `billing_address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `metadata` InstrumentMetadata: A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference. You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and `null` values are not supported. Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive. Do not store card details, credentials, or personal data you do not have consent to store in metadata. - object: Google Pay Token Request - `type` 'googlepay', required: The type of card details to be tokenized - `token_data` object: The Google Pay payment token - `signature` string: Verifies the message came from Google. The signature is created using ECDSA - `protocolVersion` string: Identifies which encryption/signing scheme created this message. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0 - `signedMessage` string: A serialized JSON string containing the encryptedMessage, ephemeralPublicKey, and tag. To simplify the signature verification process, this value is serialized - object: Apple Pay Token Request - `type` 'applepay', required: The type of card details to be tokenized - `token_data` TokenData, required: The Apple Pay payment token - `version` string: Version information about the payment token. The token uses `EC_v1` for ECC-encrypted data, and `RSA_v1` for RSA-encrypted data - `data` string: Encrypted payment data. Base64 encoded as a string - `signature` string: Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm - `header` object: Additional version-dependent information used to decrypt and verify the payment - object: CVV Token Request - `type` 'cvv', required: The type of card details to be tokenized - `token_data` object, required: Data containing the CVV token value - `cvv` string: The card verification value/code. 3 digits, except for American Express (4 digits) - object: PIN Token Request - `type` 'pin', required: The type of card details to be tokenized - `token_data` object, required: Data containing the PIN token value - `pin` string: The first 2 digits of the card PIN ## Response `201` Reference token created successfully - union: The source of the payment - object: Card Token Response - `type` 'card', required: The type of card details to be tokenized - `token` string, required: The reference token - `expires_on` string, date-time, required: The date/time the token will expire - `billing_address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `expiry_month` integer, required: The expiry month - `expiry_year` integer, required: expiry year - `name` string: The cardholder's name - `scheme` string, required: The card scheme - `scheme_local` 'cartes_bancaires': The local co-branded card scheme - `last4` string, required: The last four digits of the card number - `bin` string, required: The card issuer BIN - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT': The card type - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category - `issuer` string: The name of the card issuer - `issuer_country` string: The card issuer country ISO-2 code - `product_id` string: The issuer/card scheme product identifier - `product_type` string: The issuer/card scheme product type - `metadata` InstrumentMetadata: A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference. You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and `null` values are not supported. Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive. Do not store card details, credentials, or personal data you do not have consent to store in metadata. - object: Google Pay Token Response - `type` 'googlepay', required: The type of card details to be tokenized - `token` string, required: The reference token - `expires_on` string, date-time, required: The date/time the token will expire - `expiry_month` integer, required: The expiry month - `expiry_year` integer, required: expiry year - `scheme` string, required: The card scheme - `scheme_local` 'cartes_bancaires': The local co-branded card scheme - `last4` string, required: The last four digits of the card number - `bin` string, required: The card issuer BIN - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT': The card type - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category - `issuer` string: The name of the card issuer - `issuer_country` string: The card issuer country ISO-2 code - `product_id` string: The issuer/card scheme product identifier - `product_type` string: The issuer/card scheme product type - `token_format` 'pan_only' | 'cryptogram_3ds': The format of the token. - object: Apple Pay Token Response - `type` 'applepay', required: The type of card details to be tokenized - `token` string, required: The reference token - `expires_on` string, date-time, required: The date/time the token will expire - `expiry_month` integer, required: The expiry month - `expiry_year` integer, required: expiry year - `scheme` string, required: The card scheme - `scheme_local` 'cartes_bancaires': The local co-branded card scheme - `last4` string, required: The last four digits of the card number - `bin` string, required: The card issuer BIN - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT': The card type - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category - `issuer` string: The name of the card issuer - `issuer_country` string: The card issuer country ISO-2 code - `product_id` string: The issuer/card scheme product identifier - `product_type` string: The issuer/card scheme product type - `token_format` 'cryptogram_3ds': The format of the token. - object: CVV Token Response - `type` 'cvv', required: The type of card details to be tokenized - `token` string, required: The reference token - `expires_on` string, date-time, required: The date/time the token will expire - `expiry_month` integer: The expiry month - `expiry_year` integer: expiry year - `scheme` string: The card scheme - `scheme_local` 'cartes_bancaires': The local co-branded card scheme - `last4` string: The last four digits of the card number - `bin` string: The card issuer BIN - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT': The card type - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category - `issuer` string: The name of the card issuer - `issuer_country` string: The card issuer country ISO-2 code - `product_id` string: The issuer/card scheme product identifier - `product_type` string: The issuer/card scheme product type - object: PIN Token Response - `type` 'pin', required: The type of card details to be tokenized - `token` string, required: The reference token - `expires_on` string, date-time, required: The date/time the token will expire - `expiry_month` integer: The expiry month - `expiry_year` integer: expiry year - `scheme` string: The card scheme - `scheme_local` 'cartes_bancaires': The local co-branded card scheme - `last4` string: The last four digits of the card number - `bin` string: The card issuer BIN - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT': The card type - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category - `issuer` string: The name of the card issuer - `issuer_country` string: The card issuer country ISO-2 code - `product_id` string: The issuer/card scheme product identifier - `product_type` string: The issuer/card scheme product type ## Other responses - `401`: Unauthorized - `422`: Invalid data was sent - `504`: Gateway timeout --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)