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, or recurring tokenized transactions.
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 for the following transaction types:
- Auth
- Pre-Auth
Initial Transaction - First Store
- Initiate a transaction ensuring the CoF properties are included in the request. This transaction is known as the 'first store'. See example 1 below.
-
ekashu_cof_initiated_by
must be set to eitherCardHolder
orMerchant
. -
ekashu_cof_reason
must be set to be of the following:Empty
,Unscheduled
,Installment
,Recurring
,Incremental
,Resubmission
,DelayedCharge
,ReAuth
,NoShow
. -
ekashu_3d_secure_v2_challenge_indicator
must be set to04
.
-
- 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 (
ekashu_card_reference
), Card Hash (ekashu_card_hash
), and the CardEase Reference (ekashu_transaction_id
) as they'll be needed when performing subsequent CoF transactions.
- Ensure to store the Card Reference (
Subsequent Transactions
Typically, solutions utilizing the CoF transaction flow would use NMI's Direct Connect solution to programmatically send a request to the NMI gateway, more information on that process can be found in this article. However, NMI's Hosted Payment Page solution can be used to process these transactions.
- Perform a transaction using the card reference and card hash (token). See example 2 below.
-
ekashu_card_reference
must be set to the Card Reference token part. -
ekashu_card_hash
must be set to the Card Hash token part. -
ekashu_cof_initiated_by
must be set to eitherCardHolder
orMerchant
. -
ekashu_cof_reason
must be set to be of the following:Empty
,Unscheduled
,Installment
,Recurring
,Incremental
,Resubmission
,DelayedCharge
,ReAuth
,NoShow
. -
ekashu_cof_id
must be set to the first store CardEaseReference value.
-
Examples:
Initial Transaction (First Store)
<form action="https://test.ekashu.com" method="post"> ... <input type='hidden' name='ekashu_cof_initiated_by' value='Cardholder'/> <input type='hidden' name='ekashu_cof_reason' value='Recurring'/> ... </form>
Subsequent Transactions
<form action="https://test.ekashu.com" method="post"> ... <input type='hidden' name='ekashu_card_hash' value='{CardHash}'/> <input type='hidden' name='ekashu_card_reference' value='{CardReference}'/> <input type='hidden' name='ekashu_cof_id' value='{CardEaseReference}'/> <input type='hidden' name='ekashu_cof_initiated_by' value='Merchant'/> <input type='hidden' name='ekashu_cof_reason' value='Recurring'/> ... </form>