What's NewAnnouncementsWebinarsCommunityBlog

Card on File compliance for REST Pay Display

United States
Canada

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:

960

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