Skip to main content

​
Overview

A virtual account is a real Nigerian bank account number (NUBAN format) assigned to one of your customers or use cases. Funds deposited into this account appear in your platform’s ledger immediately. You can create as many virtual accounts as you need — one per customer, one per transaction, or one per product. Virtual accounts created in sandbox use test NUBANs that do not process real money. Production accounts are fully live.

​
Base URL

EnvironmentBase URL
Sandboxhttps://sandbox.api.unionbank.ng
Productionhttps://api.unionbank.ng

​
Authentication

All Accounts endpoints require an API key in the request header: 
Authorization: ApiKey <your-api-key>

​
Endpoints

​
Create Virtual Account

POST /v1/accounts Creates a new virtual account. The platform generates a unique NUBAN (10-digit Nigerian bank account number) and links it to your business. What you send:
FieldTypeRequiredDescription
customer_idstringYesYour internal ID for the customer this account belongs to
account_namestringYesDisplay name for the account (e.g., customer’s full name or a label like “Escrow - Order 4521”)
currencystringYesAlways NGN (Nigerian Naira)
typestringNoindividual or business. Defaults to individual
metadataobjectNoAny key-value pairs you want to store alongside this account (e.g., {"order_id": "ORD-001"})
What you get back:
FieldDescription
account_idUnique ID used to reference this account in future API calls
account_number10-digit NUBAN — the number your customer gives to senders
bank_nameAlways Union Bank of Nigeria
bank_codeCBN bank code for Union Bank
account_nameConfirmed display name
statusactive — the account is ready immediately
Example request: 
{
  "customer_id": "cust_8f3a2b",
  "account_name": "Amina Bello",
  "currency": "NGN",
  "type": "individual",
  "metadata": {
    "plan": "premium",
    "signup_date": "2024-01-15"
  }
}
Example response: 
{
  "account_id": "acct_9d7e1c",
  "account_number": "0123456789",
  "bank_name": "Union Bank of Nigeria",
  "bank_code": "032",
  "account_name": "Amina Bello",
  "currency": "NGN",
  "status": "active",
  "created_at": "2024-01-15T10:23:00+01:00"
}

​
Get Account Details

GET /v1/accounts/{account_id} Retrieve the current balance and details for a single virtual account. Path parameter:
ParameterDescription
account_idThe account_id returned when the account was created
What you get back:
FieldDescription
account_idUnique account identifier
account_number10-digit NUBAN
account_nameDisplay name
balanceCurrent available balance in kobo (1 Naira = 100 kobo). Divide by 100 to get Naira
ledger_balanceTotal balance including pending transactions
statusactive, frozen, or closed
currencyAlways NGN
Balances are returned in kobo, not Naira. A balance of 500000 means ₦5,000.00. This avoids floating-point precision issues in financial calculations.

​
List Accounts

GET /v1/accounts Returns a paginated list of all virtual accounts under your business. Query parameters:
ParameterTypeDefaultDescription
pageinteger1Page number
per_pageinteger20Results per page (max 100)
statusstringallFilter by active, frozen, or closed
customer_idstring—Return only accounts for this customer

​
List Account Transactions

GET /v1/accounts/{account_id}/transactions Returns all credits and debits for a specific virtual account, newest first. Query parameters:
ParameterTypeDefaultDescription
fromstring—Start date in YYYY-MM-DD format (WAT timezone)
tostring—End date in YYYY-MM-DD format
typestringallcredit or debit
pageinteger1Page number
per_pageinteger20Results per page (max 100)
Transaction object fields:
FieldDescription
transaction_idUnique ID for this transaction
typecredit (money in) or debit (money out)
amountAmount in kobo
balance_afterAccount balance after this transaction, in kobo
narrationDescription as it appears on a bank statement
referenceYour idempotency key or the sender’s reference
statuscompleted, pending, or reversed
timestampISO 8601 datetime in WAT (UTC+1)

​
Freeze / Unfreeze Account

PATCH /v1/accounts/{account_id} Temporarily prevent an account from sending or receiving funds. Useful for fraud holds or compliance reviews. What you send:
FieldTypeRequiredDescription
statusstringYesfrozen to freeze, active to unfreeze
reasonstringNoInternal reason for the status change (stored in audit log)

​
Close Account

DELETE /v1/accounts/{account_id} Permanently closes a virtual account. This action cannot be undone. Any remaining balance must be swept out before closing.
Closing an account is permanent. The NUBAN number is decommissioned and cannot be reactivated. Ensure the balance is zero before calling this endpoint.

​
Error Codes

HTTP StatusError CodeMeaning
400VALIDATION_ERRORMissing or invalid fields
404ACCOUNT_NOT_FOUNDNo account with this ID under your business
409ACCOUNT_ALREADY_CLOSEDAccount has already been closed
422BALANCE_NOT_ZEROCannot close an account with a remaining balance
429RATE_LIMIT_EXCEEDEDToo many requests — see Rate Limits

​
Full API Reference

Open API Playground

Try Accounts endpoints live in the browser