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
Reuserequest_id to retry a submit safely:
- Same body. If a conversion already exists for that
request_idand 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 thesourceordestinationcurrency, payment method, chain, orpayment_instructions_id— Bastion returns409ALREADY_EXISTS. The error’sdetails.fieldnames the first field that differs. Submit with a newrequest_idto use different terms. - In flight. If the retry arrives while Bastion is still creating the original conversion, it returns
503SERVICE_UNAVAILABLE. This is retryable — resend the samerequest_idand body. A US off-ramp submitted without aquote_idcan instead get409ALREADY_EXISTSin this window, even with an unchanged body. On a409for a body you know is unchanged, don’t resubmit with a newrequest_id— the original conversion is still being created, and its webhooks carry your originalrequest_id. - Rejected submit. A submit that was rejected before a conversion was created — for example
QUOTE_EXPIRED— never occupied therequest_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_reasonnames the rejected field path and the provider’s message, for examplerecipient.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 newpayment_instructions_id. - Anything else. Retry if it looks transient, otherwise route to support.
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 aquote_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_idare idempotent and do not consume a second quote — see Retrying a submit. - Expiry. Submitting after
expires_atreturnsQUOTE_EXPIRED. - Consistency. The conversion must match the quote. The
amountmust equal the quotedsource.amount, and the destination corridor must be the one that was priced.
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 roundssource.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
ididentifies the event and is regenerated if the event is reprocessed, so don’t use it as your deduplication key. data.idis the conversion ID and is stable across every event for that conversion. Deduplicate business logic ondata.idtogether withdata.status.
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. PollGET /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.