API Changelog

Partner Onboarding

Partners can now register, verify their email, and complete Know Your Business (KYB) review entirely through the API and portal.

POST /api/Auth/register — create a partner account with company name, email, and contact details.
POST /api/Auth/verifyEmailCode — verify your email address with the OTP sent at registration.
POST /api/Auth/resendVerificationEmail — request a new OTP if yours expired.
KYB document submission: upload Certificate of Incorporation, Director ID, and Utility Bill for compliance review.
Production access request workflow: once sandbox testing is complete, submit a go-live request for review.

KYC Verification

Automated identity verification for individuals and businesses, with PII masking on all responses.

POST /api/v1/kyc/bvn/verify — verify a Bank Verification Number (BVN) against the central bank registry. Returns name match and masked identity fields.
POST /api/v1/kyc/nin/verify — verify a National Identification Number (NIN) against the NIMC database. Returns name match and masked identity fields.
POST /api/v1/kyc/cac/lookup — look up a company by its Corporate Affairs Commission (CAC) registration number. Returns company status, registered address, and director information.

All three endpoints mask PII in responses: BVN, NIN, date of birth, and phone numbers are never returned in full.

API Key Management

Full lifecycle management for API credentials.

Generate API keys (sandbox and production, scoped separately).
Rotate keys — generate a new key while the old one remains active for a grace period.
Revoke keys — immediately invalidate a key. Revocation is instant and irreversible.
Key hashing: raw keys are never stored; only Argon2id hashes are retained.

Virtual Accounts

Create and manage virtual bank accounts issued under Union Bank’s licence.

POST /api/v1/accounts — create a virtual account. Two types supported:
- STATIC: a permanent account number assigned to a customer. Suitable for wallets, savings products, and any use case where the customer has a stable account identity.
- DYNAMIC: a single-use account number generated for a specific expected payment. Expires after the payment is received or after a configurable timeout.
GET /api/v1/accounts/{accountNumber} — retrieve account details and current balance.
GET /api/v1/accounts/{accountNumber}/transactions — list transaction history with pagination.

Payments

Initiate outbound transfers through the Nigerian interbank payment networks.

POST /api/v1/payments/account-enquiry — look up an account at any Nigerian bank before sending a transfer. Returns account name for confirmation.
POST /api/v1/payments/transfer — initiate an outbound transfer. Two schemes supported:
- NIP (NIBSS Instant Payment): real-time, 24/7, settles in seconds. Maximum ₦10,000,000 per transaction.
- NEFT (Nigeria Electronic Funds Transfer): scheduled batch, settles same day or next day. No maximum limit.
Idempotency keys supported on all transfer requests — duplicate requests with the same key return the original response without creating a second transaction.
GET /api/v1/payments/{reference} — query the status of a payment by its reference number.

Collections

Receive inbound payments from customers into your virtual accounts.

Virtual collection accounts: each virtual account can receive inbound NIP transfers from any Nigerian bank.
Real-time webhook notifications on every incoming credit — your system is notified the moment funds arrive.
GET /api/v1/accounts/{accountNumber}/transactions — query received payments with full metadata including the sender’s name, bank, and narration.

Webhooks

Event-driven notifications for asynchronous operations.

POST /api/v1/webhooks — register a webhook endpoint URL for your partner account.
GET /api/v1/webhooks — list all registered webhook endpoints.
DELETE /api/v1/webhooks/{webhookId} — remove a webhook endpoint.
GET /api/v1/webhooks/deliveries — view delivery history including HTTP status codes, response times, and retry attempts.
Automatic retry with exponential backoff: failed deliveries are retried up to 5 times over 24 hours.
HMAC-SHA256 signatures on every delivery: verify the X-UBN-Signature header to confirm authenticity.

Events supported at launch:

Event	Trigger
`payment.transfer.success`	Outbound transfer completed
`payment.transfer.failed`	Outbound transfer failed
`collection.received`	Inbound credit to a virtual account
`kyc.verification.completed`	KYC check returned a result
`account.created`	New virtual account provisioned

Sandbox Environment

Full production-equivalent testing environment.

Sandbox base URL: https://sandbox.api.unionbank.ng
Pre-configured test data for BVN, NIN, CAC, and account number verification.
GET /dev/outbox-preview — inspect the last 50 emails and SMS messages that would have been sent in production.
Identical rate limits to production — backoff logic tested in sandbox works correctly in production.
Instant transfer settlement — no need to wait for batch windows during development.

Control	Detail
API key hashing	Argon2id — raw keys are never stored
Document encryption at rest	AES-256 for all uploaded KYB documents
Encryption in transit	TLS 1.3 on all API endpoints
Mutual TLS (mTLS)	Required for production payment and KYC calls
Request signing	HMAC-SHA256 for all payment and KYC requests
Environment isolation	Sandbox and production share no data or infrastructure
WORM audit logging	Immutable record of every API call and data access event
Circuit breaker protection	Automatic failure isolation for upstream payment network dependencies
SAST/DAST scanning	Run on every code change before deployment

Standard	Status
OpenAPI 3.1.0 specification	Full spec published at `/api-reference/openapi.yaml`
RFC 7807 Problem Details	All error responses use the standard `type`, `title`, `status`, `detail` format
NDPR compliance	PII minimisation, consent capture, immutable audit trail
CBN KYC guidelines	BVN/NIN verification aligned to current CBN KYC circular

v1.0.0 — 25 March 2026