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

# Charge Saved Cards Using Stored Credentials and MIT

> Use stored credentials to charge customers without them being present — recurring billing, installments, and unscheduled MIT payments with Therius.

Stored credentials — also called Merchant Initiated Transactions (MIT) — let you charge a customer's saved card at any point after they have explicitly authorized you to do so. Common use cases include subscription renewals, installment plans, and unscheduled charges such as usage-based billing. Card scheme rules (Visa, Mastercard, and others) require you to declare the credential usage type on both the initial charge and every subsequent charge. Therius passes this information directly to the card networks on your behalf, but you must supply the correct fields.

## CIT vs. MIT

Every stored-credential relationship starts with a **Customer Initiated Transaction (CIT)**, during which the customer is present and explicitly authorizes future charges.

<CardGroup cols={2}>
  <Card icon="user" title="CIT — Customer Present">
    The customer is actively completing checkout. You collect the card via a fresh nonce (or raw card number) and set `cardOnFile.usage: "first"`. The response returns `card.networkTransactionId` and `card.networkReferenceId` — **store both values** in your database. You will need them for every subsequent MIT.
  </Card>

  <Card icon="server" title="MIT — Merchant Initiated">
    The customer is not present. You pass the saved vault token plus the stored-credential fields, including the `networkTransactionId` and `networkReferenceId` from the original CIT. The card networks use these references to link the charge back to the authorized mandate.
  </Card>
</CardGroup>

***

## The `cardOnFile` Object

Add a `cardOnFile` block inside the `card` object on both the CIT and every MIT. `cardOnFile` itself is optional (Therius derives a default from context — a fresh `tokenize` vs. a `tokenData` reuse — when omitted), but once you send it, `usage`, `initiatedBy`, and `type` are the three fields that together classify the charge for the card networks.

| Field             | Values                                                                                          | Required on                        |
| ----------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------- |
| `initiatedBy`     | `"cardholder"` \| `"merchant"`                                                                  | CIT + MIT                          |
| `type`            | `"recurring"` \| `"installment"` \| `"unscheduled"`                                             | CIT + MIT                          |
| `usage`           | `"first"` \| `"subsequent"`                                                                     | CIT + MIT                          |
| `exceptionReason` | `"resubmission"` \| `"incremental"` \| `"reauthorization"` \| `"delayed_charge"` \| `"no_show"` | MIT only, and only when applicable |

<Note>
  `initiatedBy` uses `"cardholder"`, not `"customer"` — match the enum exactly.
</Note>

`exceptionReason` is **optional** and sits on its own axis, independent of `type` — it does not replace `type`, it adds a business-exception label on top of it. Most subsequent MIT charges never send it; set it only when the specific charge falls into one of these scheme-defined categories:

| Value             | Meaning                                                                                           | Example                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `resubmission`    | Retrying a previously soft-declined charge (insufficient funds, do-not-honor) for the same amount | A subscription renewal retried the next day after a `51` decline |
| `incremental`     | An authorization top-up on an existing mandate                                                    | A hotel folio adds a room-service charge before checkout         |
| `reauthorization` | A fresh authorization because the original one expired before capture                             | Goods not yet shipped when the initial auth window lapses        |
| `delayed_charge`  | The final amount differs from an earlier estimate or hold                                         | Car-rental extra mileage; a restaurant tip added after the meal  |
| `no_show`         | The cardholder didn't show up for a reserved, guaranteed booking                                  | A hotel no-show fee                                              |

***

## Initial CIT Example

Collect the card as normal (using a nonce from the SDK or raw card data on a PCI-compliant server), tokenize it by setting `tokenize: true`, and include the `cardOnFile` block.

```json theme={"dark"}
POST /payment/purchase

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-CIT-001",
  "amount": { "currency": "USD", "value": 1999, "exponent": 2 },
  "card": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2027",
      "cvv": "123",
      "tokenize": true
    },
    "cardOnFile": {
      "initiatedBy": "cardholder",
      "type": "recurring",
      "usage": "first"
    }
  },
  "shopper": { "id": "customer-42" }
}
```

From the response, save these two fields to your database — linked to the customer's vault token:

```json theme={"dark"}
{
  "card": {
    "token": "vt_a1b2c3d4e5",
    "networkTransactionId": "016153570XXXXXX",
    "networkReferenceId": "MCC000XXXXXXXXXXXX"
  }
}
```

***

## Saving a Card Without Knowing the Future Charge Pattern

If you're vaulting a card and don't yet know whether it will become a recurring subscription, an installment plan, or a one-off unscheduled top-up, declare it as `"type": "unscheduled"` — the category card networks intend for "cardholder authorized future use, pattern not yet determined." Store the returned `networkTransactionId`/`networkReferenceId` regardless; you'll need them for whichever MIT you eventually send.

```json theme={"dark"}
POST /payment/purchase

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-SAVE-003",
  "amount": { "currency": "USD", "value": 1999, "exponent": 2 },
  "card": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2027",
      "cvv": "123",
      "tokenize": true
    },
    "cardOnFile": {
      "initiatedBy": "cardholder",
      "type": "unscheduled",
      "usage": "first"
    }
  },
  "shopper": { "id": "customer-42" }
}
```

<Note>
  If the card will only ever be reused at a **future customer-present** checkout — the shopper picks it from their saved methods and confirms the charge themselves, never charged unattended by you — you don't need a `cardOnFile` block at all. Just send `tokenize: true` with `shopper.id`. `cardOnFile` only matters once an MIT will occur.
</Note>

***

## Subsequent MIT Example — Recurring Renewal

On every subsequent charge — a renewal, an installment, an unscheduled top-up — pass the vault token plus the stored-credential fields and the network references from the original CIT. This example shows a recurring (subscription-style) renewal; swap `type` for `installment` or `unscheduled` to match the mandate you established on the CIT.

```json theme={"dark"}
POST /payment/purchase

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-MIT-002",
  "amount": { "currency": "USD", "value": 1999, "exponent": 2 },
  "card": {
    "tokenData": { "token": "vt_a1b2c3d4e5" },
    "cardOnFile": {
      "initiatedBy": "merchant",
      "type": "recurring",
      "usage": "subsequent"
    },
    "networkTransactionId": "016153570XXXXXX",
    "networkReferenceId": "MCC000XXXXXXXXXXXX"
  }
}
```

<Note>
  The Therius subscription engine manages stored credentials internally for all subscription renewals. You never need to supply `cardOnFile` or network reference fields when using the subscription API — this guide is only relevant if you are building your own billing logic outside the subscription engine.
</Note>

<Tip>
  If your initial CIT goes through the Checkout Widget rather than a direct API call, you don't need to construct this `cardOnFile` block by hand — pass it once when creating the SDK session instead (`POST /sdk/session`'s `cardOnFile`). The widget then shows a "card will be saved" disclosure and the server applies the stored-credential tagging and tokenization for you. See [Merchant-managed subscriptions](/sdk/session-bootstrap#merchant-managed-subscriptions).
</Tip>

***

## Credential Types

<CardGroup cols={2}>
  <Card icon="rotate" title="Recurring">
    Use `"type": "recurring"` for fixed-amount charges that repeat on a predictable schedule — monthly SaaS fees, annual renewals, membership dues.
  </Card>

  <Card icon="list-ol" title="Installment">
    Use `"type": "installment"` when a customer authorizes a split payment over a fixed number of charges — for example, three monthly payments for a single purchase.
  </Card>

  <Card icon="bolt" title="Unscheduled">
    Use `"type": "unscheduled"` for charges that are authorized in advance but triggered by a merchant-defined event — usage-based billing, account top-ups, convenience fees, or a card saved for future use before you know its eventual pattern.
  </Card>
</CardGroup>

See [Exception Reasons](#the-cardonfile-object) above for `exceptionReason` — a separate, optional axis from `type`, used only when a specific MIT falls into a scheme-defined exception category.

***

<Warning>
  Card scheme rules require accurate CIT/MIT declaration on every transaction. Misclassifying a charge — for example, sending an MIT without the original `networkTransactionId` — can result in increased decline rates, chargebacks, or acquirer penalties. When in doubt, contact Therius support before going live with a new billing model.
</Warning>