Simulate an inbound payment event

Authorizations

x-api-key

string

header

required

Headers

x-idempotency-key

string<uuid>

required

Unique key to ensure request idempotency. If the same key is used within a certain time window, the original response will be returned instead of executing the request again.

X-Sandbox-Scenario

enum<string>

Sandbox-only. Applies a preset failure or behavior mode for the request, selecting a coherent combination of error step, status, and message. The full set of scenarios is also exposed dynamically via GET /sandbox/scenarios along with descriptions and per-rail applicability. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Available options:

happy_path,

delayed_settlement,

insufficient_funds,

compliance_block,

invalid_account,

provider_maintenance,

network_congestion,

kyb_manual_review,

kyb_rejected,

kyb_expired,

network_timeout,

intermittent_errors,

account_frozen,

document_expired,

invalid_swift

Example:

"insufficient_funds"

X-Sandbox-Error-Step

enum<string>

Sandbox-only. Names the pipeline step at which the injected error fires. Pair with X-Sandbox-Error-Status and (optionally) X-Sandbox-Error-Message to drive a deterministic failure mode at a known point in the request lifecycle. Values longer than 100 characters are ignored. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Available options:

transaction_processing,

compliance_check,

account_validation,

provider_call,

kyb_submission,

kyb_approval,

network_call

Maximum string length: 100

Example:

"provider_call"

X-Sandbox-Error-Status

integer

Sandbox-only. Sets the HTTP status code returned when the sandbox injects an error at the configured step (see X-Sandbox-Error-Step). Must be a valid HTTP status code in the range 100-599; values outside that range are ignored. Status codes >= 400 cause the request to short-circuit immediately with a structured error response. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Required range: 100 <= x <= 599

Example:

503

X-Sandbox-Error-Message

string

Sandbox-only. Sets the human-readable message field of the injected sandbox error response. Truncated values longer than 500 characters are ignored. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Maximum string length: 500

Example:

"Provider temporarily unavailable for maintenance."

X-Sandbox-Instant-Completion

boolean

default:false

Sandbox-only. When true, asynchronous simulation flows complete immediately rather than progressing through their normal timed states. Useful for fast end-to-end test runs that do not need to exercise intermediate webhook events. Accepts true/false (also 1/0, yes/no); other values are treated as false. Effective only on https://api.platform.sandbox.dakota.xyz. Ignored in production.

Example:

true

Body

application/json

simulation_id

string

required

Unique ID for this simulation (used for idempotency)

Required string length: 1 - 128

Example:

"sim_01H..."

type

enum<string>

required

Payment rail and direction. Use the fedwire_* values for Fedwire flows; the wire_* values are accepted as legacy aliases for backwards compatibility and may be removed in a future major version.

Available options:

ach_inbound,

fedwire_inbound,

wire_inbound,

crypto_inbound,

ach_outbound_returned,

ach_outbound_failed,

fedwire_outbound_returned,

wire_outbound_returned,

fedwire_outbound_failed,

wire_outbound_failed,

ach_outbound_settled,

ach_outbound_rejected,

fedwire_outbound_settled,

wire_outbound_settled,

fedwire_outbound_rejected,

wire_outbound_rejected,

ach_reversal,

fedwire_reversal,

wire_reversal

Example:

"ach_inbound"

amount

string

required

Amount as a decimal string

Example:

"100.00"

currency

string

required

Currency code

Example:

"USD"

account_id

string

Platform account ID of the target onramp/offramp auto account. Required for ach_inbound and fedwire_inbound. Ignored for other type values.

Example:

"acc_123"

wallet_address

string

The on-chain wallet address returned by POST /wallets (see the address field in the response). Required for crypto_inbound. Ignored for other types.

Example:

"0x165cd37b4c644c2921454429e7f9358d18a45e14"

wallet_id

string

deprecated

Legacy alias for wallet_address. Prefer wallet_address — this field is accepted for backwards compatibility and may be removed in a future major version.

Example:

"0x165cd37b4c644c2921454429e7f9358d18a45e14"

one_off_transaction_id

string

The one-off transaction ID returned by POST /transactions/one-off (see the id field in the response). Required for outbound types (ach_outbound_*, fedwire_outbound_*, *_reversal). Ignored for inbound types.

Example:

"2NfHrqBHb3cTfLVkFSGmHZqdDQ7"

movement_id

string

deprecated

Legacy alias for one_off_transaction_id. Prefer one_off_transaction_id — this field is accepted for backwards compatibility and may be removed in a future major version.

Example:

"2NfHrqBHb3cTfLVkFSGmHZqdDQ7"

scenario

string

Simulation scenario. Defaults to success_immediate.

success_immediate: callbacks fire immediately
success_delayed: callbacks fire after delay_seconds (default 30s) For crypto_inbound: success_immediate | wrong_chain | unsupported_token | address_mismatch | partial_crypto | unconfirmed

Example:

"success_immediate"

partial_amount

string

Amount actually received (for crypto_inbound with scenario=partial_crypto only). Must be a valid decimal less than amount.

Example:

"50.00"

delay_seconds

integer

Delay in seconds for success_delayed scenario (1-86400)

Required range: 1 <= x <= 86400

Example:

30

trace_id

string

Optional trace ID for correlation

Response

Simulation accepted

simulation_id

string

state

enum<string>

State of a sandbox simulation after submission.

Available options:

accepted

trace_id

string