Card-On-File Data Inquiry Documentation

Ready to start coding?

Things To Know

A suite of technologies that bundles both new and existing Visa capabilities that allow a consumer to add, view and manage their Visa card through their Issuer’s online and mobile channels.

Message Level Encryption

Message Level Encryption (MLE) is required for all Card-On-File Data Inquiry implementations. MLE provides an enhanced security for message payload by using asymmetric encryption technique (public-key cryptography). The Card-On-File Data Inquiry request body is expected to be encrypted and the response body from the API will be encrypted as per MLE. You can generate the encryption/decryption key pairs in the Sandbox, Certification, or Production environments. For details, refer to the Message Level Encryption Documentation.

Availability

The following table lists the regional availability for Visa Account Management Suite. To view availability of all products, refer to the Availability Matrix.

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
Card-On-File Data Inquiry The Card-On-File Data API is currently being used by a few pilot issuers in each region. The pilot partners aim to expose these capabilities to consumers later this year. For questions on pilot partner status, please contact developer@visa.com.
Product Name Availability Notes
Card-On-File Data Inquiry The Card-On-File Data API is currently being used by a few pilot issuers in each region. The pilot partners aim to expose these capabilities to consumers later this year. For questions on pilot partner status, please contact developer@visa.com.
Product Name Availability Notes
Card-On-File Data Inquiry The Card-On-File Data API is currently being used by a few pilot issuers in each region. The pilot partners aim to expose these capabilities to consumers later this year. For questions on pilot partner status, please contact developer@visa.com.
Product Name Availability Notes
Card-On-File Data Inquiry The Card-On-File Data API is currently being used by a few pilot issuers in each region. The pilot partners aim to expose these capabilities to consumers later this year. For questions on pilot partner status, please contact developer@visa.com.
Product Name Availability Notes
Card-On-File Data Inquiry The Card-On-File Data API is currently being used by a few pilot issuers in each region. The pilot partners aim to expose these capabilities to consumers later this year. For questions on pilot partner status, please contact developer@visa.com.

Getting Started

Card-On-File Data Inquiry 

Consumers are storing their card credentials at more online retailers and service providers, but often lack visibility into which merchants have their card information and where the card information needs to be updated, when the card is reissued.

Transactions are either initiated by a consumer, or by a merchant based on the instructions given to them by the consumer. It is possible for a merchant to initiate a transaction without consumer action.

There are two classes of transactions:

  1. Consumer-Initiated Transactions (CIT):  A consumer-initiated transaction is a transaction where the consumer is present and provides their payment credentials. This can be through a terminal in-store, or online through a checkout experience. A consumer-initiated transaction contains proof that the cardholder was involved in the transaction. The proof may be through a number of different methods such as track data, chip data with cryptograms, cardholder verification methods, and online through the presence of Card Verification Value 2 (CVV2) or Verified by Visa (VBV) authentication data. The consumer-initiated transaction is the proof that the consumer and merchant entered into a relationship and that the payment credential presented was in fact a validly presented payment instrument.
  2. Merchant-Initiated Transactions (MIT): A merchant-initiated transaction is a transaction that relates to a previous consumer-initiated transaction, but it is conducted without the consumer present and without any additional cardholder validation performed. In all cases, a merchant-initiated transaction must refer to a consumer’s original interaction where a consumer and merchant have entered into an agreement for a recurring product or service or an automated billing or unscheduled transactions etc.
    There are many different kinds of merchant-initiated transactions. Examples include:

    Industry Specific Business Practices:
    • Reauthorization Transaction
    • Resubmission Transaction
    • Delayed Charges Transaction
    • Incremental Authorization Transaction
    • No Show Transaction

    Standing Instructions for the Initial Consumer Initiated Transaction

    • Installment Payment Transaction
    • Recurring Payment Transaction
    • Account Top Up Transaction
    • Unscheduled Stored Credential Transaction
    • Other Credential on File Transactions

Why use it ?

Card-On-File Data Inquiry was designed to provide information about the merchants with whom cardholders have stored their cards on file, and when the merchants have received updated card details, in the event of card reissuance.

API Features

  • API based on VDP standards to provide the merchant details (without the duplication of merchant names) from the transaction data, VAU requests and VTS COF Tokens for a given issuer
  • Visa PAN (or mapped Tokens) used to submit COF (authorization or full financial or account verification) transactions in the last thirteen months
  • Apply the criteria for both PAN & Token to identify where the PAN (or mapped Token) credentials are stored on file (identifying merchant names and corresponding Merchant Category Codes)
  • Provide an “update” indicator and update date in the API response to show which specific merchant(s) have received update(s) to the PAN and Token credentials via Visa Account Updater or Token Lifecycle Management

The below figure provides a high-level business concept as to how Visa scans the COF transaction data received from various sources within its systems and provides relevant merchant information in the API response.

How does it work ?

Card-on-File Data Inquiry provide issuers with information about the card-on-file merchants (to issuers) where cardholders have transacted or with whom cardholders have stored their PAN/Token credentials for merchants to initiate payments.

The most transparent way to flag “Card on File” transactions is by identifying transactions initiated with “Point of Sale Entry Mode 10 (PEM 10).” Visa introduced this transaction type in October 2016 and is working with industry participants to adopt the new PEM. However, until PEM 10 gains full industry adoption, Visa will use a combination of techniques to identify merchants for a given cardholder where that cardholder’s credential is likely stored on file by that merchant. For a given cardholder, Visa will identify merchants that:

  • Tokenized cardholder’s PAN (Through COF Token provisioning)
  • Initiated transactions using PEM 10 for that card
  • Initiated Recurring and Bill pay transactions
  • Performed VAU update for that card

Using the Card-On-File Inquiry, Issuers can enhance their mobile or online banking applications to show the list of merchants and other COF data attributes to provide visibility into where a consumer’s card credentials are stored. In the event of card reissuance, the issuer can also display information around which merchants have received updated card details.

API Included

Card-On-File Data API

This helps you easily to identify all the merchants who are having the consumer card credentials on their file for submitting recurring or bill pay type of transactions

User Experience

High-level user experience and the usage of Card-On-File Data Inquiry by the clients.

 

Prerequisites

  • VAU subscription by issuer is mandatory in order to communicate PAN updates and replacement information to Visa
  • Issuer application integrated with Visa Developer Portal to access Card-on-file Data API
  • Issuer online or mobile banking application is designed for its cardholders to provide the list of COF Merchants

Application Flow

  1. Cardholder logs into issuer online or mobile banking application and selects Payment account number to retrieve all COF Merchants
  2. Issuer submits the Payment Account Number to Visa
  3. Visa returns COF Merchant details as API response
  4. Issuer displays list of COF Merchants to cardholder

The following are example data elements that clients will receive from Visa in response to the COF Data API request:

  • Cleansed Merchant Name – Name of the merchant where the cardholder stored the card credentials and which merchant initiated the transaction.  It is important for cardholder recognition that the name that is used for the merchant descriptor be the name by which cardholders recognize the merchant
  • Merchant Category Code – Appropriate merchant category code (MCC) associated with the merchant
  • Number of transactions in the last thirteen (13) months – Number of transactions using the cardholder’s credentials stored on file in the last 13 months
  • Token Requestor ID – If the merchant is a VTS Token requestor, Visa populates the eleven-digit Token requestor ID (If not, this field will be blank)
  • Last Transaction date  - Visa populates the date in “mmddyy” format when the merchant initiated the last transaction using cardholder’s account credentials over the last thirteen (13) months
  • Update Flag – Visa populates Y or N flag when Visa sent the update to either PAN or Token credentials stored by the merchant in the last thirteen months using Visa Account Updater or Token Lifecycle Management
  • Update date – If the update flag above indicates that a recent update is made to PAN or Token credentials, Visa populates the date in “mmddyy” format when the most recent update was delivered to the merchant

Participants

This section describes the key stakeholders involved in the service and the benefits that this service offers to each of them. The below figure shows the stakeholders involved in the service utilization.

Card Issuer and Issuer Processor

Card issuers maintain and own the account relationship with the Cardholder, as well as owning authorization and ongoing risk management in the payment ecosystem including providing appropriate consumer disclosures (or obtaining consents) and addressing cardholder data privacy considerations. Issuers obtain information about the merchants who have the issuer cardholder’s account credentials on file and which merchants received updated account information when the issuer reissues or replaces the account credentials.

An Issuer processor may also submit the request to Visa on behalf of Issuer/cardholder.

Cardholder

Cardholders are issued PANs by the card issuer.  Cardholders may store card (PAN) or Token credentials at a merchant, so that the merchant can initiate transactions scheduled or unscheduled at cardholder’s request or so that the cardholder can initiate a transaction without having to input their card details at time of purchase.

In the case of card-on-file Tokenization, cardholders, generally, do not know that a Token has been issued to represent their account.  With the user experience that that issuers can provide their cardholders, cardholders benefit from increased visibility as to which merchants have their PAN and Token credentials on file, as well as the number of transactions associated with that merchant in the past thirteen (13) months.

Merchant

Merchants may store the PAN or Token credentials when a cardholder initiates a transaction on an electronic commerce website or using a merchant application running on a device.  Merchants use those payment credentials to initiate a transaction at cardholder’s request.  Merchants participating in VAU receive updated account information from Visa when issuers replace or reissue the cardholder’s account credentials.  Additionally, those merchants who are also Token Requestors will automatically benefit from issuers’ lifecycle management changes to update credentials.

Acquirer and Acquirer Processor

Acquirers process transactions (including authorization, capture clearing, and exception processing) for their merchants and send the transactions to payment networks for further processing.Acquirers participating in VAU may request updated account information from Visa on behalf of their merchants.

Visa Developer Platform

Visa Developer Platform (VDP) is a common web portal for partners and developers that provides a single entry point for all Visa Developer tools. VDP is an API management platform to enable development teams to rapidly build and deploy APIs providing ideas and sample codes.  The COF Data API will be accessible to issuers, issuer processors, and delegated agents (e.g., issuers may have application vendors to develop issuer applications) through VDP.

Visa Account Updater

VAU is a service designed to address the requirements of account-on-file transactions and to enable the secure exchange of updated account information among participating issuers, acquirers, and qualified account-on-file merchants. VAU supports typical account renewals or card replacements; account upgrades or downgrades; portfolio acquisitions and/or mergers; lost/stolen cards; other account closures; and MasterCard-to-Visa conversions. VAU provides the platform for issuers to communicate the most current changes to cardholder account information through acquirers to merchants whose business models support electronic maintenance of customer account information. Participating merchants use updated cardholder account information to support account-on-file functions, such as recurring payments, subscription services, Internet “one-click” merchants, and preferred customer programs such as travel and entertainment (T&E) Gold cards. VAU is designed to offer an automated, dedicated, and secure clearinghouse to make changes to cardholder account information available in a timely, efficient, and cost-effective manner.

Visa Token Life Cycle Management

Payment Tokens may have various life cycle events like activation, deletion, suspension and reactivation. Token Life Cycle Management is an online web application offered to the clients through Visa Online (VOL) portal.  This service enables the clients to manage situations where cardholder devices with payments Tokens are lost, stolen or damaged and a Token status update is necessary.  This service can also be used to update the new PAN or PAN expiry date when the cards are reissued to the cardholders.

Roles and Responsibilities

The following section outlines the roles and responsibilities for Visa and participating issuers regarding the API usage.

Visa

While Visa maintains sole discretion to offer and maintain the Visa Developer Platform, COF data API and all other products and services described herein, Visa presently intends to use reasonable efforts to—

  • Maintain the merchant information in its global merchant repository
  • Host Visa Developer Platform and maintain the sample code needed for the usage of COF data API on VDP
  • Review and maintain the services to comply with Visa global information security requirements and guidelines
  • Provide Level 2 and Level 3 operational support for the service

Issuers

All participating issuers must—

  • Comply with applicable Terms of Use and participation agreements with Visa to participate in the service
  • Develop or enhance their mobile application and/or online banking portal and use the information provided by Visa to provide that data to their cardholders
  • Provide account-change (account number change, expiration date change, closed accounts etc.) information to VAU
  • Provide Level 1 Help desk support for clients (consumers / cardholders) that are using their mobile application and/or online banking portal
  • Ensure availability of the services within issuer host systems for the  interactions that requires issuers to send the request and receive the response from Visa

API Description

  1. Data elements shared:
    • Input to Card-On-File Data API (From Issuers) : PAN(s) (up to 10)
    • Output from Card-On-File Data API (To Issuers) : PAN, merchant name, # of transactions (on Visa) in last 13 months, VAU update flag, token requestor ID, last transaction date, last 4 digits of old PAN