​

Identity verification

Base path: /api/v1/merchant/identity Scopes: identity:read, identity:write. Lookups require Idempotency-Key. Live keys debit your NGN wallet whenever the identity provider answers — including IDENTITY_NOT_FOUND. Only provider-down (503) lookups are refunded.

​

Typical flow

1. List products — confirm price and that available is true.
2. Verify — POST /identity/bvn/basic (validate), bvn/enhanced (full record), nin/basic, or nin/enhanced.
3. Body — BVN validate requires bvn plus at least one of firstName, lastName, dateOfBirth. BVN full and NIN require only the 11-digit number; match fields are optional and do not change the record returned.

​

Products

bvn / nin must be 11 digits. Do not send spaces or hyphens.

​

Charging

Test keys (sp_test_) simulate the same responses and do not debit. Use 00000000000 to exercise the not-found path.

​

match on BVN validate

success: true means the lookup completed. passed is whether the name/DOB matched: true when the BVN is recognised and every field you sent matched. match.bvn.value is masked (not the full 11 digits). Do not send middleName or phoneNumber on BVN validate.

​

match on lookup products (BVN full, NIN)