Creating and using a card token

The API provides the /v1/card/tokens endpoint to capture an encrypted card token and store it (vault it) for later use. This allows merchants to process recurring payments without the cardholder being present or to complete in-person transactions more quickly for returning customers. Card tokens are one-way encrypted and can be stored on systems outside of PCI DSS scope.

📘

NOTE

Multi-pay card tokens created with this endpoint can also be used for card-not-present transactions using the Ecommerce API. See REST Pay and Ecommerce Interoperability for more information.

Prerequisites

  • The POS is connected to the device using a network or cloud connection
  • The Clover device is in an idle state (that is, no payment is being taken)
  • The merchant account is configured for multi-pay tokens. This can be confirmed by getting the merchant's payment gateway information and checking that supportsMultiPayToken is true.

Vaulting a card

  1. To vault a card on the Clover device, do one of the following:
  • To obtain an Ecommerce charge token, construct a request with the required data (the tokenType):
{
  "tokenType": "ECOMM_COMPAT"
}
  • If an Ecommerce-compatible token is not needed, construct the request with an empty body.
  1. Send a POST request to the /v1/card/tokens endpoint. Be sure to include the required headers for the request you are making.

The customer is asked to present their card. After the tokenization process is complete, a success message is returned.

  1. See Showing the welcome screen for instructions on displaying the default idle screen, or take the action that is appropriate for your situation.

📘

NOTE

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

Taking payments with vaulted cards

Taking a payment with an Ecomm card token

After you have a card token stored for a customer, you can make charges against the card without the card being presented.

  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 won't be able to receive a physical receipt, so you should 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 will be emailed to the customer.

{
  "amount": 3000,
  "currency": "usd",
  "receipt_email": "[email protected]",
  "description": "Message text",
  "source": "{clv_TokenValue}"
}
  1. 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 is returned.

{
  "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"
  }
}

Taking 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 without the card being presented.

  1. Construct a request for the payment with the order amount, an externalPaymentId and a vaultedCard object with the required card information. Include a description in the request.
{
  "amount": 3000,
  "description": "Message text",
  "externalPaymentId": "{externalPaymentId}",
  "vaultedCard": {
    "expirationDate": "1221",
    "token": "{tokenValue}",
    "cardholderName": "Test Cardholder",
    "first6": "601136",
    "last4": "6668"
  }
}
  1. 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 is returned.


Did this page help you?