Conversions API overview

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

Type	Direction	Created by
`ON_RAMP`	USD to USDC	Automatically, when a wire lands at a Virtual Account
`OFF_RAMP`	USDC to fiat	`POST /v2/conversions`

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

Lifecycle

INITIATED ──→ PROCESSING ──→ PAYOUT_INITIATED ──→ PAYOUT_IN_PROGRESS ──→ COMPLETED
    │              │                 │                      │
    ▼              ▼                 ▼                      ▼
  FAILED         FAILED           FAILED                RETURNED

COMPLETED, FAILED, and RETURNED 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.

State	Terminal	Meaning
`INITIATED`	No	The conversion exists and has been accepted. For an off-ramp, the submit call succeeded. For an on-ramp, the incoming wire has been recognized
`PROCESSING`	No	Bastion is converting between the stablecoin and fiat legs. The source funds are committed at this point
`PAYOUT_INITIATED`	No	The outbound leg has been handed to the payment provider or the destination chain
`PAYOUT_IN_PROGRESS`	No	The provider or network is delivering the funds
`COMPLETED`	Yes	Funds have been delivered. `completed_at` is populated
`FAILED`	Yes	The conversion could not be completed and the payout never went out. `failure_reason` describes the cause
`RETURNED`	Yes	The payout went out and was sent back, most commonly by the receiving bank rejecting it. `failure_reason` describes the cause; `refund_details` carries the credited USDC amount, cross-app credit identifiers, and structured failure metadata

What `COMPLETED` means

COMPLETED means Bastion and its payment partner have delivered the funds. It does not mean the receiving bank has credited the recipient’s account. Receiving banks apply their own processing, including compliance screening, so funds can appear in the recipient’s account later than completed_at.

Recovering from a terminal error

FAILED means the payout never went out, so no funds are in flight. Retry if failure_reason points to a transient cause, otherwise route to support. RETURNED means the payout went out and came back. 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. Treat failure_reason as diagnostic. It reports what the provider or bank said, which belongs in your logs and support tooling rather than in front of a customer.

Values populated during the lifecycle

Some fields have no value until the conversion advances far enough to produce one.

Field	Behavior
`destination.amount`	Empty until settlement completes. US wire off-ramps are the exception and set it when the conversion is created
`exchange_rate`	Empty until settlement completes. On an international off-ramp the settled value can differ from the rate quoted
`completed_at`	Empty until `COMPLETED`
`failure_reason`	Set on `FAILED` and `RETURNED` only. GET and webhooks populate this field from the same mapping logic
`refund_details`	Present only when `status` is `RETURNED`. Individual keys inside may be omitted until the refund workflow completes

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 a quote_id on a US conversion is rejected. 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.
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.

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.

Authentication

API Reference

Webhooks

Conversions API overview

Conversion types

Lifecycle

What `COMPLETED` means

Recovering from a terminal error

Values populated during the lifecycle

Quote lifecycle

Interpreting webhook events

Polling

​Conversion types

​Lifecycle

​What COMPLETED means

​Recovering from a terminal error

​Values populated during the lifecycle

​Quote lifecycle

​Interpreting webhook events

​Polling

Conversion types

Lifecycle

What `COMPLETED` means

Recovering from a terminal error

Values populated during the lifecycle

Quote lifecycle

Interpreting webhook events

Polling