These values only work on
https://sandbox.payvessel.com. In production the same endpoints query real records.How It Works
Every reserved value ends in9999 followed by a two-digit outcome code. Any value that does not end that way returns a successful verification, so you can keep using realistic-looking test data for the happy path.
00 — Verified
00 — Verified
Returns a populated, successful response.
success is true.01 — Not Found
01 — Not Found
The record does not exist. Returns HTTP
200 with success: false and data: null.02 — Adverse Result
02 — Adverse Result
The lookup succeeds but the answer is negative: a name mismatch, a blacklist hit, a poor credit score, an expired document, or a failed liveness check.
success is true — the check ran, the outcome was unfavourable.03 — Provider Error
03 — Provider Error
The upstream bureau failed. Returns HTTP
502.04 — Timeout
04 — Timeout
The upstream bureau did not respond in time. Returns HTTP
502.05 — Invalid Request
05 — Invalid Request
Returns HTTP
400.06 — Rate Limited
06 — Rate Limited
Returns HTTP
429.Reserved Values
Hyphens and spaces are ignored, so
SBX-9999-02 and SBX999902 behave identically.
The Sandbox Identity
Reserved values return this person:
Any non-reserved identifier returns a different but consistent person — the same input always gives the same result, so you can rely on it in automated tests.
Choosing An Outcome When A Request Has Several Identifiers
The first reserved value wins, in this order:Examples
Endpoint Notes
Basic NIN and Basic BVN — how to get a MATCH
Basic NIN and Basic BVN — how to get a MATCH
These endpoints compare the identity fields you submit against the record. To see
MATCH, submit the sandbox identity above alongside the reserved value. Submitting any other name returns NO_MATCH, which is a useful test case in its own right.Bank account verification has no adverse outcome
Bank account verification has no adverse outcome
A successful bank account lookup always reports a confirmed name match, so there is no adverse variant to simulate.
0000999902 behaves the same as the not-found value.Face comparison uses explicit tokens
Face comparison uses explicit tokens
Images are base64, so the numeric suffix rule would match real data by accident. Pass the literal string
sandbox:00 (or another code) as the image instead. sandbox:01 returns a 400 for a missing face, matching production behaviour. Any real base64 image returns a successful comparison.Liveness sessions chain automatically
Liveness sessions chain automatically
The
transaction_id returned by the initialize call carries the outcome you selected with biz_id. Pass it straight to the query endpoint and you get the matching result.Insufficient funds is not simulated
Insufficient funds is not simulated
A wallet balance failure happens before verification starts, so there is no reserved value for it. To test that path, drain your sandbox wallet balance.