The first step in the Ecommerce API flow is encrypting a customer card as a source token.

iframe and API integrations

Apps using an iframe and API integration receive and send source tokens that represent encrypted customer card data. Clover uses this token to process secure payments. With a source token and your OAuth token, you can complete your Ecommerce API flows.

📘

NOTE

See the FAQ for information about using gift cards with the API.

API-only integrations

For API-only integrations, you need 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.

For using 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 for complete information.

Generating a PAKMS key

• Send a GET request to the PAKMS key endpoint (GET /pakms/apikey). Set the Authorization header as the OAuth-generated auth_token. See the PAKMS API reference for more information.

📘

NOTE

The PAKMS key is unique for each merchant, and these keys do not expire. Because of this, the PAKMS endpoint should be called only once for each merchant when they first configure your app.

Your 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

The card object in the /v1/tokens request contains the details of the card being tokenized. To tokenize an encrypted card, use the encrypted_pan property.

{
    "card": {
    "encrypted_pan": "{encrypted_card_number}",
    "first6": "601136",
    "last4": "6668",
    "exp_month": "12",
    "exp_year": "2021",
    "cvv": "123",
    "brand": "DISCOVER"
    }
}

1. To get the encryption information required for encrypted_pan, send a GET request to /v2/merchant/{mId}/pay/key.

{
    "modulus": "{modulus}", // base-10
    "exponent": "{exponent}",
    "prefix": "{prefix}" 
}

2. Encrypt the card information. Follow the encryption example code from the Java example app.
   • Prepend the prefix value to the card number.
   • Generate an RSA public key using the modulus and exponent values.
   • 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.

In response, an encrypted card number is generated. All encrypted_pan values are alphanumeric and end with ==.

📘

NOTE

The modulus returned by Clover is in base 10. Various libraries expect moduli in different bases.

Tokenizing encrypted card data

1. Create a token request containing a card object with its required fields (encrypted_pan, exp_month, exp_year, cvv, brand, first6, and last4).
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}","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.