Payment Instruments & Tokenization

A payment instrument is a tokenized payment credential. lite creates one for every card payment: card details become a token before authorization, so your systems only ever handle the token. This page covers card instruments.

Single-use and stored instruments

Single-use instruments are created automatically on every card payment. If the customer doesn’t save their card, the instrument processes that payment and its operations, then expires. You can still capture, void, or refund without touching card data, as the instrument carries the credential for the payment. Stored instruments are instruments the customer has agreed to keep. The customer can select a stored instrument at future checkouts, and, under an agreement, you can charge it when they’re not present. Whether or not the customer saved their card, capture, void, and refund work identically, because every payment has an instrument behind it.

Fields

Field	Where	Purpose
`holder_id`	instrument, payment	Stable customer identifier; the retrieval key.
`holder_type`	instrument	Holder category, e.g. `CUSTOMER`.
`payment_method`	instrument, payment	Instrument type, e.g. `card`, `applePay`
`future_usage`	instrument, payment	Why the card is stored. Current values include `recurring` and `unscheduled_card_on_file`. Use the value configured for your account.
`store_for_future`	payment	Whether to retain the instrument for reuse.
`payment_instrument.id`	payment	References an existing stored instrument.
`agreement_id`	payment	References an existing agreement on a merchant-initiated charge.
`agreement`	payment	Nested agreement object, including the consent record, when set up on the first payment.

How card data reaches lite

Lite accepts card data as an encrypted instrument payload, never a raw card number. Card details are collected through lite’s secure collection flow, so a full card number never touches your servers.

Use one customer identifier everywhere

Stored instruments are retrieved by the customer identifier you send. Send the same value when the instrument is created and at every lookup. This is the value you pass as holder_id on the instrument and as customer.id on payments. Use a stable, permanent identifier from your own system, such as your internal user ID. If the identifier at checkout differs from the one at save time, the saved card doesn’t appear and no error is returned: an empty result is indistinguishable from a new customer. The customer re-enters their card, and you accumulate duplicate instruments for the same card.

Understand what a transaction is allowed to do

Every transaction on an instrument falls into one of three categories. The category determines whether the customer authenticates and who carries fraud liability.

	Who creates the charge	Authentication	Fraud liability
Customer-initiated payment	The customer, each time	Required	Issuer, when authenticated
Operation on an existing authorization	Nobody new; resolves a charge the customer already approved	Inherited from the original authorization	Issuer
Charge under an agreement	You	None	You

A customer-initiated payment is any payment the customer actively makes, including repeat purchases with a stored instrument. mada requires 3D Secure on every customer-initiated transaction. Visa and Mastercard follow the schemes’ authentication rules. An operation on an existing authorization captures, or voids a charge the customer already authenticated. The operation references the original transaction, and the authentication travels with it. A charge under an agreement is the only case where you originate a new charge with no cardholder present. It requires an agreement and shifts fraud liability to you. The consent record and the authenticated first transaction are your protection.

Create a stored instrument

There are three ways to create a stored instrument.

Save a card at checkout

The customer chooses to save their card during a purchase. They authenticate the payment, and on success lite stores the instrument and links it to this first authenticated transaction. Saving creates no agreement and grants no permission to originate charges. Every future purchase is a fresh, customer-initiated payment with its own authentication. The gain is convenience: the customer picks their card by brand and last four digits instead of retyping it.

Tokenize a card without a payment

Using the Web SDK, you can store a customer’s card without charging it:

const instrument = await lite.tokenize('card');

The SDK collects the card details through lite’s secure collection flow, tokenizes them, and returns the instrument. The returned instrument includes its id, which you use to charge the card later. An instrument created this way has no authenticated transaction behind it. The customer can pay with it at checkout, authenticating like any customer-initiated payment. To charge it under an agreement, the first charge under that agreement must be authenticated.

Store a card with an agreement

An agreement is the customer’s documented permission to charge their instrument when they’re not present. lite supports two types:

Recurring. Charges on a fixed schedule for a defined amount. Subscriptions, memberships, utility-style billing.
Unscheduled. Charges triggered by usage or events, with variable timing. Automatic wallet top-up, parking, usage-based billing.

Setting up an agreement has three parts: present the terms, capture consent, and complete an authenticated first charge. The authenticated first charge is what makes the agreement work. The customer authenticates it with 3D Secure, and lite links it to the agreement. That link is what lets every later charge proceed without authentication, and it anchors your dispute evidence. Before the customer accepts an agreement, you present the full terms. mada requires nine disclosure steps:

Agreement identifier The unique identifier of the agreement.
Service A description of the service.
Amount The amount, or how the amount is determined.
Payment type Fixed or variable.
Duration The duration of the agreement.
Timing When charges occur.
Terms The full terms and conditions, with cancellation rights.
Confirmation The customer’s explicit confirmation.
First charge notice Notice that the first transaction is charged now, with authentication.

An unscheduled agreement has no fixed amount or schedule, so the amount and timing disclosures must state how the amount is determined and what triggers a charge. Pass the consent record with the first charge: the disclosure version presented, the acceptance timestamp, the customer’s IP address, and their device’s user agent. lite stores it against the agreement. For a recurring agreement, also provide the billing terms: amount, currency, frequency, and start date. Frequencies range from daily to yearly, plus an ad hoc option for irregular schedules. The agreement carries a reference: supply your own (such as your subscription ID). Include it on every charge under the agreement.

Set up the agreement on a new card

The first charge sets up the agreement in the same request, with the agreement and consent record nested inside the payment instrument:

POST /v1/payments

{
  "amount": 40000,
  "currency": "SAR",
  "merchant_reference": "order_98431",
  "capture": false,
  "payment_instrument": {
    "data": "<encrypted-instrument-payload>",
    "payment_method": "card",
    "future_usage": "recurring",
    "store_for_future": true,
    "agreement_id": "a499c5c1-35e8-448c-b0f1-9c5a9527eba4"
    }
  },
  "customer": {
    "id": "06463cf8-c156-4ff6-bf02-5d559b738718"
  }
}

Manage the instrument lifecycle

A stored instrument carries one of four statuses. Single-use instruments expire with their payment and don’t follow this lifecycle.

Status	Meaning
`ACTIVE`	The instrument can be used.
`SUSPENDED`	The instrument is temporarily blocked from charges.
`EXPIRED`	The underlying card has expired.
`CANCELLED`	The instrument or its agreement was cancelled and can no longer be used.

Accept Payments

Tokenization

Account

Single-use and stored instruments

Fields

How card data reaches lite

Use one customer identifier everywhere

Understand what a transaction is allowed to do

Create a stored instrument

Save a card at checkout

Tokenize a card without a payment

Store a card with an agreement

Set up the agreement on a new card

Manage the instrument lifecycle

​Single-use and stored instruments

​Fields

​How card data reaches lite

​Use one customer identifier everywhere

​Understand what a transaction is allowed to do

​Create a stored instrument

​Save a card at checkout

​Tokenize a card without a payment

​Store a card with an agreement

​Present the terms and capture consent

​Set up the agreement on a new card

​Manage the instrument lifecycle

Single-use and stored instruments

Fields

How card data reaches lite

Use one customer identifier everywhere

Understand what a transaction is allowed to do

Create a stored instrument

Save a card at checkout

Tokenize a card without a payment

Store a card with an agreement

Present the terms and capture consent

Set up the agreement on a new card

Manage the instrument lifecycle