Save a card for future transactions

North America—United States and Canada

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:

ParameterTypeDescription
ecomindstringIndicates who entered the card data used for a charge - customer (ecom) or merchant (moto). Default: ecom
emailstringRequired. Customer's email address.
firstNamestringCustomer's first name.
lastNamestringCustomer's last name.
namestringCustomer's full name.
sourcestringPayment source to charge, such as a card, gift card, or ACH.
phonestringCustomer's phone number.
shippingobjectShipping information of the 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}'\
  1. 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:
  2. 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.
  1. Set the authorization: Bearer as your OAuth-generated access_token.
  2. 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:

ObjectTypeDescription
sequencestringIndicates the sequence of the transaction for the same payment card.
Values:

- First
- Subsequent
is_scheduledbooleanIndicates whether the transaction is scheduled or part of an installment.
Values:

- True - Transaction is scheduled.
- False - Transaction is part of an installment.
Installments are only available in the US.
initiatorstringIndicates whether the transaction is initiated by the merchant or with cardholder consent.
Values:

- Merchant
- Cardholer
installment_infostringInstallment information for the transaction.
bill_pay_indicatorstringIndicates whether the transaction is a recurring or installment payment.
Values:

- Installment
- Recurring - For Canadian merchants, the value must be "Recurring"
invoice_numberstringInvoice number of the installment or recurring transaction.
descriptionstringDescription of the installment_info or recurring transaction.

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:

MessageDescriptionVariableDescription
200 Successful responsestringSuccessful response. Returns the customer object.
400 Bad RequeststringcodeAdditional information about the error to help users identify the issue.
400 Bad Requeststringdecline_codeReturned when a card issuer declines the transaction. This includes the reason for the decline if specified by the card issuer.
400 Bad Requeststringdoc_urlURL (link) for more information about the reported error code.
400 Bad RequeststringmessageDetailed information about the error code. For card-related errors, this can provide more information to users.
400 Bad RequeststringparamIf the error is related to a specific parameter, this value lists the parameter. You can use this to inform users entering card information of a specific problem with their entry.
400 Bad RequeststringtypeReturned error type:

- api_connection_error
- api_error
- authentication_error
- card_error
- idempotency_error
- invalid_request_error
- rate_limit_error