Ecommerce integration and payment flows—Use cases

North America—United States and Canada

Clover offers different types of ecommerce integrations to cater to various business needs. Your apps can integrate with Clover Ecommerce services in different ways, depending on the needs of the app and merchants who use it. See Clover Ecommerce integration types.

Payment flows and Ecommerce integration use cases

iframe and API integration

PCI burden on developers & merchants:** LOW

The iframe tokenizer lets customers provide card data securely to the Clover servers. A source, which is an encrypted card token, is provided to your app after the card is 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. Clover keeps the tokenizer up to date with any future API changes, so your app requires less maintenance.

Use case

Most ecommerce merchants require an app 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. For instance, a Clover merchant running a small retail store wants to set up an online store to expand their customer base. You can quickly build the payment aspect of the online store with an iframe and API integration.

Request flow ( iframe and API)

The fields in this example request are the minimum required for each endpoint. See the Ecommerce API for complete information.

To charge a customer's card using the iframe and API, your app completes the following flow:

Direct the customer to the iframe based on your app's user flow.
Let the customer enter and submit their card information. The Clover server returns the tokenized card as a source.
Send a POST request to the v1/charges endpoint to create a charge.
Create a charge request with the tokenized card information as source and enter an amount in cents. The card is charged for the specified amount.

API-only integration

Use Clover Ecommerce APIs for custom integrations tailored to your specific requirements. Integrate with additional services for apps requiring complete control over the payment flow.

PCI burden on developers & merchants:** HIGH

For an API-only integration, you must use the PAKMS and token APIs in addition to the Ecommerce API, which 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)

The fields in this example request are the minimum required for each endpoint. See the Ecommerce API for complete information. You need a Public Access Key Management Service (PAKMS) key that is unique for each merchant to complete the OAuth flow that lets you use the Clover Ecommerce API. The PAKMS key does not expire. You need to send a request to the PAKMS endpoint only once for each merchant when they first install and configure your app. Your app should store the returned PAKMS key for use in each of that merchant's subsequent charge requests. See the Ecommerce - PAKMS Service API reference for more information.

The entire flow to tokenize a card and create a charge is available in the Ecommerce API: Accept payments flow. Here is a high-level overview of what our app needs to complete the flow to charge a customer's card using only the Ecommerce API:

Send an API access token request containing the merchantId and Clover App ID, also known as the client_id.
Send an apiAccessKey request to the PAKMS key endpoint GET /pakms/apikey using the access_token.
Set the authorization: Bearer as your OAuth-generated access_token. See Authenticate with OAuth.

curl --request GET \
  --url 'https://scl-sandbox.dev.clover.com/pakms/apikey' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {auth_token}'

The server returns an apiAccessKey.

Create a card token request with a card object and its required fields: number, exp_month, exp_year, cvv, and brand.
In the apikey header, enter the apiAccessKey and send the request to the token endpoint: POST /v1/tokens.

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": "2031",
      "cvv": "123",
      "brand": "DISCOVER"
    }
  }'

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

Create a charge POST /v1/charges request with the Clover token as the source and an amount in cents. The card is charged for the specified amount.