Sandbox & test IDs

Build withCopy prompt

Test your Myaza KYC integration end to end: webhooks, polling, the full result payload (biodata, facial match, OCR data, captured-media URLs), and every failure branch, all without calling any government database or burning provider credits.

Sandbox accepts only published test IDs. A real (non-test) idNumber is rejected immediately at POST /verify with 422 only_test_ids_allowed.

All sandbox results are fully fake: fake biodata, fake government photos, fake OCR, and fake gov-DB data. No external API is ever called.

How test IDs work

Build withCopy prompt

Pass a test ID in the idNumber field of POST /verify. The last one or two digits encode the scenario; everything before is zero-padding so the value stays format-valid for its ID type. Example for NG BVN:

00000000001  → verified
00000000002  → not_found
00000000004  → selfie_mismatch
00000000007  → document_expired   (document IDs only)
00000000012  → provider_error

Scenario reference

Document-only scenarios (6–11, 18) are not published for number-only IDs (BVN/NIN/vNIN).

The verified test ID per ID type

Change the trailing digits per the table above to pick a different scenario.

Example: number-only ID

Build withCopy prompt

curl -X POST https://your-server/api/kyc/verify \
  -H "Authorization: Bearer pk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "idType": "bvn",
    "idNumber": "00000000001",
    "userData": { "firstName": "Chidi", "lastName": "Okafor", "dateOfBirth": "1990-04-12" },
    "metadata": { "requestId": "test-001" }
  }'

Document IDs

Build withCopy prompt

In sandbox, OCR is never run; a fake OCR result is returned instead. Either let the SDK document flow default to the verified fixture (no ID number collected), or pick a scenario by passing the document test ID in idNumber (e.g. A00000007 for an expired passport) or via the sandboxOutcome override below.

Business (KYB)

Build withCopy prompt

Business verification never calls a real registry outside production: a registry lookup is billed by the provider whichever environment asks for it, so sandbox and development serve canned data instead.

• Any registration number is accepted and resolves to a verified fixture that echoes the name you searched for. The catalogue values still pick their scenario: RC0000001 is verified, RC0000002 is not found. A business picked from the real company search (which does work in every environment) can therefore be checked on sandbox against fixture data.
• sandboxOutcome on the submit ("verified" or "not_found") pins the result for any number, and is ignored silently in production.
• The sandbox company carries a full key-people set for exercising due diligence: a 60% beneficial owner, directors, a signatory, a persona named "Pep" that the stub screening provider flags (set SCREENING_PROVIDER=stub), and a corporate shareholder, Sandbox Holdings Ltd (RC0000900), whose own register resolves to a person majority-owner and a second company above it (RC0000901), so ownership-chain look-through, effective percentages, and the depth limit are all testable at no cost.

Address presence

Build withCopy prompt

Presence verification has its own personas and a compressed clock so a multi-day watch is testable in minutes; they are documented with the feature on the Address Intelligence page. In short: outside production the watch window runs in minutes, and an externalUserId containing presence_verified, presence_fail or presence_inconclusive seeds a canned observation stream through the real scorer. A plain id gets no seed, so you can drive the ingest endpoint yourself.

Overrides

Build withCopy prompt

Both go in metadata and are ignored in production.

• sandboxOutcome: force any scenario regardless of the test ID, e.g. "sandboxOutcome": "selfie_mismatch".
• sandboxDelayMs: how long pending → completed takes (0–60000 ms). Defaults to ~1200 ms; set 0 for an instant result.

Captured media

Build withCopy prompt

Media uploaded under a test ID is kept for 3 days, then the bytes are replaced with a placeholder (an image for stills, a sample clip for videos). The data.media URLs in webhooks keep working; they just serve the placeholder after the sweep.

Webhook simulator

Build withCopy prompt

From a webhook endpoint's detail page (or POST /api/dashboard/webhooks/:id/simulate with { "event": "verification.completed" }), fire a realistic, correctly-signed sample payload of any event at your endpoint to test signature verification and your handler, without running a verification. It uses the real delivery path (HMAC signing + retry).

Notes

Build withCopy prompt

• Sandbox verifications are never charged, even for the insufficient_credits scenario.
• Test IDs bypass the ID-type allowlist, so a new organisation can test immediately. Use the id_type_not_enabled scenario to simulate a revoked allowlist.
• Branch on the stable reasonCode, not the human-readable reason.