Card on File
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
- Chase Paymentech Salem
- First Data North
- TSYS
We will continue to add support for other processors and update the documentation as they become available.
Required Code Changes
You will be required to support the new CARDONFILE
parameter based on how you send transactions to Payflow:
- Reference: 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 asMITU
. - Recurring: If you are passing the
RECURRING
parameter then you will need to support theCARDOFILE
parameter by sendingCITR
first and all future transactions sent asMITR
. - 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.
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.
Note: No changes are required for merchants using Payflow Recurring Billing service as this service will send the appropriate value as needed.
CARDONFILE Value | Name | Initiated by | TXID Required | AVS/CVV2 Required | Payflow Parameters |
---|---|---|---|---|---|
CITI |
CIT Initial | Cardholder | Yes | Customer Present CARDONFILE=CITI + SWIPE Customer Not Present CARDONFILE=CITI + ACCT |
|
CITU |
CIT Unscheduled | Cardholder | Optional | Optional | CARDONFILE=CITU + TXID + (ACCT OR ORIGID ) |
MITU |
MIT Unscheduled | Merchant | Yes | Optional | CARDONFILE=MITU + TXID + (ACCT or ORIGID ) |
CITR |
CIT Initial Recurring | Cardholder | Optional | Yes | CARDONFILE=CITR + (SWIPE or ACCT ) |
MITR |
MIT Recurring | Merchant | Yes | Optional | CARDONFILE=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.
TXID
This NPV, a transaction ID, is returned in the response and used for any future card on file transactions. Types:
Required | Optional |
---|---|
MITU |
CITU |
MITR |
CITR |
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. IfTXID
is not returned in the response, subsequent card on file transactions should be sent with the correctCARDONFILE
value without theTXID
.
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