# Testing in sandbox without spending credits

Source: https://help.didit.me/getting-started/sandbox-and-testing
Updated: 2026-10-12

Sandbox is the test environment next to Live in the console. Providers are mocked, nothing is billed, and you can force approved, declined or in review.

Switch the console to **Sandbox** with the pill under your application's name,
create a sandbox API key there, and use it. Every check is mocked, nothing is
billed, and you can force any outcome you want. Sandbox keeps its own data,
keys, webhooks and lists, apart from Live.

Didit's sandbox is the equivalent of a payment provider's test cards: it lets you reproduce any verification outcome on demand, without calling real providers, handling real personal data, or touching your balance.

## Sandbox is its own environment

This is the part that trips most people up. Live and Sandbox are **separate environments**: Sandbox is your organization's shared test application, with its own verifications, API keys, webhooks and lists, so test traffic and production data never mix. A strip across the top of every console page tells you when you're in Sandbox.

![The API keys page in the Didit console, where each key belongs to one application and one environment](https://help.didit.me/screenshots/api-keys-light.webp)

*Keys belong to one environment, so a sandbox key can never reach live data.*

1. **Switch to Sandbox**

   Click **Sandbox** on the pill under your application's name, at the top of the sidebar. Going back is deliberate: choosing **Live** first shows a short **Before you switch to Live** checklist (publish a workflow, create a live API key or link, test your webhook, confirm how you pay, review data retention), then **Switch to Live** or **Stay in Sandbox**.

2. **Create a sandbox API key**

   Open **Developers → API keys** and create a key, or pick **Sandbox** as the environment when you create one. A live key never creates a sandbox session; the key decides the environment.

3. **Build or copy a workflow**

   Sandbox has its own workflows. Build the flow you want to test, or copy it from Live.

4. **Create sessions as normal**

   Same endpoint, same code path. The only difference is which key you send.

> **Note:** If **Sandbox** is greyed out on the switch, your organization has no Sandbox
> application yet. Ask support to enable it: that's an account-level setting, not
> something you've configured wrongly.

## What sandbox changes, and what it doesn't

| | Sandbox | Live |
|---|---|---|
| External providers | All mocked - no third party is ever called | Real |
| Billing | Never billed; the balance check is skipped | Billed per completed feature |
| Session create limit | 500 per 24 hours | Your balance |
| Webhook payload | `"environment": "sandbox"` | `"environment": "live"` |
| Extracted data and status | Simulated by the scenario you choose | Derived from the real capture |
| Captured media | **Stored for real**, exactly like a live session | Stored |

> **Warning:** Sandbox stores the media it captures - documents, selfie, liveness video,
> proof-of-address files - exactly as a live session would. The *outcome* is
> simulated, but the upload is real, so use the sample documents and test data the
> flow offers rather than a real identity document or real personal information.

Because outcomes never depend on the pixels, a deliberately bad photo won't produce a decline in sandbox. The scenario decides.

The same applies to the **extracted fields**: sandbox always returns sample identity data - name, date of birth, document number - no matter which document you scan. Seeing your real passport image in the console next to somebody else's details is expected sandbox behavior, not an OCR bug, and any document type "scans" successfully regardless of what you selected. It also means chip flows that re-derive keys from the printed data (NFC BAC) can't be exercised against a real document in sandbox - the mocked OCR fields won't match your chip.

## Choosing the outcome

Pass a scenario slug as `sandbox_scenario` when you create the session, or let the tester pick one: sandbox sessions in the hosted flow show an in-card **scenario picker** before capture starts, plus a strip of sample documents under the upload component and a persistent "test data only" banner.

The scenarios cover the outcomes you actually need to build against:

| Want to test | Scenario |
|---|---|
| Everything approves | `approve` |
| Expired document | `decline_document_expired` |
| Unreadable document | `decline_could_not_recognize_document` |
| MRZ checksum failure | `decline_mrz_validation` |
| Under the minimum age | `decline_minimum_age` |
| Face match too low | `decline_face_match_low_similarity` |
| Presentation attack on liveness | `decline_liveness_attack` |
| AML sanctions / PEP hit | `decline_aml_hit` |
| Blocked IP address | `decline_ip_blocklist` |
| Address mismatch on proof of address | `decline_poa_address_mismatch` |
| NFC chip failed integrity | `decline_nfc_chip_not_verified` |
| Database validation found nothing | `decline_database_no_match` |
| Needs manual review (AML) | `review_aml_possible_match` |
| Needs manual review (borderline face match) | `review_face_match_borderline` |
| Needs manual review (partial address) | `review_poa_partial_match` |
| KYB registry mismatch | `decline_kyb_registry_mismatch` |

The `review_*` scenarios exist so you can exercise the whole manual-review path - the console review queue, the `In Review` webhook, a reviewer approving or requesting resubmission - without needing a decline-grade input.

> **Tip:** The live catalogue of scenarios and magic values is served by the API itself at
> `GET /v1/sandbox/scenarios/`. If a slug here ever looks stale, trust the endpoint.
> Full reference: [sandbox testing](https://docs.didit.me/integration/sandbox-testing).

## Telling the two apart in your own code

Every webhook carries an `environment` field - `"sandbox"` or `"live"`. Branch on that rather than trying to infer the environment from the key, and you'll never mistake a test session for a real customer.

## What sandbox will not do

- It won't return real registry data for a real company. Sandbox KYB uses mocked registry responses.
- It won't send a real SMS or email. Phone and email verification are mocked, so you can't use sandbox to preview real message deliverability.
- It won't consume your monthly plan credit - which also means a sandbox run tells you nothing about your remaining credit.

## If you need real test verifications

Some things genuinely require a live call - checking that a specific country's database service is provisioned for you, or confirming SMS delivery to a particular carrier. That needs a small top-up on a live application rather than sandbox. Ask support before spending on it, so they can confirm the service is actually enabled on your account first.