Sandbox testing and simulation labels

Bastion provides simulation labels that your team can use to simulate specific product flows in sandbox. Use simulation labels during your testing efforts and UAT integration. Simulation labels are comma separated, and you can add your own labels alongside them (e.g. sim-onboarding-result:approved,customer-42,sim-offramp:payout-refunded). Bastion ignores labels it doesn’t recognize. Set the labels in the identity’s label field when you call POST /v2/identities. They then apply to everything that identity does, including onboarding and conversions. To test a conversion outcome, put the onboarding label and the conversion label on the same identity, because the identity must be onboarded before it can convert. Simulation labels have no effect in production. Labels that set the same outcome don’t combine. For example, if an identity has two sim-onboarding-result labels, or two payout labels, only one applies. Labels for different steps, such as an onboarding result and a payout label, work together.

Onboarding and KYC/KYB simulation

For sandbox KYC and KYB, you can use the label field when calling POST /v2/identities to simulate KYC outcomes and submit dummy KYC/KYB information. Once POST /v2/identities/{identity_id}/compliance completes, the identity transitions to the state indicated by the simulation label.

Scenario	Simulation label
Simulate an approved onboarding with identity_status = `ACTIVE`	`sim-onboarding-result:approved`
Simulate a rejected onboarding with identity_status = `REJECTED`	`sim-onboarding-result:rejected`
Simulate a pending onboarding that requires IDV checks, with identity_substatus = `IDV_REQUIRED`	`sim-onboarding-result:idv-required`
Simulate the full IDV lifecycle resolving to an approved KYC result, with identity_status = `ACTIVE`, from this single label alone (no separate IDV check call).	`sim-onboarding-result:idv-approved`
Simulate the full IDV lifecycle resolving to a rejected KYC result, with identity_status = `REJECTED`, from this single label alone (no separate IDV check call).	`sim-onboarding-result:idv-rejected`

Example: POST /v2/identities

{
  "label": "sim-onboarding-result:approved",
  "identityType": "IDENTITY_TYPE_INDIVIDUAL"
}

Identity verification (IDV) simulation

For sandbox IDV checks, you can use the labels field when calling POST /v2/identities/{identityId}/id_verification to simulate IDV outcomes. Note that labels is an array.

Scenario	Simulation label
The IDV check is created and subsequently transitions to `APPROVED` status.	`sim-idv-check-result:approved`
The IDV check is created and subsequently transitions to `REJECTED` status.	`sim-idv-check-result:rejected`

Example: POST /v2/identities/{identityId}/id_verification

{
  "redirect_url": "https://www.google.com",
  "reason": "ONBOARDING",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "labels": ["sim-idv-check-result:approved"]
}

On-ramp and off-ramp conversion simulations

Simulate an on-ramp deposit

Sandbox Virtual Accounts can’t receive real deposits. Call POST /v2/simulation/on-ramp-deposit to simulate one and start the on-ramp flow a real deposit triggers. See Test the on-ramp in sandbox for the full steps.

Simulate conversion outcomes

By default, a sandbox conversion follows the happy path to COMPLETED. To test how your integration handles failures and returns, add one of these labels to the identity before starting the conversion. On-ramp

What you’re testing	Label	Result
The customer deposits less than the minimum	`sim-onramp:below-minimum-deposit`	The conversion ends in `FAILED`.

Off-ramp

What you’re testing	Label	Result
The customer’s USDC transfer to Bastion fails on-chain	`sim-ramp:onchain-transfer-fail`	The conversion ends in `FAILED` before any payout is sent. Applies to segregated accounts on EVM chains, not omnibus accounts.
The payout is rejected when it’s created, for example because the recipient’s bank details are malformed	`sim-offramp:payout-rejected`	The conversion ends in `FAILED`. No payout is sent.
The recipient’s bank returns a US payout	`sim-offramp:payout-bank-bounce`	The conversion ends in `RETURNED`. Applies to US off-ramps. For international off-ramps, use `sim-offramp:payout-refunded`.
An international payout is returned and the funds are refunded	`sim-offramp:payout-refunded`	The conversion ends in `RETURNED`. Applies to international off-ramps.
An international payout takes a while to arrive	`sim-offramp:payout-delay-<duration>`	The conversion stays in `PAYOUT_INITIATED` for the given duration, then ends in `COMPLETED`. Write the duration as a number and a unit (`s`, `m`, or `h`), for example `sim-offramp:payout-delay-90s` or `sim-offramp:payout-delay-5m`. If Bastion can’t read the duration, it ignores it and the conversion follows the happy path. Applies to international off-ramps.

Use one payout label per identity. The payout labels (sim-offramp:payout-rejected, sim-offramp:payout-bank-bounce, sim-offramp:payout-refunded, and sim-offramp:payout-delay-<duration>) don’t combine: if an identity has more than one, only one of them applies. Example: POST /v2/identities for an identity whose international off-ramps are returned

{
  "label": "sim-onboarding-result:approved,sim-offramp:payout-refunded",
  "identityType": "IDENTITY_TYPE_INDIVIDUAL"
}

Getting Started

Concepts

Quickstarts

Compliance

Security

Bastion Dashboard

LLMs and MCP Server

Sandbox testing and simulation labels

Onboarding and KYC/KYB simulation

Identity verification (IDV) simulation

On-ramp and off-ramp conversion simulations

Simulate an on-ramp deposit

Simulate conversion outcomes

​Onboarding and KYC/KYB simulation

​Identity verification (IDV) simulation

​On-ramp and off-ramp conversion simulations

​Simulate an on-ramp deposit

​Simulate conversion outcomes

Onboarding and KYC/KYB simulation

Identity verification (IDV) simulation

On-ramp and off-ramp conversion simulations

Simulate an on-ramp deposit

Simulate conversion outcomes