The REST Pay Display API provides the /v1/card/tokens endpoint to capture an encrypted card token and store or vault it for later use. Merchants can process recurring payments without the cardholder being present and quickly complete in-person transactions. Card tokens are one-way encrypted and can be stored on systems outside of Payment Card Industry Data Security Standard (PCI DSS) scope.

Before you begin

• Tokenization through REST Pay Display API is not supported in Europe.
• Multipay card tokens created using the /v1/card/tokens endpoint are also used for card-not-present transactions through the Ecommerce API.

Prerequisites

• POS is connected to the device using a network or cloud connection.
• Clover device is idle; that is, no payment is being taken.
• Merchant account is configured for multi-pay tokens. To confirm get the merchant's payment gateway information and verify that supportsMultiPayToken is true.

Vault a card

1. To vault a card on the Clover device, do one of the following:

• To get an Ecommerce charge token, construct a request with the required data—the tokenType:

{
  "tokenType": "ECOMM_COMPAT"
}

• When an Ecommerce-compatible token is not needed, construct the request with an empty body.

2. Send a POST request to the /v1/card/tokens endpoint.
3. Required. Include the required headers for your request.
   The customer is asked to present their card. After the tokenization process is complete, a success message appears.

4. See Display the welcome screen for instructions to display the default idle screen, or take other appropriate action.

📘

NOTE

The returned token must have a clv_ prefix to use with the Ecommerce API. If the token you receive is not prefixed, verify that your request specifies the tokenType as ECOMM_COMPAT.

Take payments with vaulted cards

Take a payment with an Ecommerce card token

After you have a card token stored for a customer, you can make charges against the card with card-not-present.

1. Construct a request for the charge with the order amount and currency, and set the source value as the token.

• Include a receipt type and a description in the request.
• With an Ecommerce charge, the customer cannot receive a physical receipt, so set their email address as the value of receipt_email. The following is an example of an Ecomm charge. Note the token (source) has a clv_ prefix, and the receipt is emailed to the customer.

{
  "amount": 3000,
  "currency": "usd",
  "receipt_email": "[email protected]",
  "description": "Message text",
  "source": "{clv_TokenValue}",
  "stored_credentials":  {"sequence": "SUBSEQUENT", "is_scheduled": {SCHEDULED VALUE}, "initiator": "{MERCHANT or CUSTOMER}"}
}

2. Send a POST request to the {ecommBaseUrl}/v1/charges endpoint.
   The customer's card is charged for the specified amount. After the payment is complete, a success message appears.

{
  "id": "YHT8X021TT270",
  "amount": 3000,
  "amount_refunded": 0,
  "currency": "usd",
  "created": 1617207089466,
  "description": "Message text",
  "captured": true,
  "ref_num": "1167554668",
  "auth_code": "851141",
  "outcome": {
    "network_status": "approved_by_network",
    "type": "authorized"
  },
  "paid": true,
  "status": "succeeded",
  "source": {
    "id": "clv_1TSTSQVqNDvM3t5SPBuGYT45",
    "brand": "DISCOVER",
    "exp_month": "12",
    "exp_year": "2025",
    "first6": "601136",
    "last4": "6668"
  }
}

Take a payment with a Clover legacy card token

After you have a card token stored for a customer, you can make charges against the card with card-not-present.

1. Construct a request for the payment with:

• Order amount.
• externalPaymentId.
• vaultedCard object with the required card information.
• description in the request.

{
  "amount": 3000,
  "description": "Message text",
  "externalPaymentId": "{externalPaymentId}",
  "vaultedCard": {
    "expirationDate": "1221",
    "token": "{tokenValue}",
    "cardholderName": "Test Cardholder",
    "first6": "601136",
    "last4": "6668"
  }
}

2. Send a POST request to the {baseUrl}/v1/payments endpoint.
   The customer's card is charged for the specified amount. After the payment is complete, a success message appears.