NGN Bank78 Static Accounts (Client API)

Guide for businesses (e.g. Breeze) that need a dedicated Nigerian Bank78 static NUBAN per customer, creatable via API.

Overview

Incoming NGN transfers to that NUBAN are credited to your business’s NGN wallet pool (when treasury / central wallet pool is enabled) and attributed to the customer.

Prerequisites

1. Business Client API key (live or test) with HMAC signing — see Authentication.
2. Customer registered on Sznd and linked to your business (see below).
3. Customer KYC completed on Sznd (kyc_state / identity verification cleared).
4. Customer BVN (11 digits) — required on every NGN create request.

What is user_id?

user_id is Sznd’s internal customer UUID. It is not an id from your external system.

You do not invent this UUID or send your own CRM id as user_id.

How the account links to your business

Your API key    → identifies Business (e.g. Breeze)         → customer registered via Client API              → row in business_customers (customer belongs to Breeze)                   → POST /client/virtual-wallets (NGN)                        → Bank78 static NUBAN for that customer                        → VBA tagged with business_id                        → with central wallet pool: credits go to business NGN wallet

End-to-end flow

Step 1 — Register the customer (once)

Option A — KYC link (customer completes verification)

POST /api/v1/client/customers

{  "email": "customer.a@example.com",  "first_name": "Ada",  "last_name": "Okonkwo",  "password": "SecurePass123!",  "date_of_birth": "1990-01-15",  "phone_number": "+2348012345678",  "country_code": "NG"}

Option B — Full registration (you already have KYC data)

POST /api/v1/client/customers/full

See Customers API for the full payload (address, documents, compliance fields).

Save the returned id:

{  "message": "Customer created successfully",  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "user": {    "id": "123e4567-e89b-12d3-a456-426614174000",    "email": "customer.a@example.com",    "first_name": "Ada",    "last_name": "Okonkwo"  }}

That UUID is the user_id used in later steps.

Step 2 — Confirm KYC is complete

GET /api/v1/client/customers/{user_id}/onboarding-status

Proceed only when identity / KYC is completed (same rules as other virtual wallets). Incomplete KYC → 403 on virtual wallet create.

Step 3 — Create NGN Bank78 static account

POST /api/v1/client/virtual-wallets

Headers (HMAC):

x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>Content-Type: application/json

Body:

Example:

{  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "currency": "NGN",  "bvn": "01234567890",  "account_name": "Breeze Customer A"}

Success (new account initiated):

{  "message": "Customer onboarding initiated successfully",  "currency": "NGN",  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "status": "PENDING"}

Success (idempotent — already exists):

{  "message": "Virtual wallet already exists for this customer and currency",  "currency": "NGN",  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "status": "ACTIVE",  "already_exists": true,  "virtual_wallet": {    "id": "550e8400-e29b-41d4-a716-446655440000",    "currency": "NGN",    "account_number": "78xxxxxxxxx",    "is_active": true  }}

Creation is idempotent: one NGN static VBA per customer; repeating the call returns the existing account instead of creating another.

Step 4 — Retrieve account details

List

GET /api/v1/client/virtual-wallets?user_id={user_id}&currency=NGN

Get by wallet / VBA id

GET /api/v1/client/virtual-wallets/{id}

Use the returned account_number, bank name/code, and account_name to show Customer A how to pay.

Step 5 — Deposits

When funds hit the static NUBAN, Sznd processes the Bank78 webhook, credits the linked wallet (business pool when configured), and can notify you via your business webhook URL (virtual wallet / transaction webhooks as configured).

Errors (common)

curl example

# After computing HMAC over body|timestamp with your secret key:curl -X POST "https://api.sznd.app/api/v1/client/virtual-wallets" \  -H "Content-Type: application/json" \  -H "x-api-key: $API_KEY" \  -H "x-timestamp: $TIMESTAMP" \  -H "x-signature: $SIGNATURE" \  -d '{    "user_id": "123e4567-e89b-12d3-a456-426614174000",    "currency": "NGN",    "bvn": "01234567890",    "account_name": "Breeze Customer A"  }'

Checklist for go-live (ops + business)

• Business has Client API keys
• Business NGN treasury / currency activation completed if required for pooling
• Integration registers customers via Client API and stores Sznd user_id
• Integration waits for KYC completion before NGN VBA create
• Integration always sends bvn for NGN
• Optional account_name set to a clear payee label (e.g. Breeze Customer A)
• Webhook URL configured to receive deposit / wallet events

Related docs

• Customers API — register and KYC customers
• Create virtual wallet — request/response shapes for all currencies
• Virtual wallets overview
• Virtual wallet webhook
• Authentication