Generate a card token
North America—United States and Canada
Tokenization in Ecommerce requires encrypting a customer card as a source
token using the relevant Ecommerce API endpoint. Clover uses this token to process secure payments.
Ecommerce integration types and tokenization
- Clover iframe (inline frame) and API Integration—Complete the Ecommerce API flow using an OAuth API token and the
source
token. This integration allows secure card data entry through the inline payment form and returns a tokenized card for use with the Clover payment system with a reduced PCI compliance burden. - Clover API-only integration—Complete the OAuth flow using an OAuth API token to generate an Ecommerce API key (PAKMS key). Use this static key to identify the merchant requesting tokenization and then authorize the tokenization of a card. To use the API-only integration in production, you must have (or use a service that has) a PCI DSS certification.
IMPORTANT
Clover reserves the right to disable keys suspected of misuse and violation of our terms. If needed, you can send an email to: [email protected]to request the deactivation of an Ecommerce API key.
Generate a card token
Step 1: Encrypt card data
- Retrieve the public encryption keys from CDN. These keys generally do not change and should be cached by your application. The endpoint returns:
TA_PUBLIC_KEY_DEV
for use in the sandbox environment, andTA_PUBLIC_KEY_PROD
for use in the production environment
{
"TA_PUBLIC_KEY_DEV": "...",
"TA_PUBLIC_KEY_PROD": "..."
}
- Do the following to encrypt the card information. See the following code: Java example.
- Parse the Base64 public key string (returned by the CDN). Obtain the
modulus
andexponent
. - Generate an RSA public key using the
modulus
andexponent
values. - Prepend the
prefix
value to the card number. - Using the public key, encrypt the combined prefix and card number.
- Base64 encode the resulting encrypted data into a string. This string is the
encrypted_pan
value in the/v1/tokens
request.
- Parse the Base64 public key string (returned by the CDN). Obtain the
Step 2: Tokenize encrypted card data
- Generate an Ecommerce API key or
apiAccessKey
. - Create a token request containing a
card
object with its required fields:
Field | Description | Type |
---|---|---|
encrypted_pan | Encryption service ID used to store the payment card's primary account number (PAN). | String |
transarmor_key_id | Identifier of the TransArmor key used to perform the encryption. | String |
exp_month | Month that the card will expire. | Numeric |
exp_year | Year that the card will expire. | Numeric |
cvv | Card verification value (CVV). | Numeric |
brand | Card brand, such as Mastercard®, Visa®, and so on. | Numeric |
first6 | First six digits of the card. | Numeric |
last4 | Last four digits of the card. | Numeric |
- Set the Ecommerce API key or
apiAccessKey
as the value of theapikey
header and send aPOST
request to the/v1/tokens
endpoint. See Create a card token in the API reference for more information.
curl --request POST \
--url 'https://token-sandbox.dev.clover.com/v1/tokens' \
--header 'accept: application/json' \
--header 'apikey: {apiAccessKey}' \
--header 'content-type: application/json' \
--data '{"card":{"encrypted_pan":"{encrypted_card_number}", "transarmor_key_id":"{transarmor_key_id}","first6":"601136","last4":"6668","exp_month":"12","exp_year":"2021","cvv":"123","brand":"DISCOVER"}}'
The server returns a source
token that begins with clv_
. With a source
token, you can create a charge, create and pay for orders, accept tips, and save customer cards for future transactions.
Clover provides several sandbox test cards that you can use when developing your app.
Related topics
- Ecommerce integration types
- Generate an OAuth API token or
access_token
- Generate an Ecommerce API key (PAKMS key)
- Blog: How does tokenization work?
- Blog: Ecommerce Tokenization: Understanding Methods that Keep Card Data Safe
- API reference: Create a card token
- Tutorial: Save a card for future transactions
Updated 6 days ago