Which KYC Endpoint Do I Use?

There are two ways a customer's identity reaches Bitnob, and which one you use depends on the product, not on the customer.

you want to	call	what it does
Issue a virtual card	POST /api/cards/kyc	Verifies the person and creates the customer in one step. Returns a customer_id to pass to Create Card
Issue a naira virtual account	POST /api/customers, then POST /api/virtual-accounts	You create the customer with their BVN. The BVN is verified when the account is created
Create a customer for payouts or beneficiaries	POST /api/customers	Creates the record. No identity verification runs

Cards: `POST /api/cards/kyc`

Send the customer's details and one identity document. You do not create the customer first; a successful submission creates them and returns customer_id.

Accepted id_type values: bvn, nin, passport, drivers_license, national_id, vnin, voters_card, ghana_card.

Verification can finish immediately or sit at pending. A card can only be created once it is approved.

Card KYC is enabled per account. If it is not on for you, the call returns "card KYC is not available".

Reference: Card KYC. Guide: Card KYC.

Virtual accounts: `POST /api/customers`

Create (or update) the customer with first_name, last_name, email, phone_number, date_of_birth, id_type: "bvn" and id_number.

Then call POST /api/virtual-accounts with that customer_id. The BVN is checked against the national registry at this point, not when the customer is created.

The name and date of birth must match the BVN record exactly, or verification fails even when the BVN is valid.

For a company, set customer_type: "business" and add company_name and registration_number. The personal fields are those of a director or authorised representative.

Reference: Customer Requirements. Guide: Getting Started.

Checking status

There is no separate status endpoint. Read the customer:

Endpoint

Response (excerpt)

card_program_kyc[].normalized_status is one of none, initiated, pending, approved or rejected. Prefer the virtualcard.user.kyc.* webhooks over polling. Virtual accounts have no pending state: the create call either returns the account or an error naming what failed.

Existing customers

A customer you already created with POST /api/customers can be given a virtual account once the fields above are on the record. Add missing ones with Update Customer.

One customer per email, phone number or BVN

Customers are matched on email, phone_number and BVN (id_number). Creating a customer with an email, phone number or BVN you've already used returns 201 with the existing customer, and the other fields you sent are ignored.

Field formats

field	format
date_of_birth	ISO date, YYYY-MM-DD, for example 1994-03-21. The customer must be 18 or over
id_number (bvn)	11 digits
id_type: bvn and nin	Country must be Nigeria (NGA)
country	ISO 3166-1 alpha-3: NGA, GHA, USA
phone_number / dial_code	Number without the prefix (8012345678) and the prefix separately (+234)
created_by	A UUID identifying the user or API client that created the record, kept for the audit trail. Optional on requests; an email address is rejected with 'invalid created_by: must be a valid UUID'