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

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.

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.

​
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.
initiatedBy uses "cardholder", not "customer" — match the enum exactly.
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:

​
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.
From the response, save these two fields to your database — linked to the customer’s vault token:

​
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.
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.

​
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.
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.
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.

​
Credential Types

Recurring

Use "type": "recurring" for fixed-amount charges that repeat on a predictable schedule — monthly SaaS fees, annual renewals, membership dues.

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.

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.
See Exception Reasons above for exceptionReason — a separate, optional axis from type, used only when a specific MIT falls into a scheme-defined exception category.
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.