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 on the quote 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 quote’s sourceToDestination field is a composite of the source and destination instrument categories, inferred from each side. Filter GET /transactions by the same values:

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_...",
  "status": "open",
  "customer": { "id": "cst_..." },
  "sourceToDestination": "cryptoToCrypto",
  "source": {
    "type": "walletCrypto",
    "id": "wlt_...",
    "asset": "usdc",
    "network": "polygon",
    "details": { "address": "0xabc...def" }
  },
  "destination": {
    "type": "walletExternal",
    "id": "ext_...",
    "asset": "usdc",
    "network": "polygon",
    "details": { "address": "0x123...456" }
  },
  "pricing": {
    "source":      { "amount": "100.000000", "asset": "usdc" },
    "destination": { "amount": "99.420000",  "asset": "usdc" },
    "fees": [
      { "type": "developer", "amount": "0.200000", "asset": "usdc", "side": "source" },
      { "type": "oms",       "amount": "0.350000", "asset": "usdc", "side": "source" },
      { "type": "gas",       "amount": "0.030000", "asset": "usdc", "side": "source" }
    ],
    "exchangeRate": "1.0",
    "fixedAmountSide": "source"
  },
  "expiresAt": "2026-10-16T10:35:00.000Z"
}

Set pricing.fixedAmountSide to "source" when the user specifies how much to send, or "destination" when the user specifies how much to receive.

Pricing

Every quote, transaction, and cash-in renders pricing in one shape:

Field	Shape	Notes
`pricing.source`	`{ amount, asset }`	The gross the customer pays.
`pricing.destination`	`{ amount, asset }`	The amount delivered to the destination.
`pricing.fees`	Array, always present	Each entry is `{ type, side, asset, amount }`. Known `type` values are `developer`, `oms`, and `gas`; tolerate values you do not recognize. Only non-zero fees are listed. The array is empty when no fees apply. The source net is `source.amount` minus `fees` on the source; the destination gross is `destination.amount` plus `fees` on the destination.
`pricing.exchangeRate`	Decimal string	Present only together with a destination amount.
`pricing.sponsorGas`	Boolean	Present only when `true`. Omitted when gas is not sponsored.
`pricing.fixedAmountSide`	`"source"` or `"destination"`	Which side the quote was priced from.

Every amount is a decimal string padded to the asset’s own precision: six decimals for usdc/usdt, two for usd/eur, three for bhd, eighteen for eth. The same amount renders the same string on every network and in every response and webhook. Do not trim or re-round the value; display it as received or format it with your locale.

Instrument shape

The source and destination are typed instruments discriminated by type. There are ten arms: walletCrypto, walletFiat, walletExternal, bankUs, bankIban, bankCanada, card, cash, and the auto-created-flow arms depositAddress and virtualAccount. Each instrument carries type, asset, and, where applicable, id, network, owner, and details:

Field	When present
`id`	Set when the instrument resolves to an OMS resource (an OMS wallet, a registered external account, a deposit address, a virtual account). Omitted entirely for an unregistered external party; a `null` id is never sent.
`asset`	Always present and lowercase.
`network`	Present for crypto arms, in lowercase. On a transaction, bank arms carry no `network`: the rail and the ACH options are on the transaction’s transfers.
`owner`	Present only when the account is not the resource’s own customer’s. Shape is `{ kind: "counterparty", id, name }` for a saved third-party payee, or `{ kind: "customer", id }` for another customer. A customer’s own name is never sent on their own instrument.
`details`	Typed by `type`. Carries only the fields the type owns: `address` for a crypto arm or deposit address; `bankName`, `accountNumberLast4` (`ibanLast4` on `bankIban`), `holderName`, and `memo` for a bank arm, plus `routingNumber` and `accountType` on `bankUs`; `brand`, `last4`, `cardType`, `expiryMonth`, and `expiryYear` for a card; `locationId`, `locationName`, `locationAddress`, and `locationProvider` for cash. Fields are omitted when they would be empty. A cash payout destination also carries `pickupCode` next to `details`.

Owner, precursor, and payout origin

Transaction responses carry three flat reference objects that identify who owns a non-customer account, what created the transaction, and whose name the payout goes out under:

"source": {
  "type": "walletCrypto",
  "id": "wlt_...",
  "asset": "usdc",
  "network": "polygon",
  "details": { "address": "0xabc...def" }
},
"destination": {
  "type": "bankUs",
  "id": "ext_...",
  "asset": "usd",
  "owner": { "kind": "counterparty", "id": "ctp_...", "name": "Acme Supply Co." },
  "details": { "accountNumberLast4": "6789", "bankName": "First National Bank", "holderName": "Acme Supply Co." }
},
"precursor": { "type": "depositAddress", "id": "da_..." },
"payoutOrigin": {
  "type": "bank",
  "id": "va_...",
  "accountHolder": "customer",
  "accountHolderName": "Jane Doe"
}

Field	Shape	Notes
`owner`	`{ kind, id, name? }`	Present only when the account on that side is not the resource’s own customer’s. `kind` is `counterparty` for a saved third-party payee (always carries `name`) or `customer` for another customer (carries `id` only). A customer’s own instrument has no `owner`.
`precursor`	`{ type, id }`	`type` is one of `depositAddress`, `virtualAccount`, `cashIn`, `quote`, `walletDeposit`, or `manual`. `walletDeposit` identifies a custodial-wallet deposit with no originating OMS resource (its `id` is always `null`); `id` is also `null` for the `manual` arm. The field itself is left out only for an out-of-band arrival with no recognized origin at all.
`payoutOrigin`	`{ type, id?, accountHolder?, accountHolderName? }`	Describes where last-mile delivery is sent from. `type` is `bank` for a bank or card payout and `blockchain` for a crypto send. `id` references the funding resource when one applies (`wlt_` for an OMS wallet, `va_` for a virtual account; omitted on an unregistered external origin and before execution). `accountHolder` is `customer`, `partner`, or `paymentProvider`, naming whose name the payment is sent under. `accountHolderName` resolves to the legal name the recipient sees as the sender: the customer’s legal name on a `customer` or `partner` holder, or the OMS payment-provider legal name on `paymentProvider`.

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. payoutOrigin is left out when nothing is paid out to a bank account, a card, or a wallet, so cash payouts and fiat-wallet credits carry none; a cash payout carries its pickupCode on the cash destination instead. The same payoutOrigin is carried at the top level of the transaction, the deposit address, and the virtual account.

Rendering an instrument

The typed details object on each instrument carries the fields you need to label the side in your UI. Instruments carry no pre-formatted display string, so you choose the label that fits your layout. Common recipes:

Instrument	Recommended label
`bankUs`, `bankCanada`, `virtualAccount`	`details.accountNumberLast4` masked for display (for example, `••••1234`); add `details.bankName` where you have the room.
`bankIban`	`details.ibanLast4` masked for display; add `details.bankName` where you have the room.
`card`	`details.last4` masked for display; add `details.brand` where you have the room.
`walletCrypto`, `walletExternal`, `depositAddress`	`details.address` is the on-chain address when known. Fall back to `id` when the address has not been provisioned yet.
`walletFiat`	The wallet `id`.
`cash`	`details.locationName`.

A counterparty-owned bank account also carries owner.name with the counterparty’s name. details.holderName carries the account holder: the counterparty’s name, or the sender’s name when the rail carries it. A customer’s own name lives on the customer resource.

Bank memo

Bank source and destination instruments carry an optional memo field inside details on transaction responses. When populated, it echoes the wire, ACH, or SWIFT memo that actually travelled on the rail:

"source":      { "type": "bankUs",   "details": { "memo": "Invoice 20482" } },
"destination": { "type": "bankIban", "details": { "memo": "FFC Jane Doe 12345" } }

OMS echoes only memos that a sender supplied. Any default text OMS may compose on behalf of a rail (for example, a SELL PROCEEDS line) never appears in the response. The field is present on GET /transactions/{transactionId}, on every entry of GET /transactions, and on transaction.statusChanged webhook payloads. Non-bank arms do not carry a memo.

Transfers and rail tracking

A transaction’s transfers array lists each movement of its money on one rail, in creation order. Each entry names the transfer id (trf_ prefix), its role, its rail, and its attempt:

"transfers": [
  { "id": "trf_...", "role": "payout", "rail": "wire", "attempt": 1 }
]

The array is left out until the first transfer exists. Fetch a transfer with GET /transfers/{transferId} to read the rail references in its tracking object:

Field	Meaning
`txHash`	The on-chain transaction hash.
`imad`	The Fedwire input message accountability data.
`uetr`	The SWIFT unique end-to-end transaction reference.
`endToEndId`	The end-to-end ID the rail carries.
`instructionId`	The instruction ID of an incoming wire.

tracking is left out until OMS holds a reference. The transfer also carries its own status, amount, from and to instruments, and, for an ACH payout, the secCode and companyDiscretionaryData it was sent with. See Transfers for roles, attempts, and transfer statuses.

Customer reference

Every transaction, quote, deposit address, virtual account, cash-in, external account, and customer wallet carries a customer reference that identifies the owning customer in one hop:

"customer": { "id": "cst_..." }

The field is populated on every GET, list, and POST/PATCH response, and on every v1 webhook payload. Dereference the customer by id to read their name, status, and endorsements; names are not denormalized onto the parent resources. This resolves the customer in one shape across every resource that references one.

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 `failure` object describes the cause: a `code`, a fixed `message`, and `retryable`.

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 as entries in the pricing.fees array with type: "developer", carrying the amount, asset, and side of the fee.

Timestamps

Every date-time rendered on these resources (and on their v1 webhook payloads) is UTC with three-digit millisecond precision, for example 2026-10-16T10:35:00.123Z. Parse the value with any ISO 8601 parser; do not depend on a fixed character count.

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 a transfer	`GET /transfers/{transferId}`

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

​Pricing

​Instrument shape

​Owner, precursor, and payout origin

​Rendering an instrument

​Bank memo

​Transfers and rail tracking

​Customer reference

​Transaction statuses

​Developer fees

​Timestamps

​Key operations

​Related

Direction (`sourceToDestination`)

Two-step flow

Quote object

Pricing

Instrument shape

Owner, precursor, and payout origin

Rendering an instrument

Bank memo

Transfers and rail tracking

Customer reference

Transaction statuses

Developer fees

Timestamps

Key operations

Related