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.

A customer in Dubu Pay represents one of your end users — the individual who pays money into a virtual account, accumulates a balance, or receives funds. You create and manage customers through the API; Dubu Pay stores them on your behalf, scoped entirely to your merchant account. Every virtual bank account, deposit record, balance entry, and ledger line is tied to a customer, so creating customers before issuing accounts is the recommended starting point for any integration.

​
The customer object

When you create or retrieve a customer, the API returns an object with the following shape: 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "kyc_tier": "TIER_1",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T09:00:00Z"
}
FieldTypeDescription
idUUIDUnique identifier for the customer. Use this in all subsequent requests.
emailstringCustomer email address. Must be unique within your merchant account.
first_namestringGiven name (1–100 characters).
last_namestringFamily name (1–100 characters).
kyc_tierstringCurrent verification level: UNVERIFIED, TIER_1, or TIER_2.
created_atISO 8601Timestamp when the customer was created.
updated_atISO 8601Timestamp of the most recent change.

​
KYC tiers

Dubu Pay uses a two-tier KYC system. Each tier unlocks additional account features and higher transaction limits.
Tier 1 verifies a customer’s identity using their BVN (Bank Verification Number) and a selfie image. You submit both when calling POST /customers/:id/tier1-verification.What you need:
  • bvn — exactly 11 digits
  • image_url — a URL pointing to the customer’s selfie
What it unlocks:
  • Issuing NGN virtual bank accounts (onramps)
  • Standard deposit limits
You can also initiate KYC via POST /customers/:id/kyc/initiate if you want Dubu Pay to drive the verification flow on your behalf — just supply the customer’s BVN.

​
Customer lifecycle

1

Create the customer

Call POST /customers with the customer’s email, first_name, and last_name. You receive a customer id in the response.
curl -X POST https://api.dubupay.com/api/v1/customers \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace"}'
2

Submit KYC verification

Submit Tier 1 verification to unlock virtual account issuance. Pass the customer’s BVN and a selfie URL.
curl -X POST https://api.dubupay.com/api/v1/customers/{id}/tier1-verification \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"bvn": "12345678901", "image_url": "https://cdn.example.com/selfie.jpg"}'
3

Issue a virtual account

Once the customer is verified, create an NGN virtual bank account for them via POST /customers/{id}/ngn-virtual-account. For a permanent account, the customer must be Tier 2 verified.
4

Track balance and ledger

Poll GET /customers/{id}/balance to see the customer’s current USDT balance, or GET /customers/{id}/ledger to retrieve a full transaction history.

​
How customers relate to other resources

Each customer can have:
  • One permanent NGN virtual account — linked for receiving deposits long-term
  • Multiple temporary virtual accounts — short-lived accounts tied to a specific payment
  • Crypto wallets — destination addresses on supported chains (APTOS, BASE, CELO, ETHEREUM, POLYGON, SOLANA, TRON)
  • A balance — aggregated USDT value of settled deposits
  • A ledger — paginated chronological record of all credits and debits
Store the customer id in your own database alongside your internal user record. You will use it for every subsequent Dubu Pay operation — issuing accounts, checking balances, and retrieving ledger history.

​
Endpoint overview

MethodPathDescription
POST/customersCreate a new customer
GET/customersList customers (supports email, limit, cursor filters)
GET/customers/:idRetrieve a single customer
PATCH/customers/:idUpdate first_name or last_name
POST/customers/:id/tier1-verificationSubmit Tier 1 KYC (BVN + selfie)
POST/customers/:id/tier2-verificationSubmit Tier 2 KYC (full identity profile)
POST/customers/:id/kyc/initiateInitiate Tier 1 KYC flow via BVN
POST/customers/:id/tier2-kyc/initiateInitiate Tier 2 KYC flow
POST/customers/:id/ngn-virtual-accountIssue a permanent NGN virtual account
GET/customers/:id/ngn-virtual-accountRetrieve the customer’s NGN virtual account
POST/customers/:id/crypto-walletRegister a crypto wallet destination
GET/customers/:id/crypto-walletsList registered crypto wallets
POST/customers/:id/crypto-fundingCreate a crypto funding request
GET/customers/:id/balanceGet the customer’s current USDT balance
GET/customers/:id/ledgerList the customer’s transaction ledger
The GET /customers endpoint uses cursor-based pagination. Pass cursor from the previous response to fetch the next page, and use limit (max 200) to control page size.
curl "https://api.dubupay.com/api/v1/customers?limit=50&cursor=eyJpZCI6IjEyMyJ9" \
  -H "X-Api-Key: dubu_sk_live_..."
Pass email as a query parameter to look up a specific customer without knowing their ID.
curl "https://api.dubupay.com/api/v1/customers?email=ada@example.com" \
  -H "X-Api-Key: dubu_sk_live_..."
When creating a crypto wallet or crypto funding request, chain must be one of:APTOS, BASE, CELO, ETHEREUM, POLYGON, SOLANA, TRONThe asset field accepts USDC or USDT.