Getting Started

Core Concepts

How rates, quotes, rate locks, and the rest of the API relate

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.

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

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