Entities and relationships

Every OMS integration is built from a small set of resources: customers, wallets, counterparties, external accounts, virtual accounts, deposit addresses, cash-ins, quotes, transactions, transfers, and webhooks. Knowing how they relate is the fastest way to design a correct integration.

The entity model

Customer
├── Wallets            (custodial crypto wallets and USD fiat wallets)
├── Counterparties     (people and businesses the customer pays)
├── External accounts  (bank accounts, debit cards, and external wallets,
│                       owned by the customer or one of its counterparties)
├── Virtual accounts   (persistent bank account numbers that receive fiat)
├── Deposit addresses  (persistent onchain addresses that receive crypto)
└── Cash-ins           (codes for depositing cash at a retail location)

Transaction  (one money movement, from a source instrument to a destination instrument)
├── created from a Quote                (you call POST /transactions)
├── auto-created by a Virtual account   (a bank deposit arrives)
├── auto-created by a Deposit address   (a crypto deposit arrives)
├── auto-created by a Cash-in           (cash is deposited)
└── Transfers                           (each movement of its money on one rail)

Webhooks  (project-level event subscriptions)

Every financial resource belongs to a customer. Quotes, transactions, wallets, counterparties, external accounts, virtual accounts, deposit addresses, and cash-ins are all scoped to one. External accounts belong to the customer or to one of its counterparties. Webhook subscriptions belong to your project, not to a customer.

Shapes every resource shares

The resources use a common set of conventions, so code that reads one resource reads the others. Customer reference. A resource names its customer as customer: { "id": "cst_..." }. Quotes are the exception: they carry customerId plus a display-safe customer summary with id and name. Instruments. The source and destination of a transaction, and the from and to of a transfer, are instruments with one shape:

{
  "type": "bankUs",
  "id": "ext_fky491gakzj0dd46qb6whsr2vq",
  "asset": "usd",
  "owner": { "kind": "counterparty", "id": "ctp_yp5z8m7n22svc0vh6edqgcfdat", "name": "Alice Smith" },
  "details": { "accountNumberLast4": "1234", "holderName": "Alice Smith" }
}

type names the account kind (walletCrypto, walletExternal, walletFiat, bankUs, bankIban, bankCanada, card, cash, depositAddress, or virtualAccount). Crypto instruments add a network. owner appears only when the account belongs to someone other than the customer. Bank instruments on a transaction carry no rail: the rail lives on the transfer that moved the money. Amounts and fees. Money is a decimal string at the asset’s precision ("10.00" for usd, "5.000000" for usdc). Quotes, transactions, and cash-ins report economics in one pricing object: source and destination, each { amount, asset }, plus a flat fees[] list. See Quote system. Failures and holds. A failed resource carries one failure object: { code, message, retryable }, plus bankCode when a bank gave one. A transaction waiting on you carries a hold object with a code and message. Both are left out when they do not apply. Omitted, not null. A field that does not apply to a resource is left out of the response rather than sent as null. All timestamps are UTC with millisecond precision, for example 2026-06-15T10:00:00.000Z. ID prefixes. Every ID is prefixed by its resource type:

Prefix	Resource
`cst_`	Customer
`wlt_`	Wallet (crypto and fiat)
`ctp_`	Counterparty
`ext_`	External account (every instrument type)
`va_`	Virtual account
`da_`	Deposit address
`ci_`	Cash-in
`qt_`	Quote
`txn_`	Transaction
`trf_`	Transfer
`whk_`	Webhook
`evt_`	Webhook event

Customers

A customer is the identity record every financial operation hangs off. Create one with POST /customers and a type of individual or business. Creation can return 202 while onboarding runs asynchronously; see Customer onboarding for the fields your project requires. A customer’s status tells you whether it can move money:

`status`	Meaning
`pending`	Onboarding is in progress.
`actionRequired`	Onboarding needs more information. `hold` explains what.
`active`	Onboarding is complete.
`rejected`	Onboarding failed. `failure` explains why.
`offboarded`	The customer was deleted.

Inside a customer, endorsements track onboarding per capability. Each endorsement in endorsements[] has a type and its own status, using the same five values. An endorsement never reads further along than its customer.

Endorsement	Covers
`basic`	Baseline identity verification. Included automatically with `usd`.
`cryptoCustody`	Custodial crypto wallets and the crypto services that depend on them.
`usd`	USD operations.

When you omit endorsements on create, OMS requests cryptoCustody and usd. Whether verification is required, and how it runs, is configured per project. Status changes arrive as customer.statusChanged and customer.updated webhooks.

Wallets

A wallet holds value OMS manages for a customer. OMS supports two kinds through the Payments API:

Crypto wallets (walletCrypto) hold one stablecoin on one network, with an onchain address. OMS manages the keys. Create one with POST /wallets, type: "custodial", and details: { network, asset }. The customer needs an active cryptoCustody endorsement.
Fiat wallets (walletFiat) hold a USD balance at a partner bank, with no network or address. Create one with POST /wallets, type: "fiat". See Fiat wallets.

List a customer’s wallets with GET /wallets?customerId=.... GET /wallets/{walletId} returns the wallet with its balances[]. Wallets are the source of quoted transactions and a common destination for deposits. For user-controlled keys, use OMS Wallet non-custodial wallets. The two models can be combined. Account model covers custody choices in more depth.

Virtual accounts

A dedicated bank account number assigned to a customer. When fiat arrives on a supported bank rail, OMS creates a transaction that delivers the funds to the virtual account’s destination: a stablecoin to a crypto wallet or registered external wallet, USD forwarded to a registered bank account, or USD held in the customer’s fiat wallet. Create one with POST /virtual-accounts. Give your customer the depositInstructions once they appear on the resource. Deleting a virtual account is asynchronous: it reads deleting until the underlying account closes, then deleted. See Virtual accounts.

Deposit addresses

A persistent onchain address assigned to a customer. When usdc or usdt arrives, OMS creates a transaction that delivers the funds to the deposit address’s destination: fiat to a registered bank account or the customer’s fiat wallet, or crypto to an OMS wallet or registered external wallet. Create one with POST /deposit-addresses. The address in depositInstructions appears once it is issued. There is no delete. Deposit addresses must be enabled for your project. See Deposit addresses.

Counterparties

A person or business the customer pays who is not your customer, for example a supplier. A counterparty is scoped to one customer, has an entityType of individual or business, and owns external accounts. A counterparty cannot be deleted while it owns active or pending external accounts. See External accounts.

External accounts

A registered bank account, debit card, or external wallet, owned by the customer or one of its counterparties. Every external account ID uses the ext_ prefix whatever the instrument; read type to tell them apart. Register bank accounts and external wallets with POST /external-accounts. Debit cards register only through the secure card fields of the OMS browser SDK; see Debit cards. External accounts are references, not balances. OMS never holds funds in one. They appear as the destination of a quote, deposit address, or virtual account, and as a card source on a quote.

Quotes

A quote locks pricing for a short window before you move money. You create one when the money starts in an OMS wallet or on a debit card:

POST /quotes: lock pricing and get the fee breakdown.
POST /transactions with the quoteId: execute against the locked quote.

Quotes expire quickly (30 seconds by default). See Quote system.

Transactions

A transaction is the record of one money movement from a source instrument to a destination instrument. There is no transaction type field: the corridor follows from the two instruments. Quotes report it as sourceToDestination, and GET /transactions filters on the same values. Most transactions are created for you. The resource that receives the funds decides how:

Funds arrive from	Resource	How the transaction is created
A bank transfer	Virtual account	Automatically, when the deposit arrives
A crypto wallet outside OMS	Deposit address	Automatically, when the crypto arrives
Cash at a retail location	Cash-in	Automatically, when the cash is deposited
An OMS wallet or a debit card	Quote	You call `POST /transactions` with the `quoteId`

precursor on the transaction names the resource that created it. Auto-created transactions skip the quote step, because OMS cannot lock pricing before the funds arrive.

Transfers

A transfer is one movement of a transaction’s money on one rail: the deposit coming in, the payout going out, or a refund going back. A transaction lists its transfers in transfers[], and GET /transfers/{transferId} returns the full record with its rail, status, and tracking references. See Transaction lifecycle.

Cash-ins

A code-based deposit flow for cash at retail locations. Creating a cash-in issues a code the customer presents at a partner location. When the cash is deposited, OMS converts it to a stablecoin and auto-creates a transaction. See Cash-ins and cash-outs.

Webhooks

Webhook subscriptions tell OMS where to deliver events. Create one with POST /webhooks, passing a url and the event types in subscriptions (or ["*"] for all of them). Each delivery carries the resource as a GET would return it, so you rarely need a follow-up read. See Receiving webhooks.

Overview

Introduction

Fundamentals

The entity model

Shapes every resource shares

Customers

Wallets

Virtual accounts

Deposit addresses

Counterparties

External accounts

Quotes

Transactions

Transfers

Cash-ins

Webhooks

​The entity model

​Shapes every resource shares

​Customers

​Wallets

​Virtual accounts

​Deposit addresses

​Counterparties

​External accounts

​Quotes

​Transactions

​Transfers

​Cash-ins

​Webhooks

The entity model

Shapes every resource shares

Customers

Wallets

Virtual accounts

Deposit addresses

Counterparties

External accounts

Quotes

Transactions

Transfers

Cash-ins

Webhooks