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.

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

1. Obtain an OAuth2 token (also known as, access token.) See Obtain an OAuth token.
2. Send a GET request to the Retrieve an API key.

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

1. 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, and
• TA_PUBLIC_KEY_PROD for use in the production environment

{
  "TA_PUBLIC_KEY_DEV": "...",
  "TA_PUBLIC_KEY_PROD": "..."
}

2. 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 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.

Tokenize 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.
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.