Card on File (CoF) & Recurring Payments API Guide See Also:
Introduction
This document provides implementation guidelines for partners and merchants using Payrix API to process Card-On-File transactions directly. A separate guide exists for partners and merchants using Payrix recurring billing engine to process Card-On-File transactions.
A Card-On-File transaction (also called credential on file) is defined as a transaction initiated either by a cardholder or a merchant (or merchant’s system) using a Primary Account Number (PAN) previously stored, excluding scenarios where credentials are stored solely for the purpose of completing a single transaction (i.e., storing PAN with transaction for the purpose of refund or storing PAN for the purpose of processing incremental charges on a hotel portfolio).
Valid Card-On-File use cases:
A cardholder enters and stores the card number for recurring billing
A cardholder enters and stores the card number for completing future purchases without needing to re-enter the card number
Below are not Card-On-File use cases:
ApplePay, GooglePay, or digital wallet solutions where card is not stored with the merchant
Hotel/Card Rental/Airline where card is used only for the purpose of completing a single transaction
Processing Requirements
Display/Disclosure
A merchant processing Card-On-File transactions needs to meet the following display/disclosure requirements:
When capturing PAN for the first time, an agreement (such as terms and conditions page) must be available to the cardholder which clearly identifies the following:
A truncated version of the PAN (e.g., last 4) will be stored
How the credential will be used
Expiration date of the agreement (if applicable)
How the cardholder will be notified if the agreement changes
Before using the stored credential, merchant must establish an agreement with the cardholder which clearly identifies the following:
Merchant name
Merchant address/location (if applicable)
Transaction amount and currency
Taxes, surcharges (requires card brand registration) or any additional amounts
Cancellation / Refund policies
Transaction frequency or threshold (i.e., maintain a $XX balance)
All agreements must be available to cardholder or issuers upon request
Initial Authorization Rules
A PAN should only be stored after a valid authorization is obtained. This excludes token transfers between processors. If no transaction amount is due at the time of storing the credentials, a “zero-dollar-auth” (an authorization transaction with $0.00 as the amount) must be approved before a credential can be stored.
A PAN should not be stored if transaction is declined.
Subsequent Authorization Rules
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 5 consecutive failures in authorization)
Transaction Requirements
Transaction needs to be sent with correct flag in “cofType” field. For more details, see Payrix API documentation here: https://portal.payrix.com/docs/api#txns
None Card-On-File
“cofType” should be left blank
Initial Card-On-File Transaction
Transaction type must be “sale” or “auth”
“cofType” must be set to one of the following 2 values:
Single - for a single purchase initiated by the cardholder
Scheduled - A recurring purchase
The transaction ID of the authorization must be stored and used in subsequent transactions
Subsequent Card-On-File Transaction
Transaction type must be “sale” or “auth”
“firsttxn” filed must be set and must be a valid value from initial Card-On-File transaction.
“cofType” must be set to one of the following 3 values:
Single - for a single purchase initiated by the cardholder using a previously stored credential
Scheduled - for a recurring purchase
Unscheduled - for a purchase initiated by merchant (or merchant system) without cardholder action (such as automatically replenish a balance)
Capture Requirements
The “cofType” field of a capture transaction must match the authorization transaction