Skip to navigation
CollectAdaptive Currency ConversionRate Locks

Create a rate lock

Locks the current reference rate for a currency pair so it can be reused across multiple merchant transactions until lock expiry or market-drift cancellation.

The rate, markup, and validity window are fixed when the lock is created and stay constant for its lifetime, even if pricing changes afterwards.

Pricing is mid-market reference + markup; the mid, the markup, and the resulting all-in rate are all returned.

You can hold up to two active locks per currency pair, so you can pre-fetch a replacement (typically about an hour before the current lock expires) and overlap it with the lock it succeeds. While both are active, keep pricing existing browsing sessions off the current lock and send new sessions to the new one. If fewer than two locks are active a new one is minted (201); if two are already active the freshest existing lock is returned instead (200).

Idempotency: none. Each mint creates a distinct lock, subject to the two-lock cap.

Authentication

AuthorizationBearer
Token obtained via the login flow.

Request

This endpoint expects an object.
basestringRequired

Base currency of the pair (ISO 4217) — the currency you price in, e.g. USD.

quotestringRequired

Quote currency of the pair (ISO 4217) — the currency you collect in, e.g. KES.

Response

An existing active rate lock, returned because two active locks already exist for this currency pair (the maximum of two). The freshest of the two is returned.

rateLockIdstring
statusenum
  • active — usable.
  • expired — past expiresAt. Terminal.
  • cancelled — invalidated before expiry; see cancellationReason. Terminal.

expired and cancelled are permanent — a lock never returns to active. A lock at or past expiresAt is invalid even if status still reads active.

Allowed values:
basestring

Base currency (ISO 4217).

quotestring

Quote currency (ISO 4217).

midRatestring

Reference mid-market rate the lock was priced from. 1 base = <midRate> quote.

markupBpsinteger

The markup applied over the mid, in basis points (100 bps = 1%).

allInRatestring

The rate you transact at: mid plus markup. This is the rate carried onto every transaction that uses the lock. 1 base = <allInRate> quote.

createdAtdatetime
expiresAtdatetime

End of the lock's validity window. The lock is invalid from this time even if status still reads active.

cancellationReasonenumOptional

Why the lock was cancelled. Present only when status is cancelled. market_drift — the rate moved beyond the allowed tolerance. requested — you cancelled the lock yourself via the cancel endpoint.

Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
503
Service Unavailable Error