Documentation Index
Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt
Use this file to discover all available pages before exploring further.
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:
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_..."
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"
}
}'
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 |