Card-On-File (CoF) Implementation Guide

This document provides comprehensive implementation guidelines for partners and merchants utilizing Payrix for Card-On-File transactions.

A Card-On-File transaction, or “credential-on-file”), is initiated by a cardholder or Merchant using a previously stored Primary Account Number (PAN). This definition excludes cases where credentials are stored solely for a single transaction, such as refunds or incremental hotel charges.

Card-on-File Use Cases

Understanding when to use card-on-file can significantly enhance the customer checkout experience. Recognizing the scenarios in which this payment method is applicable and those in which it is not is essential for setting accurate consumer expectations.

Use Case Scenarios

• A cardholder can enter and securely store their card number for recurring payments, which include:

  • Subscription Payments - Such as gym memberships, streaming services, and more.

  • Bill Payments - Covering utility bills, monthly car insurance, mobile phone bills, etc.

• A cardholder can also enter and store their card information for future purchases, eliminating the need to re-enter the card number for unscheduled card-on-file (COF) transactions.

  • Cardholder-Initiated Payments - Including services like lawn care, snow removal, and transit card top-ups.

• A cardholder can enter and store their card number for installment payments of a larger purchase.

  • Installment Payments - Applicable for purchases like furniture or items from home shopping networks.

Invalid Card-on-File Use Cases

• Digital wallet or pass-through wallet solutions where the card is not stored with the Merchant, such as Apple Pay or Google Pay.

• One-time transactions for hotels, car rentals, or airlines where the card is exclusively used to finalize a single transaction. For instance, a cardholder may provide their payment details to cover incidentals specifically associated with a hotel, car, or flight reservation.

Tip: See the Card-on-File Transaction Type Examples table below for a more comprehensive list of use cases.

Cardholder Disclosure Requirements

A Merchant who stores and later utilizes Card-on-File information for future transactions must comply with the following display and disclosure requirements:

First-Time Card Capture Disclosures

When capturing the PAN for the first time, it is essential to provide the cardholder with a dedicated page—such as a link to the cardholder agreement—that distinctly outlines the following information, separate from the general terms and conditions of the platform:

• A truncated version of the PAN, such as the last four digits, will be securely stored.

• How the Credential Will Be Used

• Expiration Date of the Agreement (If Applicable)

• How the cardholder will be notified if there are any changes to the agreement

Stored Card-on-File Usage Disclosures

Before utilizing stored credentials, Merchants must first establish a clear agreement with the cardholder that explicitly outlines the following details:

• Merchant Name

• Merchant address or location (if applicable)

• Transaction Amount and Currency

• Taxes, surcharges (which require card brand registration), or any additional fees that may apply.

• Cancellation and Refund Policies

• Transaction frequency or threshold (e.g., maintaining a minimum balance)

All agreements must be readily accessible to cardholders or issuers upon request.

Authorization Requirements

Once disclosure requirements are met for cardholders and issuers, a first-time card authorization must be completed to securely store the Primary Account Number (PAN) and other card information. When a card-on-file is stored, it must follow authorization rules for failed transactions, including whether the card can be used after consecutive authorization failures.

First-Time Card Authorization Requirements

A Primary Account Number (PAN) can only be stored after receiving valid authorization.

This requirement does not extend to token transfers between processors. If no transaction amount is due when storing the credentials, a “$0 Auth” (an authorization transaction with an amount of $0.00) must be approved before storing the credentials.

Warning: PANs cannot be stored if the transaction is declined.

Subsequent Authorization Requirements

A stored credential can be used up to 4 additional times within 16 days of initial authorization failure.

If no valid authorization can be obtained, the credential should no longer be used (i.e., platforms should stop using a credential after a set number of consecutive authorization failures).

Subsequent Card-on-File Authorization Rules for Card-Present Transactions (triPOS) for Future Card-Not-Present Transactions on Payrix

When a Merchant initiates a Card Present (CP) transaction using a triPOS terminal and intends to utilize the captured and stored Primary Account Number (PAN) or Token for a future Card Not Present (CNP) transaction within the Payrix system (such as the Payrix Portal or Payrix API), it is essential to include a value for recurringPaymentType in the request body during the initial triPOS Sale or Auth transaction.

The recurringPaymentType value plays a vital role, as it identifies the Merchant’s intention to securely store credentials for the effective processing of CP transactions.

Visit the Worldpay Developer Hub triPOS API specification for more information.

Transaction Requirements

The transaction needs to be sent with the correct flag in cofType field.

For more details, visit the Payrix API /txns endpoint documentation

None Card-on-File

cofType should be left blank.

Initial Card-on-File Transaction

To store a new credit card as a card-on-file in a new transaction, the transaction type (type) must be set as:

1. Card Sale (1) - Where the transaction total is processed and charged to the credit card, or;

2. Card Auth (2) - Where the requested total is authorized and held on the credit card.

cofType must be set to one of the following values:

• single - for a single purchase initiated by the cardholder

• scheduled - for recurring payments; (i.e. gym memberships, streaming services, utility bills, etc.)

• installment – for installment payments; (i.e. furniture purchase, shopping network purchase, etc.)

The transaction ID returned from processing this first authorization must be provided in all subsequent transactions (firstTxn) when the card information is stored outside the Payrix system.

This requirement does not apply if Payrix tokens or Omnitoken are used to process the initial transactions.

Subsequent Card-on-File Transaction

To utilize a stored card-on-file in a new transaction, the transaction type (type) must be set as:

1. Card Sale (1) - Where the transaction total is processed and charged to the credit card, or;

2. Card Auth (2) - Where the requested total is authorized and held on the credit card.

To associate the new transaction with the stored card-on-file, it is essential to set the firstTxn value. This value corresponds to the ID of the initial transaction on the Payrix platform when the cardholder's credit card was first stored. If Payrix tokens or Omnitoken are used to store the card-on-file, this field becomes optional and does not require submission.

cofType must be set to one of the following values:

• single - for a single purchase initiated by the cardholder

• scheduled - for recurring payments; (i.e. gym memberships, streaming services, utility bills, etc.)

• installment – for installment payments; (i.e. furniture purchase, shopping network purchase, etc.)

• unscheduled - for unscheduled payments initiated by the Merchant (e.g. balance replenishment)

Capture Requirements

The cofType field in a capture transaction must correspond to the authorization transaction.

Example: If the authorization transaction is processed with cofType set to unscheduled, the subsequent capture transaction linked to the original authorization must also have cofType designated as unscheduled.

Card-on-File Transaction Type Examples

The table below provides a comprehensive overview of the use cases available and unavailable for Card-on-File within the Payrix system. It also considers the regulations established by card brand networks and essential compliance requirements within the payments industry.

References

Below are additional external materials related to card-on-file information.

visa-rules-public.pdf

EXTERNAL Credential On File_ Merchant Core v4_62118.pdf