Skip to main content
POST
Start verifying a person
Checks a BVN and sends a code to the phone on its record. Call it from your server. See Verifying your users for the whole flow. Sending consentVersion is your statement that the person saw that consent text and agreed to it. If this externalUserId is already linked to the same BVN, you get the existing customerId straight back and no code is sent. If it’s linked to a different BVN, the response is 409.

Authorizations

x-api-key
string
header
required

Body

application/json
externalUserId
string
required

Your own ID for this person. Paj never interprets it.

Example:

"acme-user-123"

idNumber
string
required

The person's BVN. Send it from your server and never store or log it.

Example:

"22222222222"

idType
enum<string>
required
Available options:
BVN
Example:

"BVN"

country
enum<string>
required
Available options:
NG
Example:

"NG"

The version of the consent text the person agreed to, from GET /pub/v2/kyc/consent. Sending it is your statement that they saw that text and agreed.

Example:

"v1"

Response

status
enum<string>
required
Available options:
OTP_SENT,
VERIFIED,
IN_REVIEW,
DECLINED
Example:

"OTP_SENT"

sessionId
string

Absent when this person was already verified for you, since no new session was needed.

Example:

"kys_9fa17c2e4b6d8a0c1e3f5a7b"

customerId
string

What to send on orders for this person. Present on VERIFIED and IN_REVIEW. Orders are refused until the status is VERIFIED.

Example:

"cus_8f2a6c1d9e4b7f03a5c8d2e6b1f4a790"

externalUserId
string
Example:

"acme-user-123"

tier
number

The verification tier reached. Present on VERIFIED.

Example:

1

declineCode
enum<string>

Why, in general terms. Present on DECLINED.

Available options:
ID_NOT_VERIFIED,
ATTEMPTS_EXCEEDED,
ALREADY_LINKED
expiresAt
string<date-time>

When the code stops working. Present on OTP_SENT.