Overview

Tokenization or vaulted card requests made through Clover REST Pay Display API require additional steps for developers to ensure compliance with card-on-file (COF) mandates, also called the Stored Credential Transaction framework.

📘

NOTE

Tokenization through REST Pay Display API is not supported in Europe.

Card on File background

In October 2017, Mastercard^® and Visa^® issued new rules regarding the use of stored credentials. A stored credential is information, including but not limited to an account number or payment token, that a merchant or its agent stores to process future transactions. This mandate requires specific handling and transmission of stored credentials—in this case, tokens representing payment data. See Visa documentation for more information: Improving Authorization Management for Transactions with Stored Credentials.

Use 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. See Recurring Payments and Subscriptions APIs for more information.

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 or charges, then the following object or 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 to whether this transaction was 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 gym member by completing their initial payment in person. All subsequent monthly membership payments will be processed through the Clover Ecommerce Recurring and Subscription API.

• Your app initiates a payment and vaults the card using REST Pay Display, saving the token returned by Clover. See Pay and tokenize.
• Your app then creates the customer’s recurring payment plan using the Clover Ecommerce API and the saved token.

Use case: Payment upon delivery of service or goods

A customer authorizes their card in person, allowing it to be saved on file for future use. The customer and merchant agree that the final payment will be submitted upon delivery of goods or services. Subsequent recurring transactions using vaulted cards must be initiated through the Ecommerce API using a multi-pay token.

• Your app requests a token using REST Pay Display.
• Your app processes the charge through the Clover Ecommerce API using the saved token.
  Stored Credential Settings: subsequent, scheduled, and merchant-initiated.

Product update

User experience for tokenization

A key component of the Mastercard and Visa mandate is that merchants must obtain the cardholder's consent before storing their credentials (vaulted card or 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, a token is returned. Otherwise, the REST Pay Display API returns a Tokenization Failure error.

Only v2/card/tokens prompt customers for their consent. The endpoint v1/card/tokens does not support this behavior. This customer prompt can be suppressed by setting the "suppressConfirmation": true as needed, but Clover recommends always prompting 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

Clover semi-integrated payment solutions now support prompting cardholders for their consent automatically upon tokenization requests.

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 is returned, and a tokenizationFailure is 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. This is done by processing an initial payment or by verifying a $1 account through Clover REST Pay Display API. For more information, see REST Pay Display interoperability with Ecommerce API.
• Disclose to cardholders how their credentials will be used.
• Notify cardholders when any changes are made to the terms of use.