Skip to main content
This page defines how a conversion behaves over time: the states it moves through, what each one means, how quotes bind to a conversion, and what to do when something fails. For what a conversion is, see Stablecoin on/off-ramp conversions. For step-by-step implementation, see the quickstarts for on-ramps and off-ramps. For request and response shapes, see the endpoint pages.

Conversion types

Both types share the same lifecycle and the same webhook event type.

Lifecycle

COMPLETED, FAILED, RETURNED, and CANCELLED are terminal. Every other state is transient. FAILED is reachable from INITIATED, PROCESSING, and PAYOUT_INITIATED. Once the payout is in flight the terminal error is RETURNED instead, because the funds left and are coming back. A successful submit call does not mean a conversion will reach payout, so handle a terminal error out of every transient state.

Retrying a submit

Reuse request_id to retry a submit safely:
  • Same body. If a conversion already exists for that request_id and the retry’s body matches it, Bastion returns the existing conversion. No new conversion is created and no quote is consumed.
  • Different body. If the retry’s body differs from the original — account_id, amount, quote_id, payment_purpose, or the source or destination currency, payment method, chain, or payment_instructions_id — Bastion returns 409 ALREADY_EXISTS. The error’s details.field names the first field that differs. Submit with a new request_id to use different terms.
  • In flight. If the retry arrives while Bastion is still creating the original conversion, it returns 503 SERVICE_UNAVAILABLE. This is retryable — resend the same request_id and body. A US off-ramp submitted without a quote_id can instead get 409 ALREADY_EXISTS in this window, even with an unchanged body. On a 409 for a body you know is unchanged, don’t resubmit with a new request_id — the original conversion is still being created, and its webhooks carry your original request_id.
  • Rejected submit. A submit that was rejected before a conversion was created — for example QUOTE_EXPIRED — never occupied the request_id. Reuse it freely, with new terms if needed.

Recovering from a FAILED conversion

FAILED means the payout never went out, so no funds are in flight. Route on failure_details.type when it is present: When failure_details is absent, failure_reason names the cause. Common cases:
  • Payment instruction issues. Most of these are caught synchronously at registration — see Format requirements. Occasionally one slips past that check and the payment provider only rejects it at payout time. When that happens, failure_reason names the rejected field path and the provider’s message, for example recipient.individual.address.postal_code: has invalid value for the given country — multiple rejected fields are joined with |. Correct the named field, register new payment instructions, and retry with the new payment_instructions_id.
  • Anything else. Retry if it looks transient, otherwise route to support.
Treat failure_reason as diagnostic. It reports what the provider or bank said, or why the source-balance check found insufficient funds. It belongs in your logs and support tooling rather than in front of a customer.

Handling a RETURNED conversion

RETURNED means the payout went out and came back, most commonly because the receiving bank rejected it — this applies to US and international off-ramps alike. Retrying against the same payment instructions will usually fail the same way, so have the customer verify the destination bank details and register corrected instructions first. RETURNED sets both failure_reason (the same diagnostic field used on FAILED) and refund_details, a structured record of the money moving back to the customer. The refunded USDC is credited back to the customer’s account automatically, and refund_details carries: The refund also arrives as a standard deposit webhook, before the RETURNED conversion event. Correlate the two on transaction_hash, which matches refund_details.transaction_hash, so you don’t count the refund twice.

Values populated during the lifecycle

Some fields have no value until the conversion advances far enough to produce one. Show quoted figures as estimates, and use the values from the COMPLETED event on receipts and in your ledger.

Quote lifecycle

International off-ramps must reference a quote. US off-ramps do not use quotes, and Bastion rejects a quote_id on a US conversion. A quote is created by GET /v2/conversions/quotes, is persisted, and carries an expires_at. It binds fee terms and pricing to the conversion that later references it, which is why fee fields are not accepted on submit. Three rules govern the binding:
  • Single use. A quote supports one successful conversion. Retries that reuse the same request_id are idempotent and do not consume a second quote — see Retrying a submit.
  • Expiry. Submitting after expires_at returns QUOTE_EXPIRED.
  • Consistency. The conversion must match the quote. The amount must equal the quoted source.amount, and the destination corridor must be the one that was priced.
Pricing is indicative rather than locked. Re-fetch a quote whenever the customer’s input changes, and again before showing a confirmation screen, so the figures they approve are as current as possible.

Amount precision

Every amount on a quote is a decimal string formatted at its currency’s native decimal precision. USDC carries six decimal places, most fiat currencies two, JOD three, and JPY zero. Parse amounts as decimals rather than assuming a fixed two-decimal rendering. Bastion rounds source.amount to the source currency’s native precision before returning the quote, so the value is always accepted as amount on submit. POST /v2/conversions accepts amount with up to six decimal places. limits.min_amount and limits.max_amount are denominated and formatted in limits.currency. Quote request amounts have their own caps: source_amount and source_total_max accept up to six decimal places. destination_amount is capped at the destination currency’s own native precision instead — for example three places for JOD, zero for JPY, KRW, and CLP, two for most others. A finer value on any of these returns INVALID_INPUT naming the field. Conversion objects follow the same rule. Every amount on POST /v2/conversions and GET /v2/conversions/{conversion_id} responses, and on conversion_notification_update events, renders at the precision of the currency that denominates it. Source-side amounts use the source currency, destination.amount the destination currency, and fee amounts their fee currency.

Interpreting webhook events

Conversions emit a single event type, conversion_notification_update, on every state change. The conversion object arrives in data, matching the shape returned by GET /v2/conversions/{conversion_id}. Two identifiers, used for different things:
  • The top-level id identifies the event and is regenerated if the event is reprocessed, so don’t use it as your deduplication key.
  • data.id is the conversion ID and is stable across every event for that conversion. Deduplicate business logic on data.id together with data.status.
A delivery can repeat, so the same status may arrive more than once. Make your handler idempotent. Because INITIATED is the first event on an on-ramp, that event is also the first time you learn the conversion’s ID. Route it using account_id and the Virtual Account it landed against. For delivery behavior, retries, and sender verification, see Webhooks. For payload field definitions, see Conversion notifications.

Polling

Webhooks are the recommended way to track a conversion. Poll GET /v2/conversions/{conversion_id} as a fallback when an expected webhook has not arrived within a reasonable window. Polling returns current state, not history, and there is no endpoint that lists conversions. Persist each event as it arrives, keyed on data.id, and store identity_id, account_id, and payment_instructions_id alongside your own records. That gives you transition history, event routing, and period reconciliation without querying Bastion.