Transaction lifecycle

Every transaction in OMS moves through a predictable set of statuses. The top-level status is designed for programmatic branching. subStatus is always present and provides operational detail without complicating your core logic.

Direction

A transaction’s direction is the pair of its source and destination instrument categories. OMS infers it from the two instruments; you do not set it. Quotes report it as sourceToDestination, and GET /transactions accepts the same values as a sourceToDestination filter:

Value	What it does
`cryptoToCrypto`	USDC moves from one wallet to another, or to an external address
`cryptoToFiatAccount`	USDC out of a wallet, fiat delivered to a bank account
`cryptoToCash`	USDC out of a wallet, delivered as a cash pickup
`fiatAccountToCrypto`	Fiat in from a bank account, USDC delivered to a wallet
`cashToCrypto`	Cash in from a retail deposit, USDC delivered to a wallet
`fiatAccountToFiatAccount`	Fiat in from a bank account, fiat delivered to a bank account or fiat wallet

Transfers

A transaction records what moved from where to where. Each movement of its money on one rail is a transfer (trf_ prefix). The transaction lists its transfers in creation order in transfers, each as { id, role, rail, attempt }; the array is left out until the first transfer exists.

role is deposit (money coming in), payout (money going out to the destination), or refund (money sent back to the sender).
rail is how the money moved: ach, achSameDay, wire, internationalWire, rtp, bookTransfer, blockchain, card, or cash. The transaction’s source and destination instruments carry no rail.
attempt is 1 for the first send. A payout sent again after a confirmed failure is a new transfer with the next attempt; the failed one stays failed.

Fetch a transfer with GET /transfers/{transferId} for its status, amount, from and to instruments, ACH options (secCode, companyDiscretionaryData), originatorName, and tracking. tracking holds the references that trace the transfer outside OMS (txHash, imad, uetr, endToEndId, instructionId) and is left out until OMS holds one. An outgoing transfer (payout or refund) moves through initiated, pending, and settled; a deposit moves through pending and settled. Any transfer can end failed, with a failure object. A payout the receiving bank sends back, or a virtual account deposit the sending bank takes back, ends returned after settled, with a return object.

Status model

processing                      (initial state; the quote is already accepted)
    │
    ├──► completed              (standard flows)
    │
    ├──► awaitingAction         (non-terminal; blocked on developer, upstream, or compliance action)
    │        └──► processing    (once the hold clears)
    │
    └──► failed

The four top-level statuses are processing, awaitingAction, completed, and failed. A transaction begins at processing the moment it is created from a quote. awaitingAction is a non-terminal hold state; the hold object explains what you must do, and the transaction returns to processing once cleared. The hold object carries a code and a fixed message for that code:

`hold.code`	`subStatus`	Meaning
`senderAttribution`	`awaitingAction.awaitingSenderAttribution`	A deposit address received crypto from a sender OMS cannot attribute. `hold.match` carries the sender’s `address` and `network` (the network family); registering that wallet as a `walletExternal` external account releases the hold. `hold.deadline` is when the hold times out and the transaction fails.
`payoutDestinationMissing`	`awaitingAction.payoutDestinationMissing`	A deposit cannot be paid out because the destination of its virtual account or deposit address is unusable. Re-point `destination` on that resource to a healthy account and OMS resumes the payout.

Branch on status only. subStatus is always present. It is a status-scoped string carrying operational detail namespaced by its parent status (for example processing.fundsPulled, processing.cashPickupReady, or completed.cashPickupCollected). processing, completed, and failed each carry a default member (processing.initiated, completed.settled, and failed.unspecified) when no more specific value applies; every awaitingAction value names a specific blocking reason. Cash off-ramp lifecycle events surface here rather than as top-level statuses, and payout execution does too. Payout execution reports its stages on subStatus:

`subStatus`	Meaning
`processing.fundsPulled`	The source funds are in OMS custody; the payout transfer has not been created yet.
`processing.awaitingCryptoOut` / `processing.cryptoOut`	A crypto payout is being prepared, then submitted to its network.
`processing.awaitingFiatOut` / `processing.fiatOut`	A fiat payout is being prepared, then submitted to the rail.
`processing.payoutRetrying`	A payout failed and OMS is sending it again automatically. The new attempt is a new payout transfer on the transaction.
`processing.payoutUnconfirmed`	A payout was submitted but the provider never confirmed an outcome. The payout transfer stays `pending`; no action is required from you.
`processing.returningToSender`	A refund to the sender is in flight.
`processing.underReview`	OMS is holding the money while it decides what happens next.

Terminal failures that match these stages also carry a dedicated reason:

`subStatus`	Meaning
`failed.outboundFailed`	A payout failed on every path OMS could try. The payout transfer reads `failed`.
`failed.returnedToSender`	The funds were returned to the sender. This one value covers both a crypto send-back and a bank return.

Use subStatus for display and logging, not for control flow. A payout in flight never changes the top-level status: a withdrawal reads processing.fundsPulled until its payout transfer exists, then processing.cryptoOut or processing.fiatOut, and processing.payoutUnconfirmed or processing.payoutRetrying on the exceptional branches. The enum is open: new members may be added without an API version bump. If your client receives an unrecognized value, fall back to the status prefix before the dot (an unrecognized processing.someFutureThing still means processing).

Failed transactions and returns

failed is terminal for the transaction, but not for the funds. When OMS has already received the inbound funds and the payout cannot be completed, the funds are returned in the same asset that was received, with no action required from you. The return is a refund transfer on the transaction. While it is in flight, the transaction reads processing.returningToSender; once it settles, the transaction reads failed with subStatus failed.returnedToSender. Each status change fires transaction.statusChanged, so you can render a “refund in progress” state without polling.

Where returned funds go

The return path depends on how the transaction was created:

Created by	Return path
Quote	Back to the source payment method: the wallet or card that funded it. Nothing to configure.
Deposit address	The deposit address’s `returnDestination`, or the on-chain sender when none is set.
Virtual account	The virtual account’s `returnDestination`, or held for manual refund processing when none is set.

Configuring return destinations

Deposit addresses and virtual accounts accept an optional returnDestination at create or PATCH. Send an explicit null in a PATCH body to clear one you set earlier. For a deposit address, returnDestination is a crypto target: a multi-asset OMS wallet (walletCrypto) or a registered external wallet (walletExternal), plus the network to return on, which must match the network the address accepts (expectedSourceNetwork on create, read back as depositInstructions.network). A custodial, non-multi-asset OMS wallet is rejected with 422 ReturnDestinationMustBeMultiAsset. For a virtual account, it is a fiat target: a registered bank account (bankUs, bankIban, or bankCanada), each with a required rail in network. USD bank rails are the only ones accepted today; the fiat balance wallet (walletFiat) and CAD (bankCanada with network: "local") are rejected with 422 RailNotSupported.

Set a returnDestination on every deposit address and virtual account. Without one, returned crypto goes back to the on-chain sender, which may be an exchange hot wallet the customer cannot receive on, and returned fiat is held for manual processing.

Webhook events

OMS fires a webhook on every meaningful state change. Each delivery carries the full transaction object under data, so your handler reads the status (and, if needed, subStatus) directly off it. Polling GET /transactions/{transactionId} is rarely necessary once webhooks are configured. Subscribe to events through the Webhooks endpoints or the OMS Dashboard. A subscription is an endpoint URL plus the list of event types you want:

POST /webhooks
{
  "url": "https://your-app.example.com/oms/webhooks",
  "subscriptions": ["*"]
}

Pass ["*"] in subscriptions to receive every event type, or list specific event names to filter. The Webhooks endpoints support full CRUD (GET/PATCH/DELETE /webhooks/{webhookId}) plus lifecycle actions (POST /webhooks/{webhookId}/enable | /disable | /rotate-key | /test), and the create response returns a signingKey once, which you use to verify the Webhook-Signature header on incoming deliveries. Inspect and replay delivery history at GET /webhooks/{webhookId}/deliveries and POST /webhooks/{webhookId}/deliveries/retry. Transactions emit one event, transaction.statusChanged, on every status transition described above, in either direction and on any rail. The full transaction arrives under data, so branch on data.status and use data.subStatus for detail. The envelope’s previousStatus names the status it left. To be notified when a transaction is held for compliance review, subscribe explicitly to transaction.fiatToCrypto.underReview, transaction.cryptoToFiat.underReview, or transaction.cryptoToCrypto.underReview; the * wildcard does not include them. See the webhook events catalog for every event type and the delivery envelope.

Auto-created transactions

Deposit addresses, virtual accounts, and cash-ins bypass the quote step. OMS creates the transaction internally when funds arrive and moves it directly to processing. The same status model and webhook events apply.

Idempotency

Every POST endpoint except the token endpoints (POST /auth/token and POST /customers/{customerId}/token) requires an Idempotency-Key header. Use a stable key (UUID tied to your internal order ID) to safely retry on network failure. OMS returns the same response for any subsequent request with the same key within the idempotency window.

Set Idempotency-Key on every write request in production. It protects against double-execution without any coordination on your side.

Overview

Introduction

Fundamentals

Direction

Transfers

Status model

Failed transactions and returns

Where returned funds go

Configuring return destinations

Webhook events

Auto-created transactions

Idempotency

​Direction

​Transfers

​Status model

​Failed transactions and returns

​Where returned funds go

​Configuring return destinations

​Webhook events

​Auto-created transactions

​Idempotency

Direction

Transfers

Status model

Failed transactions and returns

Where returned funds go

Configuring return destinations

Webhook events

Auto-created transactions

Idempotency