Transactions - Polygon Developer Docs

A transaction moves money through OMS. You specify a source instrument and a destination instrument on the quote; OMS infers the direction from those two sides and reports it as sourceToDestination. There is no settable transaction “type”. Standard sends and payouts follow a two-step flow: create a quote to lock pricing, then create a transaction to execute it. Cash-in and auto-created transactions (virtual accounts, deposit addresses) skip the quote step.

Direction (`sourceToDestination`)

The sourceToDestination field is a composite of the source and destination instrument categories, inferred from each side:

Value	Source	Destination
`cryptoToCrypto`	OMS wallet	OMS wallet or external on-chain address
`cryptoToFiatAccount`	OMS wallet	Registered bank external account
`cryptoToCash`	OMS wallet	Cash pickup (early access)
`fiatAccountToCrypto`	Bank account, via a virtual account	OMS wallet
`cashToCrypto`	Cash, via a cash-in	OMS wallet

Two-step flow

POST /quotes   →  quote in "open" status (rate locked)
                    │
POST /transactions  →  transaction in "processing"
                    │
              completed | failed

The quote locks the exchange rate and fee breakdown for a short validity window. To execute it, call POST /transactions with a body of { "quoteId": "qt_..." }. If the quote expires before you create the transaction, create a new quote.

Quote object

{
  "id": "qt_...",
  "object": "quote",
  "status": "open",
  "customerId": "cst_...",
  "sourceToDestination": "cryptoToCrypto",
  "source": {
    "type": "walletCrypto",
    "category": "crypto",
    "id": "wlt_...",
    "asset": "usdc",
    "network": "polygon",
    "displayName": "0xabc…def"
  },
  "destination": {
    "type": "walletExternal",
    "category": "crypto",
    "id": "ext_wlt_...",
    "asset": "usdc",
    "network": "polygon",
    "displayName": "0x123…456"
  },
  "pricing": {
    "source": {
      "asset": "usdc",
      "amountGross": "100.00",
      "amountNet": "99.42",
      "feesDeducted": { "total": "0.58", "developer": "0.20", "oms": "0.35", "gas": "0.03" }
    },
    "destination": {
      "asset": "usdc",
      "amountGross": "99.42",
      "amountNet": "99.42"
    },
    "pair": "usdc/usdc",
    "exchangeRate": "1.0",
    "effectiveRate": "0.9942",
    "fixedAmountSide": "source"
  },
  "expiresAt": "2025-01-15T10:35:00Z"
}

Set pricing.fixedAmountSide to "source" when the user specifies how much to send, or "destination" when the user specifies how much to receive. The source and destination are typed instruments discriminated by type: an OMS wallet (walletCrypto), an externally-custodied wallet (walletExternal), a bank account (bankUs, bankIban, bankCanada), a debit card (card), or cash pickup (cash). Each instrument carries the reference fields (id, asset, network) directly, alongside type, category, and displayName. The one exception is an unregistered external party, where id is null and a small details object carries either blockchainAddress (crypto) or accountNumberLast4 and bankName (fiat).

Party, precursor, and payout origin

Transaction and quote responses carry three flat reference objects that identify who is on each side, what created the transaction, and which of your resources funded the payout:

"source": {
  "type": "walletCrypto",
  "category": "crypto",
  "id": "wlt_...",
  "asset": "usdc",
  "network": "polygon",
  "party": { "relationship": "customer", "id": "cst_...", "name": "Jane Doe" }
},
"precursor": { "type": "depositAddress", "id": "da_..." },
"payoutOrigin": { "type": "virtualAccount", "id": "va_..." }

Field	Shape	Notes
`party`	`{ relationship, id, name }`	`relationship` is one of `customer`, `otherCustomer`, `externalRegistered`, `externalUnregistered`. Sits on the side it describes.
`precursor`	`{ type, id }`	`type` is one of `depositAddress`, `virtualAccount`, `cashIn`, `quote`, or `manual`. `id` is `null` for the `manual` arm; the field itself is `null` for out-of-band arrivals with no OMS-originating resource.
`payoutOrigin`	`{ type, id }`	`type` is `wallet` for a crypto-source send or `virtualAccount` for a fiat-account payout. `id` is `null` before execution and on cash off-ramp pickups.

Dereference the referenced resource by id to retrieve richer detail. Bank account numbers, routing numbers, and BICs are not returned on payoutOrigin; read them from the funding virtual account or external account directly. Cash payouts render the pickupCode at the destination top level (a sibling of payoutOrigin), not inside the instrument.

Instrument display name

Every source and destination instrument carries a displayName: an opaque, ready-to-render label for the value being moved. The field is always present and is the value you should show in receipts, tables, and confirmation UIs; do not compose your own from other instrument fields.

Instrument	`displayName`
`bankUs`, `bankIban`, `bankCanada`, `card`	The stored last four, mask-prefixed (`••••1234`)
`walletOms`, `walletExternal`	The blockchain address, falling back to the wallet ID when the address is not yet provisioned
`walletFiat`	The OMS wallet ID (`wlt_fiat_…`)
`cash`	The retail location name

The value is derived server-side from the stored data on each instrument. Format is deliberately unversioned: OMS may refine the rendering without changing the schema, so treat it as an opaque string.

Customer summary on a transaction

Transactions carry a customer summary that resolves the transaction’s customer in one hop:

"customer": {
  "id": "cst_...",
  "name": "Jane Doe"
}

The field is populated on GET /transactions/{transactionId}, in POST /transactions responses, and on every entry of GET /transactions. Names on a list response resolve from the same request context, so listing a page of transactions from the same customer does not multiply the underlying customer read. The same customer shape appears on virtual accounts and deposit addresses; external accounts carry the same field plus a bare ownerDisplayName for the owning customer or counterparty.

Transaction statuses

Status	Meaning
`processing`	Executing. Funds are being pulled or converted.
`awaitingAction`	Non-terminal. Blocked on developer, upstream, or compliance action; see the `hold` object. Returns to `processing` once cleared.
`completed`	Funds delivered to the destination.
`failed`	Terminal failure. The `error` object describes the cause.

OMS fires transaction.statusChanged on every status change, so your handler branches on the transaction’s status field rather than parsing an event-name string. Subscribe with the Webhooks endpoints (POST /webhooks with a body of { url, subscriptions }; pass ["*"] for all partner-visible events) or in the OMS Dashboard. See the transaction lifecycle for the delivery model.

Developer fees

Developer fees are configurable per integration and are never shown to the end user. Set them on your OMS account or pass them in the quote request. They appear in the feesDeducted.developer field on both the source and destination sides of the pricing object.

Key operations

Operation	Endpoint
Create a quote	`POST /quotes`
Get a quote	`GET /quotes/{quoteId}`
Create a transaction	`POST /transactions`
Get a transaction	`GET /transactions/{transactionId}`
List transactions	`GET /transactions`

GET /transactions returns results newest-first and filters by status, sourceToDestination, customerId, the originating instrument (walletId, virtualAccountId, depositAddressId, cashInId), and inclusive createdAfter/createdBefore date bounds. Pagination uses limit, startingAfter, and endingBefore.

All POST endpoints accept an Idempotency-Key header. Use a stable key tied to your internal order ID to safely retry on network failure without risk of double-execution.

Fiat to crypto guide: cash-in and virtual-account funding
Send from a wallet guide: crypto sends and bank payouts
Bank transfers guide: ACH and wire transfer details

​Direction (sourceToDestination)

​Two-step flow

​Quote object

​Party, precursor, and payout origin

​Instrument display name

​Customer summary on a transaction

​Transaction statuses

​Developer fees

​Key operations

​Related

Direction (`sourceToDestination`)

Two-step flow

Quote object

Party, precursor, and payout origin

Instrument display name

Customer summary on a transaction

Transaction statuses

Developer fees

Key operations

Related