Core concepts

Tokeflow is the infrastructure behind your platform. You model your business once — its accounts, catalog, customers, and payments — and Tokeflow standardizes those objects across every connected payment provider. This page is the canonical glossary and object model: each entity, what it represents, its ID prefix, and how the pieces fit together.

The object model at a glance

Everything in Tokeflow hangs off a two-level tenancy model: an Organization (your platform) that contains one or more Merchants (the brands or business units that actually sell). Almost every other resource is scoped to a single merchant.

Tenancy

Organization

Your platform — the top-level tenant and billing/governance boundary. An organization owns one or more merchants and carries org-wide compliance identity (legal name, registration, country). Organization-scoped API keys (sk_live_org_… / pk_live_org_…) can act across every merchant in the org.

ID prefix: org_

Merchant

A single brand or business unit that sells under your platform. A merchant is the scope for nearly every operational resource — customers, catalog, checkout, transactions, orders, and subscriptions all belong to exactly one merchant. Merchant-scoped keys (sk_live_mer_… / pk_live_mer_…) infer the merchant automatically.

ID prefix: mrc_

Customers and payment data

Customer

A buyer under a specific merchant. Holds identity (name, email, phone), an optional tax document, and a billing address. Customers are de-duplicated by email within a merchant, and the same person may exist independently under different merchants.

ID prefix: cust_

Payment Instrument

A reusable, tokenized payment method owned by a customer — typically a card stored for future charges (returning checkout, subscriptions, one-click). Tokeflow stores only safe metadata such as brand, last four digits, and expiry; raw card data is never persisted on Tokeflow's systems.

ID prefix: pi_

Card Token

A short-lived, single-use reference to card data collected in the browser by Tokeflow's secure fields. Secure fields run inside isolated, cross-origin iframes; card data is encrypted in the browser and never touches your servers. Your client receives a card token and hands it to your backend, which exchanges it (server-side, with a secret key) into a durable Payment Instrument.

ID prefix: tok_

Catalog

Your sellable catalog is a four-level hierarchy: a Product Family groups related Products; each product is sold as one or more Offers; each offer is priced via Offer Prices (one per currency). Offer Transitions define how a subscriber may move between offers (upgrade/downgrade) within a family.

Product Family

A grouping of related products that a subscriber can move between (for example, tiers of a plan). The family defines the default behavior — change_charge_behavior — for transitions between its offers. A product belongs to a family when it participates in upgrade/downgrade flows.

ID prefix: pfa_

Product

Something you sell. A product is either one_time or recurring (type), and is active or archived (status). When part of a family, it carries a tier position so plans can be ordered for upgrade/downgrade logic.

ID prefix: prd_

Offer

A purchasable configuration of a product — the thing a customer actually buys. An offer fixes the billing cycle, trial and setup behavior, and how many cycles to charge. A product can expose several offers (for example, a monthly and a yearly offer).

ID prefix: ofr_

Offer Price

The amount for an offer in a single currency. An offer has one price per currency, with one marked as the default. Amounts are integer minor units and always paired with an ISO 4217 currency.

ID prefix: opr_

Offer Transition

A directional rule connecting two offers in the same family — the path a subscriber takes when upgrading or downgrading. A transition can override the family's default change_charge_behavior (next_renew, prorated, or override) for that specific pair, and can be activated or deactivated.

ID prefix: oft_

Checkout

A hosted, stateful purchase flow. A Checkout Session tracks a buyer from arrival to completion, holds the chosen offers as Checkout Items, and records a timeline of Checkout Events (including UTM attribution) for funnel analysis. A completed session produces an Order.

Checkout Session

The container for one checkout attempt. Tracks the primary offer, the (eventually identified) customer, the selected currency, and a lifecycle status: initiated, customer_identified, payment_pending, completed, expired, abandoned.

ID prefix: cks_

Checkout Item

A line within a session: an offer, its currency and snapshotted amount, quantity, and selected installments. Amounts are snapshotted from the offer price at session time so later catalog edits don't change an in-flight checkout.

ID prefix: cki_

Checkout Event

An append-only event in a session's timeline. Event types: initiated, customer_identified, currency_changed, payment_started, payment_failed, payment_succeeded, completed, expired, abandoned. Carries optional attribution (utm_source, utm_medium, utm_campaign) and request context.

ID prefix: cke_

Payments

Transaction

A single payment attempt against a provider — the normalized record of one authorization/capture, regardless of which connected provider handled it. Carries the payment method, amounts (authorized and captured, in minor units), currency, country, and a rich status. Transactions are idempotent on create and may be linked to an Order.

ID prefix: tx_

status: pending, pre_authorized, authorized, failed, canceled, voided, charged_back, refund_pending, capture_pending, refunded, partially_refunded, expired.

Order

The merchant-facing, normalized record of a single sale. An order links to at most one Transaction that settles it, references the customer, and may be tied to a Subscription when it's a renewal or trial setup. Use the order as your stable business reference; the transaction is the payment mechanics behind it.

ID prefix: ord_

status: pending, pre_authorized, authorized, failed, canceled, refunded, partially_refunded, charged_back, refund_pending.

Refund

A full or partial reversal of a captured transaction. A transaction may have multiple refunds (e.g. successive partial refunds). Each refund records an amount in minor units, a currency, a status, and a reason.

ID prefix: ref_

Subscription

A recurring billing agreement: a customer billed on an Offer using a stored Payment Instrument. Tokeflow tracks the current offer and amount, the billing period, trial windows, dunning state for failed renewals, and a lifecycle status. Each renewal charge produces an Order (and its transaction).

ID prefix: sub_

Money and formatting conventions

Consistency across providers and currencies is enforced by a few rules. Apply them everywhere.

Standard response envelope

Every API response wraps the resource in a consistent envelope. A single resource omits meta; a list includes meta.pagination.

{
  "success": true,
  "data": {
    "id": "tx_8f3c2a1b",
    "status": "authorized",
    "payment_method": "credit_card",
    "amount_authorized": 15000,
    "amount_captured": 15000,
    "currency": "BRL",
    "country": "BR"
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

A list response sets data to an array and includes pagination:

{
  "success": true,
  "data": [
    { "id": "ord_a1b2c3", "status": "authorized", "total_amount": 9900, "currency": "USD" }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

ID format reference

Every Tokeflow object carries a prefixed, opaque identifier. Prefixes are stable — match on them rather than parsing the random suffix.

Next steps

• Authentication — key types, scopes, and the merchant_id rule for org keys.
• Idempotency — safe retries on create and charge calls.
• SDK — collect cards with secure fields and exchange card tokens into payment instruments.
• Webhooks — normalized event delivery and signature verification.