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, or crypto via a deposit address	OMS wallet or external wallet
`cryptoToFiatAccount`	OMS wallet, or crypto via a deposit address	Bank account or fiat wallet
`cryptoToCash`	OMS wallet	Cash pickup (early access)
`fiatAccountToCrypto`	Bank deposit via a virtual account	OMS wallet or external wallet
`fiatAccountToFiatAccount`	Bank deposit via a virtual account, or a fiat wallet	Bank account or fiat wallet
`cashToCrypto`	Cash, via a cash-in	OMS wallet or external 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: 30 seconds by default, configurable per project. To execute it, call POST /transactions with a body of { "quoteId": "qt_..." }. A quote that has expired returns 422 QuoteExpired, and one already used returns 422 QuoteConsumed; create a new quote in either case. In the quote request, set amount on exactly one side, source or destination; OMS calculates the other. See the send from a wallet guide for full requests. The quote step also validates that the customer holds the endorsements the requested instruments require. A customer without an active cryptoCustody endorsement on a flow that moves funds through an OMS custodial wallet gets 403 KYCRequired at POST /quotes, rather than at POST /transactions. Resolve the customer’s endorsements before quoting; see Endorsements.

Quote object

{
  "id": "qt_...",
  "object": "quote",
  "status": "open",
  "customerId": "cst_...",
  "customer": { "id": "cst_...", "name": "Jane Smith" },
  "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",
  "createdAt": "2026-10-16T10:34:30.000Z"
}

status is open while the pricing is locked, then accepted once a transaction is created from it, or expired. Unlike other resources, a quote carries both customerId and a customer summary with the customer’s name.

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"`	The side whose `amount` you set on the request. OMS calculated the other.

Every amount is a decimal string padded to the asset’s own precision, for example six decimals for usdc and two for usd. The same amount renders the same string 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, deposit address, virtual account, cash-in, external account, counterparty, 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 webhook payload. Dereference the customer by id to read their name, status, and endorsements; names are not copied onto these resources. Quotes are the exception: they carry customerId and a customer summary that includes the name.

Transaction statuses

Status	Meaning
`processing`	Executing. Funds are being pulled, converted, or paid out.
`awaitingAction`	Non-terminal. Blocked until something is resolved. When you must act, the `hold` object says what to do. Returns to `processing` once cleared.
`completed`	Funds delivered to the destination. A returned deposit can still move afterwards (see transaction lifecycle).
`failed`	Terminal for most transactions. A failed deposit can still settle on a late provider report, and a return to the sender can start after a failure. The `failure` object describes the cause: a `code`, a fixed `message`, and `retryable`.

Every transaction also carries a dotted subStatus (for example processing.fundsPulled) that refines its status. Tolerate sub-statuses you do not recognize by falling back to the part before the dot. See the transaction lifecycle for every sub-status. OMS fires transaction.created once and transaction.statusChanged on every status or sub-status change, so your handler branches on the payload’s status and subStatus fields. See Receiving webhooks to subscribe.

Developer fees

Developer fees are configured per project; the quote request has no fee field. They 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. Paginate with limit (default 50, maximum 100; values outside 1 to 100 are clamped), startingAfter, and endingBefore. Pass a page’s nextCursor as startingAfter to read the next page, or its previousCursor as endingBefore to read the previous one. Cursors are opaque; do not parse them.

POST /quotes and POST /transactions require an Idempotency-Key header. Use a stable key tied to your internal order ID so a retry after a network failure cannot execute twice. Reusing a key with a different body returns 422 IdempotencyKeyReuse.

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