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. 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

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.

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.

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

• The app requests to pay and vault through REST Pay Display, saving the token returned from Clover. See Pay and tokenize.

• The app creates the customer's recurring payment plan on Clover Ecommerce API using the previously obtained token.

Use case: Payment upon delivery of service or goods

A customer requests to authorize the card in person, saving their card on file for future use. The customer and merchant agree to submit the final payment upon receiving goods or services. See Use a multi-pay card token for more information.

• The app requests the token through REST Pay Display.

• The app creates a charge through the Clover Ecommerce API using previously obtained tokens. 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.