Simulate a transaction terminal outcome (sandbox only)
Requests a sandbox terminal transition for the transaction. outcome is completed or failed; the transaction type decides whether its current phase can accept that terminal outcome. For withdrawals, outcome: "failed" can run as soon as POST /v2/payouts accepts the payout: before any transfer is sent the payout is cancelled (transaction.cancelled), after that the transfer in flight fails (transaction.failed); outcome: "completed" requires a transfer in flight. While the payout is in an in-progress phase with no transfer reference this endpoint can safely drive, neither outcome is applied and it returns 422 SANDBOX_TRANSACTION_NOT_FORCE_TERMINAL_READY. A retry clears that once a reference is recorded; a payout that keeps refusing should be read with GET /v2/transactions/{id} for its current state rather than retried indefinitely. For deposits, outcome: "completed" supplies default sender information when needed and approves pending compliance review; an existing AML rejection cannot be overridden. outcome: "failed" freezes the received funds and reports the public failed status. For ONRAMP / OFFRAMP, outcome: "completed" requires the conversion to have delivered funds to the destination — before that it returns 422 SANDBOX_TRANSACTION_NOT_FORCE_TERMINAL_READY; use outcome: "failed" to exit an earlier state. The transaction publishes the matching public event (transaction.completed / transaction.failed for withdrawals and deposits; order.succeeded / order.failed for ONRAMP / OFFRAMP) with the same shape it would in production, and the matching terminal status is recorded atomically. utr (only meaningful on completed) is the synthetic settlement reference for withdrawals; it defaults to sandbox-utr-<transactionId> when omitted. A withdrawal whose simulated bank already settled the transfer keeps the answer the bank reported, so utr and reason are ignored there. Deposits retain their original detection reference. A delivered ONRAMP / OFFRAMP already carries the settlement reference its stand-in provider reported, so utr and reason are ignored there. reason defaults to a generic sandbox-driven sentinel. For withdrawals and conversions, failed releases reserved funds and reverses booked transfers. Supported types today: WITHDRAWAL, ONRAMP, OFFRAMP, DEPOSIT. Calls against INTERNAL_TRANSFER return 422 SANDBOX_TRANSACTION_TYPE_NOT_SIMULATABLE. Replays (caller asks outcome: "completed" against a transaction already settled failed, or vice versa) return the Transaction at its actual terminal state, with status reflecting reality, not the verb the caller used; a replay is a pure read and does not disturb settlement work still finishing (such as fee collection). A 200 response always carries the transaction at a terminal status (completed / failed / cancelled); the endpoint waits for the terminal state to be recorded before responding. In the rare case it has not been recorded within the wait budget, it returns 503 SERVICE_UNAVAILABLE rather than a still-processing body, so retry the read (GET /v2/transactions/{id}) or the call. A payout parked at a review cannot be forced to a terminal state while the review is open, so it returns 422 SANDBOX_TRANSACTION_NOT_FORCE_TERMINAL_READY — call POST /v2/sandbox/payouts/{id}/simulate-review-approve (or simulate-review-reject) first.
Authorizations
Path Parameters
"txn_1A2b3C4d5E6f7G8h9I0jKl"
Body
completed, failed Settlement reference (UTR / on-chain tx hash) attached to the synthetic transaction.completed event. Only meaningful when outcome is completed. Defaults to sandbox-utr-<transactionId> when omitted.
1 - 120Free-text reason persisted as the transaction's failure / completion reason, which operators see. The client's failureMessage carries the standard text for the failure code, as in production. Defaults to a generic sandbox-driven sentinel when omitted.
1 - 500Response
The transaction at its terminal state
Client-facing view of an outbound withdrawal (debit out of a customer VA/wallet).
^txn_[0-9A-Za-z]{22}$^cus_[0-9A-Za-z]{22}$pending, processing, completed, failed, cancelled One side (source or destination) of a transaction. Discriminated by type.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
One side (source or destination) of a transaction. Discriminated by type.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
True when at least one published (non-draft, non-cancelled) RFI targets this transaction. Always present; derived at read time, no stored column.
withdrawal Whether this payout is eligible for POST /v2/payouts/{id}/cancel. Always present, derived at read time. It is false at a terminal status, and false once the payout is dispatched for settlement: the bank has answered its submit, or its on-chain send started. Eligibility is not a guarantee that the next cancel succeeds: while the payout starts up, a cancel can answer 409 PAYOUT_CANCEL_IN_PROGRESS although cancellable is true — retry shortly — and a payout that moves on between the read and the cancel answers 409 PAYOUT_NOT_CANCELLABLE. That includes a fiat payout whose submit is still waiting for the bank's answer: its cancel already answers 409 while cancellable still reads true.
Display name of the customer that owns the transaction: business legal name or individual full name. Same value on the transactions and payouts reads for the same row. Omitted when the customer's identity record hasn't resolved a name yet; per the public omit-don't-null convention, absence is never surfaced as null.
Client-supplied reference, unique per resource within your organization. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces.
^[A-Za-z0-9_\-:.]{1,255}$Progress signal for a non-terminal transaction, informational only — it does not replace requiresUserSignature, hasRfi, or failureCode for deciding whether your integration needs to act. awaiting_signature: waiting on the required transaction signature (see requiresUserSignature). awaiting_customer_action: further input is needed before the transaction can go on. Read hasRfi to learn where the ask is: true means a request for information holds the answer — rfiId names it, and GET /v2/rfis/{id} carries what to send; false means the matching event carries the detail (e.g. transaction.awaiting_sender_information). under_review: compliance, document, or verification review of something already submitted is in progress — usually no action needed; check hasRfi if unsure. settling: funds movement or settlement is in progress, no customer action required — covers long-lived fiat rails like SWIFT that legitimately take days as well as any other non-blocked in-flight state. Omitted once status reaches a terminal value (completed / failed / cancelled). The set of values may grow over time — treat unrecognized values the same as processing.
awaiting_signature, awaiting_customer_action, under_review, settling ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
user_signature_timeout, user_signature_expired, user_signature_declined, user_signature_rejected_by_provider, crypto_wallet_misconfigured, compliance_hold, compliance_review_rejected, compliance_rejected, returned_by_sender, rail_policy_rejected, insufficient_funds, insufficient_funds_at_settle, rail_unavailable, sender_info_timeout, travel_rule_rejected, provider_rejected, chain_broadcast_failed, roster_changed, insufficient_onchain_balance, source_account_unavailable Conduit's own wording for failureCode: the public error catalog text for the code, or the generic failure text when there is no code. The same text as failureMessage on the transaction.failed webhook. It never carries text from a bank, a chain or a sandbox simulator reason.
ISO-8601 timestamp when the transaction was cancelled. Present only on status: cancelled.
"2026-01-15T09:30:00.000Z"
Machine-readable cancellation reason. client_cancelled when the client called POST /v2/payouts/:id/cancel; expired is reserved. Omitted on non-cancelled rows. Mirrors orders.cancellationReason.
expired, client_cancelled ^ord_[0-9A-Za-z]{22}$The business purpose declared at payout creation. Drives compliance gating: intercompany requires a whitelisted recipient of the customer or its group; personal_transfer_of_funds requires the customer's own whitelisted account; prefunding requires a customer's issued account; other values require supporting documentation.
intercompany, treasury_management, payment_for_goods_or_services, payroll, investments, other, prefunding, purchase_of_goods, rent, loan_payment, personal_transfer_of_funds, gift, bill_payment, charity, tax_payment, person_to_person_transfer The customer's own words for the payment. Omitted when none was sent, and on the transaction list: read the single transaction to get it.
The most recently published such RFI — usually the one stage refers to, but a later unrelated RFI on the same transaction takes this slot instead. Omitted (never null) when hasRfi is false.
^rfi_[0-9A-Za-z]{22}$The free-text reference the payer supplied on the payout, fiat or crypto. On a transfer between two of the customer's own wallets the same value reads on both halves: the withdrawal that sent it and the deposit that credits it.
The UETR of the fiat leg — the ISO 20022 unique end-to-end transaction reference. Present whenever the payment carried one, including on a deposit whose source is still external_unknown because the sender has not resolved. The side that carries wire references repeats it — destination.swiftUetr on a payout, source.swiftUetr on a deposit — but not every side does, which is why it reads here as well. A Fedwire message carries a UETR too, so its presence does not mean the payment travelled on SWIFT. Omitted (never null) when the rail supplied none.
The return code the bank sent when it returned this transfer, for example the Nacha code R01 on an ACH return. Present only with failureCode: returned_by_sender, and only when the bank sent a Nacha return code. returnReason says why the bank returned the transfer. The bank's free-text return reason is never returned.
Why the bank returned this transfer, as a Conduit code. Present only with failureCode: returned_by_sender when Conduit recorded the bank's return, with or without returnCode. Absent on a return recorded before this field existed. account_closed: The bank account is closed. incorrect_account_number: The bank found no account with this account number. beneficiary_name_mismatch: The account holder's name does not match the name on the payment. payment_not_permitted: The bank does not permit this payment on the account. other: The bank returned the payment for a different reason or gave no reason. Contact support for details. The set of values can grow. Treat a value you do not recognise as other. The bank's free-text return reason is never sent.
account_closed, incorrect_account_number, beneficiary_name_mismatch, payment_not_permitted, other ISO-8601 timestamp when Conduit recorded the bank's return of this transfer. Present with failureCode: returned_by_sender when the return is recorded, with or without returnCode.
"2026-01-15T09:30:00.000Z"
The margin you declared on this payout, echoed back. Present when you declared one that came to at least one minor unit of the payout's asset. bps and flatAmount read back for the life of the payout, whatever becomes of it, so you can always confirm what you sent. What each payout accrued to you is answered by GET /v2/markup/statement-lines, where a reversal reads as a negative amount.
Position in the per-(wallet, chain) signing queue. Only waiting payouts (position ≥ 1) expose this field; the active/head payout omits it. Absent when the payout is not on the user-signature path or has reached a terminal status.
1 <= x <= 9007199254740991The payout this one replaces. Present when an operator re-sent a payout the receiving bank returned; the original transfer reads failed with failure code returned_by_sender.
^txn_[0-9A-Za-z]{22}$The supporting documents attached at creation, as sent on documents. Omitted when none were attached.
^doc_[0-9A-Za-z]{22}$