Skip to content
CatholicPayDevelopers

Account numbers

An account number lets a payer pay you by bank transfer from any Nigerian bank. Whatever arrives is credited to your wallet, less your organisation’s inflow fee, and you hear about it by webhook.

Kind Use it for
ONE_OFF One expected payment: an invoice, an order, a booking. It expires after expires_in_minutes.
PERMANENT One of your customers, paying any number of times: their own number. Their BVN or NIN must be verified first.

Create a one-off number

Section titled “Create a one-off number”
Terminal window
curl https://api.catholicpay.example/api/v1/merchant/account-numbers \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "ONE_OFF",
    "reference": "INV-1001",
    "amount": "45000.00",
    "expires_in_minutes": 60
  }'
{
  "data": {
    "reference": "INV-1001",
    "kind": "ONE_OFF",
    "account_number": "9900000001",
    "account_name": "St Leo's College",
    "bank_name": "Partner Bank",
    "expected_amount": "45000.00",
    "received_amount": "0.00",
    "status": "ACTIVE",
    "expires_at": "2026-11-10T10:00:00Z"
  }
}

Show the payer the account_number, bank_name and account_name, and the amount. A one-off number lives from 15 minutes to 90 days (30 minutes by default). The money goes to wallet_id, or your main wallet.

Create a permanent number

Section titled “Create a permanent number”
{ "kind": "PERMANENT", "reference": "STU-001-NUMBER", "customer_id": "…" }

A permanent number takes payments until you close it. For payers who should have their own wallet with you, use payer wallets instead.

Know when it is paid

Section titled “Know when it is paid”

Each payment sends a webhook with the number, the amount and the sender:

Event When
account_number.created The number was issued
account_number.paid A one-off number received at least what it expects; or any payment to a permanent number
account_number.underpaid A one-off number received less than it expects
account_number.overpaid A one-off number received more than it expects
account_number.expired A one-off number expired

Whatever arrives is credited, underpaid or overpaid: decide in your system what to do with a difference. You can also ask:

Terminal window
curl https://api.catholicpay.example/api/v1/merchant/account-numbers/INV-1001/funding \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY"
{
  "data": {
    "reference": "INV-1001",
    "expected_amount": "45000.00",
    "received_amount": "45000.00",
    "funded": true,
    "outcome": "PAID"
  }
}

outcome is PAID, UNDERPAID, OVERPAID or NOT_PAID. Pass amount to check against a different amount.

Close a number

Section titled “Close a number”
Terminal window
curl -X POST https://api.catholicpay.example/api/v1/merchant/account-numbers/INV-1001/close \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY"

A closed number takes no more money. Closing again changes nothing.

Test it

Section titled “Test it”

In the sandbox, simulate a payment: by default the amount the number expects, or any amount to underpay or overpay.