Customers & identity checks

A customer is someone you collect from: a pupil’s family, a member, a client. Keep them with CatholicPay to give them permanent account numbers or a payer wallet.

Create a customer

curl https://api.catholicpay.example/api/v1/merchant/customers \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Chidi",
    "last_name": "Okeke",
    "email": "parent@example.com",
    "phone": "08030002102",
    "external_reference": "STU-001",
    "metadata": { "class": "JSS1" }
  }'

external_reference is your own ID for them, unique in your organisation (409 if it is taken). metadata holds your own string values. Phones are returned in international form (+2348030002102).

Read, update and delete with GET, PUT and DELETE /merchant/customers/{id}. An update changes only the fields you send. List them with GET /merchant/customers: search names, email, phone and reference with q, and payer=true lists synced payers only.

Verify a BVN or NIN

curl https://api.catholicpay.example/api/v1/merchant/customers/{id}/identities \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "bvn": "22200002102" }'

The customer’s identity shows the outcome (status, type) and the name on the identity record. The number itself is never stored. Send nin instead of bvn for a NIN.

Each live check is charged to your main wallet; BVN and NIN checks are priced separately. A verified identity is needed for a permanent account number.

Create a customer from an identity

POST /merchant/customers/verify checks the BVN or NIN and creates the customer in one step, named from the identity record:

{ "bvn": "22200002103", "external_reference": "STU-002" }

Delete a customer

DELETE /merchant/customers/{id} removes them (204). A synced payer’s wallet must be empty first (422 WALLET_NOT_EMPTY); their account number is closed.

Test it

The sandbox has test identities: any 11 digits, with endings that give each outcome.