Clover development basics

With the Clover Ecommerce API and SDKs, you can build seamless PCI compliant payment experiences for merchants with hosted iframes and API integrations.

All payments and transactions with the Clover Ecommerce API are PCI compliant.

📘

NOTE

The API and all related features are currently available in the US and Canada. We will provide updated information as Clover extends availability for more regions.

Accepting payments

The standard flow for accepting payments with Ecommerce API consists of two steps.

Ecommerce API standard flowEcommerce API standard flow

Ecommerce API standard flow

🚧

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. See Integration types for more information.

For using the API only integration in production, you must have (or use a service that has) a PCI DSS certification.

Step 1: Tokenize a customer card

Securely encrypt a customer card as a source token.

In the following example, you send a POST request to the /v1/tokens REST API endpoint to tokenize a card number. Using this endpoint requires a Public Access Key Management Service (PAKMS) key. This key uniquely identifies the merchant tokenizing customer cards.

To generate a PAKMS key, send a GET request to the /v1/pakms/apikey endpoint. Set the authorization: Bearer header value as an OAuth-generated auth_token for a test merchant with specific permissions.

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 PAKMS key. Set this value as the apikey header and send a POST request to the /v1/tokens endpoint. See Generating a card token for more information about encrypting card data and then tokenizing the encrypted data.

curl --request POST \
  --url 'https://token-sandbox.dev.clover.com/v1/tokens' \
  --header 'accept: application/json' \
  --header 'apikey: {apikey}' \
  --header 'content-type: application/json' \
  --data '{"card":{"number":"6011361000006668","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_.

Step 2: Pay for a charge or order

Use the source token to pay for a charge or an order.

In the following example, you send a POST request to the /v1/charges endpoint to pay for an $18.00 charge. Set the authorization: Bearer header value as the auth_token generated in step 1. Set the source value as the token generated in step 1.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/charges' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {auth_token}' \
  --header 'content-type: application/json' \
  --data '{"amount":1800,"currency":"usd","source":"{token}"}'

The server returns a unique charge id, payment status, and additional information about the transaction.

See Ecommerce data model for more information about the different data objects your apps interact with for different Ecommerce API flows.

📘

NOTE

With the exception of tokenizing a card, all Ecommerce API endpoints require an OAuth-generated auth_token with specific permissions.

There can be additional steps for flows such as creating orders, creating customers, or refunding charges.

Ecommerce API tools

Depending on the app features you want to build for merchants, you can integrate with different Ecommerce API tools.

Clover-hosted iframe

Customers can use the Clover-hosted iframe to securely submit card data and pay for products and services. The customer card data is encrypted as a source token for a subsequent transaction with the merchant.

Clover-hosted iframeClover-hosted iframe

Clover-hosted iframe

You can embed and customize the hosted iframe in your Ecommerce solutions, such as an online store, for Clover merchants. See Clover iframe integrations for more information.

🚧

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. See Integration types for more information.

For using the API only integration in production, you must have (or use a service that has) a PCI DSS certification.

REST API

With the Ecommerce REST API services, you can pay for charges or orders. The source tokens for these payments are generated by the Clover-hosted iframe.

In addition, you can build custom solutions where you control the entire payment flow, including generating a source token.

Next steps

In the following sections, you can learn more about using the Clover Ecommerce API:


Did this page help you?