Card on File ( Automated Charging )

Card on File lets you save a customer's card once and charge it programmatically at any future point, without the customer needing to re-enter their details. Think of how Uber charges the passenger's card automatically at the end of every ride: the customer approves it once, and every charge after that is invisible to them.

Your customer enters their card details once and pre-approves your business to charge them in the future. You receive an encrypted token for their card. You store it. You charge it whenever you need to any amount, on demand, from your backend code alone.

What can I use it for?

Card on File is suitable for any product or business where you have known, registered customers and want to charge them on demand without asking them to manually enter card details every time.

SaaS & subscriptions

Monthly subscription billing

Charge a fixed plan price on the 1st of every month. Customer approves once at signup, you handle every renewal silently. Works for Basic / Pro / Enterprise tiers.

Usage-based

Pay as you go

Tally API calls, data consumed, or seats used at period-end. Charge exactly what the customer owes, the token stays the same, only the amount changes each cycle.

Mobile & in-app

In-app purchases on demand

Multiple in-app purchases or on-demand services without redirecting users to a payment page each time. Charge instantly when the user triggers an action.

E-commerce

One-click repeat purchases

Returning customers checkout in one click. No card re-entry, no redirect. Especially powerful for high-frequency buyers and loyalty programs.

How it works - 3 steps

The entire Card on File flow reduces to three things: get permission, store the token, charge when needed.

Get pre-approval

Customer saves card once

Store the token

Save tok_ ID in your DB

Charge on demand

Any amount, any time

Step 1 — Pre-approval

Your customer creates a profile on your platform. You redirect them to the OnePay secure card-entry page. They enter their card details and consent to future charges. OnePay returns a cus_ ID and a redirect_url.

Step 2 — Token Storage

After the customer completes card entry, call the List Cards endpoint to retrieve their tok_ token. Store this token in your database alongside the customer record. This is the only identifier you need for all future charges.

Step 3 — Automated Charging

Whenever you need to charge the customer — on a schedule, on usage trigger, or on demand — make a single API call with their customer_id,token_id, and theamount. No customer interaction needed.

Billing models

Once you have a token, you control exactly how and when you charge. Two patterns cover virtually every business model:

FIXED BILLING

Fixed price every billing cycle

Charge the exact same amount on a predictable schedule, weekly, monthly, or annually. Your system stores the next billing date and fires the charge endpoint automatically. No customer action, no payment page.

e.g. SaaS Pro plan at LKR 2,500/month cron fires on the 1st, chargestok_XXXXX for"2500.00". Customer sees a charge on their card statement. Nothing else needed.

VARIABLE BILLING

Variable amount - pay as you go

Calculate the exact amount owed at the end of each billing period based on actual usage (API calls, data, seats, units). Charge precisely that amount. The token is reused, only the amount parameter changes each cycle.

e.g. API platform at LKR 0.50/call — tally 4,200 calls in April → chargetok_XXXXX for"2100.00". Next month: 6,100 calls → charge "3050.00". Token never changes.

Detailed API flow

Create customer

POST

/v3/customers/

Redirect to card page

use

data.redirect_url

Retrieve token

GET

/customers/{id}/cards/

Store token_id

save in

your database

Charge on demand

POST

/customers/{id}/payments/

Authentication uses an Access Token in the Authorization header — different from the hash-based auth used by the Payment API. Format: Authorization: 2c4e7c3ee0013882.... Obtain from the merchant dashboard under API Keys.

What is Card on File?

Tokenization is the process of replacing sensitive card data with a non-sensitive substitute, the token that has no exploitable value outside the system it was designed for.

When your customer enters their card details on the OnePay-hosted card page, those details are sent directly and securely to the card network (Visa or Mastercard) and the customer's issuing bank. The bank validates the card and returns a unique encrypted token back to OnePay. That token is what gets stored and what gets passed to your system as a tok_ ID.

If that token were ever intercepted or leaked, it would be useless; it cannot be used to reconstruct the original card number, and it can only be charged by the specific merchant account it was issued for. This is fundamentally different from storing an encrypted card number, which could theoretically be decrypted.

The flow in plain terms: Customer enters card → card details go to the bank → bank issues a token → token comes back to OnePay → OnePay gives you a tok_ ID → you store only the token ID. No card numbers ever touch your server or OnePay's database.

Card on File is currently available for Visa and Mastercard only. Other payment methods are not supported for automated charging at this time.

Base URL

All API requests should be made to the following base URL:

https://api.onepay.lk

Authentication

All endpoints require authentication via an Authorization header and a strictly defined Content-Type.

AUTHENTICATION HEADERS

HEADER	VALUE	REQUIRED
`Authorization`	Your Access Token (e.g. 2c4e7c3ee001...)	Yes
`Content-Type`	`application/json`	Yes

Customers

Manage your customer base. Each customer gets a unique cus_ prefixed ID. Customers can have one or more saved card tokens. All endpoints require the Authorization access token header.

List customers

GEThttps://api.onepay.lk/v3/customers/

Retrieves a list of all customers associated with the authenticated application. No query parameters required — authentication is via the Authorization header only.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`status`	number	`200` on success.
`data`	array	Array of customer objects.
`data[].customer_id`	string	Unique customer identifier, e.g. `cus_907fa39a`.
`data[].first_name`	string	Customer's first name.
`data[].last_name`	string	Customer's last name.
`data[].email`	string	Customer's email address.
`data[].phone_number`	string	Customer's phone number.
`data[].address`	string	Customer's billing or physical address.

Get customer details

GEThttps://api.onepay.lk/v3/customers/{customer_id}/?app_id={app_id}

Retrieves detailed information for a specific customer, including their associated cards and full transaction history.

PATH & QUERY PARAMETERS

PARAMETER	TYPE	IN	DESCRIPTION
`customer_id` required	string	Path	Unique customer identifier, e.g. `cus_907fa39a`.
`app_id` required	string	Query	Your application identifier.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`data.customer_id`	string	Unique customer identifier.
`data.first_name`	string	Customer's first name.
`data.last_name`	string	Customer's last name.
`data.email`	string	Customer's email address.
`data.phone_number`	string	Customer's phone number.
`data.address`	string	Customer's billing or physical address.
`data.cards`	array	Array of saved card token objects associated with this customer.
`data.transactions`	array	Array of historical transaction objects for this customer.

Create customer and request card token

POSThttps://api.onepay.lk/v3/customers/

Creates a new customer profile and returns a redirect_url. Redirect the customer to that URL so they can securely enter and save their card. OnePay handles all card data, your system only ever receives back a token.

REQUEST BODY

PARAMETER	TYPE	DESCRIPTION
`app_id` required	string	Your application identifier.
`first_name` required	string	Customer's first name.
`last_name` required	string	Customer's last name.
`email` required	string	Customer's email address.
`phone_number` required	string	Phone number with country code, e.g. `+94771234567`.
`address` required	string	Customer's billing or physical address.
`redirect_url` required	string	The URL the customer will be redirected to after successfully adding their card.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`data.customer_id`	string	The newly created customer ID (e.g. `cus_907fa39a`). Store this in your database.
`data.redirect_url`	string	The secure OnePay-hosted URL where the customer enters their card details.
`data.first_name`	string	Customer's first name as stored.
`data.last_name`	string	Customer's last name as stored.
`data.email`	string	Customer's email address.
`data.phone_number`	string	Customer's phone number.
`data.address`	string	Customer's address.

Request token for existing customer

POSThttps://api.onepay.lk/v3/customers/

If a customer profile already exists in your system and they want to add a new card or update their payment method, pass their customer_idinstead of full profile details. OnePay will generate a fresh card-entry redirect for that customer.

This uses the same endpoint as Create Customer. The difference is that you pass customer_idinstead of the full profile fields. OnePay detects the existing profile and generates a new tokenization session for them.

REQUEST BODY

PARAMETER	TYPE	DESCRIPTION
`app_id` required	string	Your application identifier.
`customer_id` required	string	Existing customer identifier, e.g. `cus_907fa39a`.
`redirect_url` required	string	The URL the customer will be redirected to after adding their new card.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`data.customer_id`	string	The existing customer's ID, confirmed.
`data.redirect_url`	string	New secure card-entry URL to redirect the customer to.

Cards (Token)

Manage saved payment methods for your customers. Each saved card is identified by a tok_ prefixed token ID. Use this token to charge the card raw card numbers never pass through your system.

List customer cards

GEThttps://api.onepay.lk/v3/customers/{customer_id}/cards/?app_id={app_id}

Retrieves all securely stored card tokens for a specific customer. Call this after the card-entry redirect completes to retrieve the new token_id and store it in your database for future charges.

PATH & QUERY PARAMETERS

PARAMETER	TYPE	IN	DESCRIPTION
`customer_id` required	string	Path	Unique customer identifier, e.g. `cus_907fa39a`.
`app_id` required	string	Query	Your application identifier.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`data`	array	Array of card token objects.
`data[].token_id`	string	Secure card token identifier, e.g. `tok_12345678`. Use this for all charge requests.
`data[].card_type`	string	Card network, e.g. `Visa`, `Mastercard`.
`data[].masked_number`	string	Masked card number for display, e.g. `** ** 4242`.
`data[].expiry`	string	Card expiry in `MM/YY` format.
`data[].is_deleted`	boolean	`true` if the card has been soft-deleted and cannot be used for charges.

Get single card

GEThttps://api.onepay.lk/v3/customers/{customer_id}/cards/{token_id}/?app_id={app_id}

Retrieves details for a specific saved card. Use the masked number, card type, and expiry to display the saved card in your UI e.g. "Visa ending in 4242, expires 12/27".

PATH & QUERY PARAMETERS

PARAMETER	TYPE	IN	DESCRIPTION
`customer_id` required	string	Path	Unique customer identifier.
`token_id` required	string	Path	Secure card token, e.g. `tok_12345678`.
`app_id` required	string	Query	Your application identifier.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`data.token_id`	string	Secure card token identifier.
`data.card_type`	string	Card network, e.g. `Visa`, `Mastercard`.
`data.masked_number`	string	Masked card number, e.g. `** ** 4242`.
`data.expiry`	string	Expiry date in `MM/YY` format.
`data.is_deleted`	boolean	`true` if the card has been soft-deleted.

Delete card (soft delete)

DELETEhttps://api.onepay.lk/v3/customers/{customer_id}/cards/{token_id}/?app_id={app_id}

Soft-deletes a saved card by setting is_deleted = true. The card token is immediately deactivated and cannot be used for any future charges. The customer profile and transaction history remain fully intact.

Deletion is irreversible. If the customer wants to pay again after a card is deleted, they must add a new card via the tokenization redirect flow.

PATH & QUERY PARAMETERS

PARAMETER	TYPE	IN	DESCRIPTION
`customer_id` required	string	Path	Unique customer identifier.
`token_id` required	string	Path	The secure card token to be deleted.
`app_id` required	string	Query	Your application identifier.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`status`	number	`200` on successful deletion.
`message`	string	Confirmation message.

Charge a Card (Charge Token)

Charge a customer's saved card token for any amount triggered entirely from your server. No customer action required at payment time. This is the core of the auto-charging model.

POSThttps://api.onepay.lk/v3/customers/{customer_id}/payments/

PATH PARAMETERS

PARAMETER	TYPE	IN	DESCRIPTION
`customer_id` required	string	Path	Unique customer identifier, e.g. `cus_907fa39a`.

REQUEST BODY

PARAMETER	TYPE	DESCRIPTION
`app_id` required	string	Your application identifier.
`token_id` required	string	The saved card token to charge, e.g. `tok_12345678`.
`amount` required	string	Amount to charge formatted as a string, e.g. `"1000.00"`.
`currency` required	string	Currency code, e.g. `LKR` or `USD`.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`status`	number	`200` on success.
`message`	string	Confirmation message.
`data.transaction_id`	string	Unique transaction identifier for this charge.
`data.status`	boolean	`true` if the charge was successfully processed.
`data.amount`	string	The amount charged.
`data.currency`	string	Currency of the charge.
`data.token_id`	string	The card token that was charged.

BASIC CHARGE EXAMPLE

Charge a single saved card immediately. The foundation for all billing patterns.

FIXED BILLING EXAMPLE — SAME AMOUNT EVERY MONTH

Run this as a cron job on your chosen billing date. The amount is constant; only the timing changes.

VARIABLE BILLING EXAMPLE — PAY AS YOU GO

Calculate usage at period-end and charge exactly what was consumed. Token is constant; only the amount varies per customer per cycle.

Customer Transactions

Retrieve the full billing history for a specific customer. Useful for displaying payment history in your product dashboard, generating invoices, reconciling subscription charges, or auditing billing cycles.

GEThttps://api.onepay.lk/v3/customers/{customer_id}/transactions/?app_id={app_id}

PATH & QUERY PARAMETERS

PARAMETER	TYPE	IN	DESCRIPTION
`customer_id` required	string	Path	Unique customer identifier, e.g. `cus_907fa39a`.
`app_id` required	string	Query	Your application identifier.

RESPONSE PARAMETERS — 200 OK

FIELD	TYPE	DESCRIPTION
`status`	number	`200` on success.
`data`	array	Array of transaction objects ordered by most recent first.
`data[].transaction_id`	string	Unique identifier for the transaction.
`data[].amount`	string	Amount charged for this transaction.
`data[].currency`	string	Currency of the transaction.
`data[].status`	boolean	`true` if the transaction was successful.
`data[].token_id`	string	The card token used for this transaction.
`data[].created_at`	string	ISO 8601 timestamp of when the transaction was created.