XKOVA Docs
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 resolve a ramp profile per call. The default sandbox profile is a
simulated conversion partner; the X-Ramp-Profile header selects a different one. Against the
simulated partner, the X-Sandbox-Scenario header forces the 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. |
Combining X-Sandbox-Scenario with a non-simulated profile is rejected with a validation
error rather than silently ignored.
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 outcome, the HTTP status, and the error code each value produces.
| Header value | Outcome | Status | Error code |
|---|---|---|---|
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 in the awaiting_institution_credit state and never settles. | 202
on create; awaiting_institution_credit surfaces as a 202 visibility
signal | awaiting_institution_credit |
x-partner-outage | Every call touching the partner fails, modeling a full provider outage. | 503, retryable, honors the Retry-After
header | x_partner_outage |
The published error catalog additionally defines sandbox_scenario_triggered
(503, retryable) as a generic sandbox test signal that carries the triggering scenario
name in its details.scenario field.
The faucet: real testnet funds
Funding with X-Ramp-Profile: faucet mints real testnet USDC on Avalanche Fuji to the
destination wallet and settles synchronously in one on-chain transaction, so downstream flows (payments,
distributions, treasury) run against genuine on-chain balances. The faucet is capped per destination
wallet per day; exceeding the cap returns a clear error.
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.
Related
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.