Apps can integrate with the Ecommerce services in different ways, depending on the needs of the application and merchants who use it.

The simplest integrations rely on a Clover-hosted iframe tokenizer, a component provided to make Ecommerce app development as easy as possible. See the iframe and API section for more information.

For applications requiring complete control over the payment flow, you'll integrate with additional services. See the API only section for more information.

iframe and API

PCI burden on developers & merchants: LOW

The iframe tokenizer is an embeddable, customizable component you can add to your application. It allows users to securely provide card data to the Clover servers.

A source (an encrypted card token) is provided to your application after the card has been encrypted and tokenized for use with the Clover payment system. This gives your app the benefit of reduced PCI compliance burden, as well as speeding up the integration and coding process by using a pre-built component. Further, Clover will keep the tokenizer up to date with any future API changes so your app will require less maintenance.

Use cases

Most Ecommerce merchants require an application built with this type of integration. It provides the greatest business benefit and the lowest security risk for card-not-present payments through a third-party Clover app.

Imagine a Clover merchant running a small retail store wants to set up an online store and expand their customer base. The payments aspect of the online store can be quickly built with an iframe and API integration.

Request flow (iframe and API)

To charge a customer's card using the iframe and 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.

1. Direct the user to the iframe in a manner consistent with your application's user flow.
2. Wait for the user to enter and submit their card information.
   The server returns the tokenized card as a source.
3. Create a charge request with the source and a specific amount in cents.
4. Send the charge request to the SCL charge endpoint (POST /v1/charges).
   The card is charged for the specified amount.

API only

🚧

IMPORTANT

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.

PCI burden on developers & merchants: HIGH

For an API only integration, you must use the PAKMS and token APIs in addition to the SCL API that provides access to charges and customer data). These APIs provide operations for your app to retrieve an encryption key and use that key to encrypt and tokenize card data.

Request flow (API only)

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.

1. Create a key request containing the merchant ID and Clover application ID.
2. Send the key request to the PAKMS key endpoint (GET /pakms/apikey). Set the authorization: Bearer as your OAuth-generated auth_token.

📘

NOTE

The PAKMS key is unique for each merchant, and these keys do not expire. 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.

3. Create a token request containing a card object with its required fields (number, exp_month, exp_year, cvv, and brand).
4. Set the apiAccessKey as the value of the apikey header and send the request to the token endpoint (POST /v1/tokens). See Generating a card token for more information about encrypting card data and then tokenizing the encrypted data. 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: {apiAccesssKey}' \
  --header 'content-type: application/json' \
  --data '{ "card": { "number": "6011361000006668","exp_month": "12","exp_year": "2021","cvv": "123","brand": "DISCOVER"}}'

The server returns the tokenized card as a source. All source tokens are alphanumeric and begin with clv_.

5. Create a charge request with the source and a specific amount in cents.
6. Send the charge request to the SCL charge endpoint (POST /v1/charges).
   The card is charged for the specified amount.