Generating a card token
The first step in the Ecommerce API flow is encrypting a customer card as a source
token. Apps using an iframe
(refer to Using the Clover-hosted iframe) and API integration
(refer to API Integration) receive and send source
tokens that represent encrypted customer card data. Clover uses this token to process secure payments. Complete an Ecommerce API flow by using the source
token, along with an OAuth token.
NOTE
Refer to the using gift cards FAQ for more information on generating a gift card.
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
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 emailing [email protected]
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.
Generating a PAKMS key
Perform the following steps to generate a PAKMS Key:
- The first step in generating an PAKMS key is to obtain an
OAuth2
token (also known as,access token.)
Refer to Obtaining an OAuth token. - Send a
GET
request to the Retrieve an API key.


- Set the Authorization header as the
auth_token.
NOTE
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://apisandbox.dev.clover.com/pakms/apikey' \
--header 'accept: application/json' \
--header 'authorization: Bearer {auth_token}'
The server returns an apiAccessKey
.
Encrypting card data
Perform the following steps to encrypt the PAN:
- Retrieve the public encryption keys from CDN. These keys will generally not change and should be cached by your application. The endpoint returns a TA_PUBLIC_KEY_DEV which should be used in Sandbox and TA_PUBLIC_KEY_PROD which should be used in production.
{
"TA_PUBLIC_KEY_DEV": "...",
"TA_PUBLIC_KEY_PROD": "..."
}
- Do the following to encrypt the card information. Refer to 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
Tokenizing encrypted card data
- Create a token request containing a
card
object with its required fields, including:
Field | Description | Type |
---|---|---|
| Enter the encryption service ID used to store payment card Primary Account Number (PAN). | String |
| Enter the ID of the TransArmor key used to perform the encryption. | String |
| Enter the month that the card will expire. | Numeric |
| Enter the year that the card will expire. | Numeric |
| Enter the CVV (Card Verification Value) number. | Numeric |
| Enter the brand ID (that is, Master Card, Visa, etc.) | Numeric |
| Enter the first six digits for the card. | Numeric |
| 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. 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 can be used when developing your app.
Updated about 1 month ago