REST Pay Display API and Ecommerce API can work together seamlessly. Merchants can use card on file (COF) information generated using the REST Pay Display API when a customer visits a store and makes a card-present payment. This token can be used later for card-not-present transactions through the Ecommerce API when creating a charge.

Use REST Pay Display API tokens with the Ecommerce API

The interoperability of REST Pay Display API and Ecommerce API ensures consistent payment processing across purchase-and-pay omnichannels. The high-level steps for this interoperability are:

1. Send a pay request with the option to tokenize the card in the request. In this case, the tokens returned are always Ecommerce compatible if the vaultCard parameter in deviceOptions is set to true. This token is used in the Ecommerce API. See Pay and tokenize for the request and response parameters.
2. Set the token generated through REST Pay Display API as the source value on the Ecommerce API.

Check merchant setup for multi-pay tokens

Subsequent recurring transactions using vaulted cards must be initiated through the Ecommerce API using a multi-pay token.

If the merchant is configured for multi-pay tokens, you can use the card tokens from the {baseUrl}/connect/v1/payments endpoint for recurring card-not-present (CNP) payments. This lets you build an integrated app where a customer's card data is captured in-person and then charged in the future without being present.

To check if a merchant is set up for multi-pay tokens:

1. Send a GET request to the /v3/merchants/{merchantUUID}/gateway endpoint.
2. In the response, check that the supportsMultiPayToken value is true. You can also see the merchant's credit card surcharge rate in the rate field.

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{merchantUUID}/gateway' \
  --header 'accept: application/json'

{
  "accountName": "Sandbox Test Merchant",
  "supportsMultiPayToken": true,
  ...
}

Use case 1: One-time charge with a recurring subscription

A retail store offers a monthly soap subscription mailed to the customer's home. The initial charge is $20, and each month is an additional $15. A new customer enrolls in December for an annual subscription and pays the $20 charge in the store.

Step 1: REST Pay API is used: When the customer makes a purchase in a store, the presented card information is tokenized to use for future payments. See Pay and tokenize for the request and response parameters.

Step 2: Ecommerce API is used: After the first payment of $20, on the 1st of each of the following months until the subscription is active, the merchant automatically charges the customer $15 for that month's soap delivery using the Ecommerce API /v1/charges endpoint. When the recurring charge is processed, the customer is automatically notified with an email receipt.

Use case 2: No upfront charge with a recurring subscription

A salon offers an annual subscription for hair care services, with the first month's service free of cost. After the trial month, the customer has to pay $22 for each of the next 11 months of service.

This scenario, with a recurring subscription without an upfront charge, is not supported. Clover recommends leveraging use case 1 to address such a scenario and applying a one-time charge of the smallest acceptable amount, such as $1, to create a token. This one-time charge needs to be voided immediately after a token is created. It's the responsibility of the developer and merchant to keep the cardholder informed about the smallest acceptable amount of transaction required on their card to validate their card details.

Note: Clover is working on addressing the limitation around use case 2 to provide an omnichannel experience where the tokens can be generated using the card token endpoint in the REST Pay API: {baseUrl}/connect/v1/payments.