Clover Ecommerce basics

United States

Canada

With the Clover Ecommerce API and SDKs, you can build seamless Payment Card Industry (PCI) compliant payment experiences for merchants with hosted iframe and API integrations. All payments and transactions with the Clover Ecommerce API are PCI compliant.

Accept payments

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

🚧
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 identifies the merchant who is tokenizing their customers' 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_.

📘
NOTE
To learn more, see our blog post Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys.

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' \
  --header 'x-forwarded-for: {client_ip}' \
  --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.

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.

API endpoints: See Ecommerce API tutorials for more information.
SDKs: See Ecommerce Software Development Kits (SDKs) for more information.

Next steps

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

Updated 2 months ago