Ecommerce API: Accept payments flow

United States
Canada

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

840

Ecommerce API standard flow

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. For more information, see Authenticate with OAuth—Canada and US.

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 Generate 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. For more information, see Authenticate with OAuth—Canada and US.

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