TagPayTagPay

API Reference

Identity Verification

Verify a customer's identity against the Nigerian national databases using their BVN or NIN. Returns the resolved biodata when the lookup succeeds, plus a `name_match` flag so you can confirm the submitted name aligns with the registered holder.

Verify a BVN

POST/v1/verify/bvn

Submits a BVN to the national identity database via TagPay's verification provider. The response contains the registered biodata (first name, last name, date of birth, gender, phone) and a name_match boolean that compares the submitted first_name and last_name against the registered record. Use the secret API key — verification calls are server-side only.

Body parameters

bvnstringrequired

11-digit numeric BVN.

first_namestringrequired

First name to match against the registered record.

last_namestringrequired

Last name to match against the registered record.

dobstringoptional

Date of birth in YYYY-MM-DD format. Improves match accuracy when supplied.

phonestringoptional

Phone number to match against the registered record.

Response

200
verifiedboolean

`true` if the BVN was found and biodata was returned. `false` when the BVN is invalid or the provider could not resolve it.

reasonstring

Present only when `verified` is `false`. Human-readable explanation.

first_namestring

Registered first name. May be `null` if the provider returned identity-match-only data.

last_namestring

Registered last name.

middle_namestring

Registered middle name, if any.

date_of_birthstring

Registered date of birth (`YYYY-MM-DD`).

phonestring

Registered phone number.

genderstring

Registered gender.

name_matchboolean

`true` when both `first_name` and `last_name` submitted match the registered record.

Errors

VALIDATION_ERROR400`bvn` must be an 11-digit numeric string.
SERVICE_UNAVAILABLE503Upstream verification provider is unreachable. Retry with backoff.

Verify a NIN

POST/v1/verify/nin

Submits a NIN to the national identity database via TagPay's verification provider. Mirrors the BVN verification response shape — registered biodata plus a name_match flag against the submitted first_name and last_name. Use the secret API key — verification calls are server-side only.

Body parameters

ninstringrequired

11-digit numeric NIN.

first_namestringrequired

First name to match against the registered record.

last_namestringrequired

Last name to match against the registered record.

dobstringoptional

Date of birth in YYYY-MM-DD format. Improves match accuracy when supplied.

phonestringoptional

Phone number to match against the registered record.

Response

200
verifiedboolean

`true` if the NIN was found and biodata was returned. `false` when the NIN is invalid or the provider could not resolve it.

reasonstring

Present only when `verified` is `false`. Human-readable explanation.

first_namestring

Registered first name. May be `null` if the provider returned identity-match-only data.

last_namestring

Registered last name.

middle_namestring

Registered middle name, if any.

date_of_birthstring

Registered date of birth (`YYYY-MM-DD`).

phonestring

Registered phone number.

genderstring

Registered gender.

name_matchboolean

`true` when both `first_name` and `last_name` submitted match the registered record.

Errors

VALIDATION_ERROR400`nin` must be an 11-digit numeric string.
SERVICE_UNAVAILABLE503Upstream verification provider is unreachable. Retry with backoff.