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:

1. 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.
2. Send a GET request to the Retrieve an API key.

3. 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:

1. 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": "..."
}

2. 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 and exponent.
   • Generate an RSA public key using the modulus and exponent 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.

Tokenizing encrypted card data

1. Create a token request containing a card object with its required fields, including:

2. Set the apiAccessKey (PAKMS key) as the value of the apikey header and send a POST 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.