Sandbox Scenarios

Your integration's hardest code paths are the failure paths, and the sandbox lets you force every one of them deterministically: a screening block, a compliance review, a failed verification, a stalled ramp, a partner outage, a held approval. Every lever on this page works only in sandbox; production rejects them outright.

Screening: allow, review, block

Value-moving create calls accept an optional sandbox_scenario body field with the value allow, review, or block. The compliance pipeline runs exactly as it does in production; only the screening decision is forced.

Value	What happens
`allow`	The screen passes and the payment proceeds to signing.
`review`	The payment holds in a pending compliance state and a compliance case opens for an operator to triage in the console, exactly the flow your team will work in production.
`block`	The screen blocks (a sanctions-style hit) and the payment lands in the terminal `blocked` state (a compliance block). No value moves and nothing reaches the chain. The granular `status` is `blocked` while `status_canonical` rolls up to `failed`, so failure handling that keys on `status === 'failed'` will not catch compliance blocks.

The field is accepted on payment create, escrow create, and the gasless token-transfer operations. Sending it in production returns a validation error, so a copy-pasted test request can never influence a live compliance decision.

Verification: pass, fail, manual review

Creating a verification session returns a hosted flow URL. In sandbox that flow is a simulator offering named demo subjects, each with a fixed outcome, so you can drive every verdict end to end, including the signed webhook back to XKOVA and the resulting status change on the account holder:

Flow	Subject	Outcome
KYC	`avery-approved`	Verified.
KYC	`riley-rejected`	Rejected (unreadable document).
KYC	`morgan-manual`	Manual review (name mismatch); the subject reads in progress until an operator decides.
KYB	`acme-llc`	Verified.
KYB	`shell-co`	Rejected (sanctions hit).
KYB	`gamma-partners`	Manual review (incomplete documents).

Ramps: stalls, rejections, outages

Funding and off-ramp requests use the workspace's conversion partner. Sandbox workspaces are automatically bound to XKOVA's sandbox conversion partner, with no profile header or partner setup. The X-Sandbox-Scenario header forces that partner's behavior:

Scenario	What happens
absent or `success`	The happy path. A mint settles synchronously; a burn walks submitted, pending settlement, fiat in flight, settled on short timers so you can watch each state.
`scenario-a-pre-issuance-fail`	The partner rejects the request synchronously with a compliance block, before any value moves.
`scenario-b-awaiting-institution-credit`	An off-ramp stalls at fiat in flight and never settles, modeling a bank credit that does not post. Use it to test your stuck-request handling.
`x-partner-outage`	Every call touching the partner returns a partner outage error, modeling a full provider outage.

Production rejects X-Sandbox-Scenario; a sandbox request never lets the caller select a production partner.

Scenario Outcomes by Value

Each X-Sandbox-Scenario value drives a distinct, deterministic outcome. Values are case insensitive, and an unrecognized value is rejected with a validation error rather than silently ignored. The table names the observable outcome and HTTP status each value produces.

Header value	Outcome	Status	Customer result
absent or `success`	The happy path. A funding request accepts and settles; an off-ramp walks its states through to settled.	`202` on create	none
`scenario-a-pre-issuance-fail`	A funding request is rejected synchronously with a compliance block, before any value moves.	`403`	`compliance_blocked`
`scenario-b-awaiting-institution-credit`	An off-ramp is accepted, then stalls while waiting for institution credit and never settles.	`202` on create and on subsequent visibility checks	Accepted but intentionally not settled
`x-partner-outage`	Every call touching the partner fails, modeling a full provider outage.	`503`, retryable, honors the `Retry-After` header	Retryable provider-unavailable response

Testnet assets and funding

Every supported testnet exposes two distinct six-decimal assets:

Asset	Issuer	How to acquire it
`dUSDC`	XKOVA demo token	Create a normal funding request with `stablecoin: "dUSDC"`, or call the chain's public demo-faucet contract directly. The sandbox conversion partner mints real on-chain tokens and observes the normal request lifecycle.
`USDC`	Circle Testnet	Use Circle's faucet or a pre-funded test wallet. XKOVA lists the token as supported but cannot mint it. Verify the exact chain address against Circle's canonical USDC contract list.

The sandbox partner accepts only dUSDC. It never wraps or substitutes Circle Testnet USDC. Select the exact asset by chain, symbol, and contract address from GET /v1/workspace-tokens; the dUSDC row also returns its exact sandbox_faucet_contract_ref. The partner's dUSDC funding is capped per destination wallet per day; exceeding the cap returns sandbox_ramp_daily_cap_exceeded.

Held approvals

No lever needed: every fresh workspace seeds owner-approval requirements on its six highest impact actions, so performing one (creating the first API key, committing the authorization policy, changing a treasury signer, adding a counterparty) returns a held response you can drive through the attest and re-submit flow. See Policies and Quorum Governance for the full journey.

For the base sandbox setup, see the Quickstart. For what screening and verification enforce, see Screening and Identity Verification. For ramp mechanics, see Funding and Off-ramp.

Was this helpful?