Generate a card token
The first step in the Ecommerce API flow is encrypting a customer card as a source
token. Apps using an iframe
and API integration
receive and send source
tokens that represent encrypted customer card data. See Using the Clover-hosted iframe and iFrame and API Integration.
Clover uses this token to process secure payments. Complete an Ecommerce API flow by using the source
token, along with an OAuth token.
API-only integrations
For API-only integrations, use a PAKMS key obtained from the PAKMS key endpoint (GET /pakms/apikey
) to authorize the tokenization of a card.
WARNING
Using the
iframe
and API integration to securely accept credit card information reduces the PCI compliance burden on app developers and on Clover merchants. To use the API-only integration in production, you must have (or use a service that has) a PCI DSS certification.
NOTE
To learn more, see our blog post Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys.
Generate a PAKMS key
To charge a customer's card using only the API, your app will complete the following flow. The fields mentioned for the various requests are the minimum required for each endpoint. See the API Reference Overview for complete information.
IMPORTANT
Clover reserves the right to disable keys suspected of misuse that violates our terms. If needed, you can request the deactivation of a key by sending an email to: [email protected]
To generate a PAKMS key
- Obtain an
OAuth2
token (also known as,access token.)
See Obtain an OAuth token. - Send a
GET
request to the Retrieve an API key.

- Set the Authorization header as the
auth_token.
IMPORTANT
PAKMS keys are unique for each merchant and do not expire. Because of this, the PAKMS endpoint should be called only once for each merchant when they first configure an app. The app should store the returned key for use in each of that merchant's subsequent charge requests. See the PAKMS API reference for more information.
curl --request GET \
--url 'https://scl-sandbox.dev.clover.com/pakms/apikey' \
--header 'accept: application/json' \
--header 'authorization: Bearer <TOKEN>'
The server returns an apiAccessKey
.
Encrypt card data
- Retrieve the public encryption keys from CDN. These keys generally 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
Tokenize encrypted card data
- Create a token request containing a
card
object with its required fields, including:
Field | Description | Type |
---|---|---|
encrypted_pan | Enter the encryption service ID used to store payment card Primary Account Number (PAN). | String |
transarmor_key_id | Enter the ID of the TransArmor key used to perform the encryption. | String |
exp_month | Enter the month that the card will expire. | Numeric |
exp_year | Enter the year that the card will expire. | Numeric |
cvv | Enter the Card verification value (CVV) number. | Numeric |
brand | Enter the brand ID (that is, Mastercard, Visa, and so on.) | Numeric |
first6 | Enter the first six digits for the card. | Numeric |
last4 | Enter the last four digits for the card. | Numeric |
- Set the
apiAccessKey
(PAKMS key) as the value of theapikey
header and send aPOST
request to the/v1/tokens
endpoint. See the Tokens 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.
Format: All source
tokens are alphanumeric and begin 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.
Updated about 1 month ago