Articles in this section

Card-On-File / Merchant Initiated Transactions

Neil Ferguson
  • Updated
Follow

Table of Contents

  1. Overview
  2. What Is Card-on-File?
  3. Card-on-File Flow
  4. C# Examples

 

Overview

The following article goes into detail of card-on-file (COF) and how these transactions should be correctly flagged on our platform.

 

What Is Card-on-File?

A card-on-file transaction is where a cardholder authorizes a merchant to store and subsequently charge their card at a later date (e.g. tokenization). Card-on-file transactions can be initiated by either the cardholder or the merchant.

Cardholder initiated transactions are the cardholder requesting the merchant to initiate a transaction. This could be paying for goods in a store, over the phone or online.

Merchant initiated transactions are the merchant processing a transaction as a result of an agreement with the cardholder such as debt recovery.

Any tokenized transactions using the card reference and card hash (e.g. the token) need to abide by the implementation details below.

 

Card-on-File Flow

The below applies for the following transaction types:

  • Auth
  • Pre-Auth
  • Linked Refund

Initial Transaction - First Store

  1. Perform a transaction using the raw card details (EMV data/full pan) and flag who initiated the transaction (the merchant or the cardholder). This indicates the transaction as being a COF initiated transaction that will be used for COF later. This transaction is known as the 'first store'. See example 1 below.
    • Ensure to flag if it was the CardHolder or Merchant who initiated the transaction using the TransactionInitiatedBy property.
      • If the transaction was initiated by the merchant, include the MerchantTransactionReason too.
      • If transaction was initiated by cardholder, include MerchantTransactionReason.Empty
  2. The card reference and card hash (token) are returned in the transaction response from our platform. This can be used at a later date to perform a subsequent, tokenized transaction flagged as COF.
    • Ensure to store the card reference, card hash, and the original CardEase Reference as they'll be needed when performing COF transactions.

Please refer to the API docs for a full list of valid property values.

Subsequent Transactions

  1. Perform a transaction using the card reference and card hash (token). See example 2 below.
    • Ensure to include the original CardEase Reference within the CardEaseReference property from the initial 'first store' transaction performed.
    • Ensure to flag if it was the CardHolder or Merchant who initiated the transaction using the TransactionInitiatedBy property.
      • If the transaction was initiated by the merchant, include the MerchantTransactionReason too.
    • If the transaction is a form of debt repayment, this should also be flagged using the DebtRepayment property. By default, this value is set to false if not sent.

Please refer to the API docs for a full list of valid property values.

C# Examples:

Example 1 - Initial Transaction (First Store)

 Request request = new Request();
​
 request.RequestType = RequestType.Auth;
 request.Amount = "123";
 request.SoftwareName = "SoftwareName";
 request.SoftwareVersion = "SoftwareVersion";
 request.TerminalID = "********";
 request.TransactionKey = "****************";
​
​
 request.PAN = "***************";
 request.ExpiryDate = "****";

 TransactionInitiatedBy transactionInitiatedBy = TransactionInitiatedBy.CardHolder;
 MerchantTransactionReason merchantTransactionReason = MerchantTransactionReason.Empty;

​ CredentialOnFile cof = new CredentialOnFile(
 transactionInitiatedBy,
 merchantTransactionReason
 );

 request.CredentialOnFile = cof;

 /*Setup the client*/
 Client client = new Client();
 client.AddServerURL("https://test.cardeasexml.com/generic.cex", 45000);
 client.Request = request;
​
 try
 {
 /*Process the request*/
 client.ProcessRequest();
 }

 Response response = client.Response;
 string cardHash = response.CardHash; /*Storing Card Hash for subsequent transactions*/
 string cardReference = response.CardReference; /*Storing Card Reference for subsequent transactions*/
 string initialcardEaseReference = response.CardEaseReference; /*Storing CardEase Reference for subsequent transactions*/

Example 2 - Subsequent Transactions

 Request cofRequest = new Request();
​
 cofRequest.RequestType = RequestType.Auth;
 cofRequest.Amount = "123";
 cofRequest.SoftwareName = "SoftwareName";
 cofRequest.SoftwareVersion = "SoftwareVersion";
 cofRequest.TerminalID = "********";
 cofRequest.TransactionKey = "****************";
 
 cofRequest.CardHash = cardHash; /*Stored Card Hash from initial transaction*/
​ cofRequest.CardReference = cardReference; /*Stored Card Reference from initial transaction*/

 TransactionInitiatedBy transactionInitiatedBy = TransactionInitiatedBy.Merchant;
 MerchantTransactionReason merchantTransactionReason = MerchantTransactionReason.Resubmission;
 bool debtRepayment = false;
​
 CredentialOnFile cof = new CredentialOnFile(
 transactionInitiatedBy,
 merchantTransactionReason,
 initialcardEaseReference, /*Stored CardEase Reference from initial transaction*/
 debtRepayment
 );

 request.CredentialOnFile = cof;

 client.Request = request;
​
 try
 {
 /*Process the request*/
   client.ProcessRequest();
 }

Related articles