Per Session

The per-session rate is the default way Adaptive Currency Conversion prices a conversion — the alternative to a pre-fetched rate lock. There is no endpoint to call and no field to set: when a session needs a conversion and no rateLockId is supplied, an implicit FX quote is minted at session creation, valid for minutes, and refreshed automatically on the hosted page if it expires.

When it applies

A per-session rate prices the session when, at Create Checkout Session:

1. The session currency (the currency you price in) differs from the payer’s collectionCurrency — or from the primary currency of payerDetails.location when collectionCurrency is omitted, and
2. no rateLockId is supplied.

If a rateLockId is supplied, the session is priced by the rate lock instead. If no conversion is needed, the payer is simply charged in the initiation currency and no FX commit is written.

Reading the rate back

The committed conversion is returned inline on Get Checkout Session as fxCommit. For a per-session rate, pricingModel is SPOT_QUOTE and quoteId is the upstream quote identifier, preserved for audit:

1
{
2
  "session": {
3
    "id": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
4
    "merchantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
5
    "merchantReference": "ORDER-20260624-001",
6
    "amount": 10000,
7
    "currencyId": "USD",
8
    "expiresAt": "2026-06-24T11:00:00Z",
9
    "customerId": "9b2d7f3a-8c4e-4f1a-9d3e-1a2b3c4d5e6f",
10
    "payerLocation": "KEN",
11
    "redirectUrl": "https://merchant.example.com/order/confirmation",
12
    "paymentAttributes": {
13
      "paymentMethod": "card",
14
      "platform": "web"
15
    },
16
    "fxCommit": {
17
      "quoteId": "qut_01951c8a-9d5e-7f3b-bc4f-6e7d8c9b0a21",
18
      "pricingModel": "SPOT_QUOTE",
19
      "collectionCurrency": "KES",
20
      "collectionAmount": "13260.00",
21
      "midRate": "130.00",
22
      "markupBps": 200,
23
      "allInRate": "132.60",
24
      "fee": "260.00",
25
      "expiresAt": "2026-06-24T10:35:00Z"
26
    }
27
  }
28
}

Compare with a rate-locked session, where pricingModel is RATE_LOCK and quoteId is the rlk_ rate lock id — see the response examples on Get Checkout Session.

Expiry and refresh

A per-session quote is valid for minutes, not hours — note fxCommit.expiresAt above versus the session’s own expiresAt:

• On the hosted checkout page — the rate refreshes automatically in place when the quote expires; the payer proceeds at the refreshed rate with no merchant action needed.
• At payment initiation — a payment submitted against an expired fxCommit is rejected with 422 (stale quote). Refresh the session and re-submit against the current rate. This is the safety net for direct-API integrations.

The expiry check runs when the payment is initiated, and this is the same for both flows. A payment initiated inside the validity window settles at the rate snapshotted onto the transaction, even if the quote expires while the payment is still being authorized — expiry never fails an in-flight payment, for a per-session rate or a rate lock alike.

Because of the refresh, fxCommit on the session reflects the latest committed conversion. The rate a payer actually transacted at is snapshotted per-attempt on the transaction (collection, fxMidRate, fxAllInRate, fxMarkupBps) — immutable once written, and authoritative for reconciliation.

When to use a rate lock instead

Use the per-session rate when you just need the payer’s currency converted at the moment of purchase. If you want one rate to hold across many checkouts — steady-state pricing, valid for hours and reusable until expiry — fetch a rate lock and pass its rateLockId at session creation.