Transaction lifecycle

A transaction is the record of one money movement from a source instrument to a destination instrument. Its top-level status is built for branching your code. subStatus is always present and adds operational detail for display and logging. Each movement of the money on a rail is a separate transfer with its own status.

Anatomy of a transaction

{
  "id": "txn_01jbx8t3m4e5f6g7h8j9k0m1n2",
  "status": "processing",
  "subStatus": "processing.fiatOut",
  "customer": { "id": "cst_vfa0nxw6zvyws9g237jrxn4y7k" },
  "precursor": { "type": "quote", "id": "qt_0gq9aesz4wb5etdv88z1j61qcm" },
  "source": { "type": "walletCrypto", "id": "wlt_5h4jzzpr9xre3bamd9ca7qyghn", "asset": "usdc", "network": "polygon" },
  "destination": { "type": "bankUs", "id": "ext_fky491gakzj0dd46qb6whsr2vq", "asset": "usd" },
  "pricing": {
    "source": { "amount": "100.000000", "asset": "usdc" },
    "destination": { "amount": "99.42", "asset": "usd" },
    "fees": [{ "type": "oms", "amount": "0.580000", "asset": "usdc", "side": "source" }],
    "exchangeRate": "1.0000",
    "fixedAmountSide": "source"
  },
  "transfers": [
    { "id": "trf_01jbx8v2a3b4c5d6e7f8g9h0j1", "role": "payout", "rail": "ach", "attempt": 1 }
  ],
  "metadata": { "orderId": "order_12345" },
  "createdAt": "2026-10-20T14:00:00.000Z",
  "updatedAt": "2026-10-20T14:00:04.000Z"
}

precursor names what created the transaction: quote, depositAddress, virtualAccount, cashIn, or walletDeposit (a crypto deposit straight into a custodial wallet, with no id).
source and destination are instruments. Bank instruments carry no rail; the rail is on the transfer.
failure appears only when status is failed, and hold only when status is awaitingAction.

There is no transaction type field. The corridor follows from the two instruments:

Corridor	What moves
`cryptoToCrypto`	A stablecoin from one wallet to another, or to an external address
`cryptoToFiatAccount`	A stablecoin out of a wallet, fiat delivered to a bank account or fiat wallet
`cryptoToCash`	A stablecoin out of a wallet, delivered as a cash pickup
`fiatAccountToCrypto`	Fiat in from a bank account or fiat wallet, a stablecoin delivered to a wallet
`fiatAccountToFiatAccount`	Fiat in, fiat delivered to a bank account or fiat wallet
`cashToCrypto`	Cash deposited at a retail location, a stablecoin delivered to a wallet

Quotes report the corridor as sourceToDestination, and GET /transactions?sourceToDestination=... filters on it.

Status model

processing ──► completed
    │
    ├──► awaitingAction ──► processing   (once you resolve the hold)
    │
    └──► failed

`status`	Meaning
`processing`	OMS is moving the money. Every transaction starts here.
`awaitingAction`	The transaction is blocked until you act. `hold` says what to do.
`completed`	The money was delivered.
`failed`	The transaction ended without delivering. `failure` says why.

Branch on status. Use subStatus for display, logging, and support. A payout in flight never changes status: a withdrawal reads processing from creation until the money lands. completed and failed are final for almost every transaction. The exceptions are covered in Failed transactions and returns.

Holds

While status is awaitingAction, the hold object carries a code and a fixed message:

`hold.code`	`subStatus`	What to do
`senderAttribution`	`awaitingAction.awaitingSenderAttribution`	A deposit address received crypto from a sender OMS cannot attribute. `hold.match` gives the sender’s `address` and network family. Register that wallet as a `walletExternal` external account for the customer to release the hold. If `hold.deadline` passes first, the transaction fails with `failed.attributionTimeout`.
`payoutDestinationMissing`	`awaitingAction.payoutDestinationMissing`	The destination of the virtual account or deposit address that received the deposit is unusable. Re-point `destination` on that resource to a healthy account and OMS resumes the payout.

Sub-statuses

subStatus is a dotted string whose prefix is always the status. processing, completed, and failed each have a default (processing.initiated, completed.settled, failed.unspecified) used when nothing more specific applies. Every awaitingAction value names a specific blocking reason.

The list is open. OMS can add sub-statuses without an API version bump. If you receive a value you do not recognize, fall back to the prefix before the dot: an unknown processing.somethingNew still means processing. If your client validates against a generated enum, make it tolerant of new members.

`processing`

`subStatus`	Meaning
`processing.initiated`	The transaction was created. Default when nothing more specific applies.
`processing.inboundPending`	An inbound deposit has been seen and is not yet confirmed.
`processing.inboundProcessing`	An inbound deposit is confirmed and being screened. Funds are not final until the transaction completes.
`processing.fundsPulled`	The customer’s own money has been taken from the wallet or card, or the cash collected. The payout transfer does not exist yet.
`processing.awaitingCryptoOut`	A crypto payout is being prepared.
`processing.cryptoOut`	A crypto payout has been submitted to its network.
`processing.awaitingFiatOut`	A fiat payout is being prepared.
`processing.fiatOut`	A fiat payout has been submitted to its rail.
`processing.cashPickupReady`	A cash pickup is ready to collect. The pickup code is in `destination.details.pickupCode`.
`processing.payoutRetrying`	A payout failed and OMS is sending it again. The new attempt is a new payout transfer.
`processing.payoutUnconfirmed`	A payout was sent and the provider never confirmed the outcome. The payout transfer stays `pending`. No action is needed from you.
`processing.payoutHeld`	The provider accepted a fiat payout and is holding it until your prefunded balance covers it. Topping up releases it.
`processing.returningToSender`	A refund to the sender is in flight.
`processing.underReview`	OMS is holding the money while it decides what happens next, for example after a payout failed before a retry exists, after a bank returned a settled payout or refund, or when a deposit is outside your limits or allowed routes.

`awaitingAction`

`subStatus`	Meaning
`awaitingAction.awaitingSenderAttribution`	Waiting for you to register the sender’s wallet. Pairs with `hold.code: senderAttribution`.
`awaitingAction.payoutDestinationMissing`	Waiting for you to re-point the receiving resource’s `destination`. Pairs with `hold.code: payoutDestinationMissing`.
`awaitingAction.depositAddressFrozen`	The deposit address that received the funds is frozen.
`awaitingAction.informationRequested`	OMS needs more information before the transaction can continue.

`completed`

`subStatus`	Meaning
`completed.settled`	The money was delivered. Default for `completed`.
`completed.cashPickupCollected`	The recipient collected the cash pickup.
`completed.cashPickupExpired`	The cash pickup window closed without collection.

`failed`

`subStatus`	Meaning
`failed.unspecified`	The transaction failed with no more specific reason recorded. Default for `failed`.
`failed.expired`	The transaction expired before it could complete.
`failed.providerDeclined`	The provider refused the order.
`failed.inboundFailed`	The inbound deposit failed.
`failed.outboundFailed`	A payout failed on every path OMS could try. The payout transfer reads `failed`.
`failed.returnedToSender`	The money reached the sender again: OMS sent the deposit back, or the sending bank took the deposit back. Never used for a returned payout.
`failed.attributionTimeout`	The sender attribution hold passed its `deadline`.
`failed.depositAddressFrozenTimeout`	The deposit address stayed frozen past the hold window.
`failed.depositAddressInactiveTimeout`	The deposit address stayed unusable past the hold window.
`failed.depositAddressClosed`	The deposit address was closed.

failure.code gives the machine-readable reason (for example insufficientFunds, payoutFailed, or accountClosed) and failure.retryable tells you whether trying again can succeed. See ReasonCode in the API reference for every value.

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, instant, intraBank, blockchain, card, or cash. instant is an RTP or FedNow payout, and the transfer names which one in instantRail. intraBank stays inside one bank, and the transfer names the same-bank rail in intraBankRail.
attempt is 1 for the first send. A payout sent again after a confirmed failure is a new transfer with the next attempt, and the failed one stays failed. A re-send of a payout whose outcome is unknown stays the same transfer.

GET /transfers/{transferId} returns the full transfer: status, amount, the from and to instruments, the ACH options it was sent with (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 has one.

Transfer `status`	Meaning
`initiated`	An outgoing transfer (payout or refund) was created.
`pending`	The transfer is on the rail. Deposits start here.
`settled`	The money arrived.
`failed`	The transfer failed. `failure` says why.
`returned`	A bank sent settled money back. `return` gives the reason, with the bank’s own code in `bankCode` (for example ACH `R03`).

Failed transactions and returns

completed and failed can still move afterwards in a few cases:

A bank takes back money that settled. A returned payout or refund reads processing.underReview while OMS decides whether to resend it or send it back. A returned deposit reads failed.returnedToSender.
A failed deposit settles late. On a late provider report, the transaction returns to processing and continues to completed.
A refund starts after a failure. While it is in flight the transaction reads processing.returningToSender; once it settles, failed.returnedToSender.

When OMS has already received the inbound funds and the payout cannot complete, it returns them in the asset it received, with no action from you. The return is a refund transfer on the transaction.

Where returned funds go

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

Deposit addresses and virtual accounts accept an optional returnDestination at create or PATCH; send null in a PATCH to clear it.

For a deposit address, it is a crypto target: an OMS wallet (walletCrypto, which must be multi-asset, otherwise 422 ReturnDestinationMustBeMultiAsset) or a registered external wallet (walletExternal), plus a network that matches the network the address accepts.
For a virtual account, it is a registered bank account (bankUs, bankIban, or bankCanada) with a required rail in network. Only USD bank rails are accepted today: walletFiat, and 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 onchain sender, which may be an exchange wallet the customer cannot receive on, and returned fiat is held for manual processing.

Webhook events

Each transaction and transfer change is delivered as a webhook, so you rarely need to poll GET /transactions/{transactionId}.

Event	Fires when
`transaction.created`	A transaction is created, from a quote or by an inbound deposit.
`transaction.statusChanged`	`status` or `subStatus` changes, in either direction.
`transfer.created`	A transfer is created on a transaction.
`transfer.statusChanged`	A transfer’s `status` changes.
`transfer.updated`	Other fields on a transfer change.

The event’s data.resource is the transaction or transfer as GET returns it, so branch on data.resource.status. On statusChanged events, data.previousStatus names the status it left. A sub-status-only change still sends transaction.statusChanged, with previousStatus equal to status. Deliveries are at least once and can arrive out of order: deduplicate on the event id and order by createdAt per resource. See Receiving webhooks and the webhook events catalog.

Idempotency

POST requests that create a quote, transaction, wallet, or other money-movement resource require an Idempotency-Key header; the API reference marks it on each operation. Use one UUID per logical operation, tied to your internal order ID, and reuse it only to retry that same request. OMS returns the original response for a repeat within 24 hours. Reusing a key with a different body returns 422 IdempotencyKeyReuse.

Overview

Introduction

Fundamentals

Anatomy of a transaction

Status model

Holds

Sub-statuses

`processing`

`awaitingAction`

`completed`

`failed`

Transfers

Failed transactions and returns

Where returned funds go

Webhook events

Idempotency

​Anatomy of a transaction

​Status model

​Holds

​Sub-statuses

​processing

​awaitingAction

​completed

​failed

​Transfers

​Failed transactions and returns

​Where returned funds go

​Webhook events

​Idempotency

Anatomy of a transaction

Status model

Holds

Sub-statuses

`processing`

`awaitingAction`

`completed`

`failed`

Transfers

Failed transactions and returns

Where returned funds go

Webhook events

Idempotency