> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paj.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifying your users

> Prove who your user is once, then use a customerId on every order.

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.

> [!NOTE]
>
> 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`](https://docs.paj.cash/api-reference/get-kyc-consent) and
show it word for word before asking for the BVN.

**2. Send the BVN**

[`POST /pub/v2/kyc/sessions`](https://docs.paj.cash/api-reference/create-kyc-session) 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`](https://docs.paj.cash/api-reference/verify-kyc-otp).
The response carries the `customerId`.

**4. Use the customerId on orders**

Send it on [onramp](https://docs.paj.cash/api-reference/create-onramp-order.md) and
[offramp](https://docs.paj.cash/api-reference/create-offramp-order.md) orders. The person doesn't
verify again.

```bash theme={null}
curl -X POST https://api.paj.cash/pub/v2/kyc/sessions \
  -H "x-api-key: $PAJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "acme-user-123",
    "idNumber": "22222222222",
    "idType": "BVN",
    "country": "NG",
    "consentVersion": "v1"
  }'
```

## 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.

> [!WARNING]
>
> 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

| `status` | Meaning | What to do |
| - | - | - |
| `OTP_SENT` | A code is on its way, and lasts 10 minutes | Ask the person for it |
| `VERIFIED` | Paj has confirmed who this is | Use the `customerId` |
| `IN_REVIEW` | A person at Paj needs to look at this | Wait for the webhook; orders are refused until then |
| `DECLINED` | Paj couldn't verify this person | Show a general message; see `declineCode` |

`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](https://docs.paj.cash/api-reference/update-webhooks.md) to hear about it:

```json theme={null}
{
  "event": "kyc.status_changed",
  "customerId": "cus_8f2a6c1d9e4b7f03a5c8d2e6b1f4a790",
  "externalUserId": "acme-user-123",
  "status": "VERIFIED",
  "tier": 1
}
```

Deliveries are [signed](https://docs.paj.cash/concepts/webhook-signatures.md), like every other webhook.
If you miss one, read the current status from
[`GET /pub/v2/customers/{customerId}`](https://docs.paj.cash/api-reference/get-customer).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.