NGN virtual bank accounts in Dubu Pay

A virtual bank account is a Nigerian Naira bank account number that Dubu Pay provisions on your behalf. You give the account details to your customer, they make a local bank transfer, and Dubu Pay detects the deposit, converts it to USDT at the prevailing exchange rate, and records it against your merchant balance. From your customer’s point of view it looks like a standard Nigerian bank transfer — there is no crypto interface required on their end.

Two types of virtual account

Dubu Pay offers two types of NGN virtual account, each suited to different use cases.

	Temporary	Permanent
Expiry	25 minutes after creation	No expiry
Amount	Fixed — set at creation	Floating — any amount accepted
Exchange rate	Locked at creation	Live rate at time of deposit
Customer BVN required	No	Yes (Tier 2 KYC)
Best for	Checkout flows, invoices, one-off payments	Recurring deposits, customer wallets

Temporary accounts

A temporary account is valid for exactly 25 minutes. You specify the exact NGN amount the customer should send, and the exchange rate is locked in at the moment you create the account. If the customer sends a different amount or pays after expiry, the account will not accept the payment. Use temporary accounts for:

Checkout pages where the customer pays a fixed invoice amount
Time-limited payment links
Any flow where you want certainty about the rate and amount

If a customer pays after the 25-minute window, the account is expired and will not settle the deposit. Always make the expiry visible in your UI and provide a way for the customer to request a new account if needed.

Permanent accounts

A permanent account has no expiry and accepts any NGN amount. The exchange rate is applied at the time each deposit clears, not at account creation. Permanent accounts require the associated customer to have completed Tier 2 KYC, including BVN verification. Use permanent accounts for:

Customers who top up a wallet balance repeatedly over time
Subscription-style payment acceptance
Any integration where you want to give a customer a stable, reusable bank account number

Permanent accounts are the preferred choice when you manage an ongoing customer relationship. They eliminate the need to re-issue an account for every payment.

Virtual account fields

A virtual account object returned by the API includes:

{
  "id": "va_01HZ...",
  "account_number": "0123456789",
  "bank_name": "Example MFB",
  "account_name": "Dubu Pay / Ada Lovelace",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "TEMPORARY",
  "status": "active",
  "expires_at": "2025-01-15T09:25:00Z",
  "amount": 50000,
  "currency": "NGN",
  "created_at": "2025-01-15T09:00:00Z"
}

Field	Type	Description
`id`	string	Unique virtual account identifier.
`account_number`	string	The Nigerian bank account number to share with your customer.
`bank_name`	string	Name of the issuing bank or microfinance institution.
`account_name`	string	Account name your customer will see when they look up the account.
`customer_id`	UUID	The customer this account belongs to.
`type`	string	`TEMPORARY` or `PERMANENT`.
`status`	string	`active` or `inactive`.
`expires_at`	ISO 8601	Expiry timestamp for temporary accounts; `null` for permanent.
`amount`	number	Expected NGN amount (temporary accounts only).
`currency`	string	Always `NGN`.

How deposits flow

When a customer sends money to a virtual account, the deposit progresses through several internal states before it appears as settled funds.

Status	Meaning
`PENDING_FX`	Deposit received. Dubu Pay is processing the NGN-to-USDT conversion.
`PENDING_WITHDRAWAL`	Conversion complete. The USDT is being routed to the settlement destination.
`SETTLED`	USDT has been credited to your merchant balance (or to the customer’s balance, depending on settlement mode).
`FAILED`	The deposit could not be processed. No funds have moved.
`FLAGGED`	The deposit has been flagged for compliance review. It will not settle until cleared.
`REVERSED`	A previously settled deposit has been reversed. The credited USDT has been debited back.

You should listen for webhook events to track deposit status changes in real time rather than polling the deposits endpoint. Dubu Pay emits an event for each status transition.

Creating virtual accounts

You can create virtual accounts in two ways:

Via the customers endpoint
Via the payments/onramps endpoint

Issue a permanent NGN virtual account directly against a customer record. The customer must have completed Tier 2 KYC.

curl -X POST https://api.dubupay.com/api/v1/customers/{customer_id}/ngn-virtual-account \
  -H "X-Api-Key: dubu_sk_live_..."

Retrieve the existing account for a customer:

curl https://api.dubupay.com/api/v1/customers/{customer_id}/ngn-virtual-account \
  -H "X-Api-Key: dubu_sk_live_..."

Create an onramp (virtual account) of either type with full control over settlement mode and asset.

curl -X POST https://api.dubupay.com/api/v1/payments/onramps \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TEMPORARY",
    "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "rate_id": "rate_01HZ...",
    "amount": 50000,
    "settlement": {
      "mode": "INTERNAL_BALANCE",
      "asset": "USDT"
    }
  }'

For a permanent account, omit amount and rate_id and ensure the customer has Tier 2 KYC:

curl -X POST https://api.dubupay.com/api/v1/payments/onramps \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PERMANENT",
    "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "settlement": {
      "mode": "INTERNAL_BALANCE",
      "asset": "USDT"
    }
  }'

Settlement modes

When creating an onramp you choose how the converted USDT is delivered after a deposit settles:

Mode	Description
`INTERNAL_BALANCE`	USDT is credited to your Dubu Pay merchant balance. Use this if you manage payouts yourself.
`ONCHAIN`	USDT is sent directly to a blockchain address you specify. Requires `chain` and `destination_address`.

Endpoint overview

Method	Path	Description
`POST`	`/payments/onramps`	Create a temporary or permanent virtual account
`GET`	`/payments/onramps`	List all onramps
`GET`	`/payments/onramps/:id`	Get a specific onramp
`POST`	`/customers/:id/ngn-virtual-account`	Issue a permanent account directly to a customer
`GET`	`/customers/:id/ngn-virtual-account`	Retrieve a customer’s permanent account
`GET`	`/customers/:id/virtual-accounts`	List all virtual accounts belonging to a customer
`GET`	`/virtual-accounts`	List all virtual accounts (supports `status`, `customer_id` filters)
`GET`	`/virtual-accounts/:id`	Get a specific virtual account

Get Started

Authentication

Core Concepts

Guides

Account & Security

NGN virtual bank accounts in Dubu Pay

Two types of virtual account

Temporary accounts

Permanent accounts

Virtual account fields

How deposits flow

Creating virtual accounts

Settlement modes

Endpoint overview

​Two types of virtual account

​Temporary accounts

​Permanent accounts

​Virtual account fields

​How deposits flow

​Creating virtual accounts

​Settlement modes

​Endpoint overview

Two types of virtual account

Temporary accounts

Permanent accounts

Virtual account fields

How deposits flow

Creating virtual accounts

Settlement modes

Endpoint overview