> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lite.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Instruments & Tokenization

> Payment instruments creation and life-cycle

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:

```typescript theme={null}
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.

#### Present the terms and capture consent

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:

```json theme={null}
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. |