Articles in this section

Card-On-File / Merchant Initiated Transactions

Neil Ferguson
  • Updated
Follow

Table of Contents

 

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, set the appropriate MerchantTransactionReason.
      • If the transaction was initiated by the cardholder set this to 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, set the appropriate MerchantTransactionReason.
    • If the transaction is a form of debt repayment, this should 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:

Initial Transaction - First Store

// Setup the request
Request request = new Request
{
	RequestType = RequestType.Auth,
	Amount = "123",
	SoftwareName = "SoftwareName",
	SoftwareVersion = "SoftwareVersion",
	TerminalId = "********",
	TransactionKey = "****************",
	PAN = "***************",
	ExpiryDate = "****",
	CredentialOnFile = new CredentialOnFile(
		TransactionInitiatedBy.CardHolder,
		MerchantTransactionReason.Empty
	)
};

// Setup the client
Client client = new Client();
client.AddServerURL("https://test.cardeasexml.com/generic.cex", 45000);
client.Request = request;

try
{
	// Process the request and handle response
	client.ProcessRequest();
	Response response = client.Response;
	/* Store for subsequent transactions:
	 *  Card Hash
	 *  Card Reference
	 *  CardEase Reference
	 */
	string sCardHash = response.CardHash;
	string sCardReference = response.CardReference;
	string sFirstStoreCardEaseReference = response.CardEaseReference;
}

Subsequent Transactions

// Setup the request
Request request = new Request
{
	RequestType = RequestType.Auth,
	Amount = "123",
	SoftwareName = "SoftwareName",
	SoftwareVersion = "SoftwareVersion",
	TerminalId = "********",
	TransactionKey = "****************",
	CardHash = sCardHash, // From first store transaction
	CardReference = sCardReference, // From first store transaction
	CredentialOnFile = new CredentialOnFile(
		TransactionInitiatedBy.Merchant,
		MerchantTransactionReason.Resubmission,
		sFirstStoreCardEaseReference, // From first store transaction
		bDebtRepayment // false/true as required
	)
};

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

Related articles