Release NotesAnnouncementsVideosBlog
Guides

Create a card token

North America—United States and Canada

A card token is a unique, single-use code that represents a customer’s credit card details. It securely processes payments without exposing the actual card information or directly handling sensitive card information. Tokenization in Ecommerce requires encrypting a customer card as a token.

Encryption conceals the content of card data to protect it from unauthorized access. Tokenization replaces sensitive data with a non-sensitive equivalent or token. Clover uses this token as the source to process secure payments using the Ecommerce APIs.

Prerequisites

  1. Create a global developer account and select the API checkbox in the Ecommerce Settings.
  2. Do one of the following:
  • If you are using the tokenization services for a single merchant or to run test scenarios, generate Ecommerce API tokens (public and private keys). Use the keys as follows:
    • Public key—Use as the Ecommerce API key or apiAccessKey for card, gift card, or ACH tokenization without the need to generate a separate PAKMS key.
    • Private key—Set as the Bearer token in the Authorization header to use Ecommerce APIs.
  • If you are using tokenization services for a merchant with multiple businesses or in the production environment, generate OAuth access_token and refresh_token pair to initiate the v2/OAuth flow.

Step 1: Encrypt card data

  1. Retrieve the public encryption keys from JSON file. 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, and
  • TA_PUBLIC_KEY_PROD for use in the production environment
{
  "TA_PUBLIC_KEY_DEV": "...",
  "TA_PUBLIC_KEY_PROD": "..."
}
  1. Do the following to encrypt the card information. See the following code: Java example.
    1. Parse the Base64 public key string from the JSON file.
    2. Get the modulus and exponent.
    3. Generate an RSA public key using the modulus and exponent values.
    4. Prepend the prefix value to the card number.
    5. Using the public key, encrypt the combined prefix and card number.
    6. Base64 encode the resulting encrypted data into a string. This string is optional encrypted_pan value in the /v1/tokens request.

      📘

      NOTE

      To minimize your app's payment card industry (PCI) compliance burden, use encrypted_pan instead of number in your POST request.

Step 2: Tokenize encrypted card data

  1. Use the OAuth API token or access_token to generate an Ecommerce API key (PAKMS key) or apiAccessKey.
  2. Send a POST request to the /v1/tokens endpoint.
  3. Enter card-related information in the required fields for the card object:
    • number or encrypted_pan
    • exp_month
    • exp_year
    • cvv
    • last4
    • first6
    • brand
  4. In the apikey header, enter the apiAccessKey from the PAKMS endpoint.

The server returns a single-pay token that begins with clv_. Example: clv_1ABCDefgHI23jKL4m5nOPqR. Use this token as the source to create a charge or pay for an order, accept tips, and save customer cards for future transactions.

Request and Response example—Generate a card token

curl --request POST \
     --url https://token-sandbox.dev.clover.com/v1/tokens \
     --header 'accept: application/json' \
     --header 'apikey: 7aacxxxx-xxxx-xxxx-xxxx-xxxxxxxxcae2' \
     --header 'content-type: application/json' \
     --data '{
       "card": {
         "encrypted_pan": "{encrypted_card_number}",
         "first6": "601136",
         "last4": "6668",
         "exp_month": "12",
         "exp_year": "2035",
         "cvv": "123",
         "brand": "DISCOVER"
       }
     }'

{
  "id": "clv_1ABCDefgHI23jKL4m5nOPqR",
  "object": "token",
  "card": {
    "exp_month": "12",
    "exp_year": "2035",
    "first6": "601136",
    "last4": "6668",
    "brand": "DISCOVER"
  }
}

Test cards

Clover provides several sandbox test cards that you can use when developing your app.

Related topics

Updated 2 days ago