> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> The core money movement operation in OMS: quote, then execute.

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](https://docs.polygon.technology/payments/guides/crypto-to-fiat.md) 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](https://docs.polygon.technology/payments/customers.md#endorsements).

## Quote object

```json theme={null}
{
  "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`, `gas`, `retailer`, and `exchange`; 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](#transfers-and-rail-tracking). |
| `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:

```json theme={null}
"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](https://docs.polygon.technology/payments/virtual-accounts.md) or [external account](https://docs.polygon.technology/payments/external-accounts.md) 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](https://docs.polygon.technology/payments/deposit-addresses.md), and the [virtual account](https://docs.polygon.technology/payments/virtual-accounts.md).

## 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:

```json theme={null}
"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`:

```json theme={null}
"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](https://docs.polygon.technology/payments/core-concepts/transaction-lifecycle.md#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:

```json theme={null}
"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](https://docs.polygon.technology/payments/core-concepts/transaction-lifecycle.md#failed-transactions-and-returns)). |
| `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](https://docs.polygon.technology/payments/core-concepts/transaction-lifecycle.md) 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](https://docs.polygon.technology/payments/guides/receiving-webhooks.md) 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.

> [!NOTE]
>
> `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`.

### Processing, unconfirmed, and failed outcomes on create

`POST /transactions` answers `201` with a `processing` transaction whenever the payout may still move the money. That includes a withdrawal whose provider send did not confirm, returned as `subStatus: processing.payoutUnconfirmed`. The next `transaction.statusChanged` event carries the outcome; no action is needed from you while the transaction is `processing`. Do not create another transaction for the same payout: a retry with the same `Idempotency-Key` replays this answer.

A `502` with a `failed` transaction means the payout failed. The cause may lie with the provider or with this service. Read `failure.retryable` on the transaction before retrying.

## Related

* [Fiat to crypto guide](https://docs.polygon.technology/payments/guides/fiat-to-crypto.md): cash-in and virtual-account funding
* [Send from a wallet guide](https://docs.polygon.technology/payments/guides/crypto-to-fiat.md): crypto sends and bank payouts
* [Bank transfers guide](https://docs.polygon.technology/payments/guides/bank-transfers.md): ACH and wire transfer details
