Core API

Virtual accounts

Create one dedicated account per customer from your product. The dashboard lists accounts; creation is API-only.

Create an account

POST /virtual-accounts

Idempotency-Key is required (max 200 characters). The same key returns the original account and does not create another. customerReference is your user id — the same reference returns the account already issued for that user.

Field	Required	Notes
`customerName`	Yes	Display name on the account
`customerEmail`	Yes	Customer email
`customerPhone`	Yes	Nigerian phone number
`customerBvn` or `customerNin`	One of	Exactly 11 digits. Encrypted at rest; never returned
`preferredBank`	Yes	`palmpay`, `wema-bank`, `titan-paystack`, or `test-bank`
`customerReference`	Recommended	Your stable user id

curl https://api.nerat.app/api/virtual-accounts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e2a14-6b31-4f08-9d2e-1a0b6c4d8e11" \
  -d '{
    "customerName": "Amaka Okafor",
    "customerEmail": "amaka@example.com",
    "customerPhone": "08012345678",
    "customerBvn": "12345678901",
    "preferredBank": "palmpay",
    "customerReference": "user-42"
  }'

Response codes

201 — account is active (typical for PalmPay). Number is in the response.
202 — waiting for the number (Wema / Paystack-Titan). Listen for virtualaccount.active.

The account name is your business name, a slash, and the customer name. Limit: 500 new accounts per business per hour.

List accounts

GET/virtual-accounts?page=1&pageSize=8&q=

Get one account

GET/virtual-accounts/:id

Deactivate

POST/virtual-accounts/:id/deactivate

Recheck deposits

Ask NeratPay to look again for a deposit that may not have been recorded.

POST/virtual-accounts/:id/recheck