Skip to main content
Every ONRAMP and OFFRAMP order includes an FX conversion leg that exchanges the source asset for the destination asset. The conversion runs automatically after the source leg settles; there is no standalone endpoint to create one. This page explains how to drive conversion failure outcomes in sandbox.
The reason field is optional (max 500 chars). When supplied, it surfaces verbatim as failureMessage on the order.failed webhook payload and on the polled GET /v2/orders/:id response, with no transformation.

​
How to fail a conversion

Use the orders/:id/simulate/conversion-failed endpoint to force a conversion to a failed terminal state. The endpoint is timing-independent: call it at any point after order creation. If the conversion is already running, it is driven to failed immediately; otherwise the failure is armed and applied as soon as the conversion starts. The order is driven to failed and order.failed is emitted. 
curl -X POST https://api.sandbox.conduit.financial/v2/sandbox/orders/$ORDER_ID/simulate/conversion-failed \
  -H "x-api-key: $SANDBOX_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Provider rate stale"}'
Returns 200 OK with the order at its current state. Returns 404 if the order is not found. Replays against an already-terminal order return 200 with the current resource (idempotent).
Rate-lock expiry SLA. POST /v2/sandbox/orders/:id/simulate/rate-lock-expired returns 200 OK with the order at its current state and the order reaches cancelled (expired) within about 3 seconds via an immediate background sweep tick. No polling backoff needed; no need to wait for the scheduled 30-second sweep.
There is no create-time outcome locking for conversions. The only way to force a conversion failure in sandbox is this endpoint, which works at any point after the order exists.

​
Webhook events

Conversion outcomes surface on the order’s webhook topic. There is no standalone conversion webhook.
EventWhen it fires
order.succeededThe full order completed successfully (source settled, conversion ran, destination credited). Terminal.
order.failedThe order failed. reasonCode (INSUFFICIENT_FUNDS / PROVIDER_UNAVAILABLE / PROVIDER_REJECTED / INTERNAL_ERROR / CANCELLED) names the failure category. Conversion failures surface here.
order.cancelledThe order was cancelled before execution completed. cancellationReason is expired or client_cancelled.
Intermediate state (conversion in progress, source settled, etc.) is not conveyed via webhooks. Poll GET /v2/orders/:id to observe the current order state between terminal events. See the Webhooks reference for full payload schemas.

​
Errors

Conversion failures produce order.failed on the order. The payload carries reasonCode (INSUFFICIENT_FUNDS / PROVIDER_UNAVAILABLE / PROVIDER_REJECTED / INTERNAL_ERROR / CANCELLED) describing the failure category. See Error codes for the broader catalog used by other event types.

​
See also