What Is Card-on-File? A Complete Guide for Sri Lankan Merchants
Card-on-file lets your customers save their card details once and pay with a single click on every future visit. It powers subscriptions, faster checkouts, and recurring billing. When implemented correctly through OnePay, it does all of this without your business ever touching raw card data.
What Is Card-on-File?
Card-on-file is a payment arrangement where a customer authorises a merchant to store their card details for use in future transactions. Instead of re-entering a 16-digit card number, expiry date, and CVV on every visit, the details are stored securely and mapped to a token. A token is a randomised reference string that represents the card without exposing it.
You have almost certainly experienced this as a customer. When a streaming service charges you every month without asking for your card again, or when you check out on an e-commerce site and see "Pay with saved card ending 3301", that is card-on-file at work.
Quick Fact
How Card-on-File Works on OnePay
When a customer saves their card on your OnePay-powered checkout, here is what happens behind the scenes:
Customer enters card details at checkout
The card number, expiry date, and CVV are entered once on the OnePay checkout page. These details are encrypted in the customer's browser before they ever reach any server, including OnePay's.
3D Secure authentication completes
OnePay mandates 3DS for all transactions. The customer receives a One-Time Password from their issuing bank and confirms their identity. This step is required before any card can be saved.
OnePay creates a token
After successful authentication, OnePay's vault generates a unique token for that customer-merchant combination. Your system receives the token, not the raw card data. You store the token, which by itself is worthless to attackers.
Future payments use the token
On the customer's next purchase, you pass the token to OnePay's API. OnePay resolves the token, re-authenticates where required, and processes the payment. The customer gets a one-click checkout experience.
You receive instant confirmation
Your system receives a payment result via OnePay's webhook callback. The transaction is complete. No card data was ever stored on your server.
PCI DSS Scope Reduction
Types of Card-on-File Transactions
Not all card-on-file payments are the same. Visa and Mastercard classify COF transactions into distinct types, and OnePay's API supports all of them. Understanding the difference matters because each type has different authentication, liability, and compliance implications.
| Transaction Type | Who Initiates | Schedule | Example |
|---|---|---|---|
One-click / Saved Card | Customer (CIT) | On demand | Returning shopper selects "Pay with saved card" at checkout |
Recurring (Fixed) | Merchant (MIT) | Fixed intervals | Monthly subscription at LKR 999, charged every 1st of the month |
Recurring (Variable) | Merchant (MIT) | Fixed intervals, variable amount | Utility bill collected monthly at varying amounts |
Unscheduled COF | Merchant (MIT) | Non-fixed, triggered by event | Auto top-up when wallet balance drops below LKR 500 |
Instalment | Merchant (MIT) | Fixed, pre-agreed number of charges | Three-instalment payment plan for a LKR 30,000 product |
CIT (Cardholder-Initiated Transaction): The customer is present and actively initiates the payment. 3DS authentication is typically required.
MIT (Merchant-Initiated Transaction): The merchant initiates the charge without the customer being present, based on a prior agreement. Authentication requirements differ and liability rules apply.
Merchant-Initiated Transactions in Sri Lanka
Who Should Use Card-on-File?
Card-on-file is not just for large enterprise merchants. Any OnePay merchant with repeat customers, whether you sell courses, software subscriptions, memberships, or physical products, can benefit from implementing COF.
Education and Tuition
Charge monthly tuition fees automatically. Parents register once and fees are collected on the same date every month without manual follow-up.
E-commerce
Returning customers skip re-entering card details. One-click checkout reduces abandonment at the payment step significantly.
SaaS and Software
Charge monthly or annual licence fees automatically. Integrate with OnePay Billing to manage subscription lifecycles end-to-end.
Travel and Hospitality
Save card at booking to charge no-show fees or complete balance payments closer to the date without customer intervention.
Gyms and Memberships
Monthly membership dues collected automatically. Reduce failed payments from card expiry using OnePay's account updater capability.
Healthcare and Services
Save card on file for recurring consultations, therapy sessions, or service retainer agreements with patient or client consent.
Tokenization: The Technology Behind COF
Tokenization is the process that makes card-on-file secure. When a customer saves their card, the raw card number (Primary Account Number) is never stored in your system. Instead, OnePay generates a token: a random alphanumeric string that acts as a secure reference to the original card.
Token Types
| Token Type | Stored By | How It Works |
|---|---|---|
Gateway Token (OnePay Vault) | OnePay | OnePay stores the encrypted card and returns a reference token to your system. This is the most common COF implementation. |
Network Token | Card Scheme (Visa / Mastercard) | Generated at the card network level. Survives card replacements and expiry updates automatically. Produces higher authorisation rates. |
Token Lifecycle
A token is not permanent. It has a lifecycle that you need to manage as a merchant.
| Event | What Happens to the Token | Your Action |
|---|---|---|
Customer saves card | Token created and returned via API or webhook | Store the token against the customer record in your system |
Card expires | Token may become invalid | Prompt customer to update card, or use OnePay's account updater |
Card replaced (lost or stolen) | Token becomes invalid for old card | Customer re-saves new card; a new token is issued |
Customer requests deletion | Token deleted from OnePay vault | Remove token from your database; do not attempt further charges |
Merchant account closed | All tokens for that merchant are purged | Export token references before account closure if needed for reconciliation |
COF vs. Standard Payment: A Direct Comparison
Frictionless checkout experience
- ✓ Customer checks out in one click
- ✓ No re-entry of card details
- ✓ Subscriptions run automatically
- ✓ Fewer abandoned carts at the payment step
- ✓ Tokens survive most card replacements with network tokens
- ✓ Your server never stores raw card data
- ✓ Reduced PCI DSS compliance burden
Standard high-friction checkout
- ✗ Customer re-enters all card details every time
- ✗ Subscriptions require manual payment each cycle
- ✗ Higher payment abandonment at checkout
- ✗ No automated recurring billing possible
- ✗ Card expiry causes failures with no recovery path
- ✗ Poor experience for loyal, returning customers
Integrating Card-on-File with OnePay
Card-on-file is available to merchants using OnePay Checkout (hosted) or the OnePay API (custom integration). The path you take depends on your technical setup.
OnePay Hosted Checkout
The simplest path. OnePay's checkout page handles the entire save-card flow, consent capture, tokenisation, and 3DS authentication. You receive the token via webhook. There is no PCI DSS scope impact on your servers.
Token Storage Rule
customer_ref) in your system. This reference links the token to a specific customer. Do not reuse the same customer reference across different customers. If you delete a customer's data from your system, you must also request token deletion from OnePay.Security, Compliance, and Consent
Getting Explicit Customer Consent
Before saving a customer's card, you must obtain clear, informed consent. This is required by both card network rules (Visa and Mastercard) and Sri Lanka's Personal Data Protection Act. The consent must explain the following:
| What to Disclose | Example Wording |
|---|---|
What is being saved | "Save my card for future purchases" |
How it will be used | "Your card will be charged automatically each month for your subscription" |
How to revoke consent | "You can remove your saved card at any time from your account settings" |
Who stores the data | "Your card details are securely stored by OnePay and never held on our servers" |
Liability and 3DS
For the initial card-saving transaction, OnePay mandates 3D Secure (3DS) authentication. This is non-negotiable. The 3DS step creates the cardholder's binding consent and triggers the liability shift: if a fraudulent transaction occurs on a 3DS-authenticated card, the liability rests with the card-issuing bank, not with you as the merchant.
For subsequent MIT transactions where the customer is not present, authentication requirements are different. OnePay handles this automatically when you correctly flag the transaction type in your API request.
Chargeback Protection
Frequently Asked Questions
Does card-on-file work with all card types on OnePay?
Card-on-file works with Visa and Mastercard debit and credit cards on OnePay. AMEX, Diners Club, and UnionPay support depends on the specific card product and issuing bank configuration. If you are building a subscription product, test your integration with both Visa debit and credit cards, as these represent the majority of Sri Lankan cardholders.
Can a customer save multiple cards?
Yes. Each saved card generates a unique token. Your system can store multiple tokens per customer reference and present them as options at checkout, for example "Visa ending 3301" or "Mastercard ending 7890". The customer selects which card to charge.
What happens when a saved card expires?
OnePay will mark the token as expired. Any attempt to charge an expired token will return a decline. You should implement a flow in your application to detect expired tokens ahead of time using the card_expiry field returned when the token was created, and prompt customers to update their card before the expiry date.
Is OTP required for every saved card payment?
For customer-initiated transactions where the customer is present at checkout, 3DS OTP is required. For merchant-initiated transactions such as subscriptions and auto-billing where the customer is not present, OTP is not prompted. The original card-save must have been 3DS-authenticated. OnePay handles this distinction automatically when you set the correct transaction_type in your API request.
How does OnePay handle card-on-file if the customer's bank blocks e-commerce?
If the customer's bank blocks the initial card-save transaction with Response Code 05 (Do Not Honour), the token cannot be created. The customer will need to enable online payments with their bank first, then re-attempt saving their card. Read our full guide on Response Code 05 →
Who is responsible if a fraudulent charge occurs on a saved card?
If the initial card-save was 3DS-authenticated, which OnePay mandates, the liability for fraudulent charges on subsequent MIT transactions shifts to the card-issuing bank, not the merchant. This is one of the most important benefits of OnePay's 3DS-mandatory policy. Always keep the original transaction reference from the card-save event as your evidence record.