Skip to main content
Fiat checkouts and exchange connections share one order model. An order is completed only once the purchased crypto has landed on-chain as a deposit, not merely when the provider reports sending it. After that, the deposit follows the standard pipeline to the account’s target.

​
Order stages

Every order moves money through four stages:
  • delivery is submitted with a txHash once the provider reports the transfer, and completed with a depositId only once that transfer landed as a deposit on the account.
  • on_hold and failed carry a reason: for example kyc_required while the user still has to verify, or cancelled and declined when a payment fails.
  • return stays none unless money goes back; a completed return carries an outcome (full_refund, adjustment, or unresolved).
Each order also has a status derived from its stages, and terminal once no stage will change again: Exchange orders reach completed the same way as fiat orders, once the transfer lands.

​
Get an order

id accepts either the order’s id or the orderId returned when you started it. It returns 404 until the provider first reports the order, which happens when the user starts paying, and for another project’s order.
  • Fiat figures: charged is what the user paid in their own currency; eur is comparable across every order; usd is present when the provider reports it. Each has a total including fees and a net before fees, and any of them is null when the provider didn’t state it.
  • rail: the payment method or exchange, or provider_selected when the provider didn’t say.
  • providerStatus: the provider’s own status, for support; don’t branch on it.
Full schema: GET /onramp/orders/{id}.

​
List orders

List your project’s orders, newest first by when each began, optionally for one account:
Pass nextCursor as cursor for the next page; it is null on the last one. Orders are kept for good, including pending and cancelled ones. Full schema: GET /onramp/orders.

​
Push updates

Each stage move sends a ramp-order webhook carrying the whole order in the shape above, so you can store the latest one rather than fetch after each event. The delivery’s txHash reappears as the transactionHash on the deposit-received event, followed by the usual bridge events. Card and Apple Pay orders typically complete within minutes; bank transfers can take days. Exchange timing depends on the provider flow.

​
Processing caveats

  • Session coverage — on-ramp purchases land on Base, so the account’s session set must include Base. The default registration flow covers every supported chain; if you restrict sessionChainIds, include Base or landed funds can’t be bridged.
  • Deposit whitelist — if you restrict accepted deposits, allow USDC on Base above your minimum. Otherwise every on-ramp purchase is rejected with deposit-rejected.
  • Same-chain target — when the account’s target is USDC on Base paid to the account itself, the purchase is already at its destination: no bridge events fire, and the order’s completed status is your terminal signal.
  • KYC and limits — identity verification and purchase limits are handled by Swapped inside the hosted UI.

​
Migrate from the deprecated route

GET /onramp/swapped/status/{smartAccount} and the onramp-order webhook keep working unchanged until their retirement is announced. They report only the account’s latest order, for seven days, with Swapped’s own statuses. Exchange orders never leave processing there. Move to GET /onramp/orders and ramp-order, which cover every order, for good, stage by stage.