Managing customers in the Dubu Pay API

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"
}

Field	Type	Description
`id`	UUID	Unique identifier for the customer. Use this in all subsequent requests.
`email`	string	Customer email address. Must be unique within your merchant account.
`first_name`	string	Given name (1–100 characters).
`last_name`	string	Family name (1–100 characters).
`kyc_tier`	string	Current verification level: `UNVERIFIED`, `TIER_1`, or `TIER_2`.
`created_at`	ISO 8601	Timestamp when the customer was created.
`updated_at`	ISO 8601	Timestamp 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 — Basic identity
Tier 2 — Advanced identity

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.

Tier 2 collects a full identity profile including residential address, nationality, date of birth, a government-issued ID document, and source-of-funds information. Submit it via POST /customers/:id/tier2-verification.What you need:

residential_address — street, city, subdivision, postal code, and ISO 3166-1 alpha-3 country code
nationality — ISO 3166-1 alpha-3 country code
birth_date — YYYY-MM-DD format
identifying_information — at least one document of type passport, drivers_license, or national_id, with image_front and expiration date
source_of_funds — one of: salary, savings, company_funds, investments_loans, inheritance, and others
account_purpose — e.g. ecommerce_retail_payments, receive_payment_for_freelancing
expected_monthly_payments_usd — one of 0_4999, 5000_9999, 10000_49999, 50000_plus
employment_status and most_recent_occupation
acting_as_intermediary — boolean, must be false for standard merchant use

What it unlocks:

Permanent NGN virtual bank accounts (no expiry)
Higher transaction and balance limits

All Tier 2 document images must be hosted at publicly accessible URLs. Dubu Pay fetches them during verification — do not use presigned URLs that expire quickly.

Customer lifecycle

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"}'

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"}'

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.

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

Method	Path	Description
`POST`	`/customers`	Create a new customer
`GET`	`/customers`	List customers (supports `email`, `limit`, `cursor` filters)
`GET`	`/customers/:id`	Retrieve a single customer
`PATCH`	`/customers/:id`	Update `first_name` or `last_name`
`POST`	`/customers/:id/tier1-verification`	Submit Tier 1 KYC (BVN + selfie)
`POST`	`/customers/:id/tier2-verification`	Submit Tier 2 KYC (full identity profile)
`POST`	`/customers/:id/kyc/initiate`	Initiate Tier 1 KYC flow via BVN
`POST`	`/customers/:id/tier2-kyc/initiate`	Initiate Tier 2 KYC flow
`POST`	`/customers/:id/ngn-virtual-account`	Issue a permanent NGN virtual account
`GET`	`/customers/:id/ngn-virtual-account`	Retrieve the customer’s NGN virtual account
`POST`	`/customers/:id/crypto-wallet`	Register a crypto wallet destination
`GET`	`/customers/:id/crypto-wallets`	List registered crypto wallets
`POST`	`/customers/:id/crypto-funding`	Create a crypto funding request
`GET`	`/customers/:id/balance`	Get the customer’s current USDT balance
`GET`	`/customers/:id/ledger`	List the customer’s transaction ledger

List customers with pagination

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_..."

Filter customers by email

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_..."

Supported crypto chains for wallets and funding

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.

Get Started

Authentication

Core Concepts

Guides

Account & Security

Managing customers in the Dubu Pay API

The customer object

KYC tiers

Customer lifecycle

How customers relate to other resources

Endpoint overview

​The customer object

​KYC tiers

​Customer lifecycle

​How customers relate to other resources

​Endpoint overview

The customer object

KYC tiers

Customer lifecycle

How customers relate to other resources

Endpoint overview