Skip to main content

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.

Virtual accounts give your customers a real Nigerian Naira bank account number they can fund from any local bank. When NGN arrives in the account, Dubu Pay converts it to USDC or USDT and routes the proceeds to your configured settlement destination. You can issue accounts directly to a customer via the Customers API, or create standalone onramps with flexible settlement options.

​
Authentication

All endpoints require either a Bearer token or an API key. 
Authorization: Bearer <access_token>

X-Api-Key: dubu_sk_live_...

​
TEMPORARY vs PERMANENT accounts

FeatureTEMPORARYPERMANENT
Expiry25 minutes after creationNo expiry
RateLocked at creation timeFloating (current market rate)
amount fieldRequiredNot applicable
KYC requirementNoneCustomer must have Tier 1 BVN verification
Use TEMPORARY accounts for single-use checkout flows where you want to guarantee a fixed exchange rate for a short window. Use PERMANENT accounts for customers who deposit repeatedly over time.

​
Issue an NGN virtual account to a customer

POST https://api.dubupay.com/api/v1/customers/:id/ngn-virtual-account Creates a permanent NGN virtual bank account and links it to the specified customer. The customer must have completed at least Tier 1 KYC (BVN verification) before you can issue a permanent account.

​
Path parameters

​
id
string
required
The customer’s UUID.

​
Response

​
data
object
The issued virtual account details.

​
Example

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

​
Get a customer’s NGN virtual account

GET https://api.dubupay.com/api/v1/customers/:id/ngn-virtual-account Retrieves the NGN virtual account currently assigned to a customer.

​
Path parameters

​
id
string
required
The customer’s UUID.

​
Example

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

​
Create an onramp

POST https://api.dubupay.com/api/v1/payments/onramps Creates an NGN virtual bank account (onramp) with configurable type, settlement mode, and target asset. This is the most flexible way to accept NGN deposits.
This endpoint supports idempotency. Pass an X-Idempotency-Key header to safely retry requests without creating duplicate onramps.

​
Request body

​
type
string
required
The onramp type. One of TEMPORARY or PERMANENT. TEMPORARY accounts expire after 25 minutes with the rate locked at creation. PERMANENT accounts have no expiry and use the floating market rate at the time of deposit.
​
customer_id
string
UUID of the customer to associate with this onramp. Required for PERMANENT onramps.
​
rate_id
string
ID of a previously fetched rate to lock in for this onramp. See Exchange Rates.
​
amount
number
The NGN amount to lock for this virtual account. Required for TEMPORARY onramps.
​
settlement
object
How and where proceeds are settled after a deposit converts.

​
Response

​
data
object
The created onramp.

​
Example — TEMPORARY onramp

curl -X POST https://api.dubupay.com/api/v1/payments/onramps \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "X-Idempotency-Key: checkout-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TEMPORARY",
    "amount": 50000,
    "rate_id": "rate_abc123",
    "settlement": {
      "mode": "ONCHAIN",
      "asset": "USDT",
      "chain": "TRON",
      "destination_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
    }
  }'

​
Example — PERMANENT onramp with internal balance

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": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "settlement": {
      "mode": "INTERNAL_BALANCE",
      "asset": "USDT"
    }
  }'

​
List onramps

GET https://api.dubupay.com/api/v1/payments/onramps Returns a paginated list of onramps created under your merchant account.

​
Query parameters

​
page
number
Page number (1-indexed).
​
limit
number
Results per page. Up to 100.
​
status
string
Filter by status: ACTIVE, EXPIRED, or INACTIVE.

​
Example

curl "https://api.dubupay.com/api/v1/payments/onramps?status=ACTIVE&limit=20" \
  -H "X-Api-Key: dubu_sk_live_..."

​
Get an onramp

GET https://api.dubupay.com/api/v1/payments/onramps/:id Retrieves a single onramp by ID, including its current status and account details.

​
Path parameters

​
id
string
required
The onramp ID.

​
Example

curl "https://api.dubupay.com/api/v1/payments/onramps/onr_01HXYZ" \
  -H "X-Api-Key: dubu_sk_live_..."