Skip to main content
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

FieldWherePurpose
holder_idinstrument, paymentStable customer identifier; the retrieval key.
holder_typeinstrumentHolder category, e.g. CUSTOMER.
payment_methodinstrument, paymentInstrument type, e.g. card, applePay
future_usageinstrument, paymentWhy the card is stored. Current values include recurring and unscheduled_card_on_file. Use the value configured for your account.
store_for_futurepaymentWhether to retain the instrument for reuse.
payment_instrument.idpaymentReferences an existing stored instrument.
agreement_idpaymentReferences an existing agreement on a merchant-initiated charge.
agreementpaymentNested 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 chargeAuthenticationFraud liability
Customer-initiated paymentThe customer, each timeRequiredIssuer, when authenticated
Operation on an existing authorizationNobody new; resolves a charge the customer already approvedInherited from the original authorizationIssuer
Charge under an agreementYouNoneYou
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:
  1. Agreement identifier The unique identifier of the agreement.
  2. Service A description of the service.
  3. Amount The amount, or how the amount is determined.
  4. Payment type Fixed or variable.
  5. Duration The duration of the agreement.
  6. Timing When charges occur.
  7. Terms The full terms and conditions, with cancellation rights.
  8. Confirmation The customer’s explicit confirmation.
  9. 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.
StatusMeaning
ACTIVEThe instrument can be used.
SUSPENDEDThe instrument is temporarily blocked from charges.
EXPIREDThe underlying card has expired.
CANCELLEDThe instrument or its agreement was cancelled and can no longer be used.