What is card on file (COF)?

Card on file (COF) transactions are payments in which the cardholders have authorized merchants to store their credit or debit card information to use for future purchases or recurring payments. You can use sandbox test cards to build and test the COF feature. A COF payment requires that the Clover merchants have multi-pay tokens enabled in their gateway settings. After you generate a card token, use the source token to save COF.

🚧

IMPORTANT

Clover requires getting the customer’s consent before you save card-on-file in the customer’s profile.

Prerequisites

Before you create a customer, complete the following:

1. Create a sandbox account.
2. Create an app.
3. Install your app to your test merchant.

Save a card for a new customer

1. Send a POST request to the /v1/customers endpoint to create a card-on-file customer.
2. Enter the values in the following required parameters in the request body:
   1. email
   2. source

Request example

The following is a sample request when issuing a Create a card on file customer endpoint:

curl --request POST \
     --url https://scl-sandbox.dev.clover.com/v1/customers \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ab86a5e8-48f3-b3bd-8c45-d415e9867833' \
     --header 'Content-Type: application/json' \
     --data '{"ecomind":"ecom"}'

Request parameters

The following table describes the request parameters to use when creating a card-on-file customer:

Response parameters

The following is a sample response when issuing a Create a card on file customer endpoint.

{
  "id": "SSHHCDEXTF550",
  "object": "customer",
  "created": 1659650347317,
  "currency": "USD",
  "email": "[email protected]",
  "phone": "4085551858",
  "name": "Joe Doe",
  "sources": {
    "object": "list",
    "data": [
      "ND2EFTHF8HM34"
    ]
  },
  "shipping": {
    "name": "Joe Doe",
    "phone": "4085551858"
  }
}

In response, a unique id (customer ID) is generated for the created customer. You can use this customer id as the source value to submit payments with a saved customer card or card-on-file. See Use customer ID.

Save a new card for an existing customer

To save a new card for an existing customer, you need to complete two steps:

1. Revoke the existing card.
2. Add the new card information.
3. Send a DELETE request to /v1/customers/{customerId}sources/{cardId}.

curl --request DELETE \
--url 'https://scl-sandbox.dev.clover.com/v1/customers/{customerId}/sources/{cardId}' \
--header 'accept: application/json' \
--header 'authorization: Bearer {accessToken}'\

4. After the existing card is revoked, send a PUT request to the /v1/customers/{customerId} endpoint to add a new card to the existing customer record:
5. Complete or review the information in the required fields:

• source token value
• customerId
• email address—Used to notify the customers that their card data is saved to their profile. See the API reference for more information about other values you can set.

6. Set the authorization: Bearer as your OAuth-generated access_token.
7. Retokenize the card using your OAuth-generated access_token. See Generate a card token.

curl --request PUT \
  --url 'https://scl-sandbox.dev.clover.com/v1/customers/{customerId}' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"source":"{token}"}'

Make subsequent payments with saved cards

To make a payment and then subsequent payments with a saved customer card, you can use either the customer id or the multi-pay card token as the source value in your payment request.

Use customer ID

To create a charge request, set the amount (in cents), currency, and source as the customer id.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/charges' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'idempotency-key {uuid4_key}' \
  --header 'content-type: application/json' \
  --header 'x-forwarded-for: {client_ip}' \
  --data '{"amount":2300,
  				"currency":"usd",
          "Source":"{customer_id}"}'

📘

NOTE

If your use case requires you to save one card per customer, set the source as the customer id in any subsequent payments for that customer. If you are saving multiple cards per customer, use the multi-pay token for that customer in subsequent payments.

Use a multi-pay card token

When you save a card on file using /v1/customers, Clover sets the card source token as a multi-pay token for the customer. If you set the source value as this multi-pay token for the customer, you must also include the required stored_credentials values in the payment request:

Multi-pay card token example

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/charges' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'idempotency-key {uuid4_key}' \
  --header 'content-type: application/json' \
  --header 'x-forwarded-for: {client_ip}' \
  --data '{"amount":1800,
  "currency":"usd",
  "source":"{multi_pay_token}",
  "stored_credentials":{
  "sequence": "SUBSEQUENT",
  "is_scheduled": false,
  "initiator": "CARDHOLDER"}}'

See the Create a charge for more information about otherPOST /v1/charges values you can set.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/orders/{orderId}/pay' \
  --header 'accept: application/json'
  --header 'authorization: Bearer {access_token}'
  --header 'content-type: application/json'
  --header 'x-forwarded-for: {client_ip}' \
  --data '{"source":"{multi_pay_token}",
  "email":"[email protected]",
  "stored_credentials":{
  "sequence": "SUBSEQUENT",
  "is_scheduled": false,
  "initiator": "CARDHOLDER"}}'

See the Create an order for more information about otherPOST /v1/orders/{orderId}/pay values you can set.

Possible responses

The following table describes the possible responses when running the create a card-on-file customer endpoint: