Articles in this section

Credential-On-File - Cardholder Initiated and Merchant Initiated Transactions

Neil Ferguson
  • Updated
Follow

Table of Contents

 

Overview

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

 

What Is Credential-on-File?

A Credential-on-File (COF), or 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). Credential-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.

 

Credential-on-File Flow

The below applies for the following transaction types:

  • Auth
  • Pre-Auth

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.
    • Include the TransactionReason if possible.
  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.
      • Include the TransactionReason if possible.

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

 

Overriding Default First Store Behavior

The presence of Card Data (PAN/Track 2) will, by default, determine if a transaction is a first store transaction. In the absence of Card Data, a tokenized transaction (using Card Hash and Card Reference) will default to indicate that the transaction is a subsequent transaction.

If you are using your own card store and sending card details in each card transaction, instead of a token, then it is necessary to include the FirstStore flag to override the default value (true).

 

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, // Transaction reason if submitted by merchant
		sFirstStoreCardEaseReference // From first store transaction
	)
};

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