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
- 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
orMerchant
who initiated the transaction using theTransactionInitiatedBy
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
- If the transaction was initiated by the cardholder set this to
- Ensure to flag if it was the
- 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
- 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
orMerchant
who initiated the transaction using theTransactionInitiatedBy
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 tofalse
if not sent. This flag should only be used by merchants wherein the transaction is a form of debt repayment. It should not be flagged during resubmissions of transactions that have previously failed, and as a result the cardholder is in 'debt' to the merchant.
- Ensure to include the original CardEase Reference within the
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; }