Deposits in sandbox

Fiat deposits on this page are simulated: the balance is credited synthetically, with no real banking connection or third-party vendor calls, and the outcome is driven by your request data (account-number suffixes or an explicit outcome field). Customer-wallet crypto deposits on supported chains run on a real public testnet and are not simulated — you fund a wallet by sending real testnet crypto to its address from a faucet, and it is detected automatically (Use a real testnet). Stellar is supported; a Tron wallet cannot receive here — Tron is excluded from the default claim, and even a wallet you claim for it explicitly cannot transact (422 CHAIN_NOT_SUPPORTED on any quote, order or payout). Deposit-funded orders must also receive real testnet transfers at their published funding address. See Sandbox overview for the full posture. This page covers three deposit types, one per fundable resource:

Fiat deposits land on a customer’s virtual account via a simulate endpoint. The deposit is ingested asynchronously; no bank transfer occurs.
Crypto deposits on supported chains land on a customer’s wallet from a real testnet faucet sent to the wallet’s address. The deposit goes through the same compliance screening and sender-information gate as any external deposit.
Deposit-funded order transfers land on the funding address the order publishes. The transfer is an ordinary deposit transaction you can read back. See Deposit-funded orders for the concept.

Use fiat deposits when testing order-funded flows (onramps, conversions). Use crypto deposits when testing the inbound wallet flow including compliance and Travel Rule sender-info scenarios. Send funds to the published address when an order does not debit a named wallet.

Prerequisites

Your organization’s sandbox API key, and an active customer. Set SANDBOX_API_KEY, CUSTOMER_ID, VA_ID (virtual account), and WALLET_ID in your shell.
For fiat: the virtual account must be active. Deposit in the currency it holds — USD on the sandbox accounts you get by default.
For crypto: the wallet must be active and have a deposit address.
Base URL: https://api.sandbox.conduit.financial.

The idempotency-key header is required on the POST endpoints that the API reference marks with it. A successful response is kept for 30 days — replay the same key to safely retry; use a fresh key for a new operation.

Fiat deposit — happy path

Inject a synthetic deposit into a customer’s virtual account, in the currency that account holds.

POST https://api.sandbox.conduit.financial/v2/sandbox/customers/{customerId}/virtual-accounts/{virtualAccountId}/deposits/simulate

Request body:

Field	Type	Required	Description
`assetAmount`	object	yes	`{ "code": "USD", "amount": "1000.00" }`. `code` is any fiat currency Conduit supports and must match the virtual account’s own currency — a mismatch returns `422 VIRTUAL_ACCOUNT_ASSET_MISMATCH`. `amount` is a decimal string at that currency’s precision: two decimals for USD or EUR, none for a zero-decimal currency such as JPY (`"5000"`). Do not send `chain` — that is for crypto deposits.
`outcome`	enum	no	`"completed"` (default), `"frozen"`, or `"returned"`. `frozen` parks the deposit in a sanctions-freeze terminal state. `returned` parks it in a compliance-return terminal state. Equivalent to the `senderInfo.accountNumber` suffix catalog but explicit; takes precedence when both are set.
`rail`	string	no	`"ach"`, `"fedwire"`, `"rtp"`, `"swift"`, `"sepa"`, `"faster_payments"`, or `"chaps"`. Sets the rail the deposit reports as `source.rail` and the synthetic references it carries: `ach` an `achTraceNumber`, `fedwire` a `fedwireImad` and `fedwireOmad`, `rtp` an `rtpTransactionId`, `swift` a `swiftUetr`; `sepa`, `faster_payments` and `chaps` carry none. The references are deterministic for a given deposit, and their date is `detectedAt`’s UTC day when you set it, else the UTC day of the simulation. `rail` also picks the `wireReceive` arm, as before: a `faster_payments` or `chaps` simulation into a GBP account reaches the `uk` arm of `virtual_account.wireReceive` the way a live credit does, and an account with a routing number reports the `us` arm on every rail, `swift` included. It has no default and it does not change how the deposit settles.
`omitWireReferences`	boolean	no	`true` sends the deposit with no wire references. A production bank does not guarantee a reference on every credit, so use it to test your reconciliation when one is missing. Default `false`.
`senderInfo`	object	no	Synthetic sender details (`name`, `accountNumber`, `routingNumber`, `sortCode`, `iban`, `bic`, `country`). Pass `senderInfo.accountNumber` ending in a fiat compliance suffix to force a compliance outcome (see Suffix catalog).
`externalReference`	string	no	Custom reference for the synthetic transfer. It is scoped to your organization, so another organization can use the same value. The response returns an opaque `sandbox_…` reference derived from it.

References reach the deposit’s source only when the deposit is external_bank_inbound, which requires at least one senderInfo field to be set; without senderInfo the deposit is external_unknown, which carries no references in source. Replaying the same externalReference returns the first deposit, references included, whatever rail or omitWireReferences the replay sends.

curl -X POST "https://api.sandbox.conduit.financial/v2/sandbox/customers/${CUSTOMER_ID}/virtual-accounts/${VA_ID}/deposits/simulate" \
  -H "x-api-key: ${SANDBOX_API_KEY}" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "assetAmount": { "code": "USD", "amount": "1000.00" }
  }'

const res = await fetch(
  `${process.env.SANDBOX_HOST}/v2/sandbox/customers/${customerId}/virtual-accounts/${vaId}/deposits/simulate`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.SANDBOX_API_KEY!,
      "idempotency-key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ assetAmount: { code: "USD", amount: "1000.00" } }),
  },
);
const { externalReference } = await res.json();
// 202 acknowledgement: { externalReference: "sandbox_..." } — the reference the
// deposit is detected under. Resolve the deposit itself with:
//   GET /v2/transactions?type=deposit&externalReference=${externalReference}

import httpx, os, uuid

r = httpx.post(
    f"{os.environ['SANDBOX_HOST']}/v2/sandbox/customers/{customer_id}/virtual-accounts/{va_id}/deposits/simulate",
    headers={
        "x-api-key": os.environ["SANDBOX_API_KEY"],
        "idempotency-key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={"assetAmount": {"code": "USD", "amount": "1000.00"}},
)
external_reference = r.json()["externalReference"]
# 202 acknowledgement: {"externalReference": "sandbox_..."} — resolve the deposit with
#   GET /v2/transactions?type=deposit&externalReference=<external_reference>

202 Accepted means the deposit was accepted for processing. Processing is asynchronous — exactly as it is in production, where no endpoint creates a deposit synchronously — so the response body carries only externalReference: the sandbox_… reference the deposit is detected under. It is derived from your organization and the reference you sent, or from the deposit details when you omitted it. Send it back verbatim: the acknowledged reference — not your original string — is the one to filter on. Observe the deposit through the transaction.created webhook, or read it back with GET /v2/transactions?type=deposit&externalReference=…. Re-sending the same externalReference from your organization re-acknowledges the existing deposit rather than creating a duplicate. The customer’s USD balance updates within a few seconds, and your webhook endpoint receives transaction.completed.

Fiat deposit — compliance failure paths

Fiat deposits use the same suffix protocol as crypto deposits, matched against the last 8 digits of the sender’s bank account number (non-digit characters stripped). Pass a senderInfo.accountNumber ending in a documented suffix to force a specific compliance outcome. The deposit-specific suffix values are listed in the Suffix catalog below. For the consolidated suffix table across deposits and withdrawals, see Scenario suffixes.

Crypto deposits

Send real testnet funds to the customer wallet address or to the funding address in a deposit-funded order’s depositInstructions. The sandbox detects the transfer and credits it after chain finality and compliance checks. Use a supported chain and a testnet faucet. Crypto deposit simulation endpoints are unavailable. Watch transaction.created or query GET /v2/transactions?type=deposit&chain=<chain>&txHash=<transfer-hash>. For a deposit-funded order, register the sending address first. Send the order’s totalDebit to the published funding address before lockExpiresAt. A transfer from an unregistered address is returned. See Deposit-funded orders.

Resolving a held funding transfer

When a transfer into a funding address is held for compliance review, resolve it on the order: POST https://api.sandbox.conduit.financial/v2/sandbox/orders/{orderId}/deposits/simulate/compliance-decision

curl -X POST "https://api.sandbox.conduit.financial/v2/sandbox/orders/${ORDER_ID}/deposits/simulate/compliance-decision" \
  -H "x-api-key: ${SANDBOX_API_KEY}" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "reject" }'

reject holds the funds permanently, with no webhook for the loss — they are never returned to the sender and never fund the order. The transfer’s own transaction reads failed with no failureCode, and once lockExpiresAt has passed, the order cancels at the next sweep with order.cancelled. approve releases the hold and the funds go on to fund the order, which works even once lockExpiresAt has passed — the transfer arrived in time, so the order is still pending waiting on this decision; it is available only while the review is still open, and returns 409 once the review has already rejected the transfer — a rejected review can only be rejected. 202 Accepted returns the order as of the call. 404 SANDBOX_ORDER_NO_PARKED_FUNDING means nothing is currently held for review. For a full walkthrough — register the sender, create the order, read the address, fund it, watch it auto-execute — see Offramps.

Sender information for a real crypto deposit

When a real transfer needs sender information, the deposit waits at the sender-information gate. Send the originator details to POST /v2/transactions/{depositId}/sender-information while it is pending, with register: true to register the sending address so its later deposits skip the gate. The sandbox deadline is about 10 minutes after Conduit detects the deposit. Use the deadlineAt value from the webhook. After it, the deposit stays held. See Use a real testnet.

Suffix catalog

Suffixes are matched against the last 8 characters of the source identifier:

Crypto deposits: last 8 hex characters of sourceAddress (case-insensitive on EVM; Base58 verbatim on Solana). A testnet faucet is the source of a faucet-funded deposit, so the faucet’s address — not a wallet you control — is what gets matched; a faucet deposit cannot be made to match a suffix. To force a scenario, send from a wallet you control whose address ends in the suffix, or use a reserved originator name (below).
Fiat deposits: last 8 digits of senderInfo.accountNumber (non-digit characters stripped before matching).

Addresses and account numbers not matching any suffix take the happy path: compliance approved, deposit completes.

Crypto deposit suffixes (matched on `sourceAddress`)

Suffix	Scenario	failureCode
`DEAA49F1`	compliance approved (explicit happy path)	—
`DEAA8E51` / `DEAA5A4D`	compliance non-CLEAR (high-risk or sanctions) — deposit holds for a compliance decision, then freezes on reject †	`compliance_hold`
`DE5E11F1`	Sender-information gate required — deposit parks; it stays held after the ~10 min sandbox deadline	—

Reserved originator names

When you cannot control the source address — a faucet deposit, for example — submit sender information with entityType: "BUSINESS" and one of these names as originator.legalName (plus a country) to force the matching compliance scenario instead:

Originator legal name	Scenario	failureCode
`SANCTIONED SENDER LLC`	compliance non-CLEAR (sanctions) — deposit holds for a compliance decision, then freezes on reject †	`compliance_hold`
`BLOCKED SENDER LLC`	compliance non-CLEAR (high-risk) — deposit holds for a compliance decision, then freezes on reject †	`compliance_hold`
`RISKY SENDER LLC`	compliance elevated risk — routes approved at current threshold; no observable difference	—
`PENDING SENDER LLC`	compliance review pending — deposit pauses for compliance review until an operator decision	—

Fiat deposit suffixes (matched on `senderInfo.accountNumber` digits)

Suffix	Scenario	failureCode
`95000000`	compliance approved (explicit happy path)	—
`95009001` / `95009002`	compliance non-CLEAR (high-risk or sanctions) — deposit holds for a compliance decision, then freezes on reject †	`compliance_hold`

† On deposits, a non-CLEAR compliance classification (high-risk or sanctions match) holds the deposit rather than failing it outright: it stays pending, uncredited, until the decision lands. Resolve it in sandbox with POST https://api.sandbox.conduit.financial/v2/sandbox/transactions/{depositId}/simulate/compliance-decision and { "outcome": "reject" }, which freezes it with the public failure code compliance_hold; approve is not available on an already-rejected review. If the deposit is the source funding event for the oldest pending autoExecute: true ONRAMP order it could cover, that order also fails with reasonCode: "provider_rejected".

Webhook events

Event	When it fires
`transaction.created`	After the real transfer is detected or a fiat simulation is accepted
`transaction.awaiting_sender_information`	Deposit parks at the sender-information gate. Into a customer wallet, three drivers: the sender is not registered (any amount), the amount is 10,000 units or more (even from a registered sender), or `sourceAddress` ends in `DE5E11F1`. Customer wallets only. A transfer into the funding address of a deposit-funded order never parks and never emits this event: an unregistered sender, or a `sourceAddress` ending in `DE5E11F1`, is returned as a `deposit_return`. See Use a real testnet.
`transaction.completed`	Deposit reaches terminal `completed` state
`transaction.failed`	Deposit reaches terminal `failed` state (compliance non-CLEAR); fiat source deposits can also fail a matching amount-covered pending auto-execute ONRAMP order

transaction.failed payloads carry a failureCode when the cause is actionable. transaction.awaiting_sender_information includes daysRemaining and deadlineAt. The sandbox deadline is compressed to ~10 minutes, so the past-deadline path is fast to test: the deposit stays held.

Errors

See Errors for the full catalog. Deposit-relevant failure codes:

VIRTUAL_ACCOUNT_ASSET_MISMATCH (422) — the fiat simulate body’s assetAmount.code is not the currency the virtual account holds. Fetch the virtual account to read its currency, then resend with that code.
compliance_hold — compliance screening returned a non-CLEAR decision (high-risk or sanctions match); the deposit is frozen and cannot be credited.
returned_by_sender — the inbound transfer was returned by the originating institution before it could be credited. Sandbox triggers this branch via the outcome: "returned" field on the deposit simulate endpoint.
sender_info_timeout — legacy: Conduit no longer sets it on new deposits. An older deposit carries it when its sender-information deadline passed.

Diagrams

Crypto deposit state machine

Sender-information gate — timeline

Sandbox overview — full sandbox posture and what’s mocked
Scenario suffixes — the consolidated compliance magic-suffix catalog for deposits and withdrawals
Withdrawals — crypto withdrawal lifecycle and cosign flows
Virtual Accounts — virtual account model and deposit instructions

Get started

Transaction guides

References

Scenario libraries

Prerequisites

Fiat deposit — happy path

Fiat deposit — compliance failure paths

Crypto deposits

Resolving a held funding transfer

Sender information for a real crypto deposit

Suffix catalog

Crypto deposit suffixes (matched on `sourceAddress`)

Reserved originator names

Fiat deposit suffixes (matched on `senderInfo.accountNumber` digits)

Webhook events

Errors

Diagrams

Crypto deposit state machine

Sender-information gate — timeline

​Prerequisites

​Fiat deposit — happy path

​Fiat deposit — compliance failure paths

​Crypto deposits

​Resolving a held funding transfer

​Sender information for a real crypto deposit

​Suffix catalog

​Crypto deposit suffixes (matched on sourceAddress)

​Reserved originator names

​Fiat deposit suffixes (matched on senderInfo.accountNumber digits)

​Webhook events

​Errors

​Diagrams

​Crypto deposit state machine

​Sender-information gate — timeline

​Related pages

Prerequisites

Fiat deposit — happy path

Fiat deposit — compliance failure paths

Crypto deposits

Resolving a held funding transfer

Sender information for a real crypto deposit

Suffix catalog

Crypto deposit suffixes (matched on `sourceAddress`)

Reserved originator names

Fiat deposit suffixes (matched on `senderInfo.accountNumber` digits)

Webhook events

Errors

Diagrams

Crypto deposit state machine

Sender-information gate — timeline

Related pages