curl --request POST \
  --url https://api-partner.onecluster.co/api/v1/accounts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "partnerId": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "accountType": "STATIC"
}
'

{
  "success": true,
  "responseCode": "00",
  "message": "Account created",
  "data": {
    "accountNumber": "0123456789",
    "bankCode": "032",
    "bankName": "Union Bank of Nigeria",
    "accountType": "STATIC",
    "currency": "NGN",
    "createdAt": "2026-03-25T10:00:00+01:00"
  }
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

Accounts Endpoints

Create Virtual Account

Opens a new virtual bank account. Virtual accounts are real Nigerian bank accounts (with valid account numbers) that sit under your master account.

Two types:

STATIC: Permanent account. Stays open until you close it. Good for assigning one account per customer.
DYNAMIC: Temporary account with an expiry time (in hours). After expiry, it is automatically closed. Good for one-time payment links.

Funds received into virtual accounts show up in your dashboard and trigger webhook notifications.

POST

api

accounts

curl --request POST \
  --url https://api-partner.onecluster.co/api/v1/accounts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "partnerId": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "accountType": "STATIC"
}
'

{
  "success": true,
  "responseCode": "00",
  "message": "Account created",
  "data": {
    "accountNumber": "0123456789",
    "bankCode": "032",
    "bankName": "Union Bank of Nigeria",
    "accountType": "STATIC",
    "currency": "NGN",
    "createdAt": "2026-03-25T10:00:00+01:00"
  }
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

Authorizations

Authorization

string

header

required

Your API key, formatted as: ApiKey ubn_sb_your_key_here

Sandbox keys start with ubn_sb_
Production keys start with ubn_pk_
Never use production keys during testing, they will charge real money

Headers

X-Correlation-ID

string<uuid>

A UUID v4 you generate to trace this request through our systems. If you don't provide one, we generate it for you. Always include it in support requests, it helps us find your request in logs.

Example:

"7f3a9c21-4e8b-4a12-b6d1-3c8a7f2e1b09"

X-Idempotency-Key

string<uuid>

required

A UUID you generate. If you send the same request twice with the same key (within 24 hours), we return the original response, not a duplicate action. Generate a new UUID for every new operation.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

partnerId

string<uuid>

required

Your Partner ID

accountType

enum<string>

required

STATIC: Permanent account (stays open until you close it)
DYNAMIC: Temporary account that auto-closes after expiryHours

Available options:

STATIC,

DYNAMIC

expiryHours

integer

How many hours until this account closes. Required when accountType is DYNAMIC.

Required range: 1 <= x <= 720

Example:

24

Response

Virtual account created

Standard response wrapper for all successful API calls

success

boolean

required

Always true for successful responses

Example:

true

responseCode

string

required

00 means success

Example:

"00"

message

string

required

Human-readable description of the result

Example:

"Request processed successfully"

data

object

required

The actual response data (varies by endpoint)

Accounts API Get Account Balance

API Reference

Health & Status

Accounts Endpoints

Payments Endpoints

Collections Endpoints

Billing Endpoints

KYC Endpoints

Create Virtual Account

Authorizations

Headers

Body

Response