Credential on File - Cardholder and Merchant Initiated Transactions

Table of Contents

• Overview
• What Is Credential on File?
• Credential on File Transaction Flow
  1. Initial Transaction - First Store
  2. Subsequent Transactions
  3. Overriding Default First Store Behavior
• C# Examples
  1. Initial Transaction - First Store
  2. Subsequent Transactions

Overview

The following article goes into detail about 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 Transaction Flow

The below applies to the following transaction types:

• Auth
• Pre-Auth

Initial Transaction - First Store

NMI's Hosted Payment Page (eKashu) solution can also be used to carry out the First Store process. For more information on that, please reference this article.

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",
	...
	PAN = "***************",
	ExpiryDate = "****",
	CredentialOnFile = new CredentialOnFile(
		TransactionInitiatedBy.CardHolder,
		TransactionReason.Empty
	)
};
// Setup the client
Client client = new Client();
client.AddServerURL("{PLATFORM_ENDPOINT}", 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",
        ...
	CardHash = sCardHash, // From first store transaction
	CardReference = sCardReference, // From first store transaction
	CredentialOnFile = new CredentialOnFile(
		TransactionInitiatedBy.Merchant,
		TransactionReason.Resubmission, // Transaction reason if submitted by merchant
		sFirstStoreCardEaseReference // From first store transaction
	)
};
// Setup the client
Client client = new Client();
client.AddServerURL("{PLATFORM_ENDPOINT}", 45000);
client.Request = request;
try
{
	// Process the request and handle response
	client.ProcessRequest();
	Response response = client.Response;
}