Card on File

Last updated: April 18th 2022, @ 9:50:42 am


A Card on File, or stored credentials, is information a merchant, its agent, a payment facilitator, or a staged digital wallet operator stores about a cardholder to process future transactions. The stored information includes, but is not limited to, an account number or a payment token. Credentials are not considered a stored when the details of a card are used to:

  • Complete a single transaction
  • Complete multiple authorizations related to the initial transaction, such as incremental transactions

Types of stored credential transactions

  • CIT: Cardholder Initiated. Any transaction in which the cardholder is actively participating in the transaction. This can be at a terminal in-store, an online checkout experience, or a subsequent stored credential transaction.
  • MIT: Merchant Initiated. Any subsequent transaction with previously stored credentials. The cardholder's prior consent to the merchant to store payment credentials for future use without active engagement from the cardholder.

Types of subsequent transactions

Standing instruction MITs

  • A separate transaction to buy a different item using the same card at the same merchant location or website
  • A recurring transaction associated with the original transaction

Industry-specific, business practice MITs

  • Resubmission (in case of insufficient fund decline response)
  • Reauthorization (in case of split shipment)
  • Incremental
  • Delayed charges
  • No show for auto rental or lodging
  • Account top up

Supported Processors

  • American Express
  • Braintree
  • Chase Paymentech Salem
  • FISERV North
  • FISERV Nashville
  • PayPal
  • TSYS

We will continue to add support for other processors and update the documentation as they become available.

Code Changes

You will be required to support the new CARDONFILE parameter based on how you send transactions to Payflow:

RequiredNot Required
Stored card: If you are currently storing the credit card details and sending the ACCT parameters; without RECURRING you are required to send in the appropriate CARDONFILE parameter based on the transaction taking place.Recurring Billing: If you are using Payflow's Recurring Billing service then no code changes are required as Payflow will handle the Card on File requirements.
Recurring: If you are passing the RECURRING parameter you will replace it with the CARDOFILE parameter by sending CITR first and all future transactions as MITR.Reference transactions: No code changes are required as Payflow will handle the Card of File requirements for you by treating the first reference transaction; without an associated TXID stored at PayPal, as CITI with all future transactions as MITU.

Supported Card on File types

Payflow currently supports a single transaction, including unscheduled and recurring transactions. Transaction types that begin with C are customer initiated. Transaction types that begin with M are merchant initiated.

  • CITI (CIT Initial) - Signifies the merchant is storing the cardholder credentials for the first time in anticipation of future stored credential transactions. For example, a cardholder sets up a customer profile for future purchases.
  • CITU (CIT Unscheduled) - Signifies a cardholder-initiated transaction using a credential currently stored with the merchant. For example, a purchase made by a cardholder at an online retailer with the cardholder’s credentials on file.
  • MITU (MIT Unscheduled) - Signifies an unscheduled transaction initiated by the merchant. This is not a recurring transaction that occurs at a scheduled interval. For example, a subsequent authorization for an electronic toll collection device when the stored balance drops below a predefined threshold.
  • CITR (CIT Initial Recurring) - Signifies a cardholder initiating the first in a recurring series of transactions. For example, a cardholder sets up billing for an ongoing monthly gym membership.
  • MITR (MIT Recurring) - Signifies a transaction in a series of transactions processed at fixed, regular intervals. These transactions represent an agreement between a cardholder and a merchant to initiate future transactions for the purchase of goods or services provided at regular intervals. For example, a magazine publisher charges the cardholder for a monthly subscription.

Note: Using Card on File; specially CITR and MITR, replaces the RECURRING flag once the card is part of the platform.

CARDONFILE ValueNameInitiated byTXID RequiredAVS/CVV2 RequiredPayflow Parameters
CITICIT InitialCardholderYesCustomer Present CARDONFILE=CITI + SWIPE Customer Not Present CARDONFILE=CITI + ACCT
CITUCIT UnscheduledCardholderOptionalOptionalCARDONFILE=CITU + TXID + (ACCT OR ORIGID)
MITUMIT UnscheduledMerchantYesOptionalCARDONFILE=MITU + TXID + (ACCT or ORIGID)
CITRCIT Initial RecurringCardholderOptionalYesCARDONFILE=CITR + (SWIPE or ACCT)
MITRMIT RecurringMerchantYesOptionalCARDONFILE=MITR + TXID + (SWIPE or ACCT or ORIGID)

New name-value pairs

CARDONFILE

This name-value pair (NVP) is sent in the response with one of the table values to annotate the type of transaction. For example, CARDONFILE=CITU tells Payflow the transaction in question is a CIT Unscheduled transaction.

Format: 4 alpha characters

TXID

This name-value pair (NVP), a transaction ID, is returned in the response and used for any future card on file transactions.

Format: Up to 15 alphanumeric characters

Types:

RequiredOptional
MITUCITU
MITRCITR

Note: For card on file transactions, you should send in TXID when it’s available as not all card associations will return it. However, it’s a required field for Mastercard or AMEX card on file transactions. If TXID is not returned in the response, subsequent card on file transactions should be sent with the correct CARDONFILE value without the TXID.

Examples

Examples here show how to do a customer-initiated recurring transaction to store the card, and a merchant doing a recurring transaction using that stored data.

CITR

Request

TRXTYPE=S&TENDER=C&AMT=9.95&ACCT=4012000033330026&EXPDATE=0125&VERBOSITY=HIGH&STREET=100 SOUTH NORTH DR&CITY=NORTHWOOD&STATE=NH&ZIP=03275&CVV2=987&CARDONFILE=CITR

Response

RESULT=0&PNREF=AS0O0D64E7C2&RESPMSG=Approved&AUTHCODE=010203&AVSADDR=Y&AVSZIP=Y&CVV2MATCH=X&TXID=X1Y2Z3100026810&HOSTCODE=00&RESPTEXT=APPROVAL&PROCAVS=Y&PROCCVV2=X&VISACARDLEVEL=A&IAVS=N
MITR

Request

TRXTYPE=S&TENDER=C&AMT=9.95&ACCT=4012000033330026&EXPDATE=0125&VERBOSITY=HIGH&STREET=100 SOUTH NORTH DR&CITY=NORTHWOOD&STATE=NH&ZIP=03275&CARDONFILE=MITR&TXID=X1Y2Z3100026810

Response

RESULT=0&PNREF=AS0O0D64E7D0&RESPMSG=Approved&AUTHCODE=010203&AVSADDR=Y&AVSZIP=Y&TXID=X1Y2Z3100026817&HOSTCODE=00&RESPTEXT=APPROVAL&PROCAVS=Y&VISACARDLEVEL=A&IAVS=N
XMLPay

Request CardOnFile is part of the Card structure.

<CardOnFile>CITI</CardOnFile>

Response TXId is part of the TransactionResult structure.

<TXId>011180692162733</TXId>