Skip to main content
You build the screens and Paj makes the decision. Your server sends the person’s BVN, Paj sends a code to the phone on their BVN record, and your server passes back the code they typed. If it matches, you get a customerId to send on every order for that person.
KYC has to be enabled for your business before these endpoints work. Until then they return 403. Contact Paj to apply.

The flow

1

Show the consent text

Read it from GET /pub/v2/kyc/consent and show it word for word before asking for the BVN.
2

Send the BVN

POST /pub/v2/kyc/sessions with your own ID for the person and the consent version they agreed to. Paj sends them a code on WhatsApp, naming your business.
3

Send the code back

Collect the code on your screen and pass it to POST /pub/v2/kyc/sessions/{id}/verify-otp. The response carries the customerId.
4

Use the customerId on orders

Send it on onramp and offramp orders. The person doesn’t verify again.

Call Paj from your server

Your app or website should talk to your own backend, and your backend to Paj. An API key inside an app can be extracted.
You handle people’s BVNs and codes here. Never store them, write them to logs, or use a code for anything except sending it straight to Paj.

The results

declineCode is deliberately general, and Paj won’t tell you more about why:
  • ID_NOT_VERIFIED — Paj couldn’t verify this person. A mistyped BVN looks the same, so let them check the number and try again.
  • ATTEMPTS_EXCEEDED — too many wrong codes on this session.
  • ALREADY_LINKED — this person is already behind another of your user IDs.
Responses never include anything from the BVN record, such as a name or phone digits. Tell the person the code went to “the phone number on your BVN”.

Limits

  • Wrong codes: three per session, and ten per person per day across every business. A wrong code returns 400 until the third, which returns DECLINED.
  • New codes: one a minute and five per person per day. A new code gives no extra guesses.
  • BVN lookups: a daily limit per business, agreed with Paj. Going over returns 429.

When things change later

A person’s status can change after the first answer, usually when a reviewer decides on an IN_REVIEW case. Set kycWebhookURL with Update your webhook URLs to hear about it:
Deliveries are signed, like every other webhook. If you miss one, read the current status from GET /pub/v2/customers/{customerId}.

On orders

Paj checks the person on every order, not just once. An order for a customerId is refused with 403 unless they are VERIFIED at that moment, and an offramp is refused with 400 unless the bank account is in their name. A customerId only works with your own API keys. The same person has a different customerId at every business.