> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Core Concepts

> The core concepts across the CrissCross Payments and FX APIs and how they relate — rate vs quote vs rate lock, and how a locked rate prices a checkout payment.

This page defines the core concepts across the CrissCross Payments and FX APIs and shows how they relate — so you can tell a *rate*, a *quote*, and a *rate lock* apart, and know which to use when.

## How to read this

Each concept below has a short **definition**, its **defining properties**, and its **relationships** to the others (what it's built on, what it becomes, what it sits alongside). The relationships matter as much as the definitions: they're what keep closely related concepts — like a quote and a rate lock — from being mistaken for one another.

## The FX pricing journey

A **rate** is the foundation; from it branch three kinds of commitment, used for different things:

* **rate → quote → order** — accept a quote to make a single FX trade.
* **rate → rate lock → checkout** — reuse one locked rate across many checkout payments.
* **rate → per-session quote → checkout** — an implicit quote minted at session creation, refreshable, applied to one session. This is [Adaptive Currency Conversion](/adaptive-currency-conversion).

### Rate

* **Definition:** the price of one currency in terms of another — a ratio, `1 base = N quote`.
* **Properties:** pure information; observed, not granted; perishable (true only *now*); **amountless**; **sideless**. Flavours: `mid` (fair midpoint), `all-in` (mid + markup), bid/ask.
* **Relationships:** the **primitive**. Everything below is a rate plus something. Exposed by `GET /rates` (indicative).

### Quote

* **Definition:** a firm, single-use offer to trade a *specific amount* at a locked rate, valid for seconds.
* **Properties:** a **commitment** you can rely on; **amount- and side-specific**; requested on demand (RFQ); **short-lived** — a firm price can only be held for seconds against a moving market; **single-use** (accepting it spends it).
* **Relationships:** **is** a rate + commitment. **Accepted → becomes an order.** **Sibling of a rate lock** (both are commitments on a rate, different shapes). `POST /quotes` → `POST /quotes/{id}/accept`. ID prefix `qut_`.

### Rate lock

* **Definition:** a rate held still for hours, reusable across many transactions, with drift protection.
* **Properties:** a **commitment**, but **amountless** at creation; **multi-use** (reused across checkouts); **hours-long**; drift-protected (cancelled if the rate moves beyond tolerance). Priced as mid + markup → all-in.
* **Relationships:** **is** a rate + commitment — but a *different shape* from a quote (no amount, reusable, hours). **Not a quote**, though a sibling of one. **Applied to** checkout sessions and the transactions within them (see *The bridge* below). `POST /rate-locks`. ID prefix `rlk_`.

### Order

* **Definition:** the booked trade that results from accepting a quote.
* **Properties:** carries the locked amounts and rate; has a fill lifecycle (`pending → filling → filled`).
* **Relationships:** **derived from** a quote (accepting one creates exactly one order). ID prefix `ord_`.

### Per-session quote (ACC's default pricing)

* **Definition:** an implicit FX quote minted at checkout-session creation when the initiation currency differs from the collection currency and no rate lock is set — the default way [Adaptive Currency Conversion](/adaptive-currency-conversion) prices a conversion. Valid for minutes, refreshable in-place on the hosted page.
* **Properties:** a **commitment** on a rate, like a Quote or Rate lock, but with a *third* shape — minute-scale (not seconds, not hours), refreshable, one-session-scope, no ID surfaced to the merchant. Priced as mid + markup → all-in, same as a rate lock.
* **Relationships:** **is** a rate + commitment. **Applied to** exactly one checkout session (see *The bridge* below). Snapshotted onto each transaction attempt as an immutable `fxCommit` record. **Not** a `Quote` (`qut_`) and **not** a rate lock (`rlk_`).

**The journey at a glance:**

```
rate ── (+ commitment, amount, side, seconds, single-use) ──▶ quote ──(accept)──▶ order
  ├──── (+ commitment, no amount, reusable, hours) ──▶ rate lock ──(apply to checkout)──▶ transactions
  └──── (+ commitment, session-scoped, minutes, refreshable) ──▶ per-session quote (ACC) ──(implicit)──▶ transactions
```

## The Payments journey

### Checkout session

* **Definition:** a merchant-initiated context for collecting a payment from a payer, in a collection currency.
* **Properties:** has `amount` (minor units) + `currency` (the initiation currency the merchant prices in); may also carry a `collectionCurrency` (the currency the payer is charged in — defaults to the primary currency for `payerDetails.location`); one or more transactions occur within it; may be created with a `rateLockId`; carries an `fxCommit` when a conversion has been applied (the lock that priced it is readable as `fxCommit.quoteId`).
* **Relationships:** **parent of** transactions. **May reference** a rate lock, or carry an implicit per-session quote (see [ACC](/adaptive-currency-conversion)).

### Transaction (payment)

* **Definition:** a single attempt to collect funds within a checkout session.
* **Properties:** primary id `transactionId`; has its own status lifecycle; inherits the session's rate lock.
* **Relationships:** **belongs to** a checkout session. **Verified against** the session's rate lock at initiation (see *The bridge* below).

### Refund

* **Definition:** a return of collected funds against a transaction.
* **Relationships:** **belongs to** a transaction; settled at that transaction's original locked rate.

## The bridge — where FX meets Payments

This is how an FX rate ends up pricing a checkout payment. There are two routes — the two pricing options of [Adaptive Currency Conversion](/adaptive-currency-conversion) — and both terminate at a **transaction** priced at an all-in rate.

**Route 1 — Rate lock (explicit, multi-session):**

* A merchant creates a **rate lock** (FX) and passes its `rateLockId` onto a **checkout session** (Payments).
* The session `currency` must equal the lock's **base** currency.
* At **transaction** initiation the lock is **verified on use**: expired / cancelled → `422`, fetch a new lock.
* Each transaction **settles at the lock's `allInRate`**; refunds settle at the original transaction's rate.

**Route 2 — Per-session quote (implicit, ACC's default):**

* No `rateLockId` is set. The merchant supplies (or defaults) a `collectionCurrency` on the checkout session that differs from `currency`.
* CrissCross mints an implicit **per-session quote** and attaches it to the session as `fxCommit`.
* The rate is presented to the payer and refreshed in-place if it expires mid-checkout.
* At **transaction** initiation, an expired `fxCommit` is rejected `422`; the page refreshes and the payer re-submits.
* Each transaction **settles at the `fxCommit.allInRate` current at initiation**; the applied rate is snapshotted onto the transaction and preserved for reconciliation.

So a **rate** is what ultimately prices a **transaction**, carried across by either a rate lock (explicit) or a per-session quote (implicit).

## Common confusions to avoid

* **Rate lock ≠ quote.** A quote is amount-bearing, single-use, and valid for seconds; a rate lock is amountless, reusable, and valid for hours. A quote ID implies a specific amount — a rate lock does not — so the two are not interchangeable.
* **"quote" the field ≠ "Quote" the resource.** `quote` in `base`/`quote` is the *quote currency* of a pair (FX convention). A `Quote` is the RFQ resource. Same word, unrelated meanings.
* **ACC's per-session quote ≠ RFQ Quote (`qut_`).** The implicit quote minted by [Adaptive Currency Conversion](/adaptive-currency-conversion) at checkout is valid for *minutes*, refreshes in place, is scoped to one session, and has **no `qut_` ID** surfaced to the merchant. An RFQ Quote is valid for seconds, single-use, and yields an `ord_` on acceptance. Three different words for "quote" sit next to each other in this API — the FX pair side (`base`/`quote`), the RFQ resource, and the ACC per-session quote — treat them as unrelated.
* **`midRate` ≠ `allInRate`.** Mid is the reference midpoint; all-in is mid + markup — the rate you actually transact at.
* **Rate lock ≠ rate.** A bare rate is indicative and carries no promise; a rate lock is a rate plus a commitment to honour it.

## Naming across the APIs

* **ID prefixes:** `qut_` quote · `rlk_` rate lock · `ord_` order · `dep_` deposit · `ben_` beneficiary · `wth_` withdrawal.
* **Currency pair:** FX rate-style resources use `base` / `quote`; FX trade-style resources (quotes, orders) use `sellCurrency` / `buyCurrency` + `side`; Payments uses a single `currency` (the collection side).

For money representation, amount formats, and other shared conventions, see [Conventions](/conventions).