POpolygon-technology
Transaction

Execute a transaction (send)

Executes a transfer by accepting an open quote. Reference the quote by its ID; OMS pulls funds from the quote's source and delivers them to its destination. Pass an Idempotency-Key header to safely retry without sending twice.

post/transactions

Request

Headers

Idempotency-Keystring required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Request body

quoteIdstring required

The quote to accept (qt_ prefix). Must be open with non-expired pricing.

deviceFingerprintstring

Device fingerprint of the end user, used for risk screening.

externalAccountIdstring

The external-account id of the debit card funding (buy) or receiving (sell) this transaction. OMS resolves it to the underlying card provider identifier.

paymentMethodIdstring

Deprecated for cards: raw card provider payment method id. Use externalAccountId instead.

partnerTransactionIdinteger

Your own transaction reference, for reconciliation.

sourceWalletAddressstring

Expected sending address for crypto-funded transactions.

tagsstring

Free-form labels attached to the transaction.

webSessionIdstring

Risk/session identifier from the client SDK.

metadataobject

Free-form key-value pairs stored on the resource and echoed back on reads.

Example request

{
  "quoteId": "qt_0gq9aesz4wb5etdv88z1j61qcm",
  "metadata": {
    "orderId": "order_12345"
  }
}

Response

The request has succeeded and a new resource has been created as a result.

idstring required

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

object'transaction' required

Resource type discriminator. Always "transaction".

sourceToDestination'cryptoToCrypto' | 'cryptoToCash' | 'cryptoToFiatAccount' | 'cashToCrypto' | 'fiatAccountToCrypto' | 'fiatAccountToFiatAccount'

Composite of source and destination instrument categories, inferred from each side. The cash corridors (cryptoToCash, cashToCrypto) are derived from a cash-pickup destination / cash-in source respectively; the rest map straight from the internal corridor type.

status'processing' | 'awaitingAction' | 'completed' | 'failed' required

Lifecycle of a transaction. processing: funds in motion. awaitingAction: non-terminal, blocked on developer/upstream/compliance (see hold); returns to processing once cleared. completed: delivered. failed: terminal failure.

subStatus'processing.fundsPulled' | 'processing.cashPickupReady' | 'processing.underReview' | 'completed.cashPickupCollected' | 'completed.cashPickupExpired' | 'awaitingAction.awaitingSenderAttribution' | 'awaitingAction.depositAddressFrozen' | 'awaitingAction.depositAddressInactive' | 'failed.attributionTimeout' | 'failed.depositAddressFrozenTimeout' | 'failed.depositAddressInactiveTimeout' | 'failed.depositAddressClosed' | 'processing.awaitingCryptoOut' | 'processing.cryptoOut' | 'processing.awaitingFiatOut' | 'processing.fiatOut' | 'processing.inboundPending' | 'processing.inboundProcessing' | 'failed.inboundFailed' | 'failed.returnPending' | 'failed.returnStarted' | 'failed.returnComplete' | 'failed.returnFailed'

Finer-grained, status-scoped sub-state of a transaction (v0.10). Each member is namespaced by its parent status (e.g. processing.cashPickupReady). Largely a closed set aligned to the v0.11 spec; the inbound-leg lifecycle values (processing.inboundPending, processing.inboundProcessing, failed.inboundFailed) are deliberate extensions mirroring the already-exposed outbound states, while the failed.return* family conforms to the spec. Absent when there is no meaningful sub-state.

(2026-07-17, product-agreed vocabulary): failed.returned is RETIRED - its meaning is absorbed by failed.returnComplete, which now covers both the OPS-triggered crypto send-back lane and the vendor-side ACH/WIRE bounce + clawback lane (isReturnedProviderStatus) under one wire value. failed.refundPending is DELIBERATELY NOT added - product agreed to collapse the OMS-wallet-refund and crypto-return status families into one (this failed.return* set); a committed OMS spec snapshot still lists failed.refundPending separately, which is a documented divergence pending that spec's revision.

customerIdstring required

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

estimatedArrivalstring date-time

Estimated completion time. Present when the destination rail has a predictable settlement time (e.g. bank payouts and some crypto legs); null otherwise.

metadataobject

Free-form key-value pairs supplied at creation or update.

createdAtstring date-time

When the transaction was created.

updatedAtstring date-time

When the transaction was last updated.

expiresAtstring date-time

Expiry of the transaction's actionable window: present on auto-created transactions and on cash payouts (the pickup-code expiry), and retained after completion for audit. Null for other quote-initiated transactions.

projectIdstring

Opaque OMSX project ID, e.g. prj_01kpxxa7esk9a.

Changes

No recorded changes to this operation across all 1 revision of this API.