Card on File compliance for REST Pay Display
Overview
Tokenization (or Vault Card) requests made through Clover REST Pay Display API require additional steps for developers to ensure compliance with Card on File mandates (also called Stored Credential Transaction framework).
Card on File background
In October 2017, Mastercard and Visa issued new rules regarding the use of stored credentials. This mandate requires specific handling and transmission of stored credentials (in this case, tokens representing payment data). See the following documentation for more information:
A stored credential is information (including, but not limited to, an account number or payment token) that is stored by a merchant or its agent to process future transactions.
Using Ecommerce API for subsequent transactions
NOTE
Only Clover Ecommerce API allows the use of Clover tokens for subsequent transactions. REST Pay Display does not support the use of a token as a payment method.
Tokens generated through REST Pay Display API can be set as the source
value on the Ecommerce API. If the token is to be used for subsequent payments/charges, then the following object/properties are also required:
- The sequence value as a FIRST or SUBSEQUENT transaction
- The is_scheduled value as whether this transaction is scheduled or part of an installment
- The initiator value as whether this transaction is initiated by the MERCHANT or with CARDHOLDER consent
"source":"{multi_pay_token}",
"stored_credentials":{
"sequence": "SUBSEQUENT",
"is_scheduled": false,
"initiator": "CARDHOLDER"
}'
Use case: Monthly gym membership
A customer enrolls as a new member of a gym completing their initial enrollment in-person by paying in-person. All subsequent payments for monthly membership will be made through Clover Ecommerce Recurring and Subscription API.
-
Application requests to Pay and Vault through REST Pay Display, saving the token returned from Clover.
-
Application creates the customer's recurring payment plan on Clover Ecommerce API using the previously obtained token.
-
See Recurring Payments and Subscriptions APIs for more information.
Use case: Payment upon delivery of service or goods
Customer requests to authorize the card in-person, saving their card on file for future use. The customer and merchant agree to submit final payment upon the receipt of goods/services.
-
Application requests the token through REST Pay Display.
-
Application creates a charge through the Clover Ecommerce API using previously obtained token.
- Stored Credential Settings: subsequent, scheduled, and merchant-initiated.
-
See Using a multi-pay card token for more information.
Product update
New user experience for tokenization
A key component of the Visa and Mastercard mandate is that merchants must obtain the cardholder's consent before storing their credential (vaulted card/token).
If a token is requested, customers are presented with the following prompt:

If the customer elects for the merchant to save their card, REST Pay Display proceeds with the tokenization attempt.
V2 tokenization
NOTE
To use
v2/card/tokens
, the Clover Core Payments App must be installed on the device.
Tokenization requests are subject to a card verification check with the payment processor. Only if the card is successfully verified, will a token be returned. Otherwise, REST Pay Display API will return a Tokenization Failure error.
Only v2/card/tokens
will prompt customers for their consent. v1/card/tokens
does not support this new behavior. This customer prompt can be suppressed by setting "suppressConfirmation": true
as needed, but Clover recommends to always prompt for consent by default.
V2 tokenization request and response
POST /connect/v2/card/tokens HTTP/1.1
Host: {env}.clover.com
X-Clover-Device-Id: {deviceSerialNumber}
X-POS-ID: {posId}
Idempotency-Key: {idempotencyKey}
Content-Type: application/json
Authorization: Bearer {oauthToken}
{
"cardEntryMethods" : ["EMV","NFC","MANUAL","MAG_STRIPE"],
"suppressConfirmation" : false
}
{
"confirmationSuppressed": false,
"expirationDate": "0521",
"first6": "512857",
"last4": "7294",
"token": "clv_1TSTSBiZ9ze8VBZCuWBkrr7t",
"tokenType": "ECOMM_COMPAT"
}
Pay and tokenize (new feature)
Clover semi-integrated payment solutions now support prompting cardholders for their consent upon tokenization requests automatically.
Pay and tokenize request and response
NOTE
"vaultCard": true
must be set in order to request a token as part of the payment response.
POST /connect/v1/payments HTTP/1.1
Host: {env}.clover.com
X-Clover-Device-Id: {deviceSerialNumber}
X-POS-ID: {posId}
Idempotency-Key: {idempotencyKey}
Content-Type: application/json
Authorization: Bearer {oauthToken}
{
"amount": 216,
"final": true,
"externalPaymentId": "SALE_VAULT_216",
"deviceOptions": {
"vaultCard": true,
"suppressConfirmation": false,
"cardEntryMethods": ["EMV","NFC","MANUAL","MAG_STRIPE"]
}
}
{
"issues": {
"duplicate": {
"description": "POTENTIAL_DUPLICATE"
},
"signature": {
"signature": {
"data": "/9j/4AAQSkZJ...",
"format": "JPG",
"gzip": false
}
}
},
"payment": {
"amount": 207,
"cardTransaction": {
"authCode": "914017",
"cardType": "MC",
"cardholderName": "CHIP TEST CARD",
"entryType": "EMV_CONTACT",
"extra": {
"applicationLabel": "4465626974",
"authorizingNetworkName": "MASTERCARD",
"routingIndicator": "C",
"cvmResult": "SIGNATURE",
"applicationIdentifier": "A0000000042203"
},
"first6": "512857",
"last4": "7294",
"referenceId": "204500606690",
"state": "CLOSED",
"transactionNo": "2500036",
"type": "AUTH"
},
"createdTime": 1644857673691,
"employee": {
"id": "G9ZDEKXHQF5V6"
},
"externalPaymentId": "SALE_VAULT_207",
"id": "T0QF97YZ2DF3A",
"offline": false,
"order": {
"id": "79KNQ85KCZFCR"
},
"result": "SUCCESS",
"taxAmount": 0,
"tipAmount": 0
},
"token": {
"confirmationSuppressed": false,
"expirationDate": "0521",
"first6": "512857",
"last4": "7294",
"token": "clv_1TSTSVmgTQD6A6L64bSD1P8b",
"tokenType": "ECOMM_COMPAT"
}
}
If the payment is successful and the tokenization fails, no token will be returned and a tokenizationFailure
will be added to the issues object.
{
"issues": {
"signature": {
"signature": {
"data": "/9j/4AAQSkZJR....",
"format": "JPG",
"gzip": false
}
},
"tokenizationFailure": {
"description": "User declined Tokenization : USER_DECLINED"
}
},
"payment": {
"amount": 204,
...
}
}
Additional requirements for developers
If your application stores tokens to use in subsequent transactions, you are responsible for the following components of this mandate:
NOTE:
Clover collects a general consent agreement from the customer to proceed with either a tokenization request and/or payment. Card on File rules require additional steps that merchants and software developers must take to reach full compliance. Merchants are still responsible to perform the following activities when saving customer cards (tokens) on file.
- “Inform” the account issuer that payment credentials are now stored on file, either by processing an initial payment or a $0 account verification through Clover REST Pay Display API.
- Disclose to cardholders how those credentials will be used.
- Notify cardholders when any changes are made to the terms of use.
Updated 2 days ago