Sandbox Test Numbers

Use these identifiers to simulate the scenarios your integration must handle. Requests made with a sandbox API key return these seeded responses instantly — no provider is called.

How Sandbox Works

• Determined by the API key you send. Sandbox and live keys are issued separately from your dashboard.
• Sandbox requests are free (priceUsdAtCall: 0) but still count toward your sandbox rate limits and show up in your verification list alongside live records.
• Async sandbox requests fire a real webhook to your registered webhook URL after a short delay (approximately 3 seconds).

Unknown identifiers

• Sending an identifier not listed on this page returns TEST_NUMBER_NOT_FOUND.
• Sending a bank code outside the per-country list below returns INVALID_BANK_CODE.

Account Verification (POST /verify/account)

Phone Verification (POST /verify/phone)

BVN Identity Verification (POST /verify/identity — NG)

SUCCESS — example response for 22222222201

{
  "id": "8f3a7b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "status": "success",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "22222222201",
  "verifiedAt": "2026-04-21T09:15:32.104Z",
  "verified": true,
  "firstName": "Test",
  "lastName": "Okoye",
  "middleName": "Sandbox",
  "dateOfBirth": "1990-01-01",
  "phoneNumber": "+2348000000001",
  "gender": "Male",
  "enrollmentBranch": "Victoria Island",
  "enrollmentInstitution": "Access Bank",
  "registrationDate": "2010-05-15",
  "nin": "12345678901",
  "levelOfAccount": "Tier 3",
  "address": {
    "town": "Lagos",
    "lga": "Eti-Osa",
    "state": "Lagos",
    "street": "10 Sandbox Street"
  },
  "title": "Mr",
  "maritalStatus": "Single",
  "lgaOfOrigin": "Onitsha North",
  "otherMobile": "+2348000000099",
  "stateOfOrigin": "Anambra",
  "watchListed": "NO",
  "nameOnCard": "OKOYE TEST SANDBOX",
  "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
  "validation": null
}

id and verifiedAt vary per call; everything else is deterministic. image is a 1×1 transparent PNG encoded as base64 — lets you exercise your decoding pipeline end-to-end without a real photo. validation is populated only when your request includes a validation block (see the BVN reference for the full matcher schema).

NOT_FOUND — example response for 22222222202

{
  "id": "…",
  "status": "failed",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "22222222202",
  "verifiedAt": "…",
  "error": { "code": "BVN_NOT_FOUND", "message": "BVN not found" }
}

PROVIDER_ERROR — example response for 22222222203

{
  "id": "…",
  "status": "error",
  "verificationType": "BVN",
  "idType": "bvn",
  "country": "NG",
  "identifier": "22222222203",
  "verifiedAt": "…",
  "error": { "code": "PROVIDER_ERROR", "message": "Simulated upstream provider error" }
}

Note the different status values: failed is a business failure (BVN does not exist upstream); error is an infrastructure failure (upstream provider returned 5xx). Matches live behavior.

Lipa Na M-Pesa (POST /verify/lipa-na-mpesa — KE)

M-Pesa Agent (POST /verify/mpesa-agent — KE)

Sandbox-valid bank & operator codes

Any bank/operator code outside this list returns INVALID_BANK_CODE.

• NG: 044 (Access), 058 (GTBank), 057 (Zenith), 033 (UBA), 011 (First Bank)
• GH: GH010100 (Ghana Commercial Bank)
• ZM: 014 (FNB), 016 (Stanbic), 017 (Standard Chartered), 022 (UBA), 023 (Zanaco), 025 (ZICB), 028 (AB Bank)
• CI, SN, CM, BF, ML, BJ, TG: ORANGE, MTN, MOOV, WAVE
• UG: bank-account verification is not supported — use phone verification instead.
• KE: no bank code field — lipa-na-mpesa and mpesa-agent endpoints do not take one.

Testing Async Webhooks

1. Register a webhook URL in your dashboard and subscribe to verification.completed.

2. POST a verification request with "mode": "async". You will receive a pending response immediately.

3. After about 3 seconds, your webhook URL receives a verification.completed event:

   {
     "event": "verification.completed",
     "data": {
       "id": "verif_abc123",
       "status": "success",
       "type": "ACCOUNT_NUMBER",
       "accountName": "Test Okoye"
     }
   }
   

   json

4. If your process crashes before delivery, the verification stays pending. This is intentional — lets you test crash recovery in your own code.