Sandbox & testing

Sandbox is a fully separate mode of the same API. You enter it by which key you use, not by any flag in a request body: a pb_sk_test_ key puts every call it makes in test mode, and a pb_sk_live_ key puts every call in live mode. The livemode field on each object is derived from the key that created it — you never set it yourself.

Test-mode sessions run against a simulator instead of the real biometric pipeline, so you can drive a verification to a chosen outcome deterministically.

Deterministic outcomes

When you mint a session with a test key, two optional fields control the simulator:

test_outcome — one of approved, review, or failed. Defaults to approved.
test_delay_seconds — an integer from 0 to 120 (seconds the simulator waits before resolving). Defaults to 5. Values outside that range are rejected with invalid_test_delay_seconds.

Set test_delay_seconds to 0 for instant resolution in automated tests, or leave it at the default to watch the lifecycle unfold in the SDK.

What a test session does — and never does

A completed test session behaves like a real one where it matters and is inert where it shouldn’t:

It produces a test VIC id of the form vic_test_... (never a real on-chain VIC).
It emits real, signed test-mode webhooks — the same signatures and payload shapes as live, so your verification and dispatch code is exercised for real.
It is never billed, never written on-chain, and never sends SMS.

The simulated customer flow

Because there’s no real capture in test mode, the hosted flow offers shortcuts so your integration tester can complete it without a wallet extension or a phone:

Phone rail — use the test number +1 555 01XX XXXX and the fixed one-time code 000000. No SMS is ever sent; there’s no send-code step at all, you go straight to entering 000000.
Wallet rail — a Simulated wallet button grants a throwaway synthetic identity; no MetaMask round trip.

Neither shortcut touches real key material or the real KYC pipeline — the synthetic identity is cosmetic, used only to advance past the auth screen so the simulator can resolve the session on its timer.

Test data is isolated from production

A test key can never see production data. This is a hard boundary, not a filter:

Listing customers with a test key returns an empty page — the sandbox has no customer roster of its own, since a completed test session persists only the session row and its test-mode events.
Fetching a specific customer with a test key returns 404 customer_not_found, even for an address that exists in live mode.

The reverse holds too: live-mode reads never surface sandbox objects. Sandbox and live are two disjoint worlds that happen to share one API.

Moving to production

When you’re satisfied with your integration, complete the go-live review to mint a pb_sk_live_ key. Your code doesn’t change — only the key does.