PayPal Pro / Payflow / New Features / Card on File

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
  • FISERV North
  • FISERV Nashville
  • 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 as MITU.
  • 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.
  • 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.

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:

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. 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