Orders & checkout

Create a deposit order, show checkout (QR / links), poll or listen for status, and close when supported.

When to use

After the user picks a currency and amount. Session must be active.

Methods

Method	Purpose
createOrder(request)	Create deposit order; returns ExchangePayOrder
getActiveOrder()	In-memory active order, or null
getOrder()	Fetch status for the active order (ExchangePayOrderStatus)
closeOrder()	Close / abandon the active order (see canClose)
reset()	Clear local active order (also happens on session refresh)

Request

type CreateExchangePayOrderRequest = {
  provider: ExchangePayProvider
  amount: string // fiat USD amount, e.g. '25.00'
  token: TokenSymbol
  blockchain: Network
}

Creating a new order closes a previous closable active order first, or clears local state if the previous order could not be closed.

Example - create

import { IntegrationProvider, Network, TokenSymbol } from '@swapped/connect-sdk'

const order = await client.exchangePay.createOrder({
  provider: IntegrationProvider.Binance,
  amount: '25.00',
  token: TokenSymbol.USDC,
  blockchain: Network.Solana,
})

console.log(order.id, order.expiresAt, order.canClose)

Checkout UI fields

Field	Use for
order.checkout.qr	QR - { type: 'image', value } or { type: 'url', value }
order.checkout.url	Desktop checkout link (may be null, e.g. OKX is QR-focused)
order.checkout.mobileUrl	Mobile / deep link (may be null)
order.expiresAt	Expiry timestamp (ms since epoch) - see Expiry
order.canClose	Whether closeOrder() hits the provider API
order.amount	Total crypto to send (includes provider + merchant fees)
order.providerFee	Exchange fee in order.currency
order.merchantFee	Swapped fee in order.currency (null when none)
order.fiatAmount	Net fiat amount (excluding fees)

Fees & formatted order

Fees come from the create-order response. Prefer getFormattedOrder() for UI — the client fetches a live quote and fills fiat values when it lands:

const formatted = client.exchangePay.getFormattedOrder()

client.exchangePay.onFormattedOrderUpdated(({ formattedOrder }) => {
  console.log(
    formattedOrder?.total.formatted.fiatValue,
    formattedOrder?.providerFee.exchangeRateLoading,
  )
})

formattedOrder includes every field from the raw order. Amounts are { amount, token, fiatCurrency, fiatValue, exchangeRate, exchangeRateLoading, formatted } — amount is always crypto. fiatValue is null and exchangeRateLoading is true until the quote loads.

Low-level helpers if you already have a rate:

import {
  getExchangePayOrderBreakdownFiat,
  getExchangePayYouReceive,
  toExchangePayFormattedOrder,
} from '@swapped/connect-sdk'

const breakdown = getExchangePayOrderBreakdownFiat(order, exchangeRateFiat)
const receive = getExchangePayYouReceive(order)
const formatted = toExchangePayFormattedOrder(order, exchangeRateFiat)

const { qr, url, mobileUrl } = order.checkout

if (qr?.type === 'image') {
  // <img src={qr.value} alt="Pay QR" />
} else if (qr?.type === 'url') {
  // render a QR from qr.value (e.g. qrcode library)
}

if (url) {
  // <a href={url}>Open checkout</a>
}

if (mobileUrl && mobileUrl !== url) {
  // <a href={mobileUrl}>Open in app</a>
}

QR types

qr.type	Meaning	Typical providers
'image'	Ready-made image (data URI / URL)	Bybit
'url'	String to encode as a QR	Binance, KuCoin, Gate, KrakPay, OKX

Closing orders (canClose)

canClose	Behavior
true	Call closeOrder() when the user leaves checkout (back, abandon). Uses provider close API.
false	Bybit / OKX - skip cancel UI. closeOrder() only clears local state. Create a new order when needed.

Starting a new order also clears the previous active order automatically.

if (order.canClose) {
  await client.exchangePay.closeOrder()
}

Status

const status = await client.exchangePay.getOrder()
console.log(status.status)
// 'PENDING' | 'PAY_SUCCESS' | 'AWAITING_PROVIDER_FUNDS'

Prefer events for live updates; use getOrder() to refresh on demand.

Completion is treated as success when status is PAY_SUCCESS or a transactionHash is present.

Errors

Code	When	What to do
SESSION_REQUIRED	No loaded session	loadSession()
SESSION_NOT_ACTIVE	Session cannot start a new payment	restartSession() first
NO_ACTIVE_ORDER	getOrder / closeOrder with nothing active	Call createOrder first
CLOSE_ACTIVE_ORDER_FAILED	Provider close API failed	Retry or create a new order
API_ERROR	Create / status / close network failure	Retry; keep user on a safe step

See Errors.