Customers API — manage payment customers

Customers represent the end users who interact with your payment flows — they can receive NGN virtual bank accounts, undergo KYC verification to unlock higher transaction limits, and maintain a balance ledger you can query at any time. All customer resources are scoped to your merchant account; customers created by one merchant are never visible to another.

Authentication

All endpoints require either a Bearer token or an API key.

Authorization: Bearer <access_token>

X-Api-Key: dubu_sk_live_...

Create a customer

POST https://api.dubupay.com/api/v1/customers Creates a new customer record. The email address must be unique within your merchant account.

Request body

string

required

A valid email address for the customer. Must be unique within your merchant account.

first_name

string

required

The customer’s first name. Between 1 and 100 characters.

last_name

string

required

The customer’s last name. Between 1 and 100 characters.

Response

success

boolean

true when the request succeeds.

data

object

The created customer object.

Show data fields

string

Unique UUID for the customer.

string

The customer’s email address.

first_name

string

The customer’s first name.

last_name

string

The customer’s last name.

kyc_tier

string

Current KYC tier. One of TIER_0, TIER_1, TIER_2.

created_at

string

ISO 8601 timestamp of when the customer was created.

Example

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.obi@example.com",
    "first_name": "Ada",
    "last_name": "Obi"
  }'

List customers

GET https://api.dubupay.com/api/v1/customers Returns a paginated list of customers belonging to your merchant account. Use cursor-based pagination for large datasets.

Query parameters

limit

number

Maximum number of customers to return. Positive integer, up to 200. Defaults to 20.

cursor

string

Pagination cursor from the previous response’s next_cursor field.

string

Filter by exact email address.

Example

curl "https://api.dubupay.com/api/v1/customers?limit=50" \
  -H "X-Api-Key: dubu_sk_live_..."

Get a customer

GET https://api.dubupay.com/api/v1/customers/:id Retrieves a single customer by their UUID.

Path parameters

string

required

The customer’s UUID.

Example

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

Update a customer

PATCH https://api.dubupay.com/api/v1/customers/:id Updates the customer’s name. At least one of first_name or last_name must be provided.

Path parameters

string

required

The customer’s UUID.

Request body

first_name

string

Updated first name. Between 1 and 100 characters.

last_name

string

Updated last name. Between 1 and 100 characters.

At least one of first_name or last_name must be included in the request body.

Example

curl -X PATCH "https://api.dubupay.com/api/v1/customers/cus_01HXYZ" \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"last_name": "Okonkwo"}'

Submit Tier 1 KYC

POST https://api.dubupay.com/api/v1/customers/:id/tier1-verification Submits a customer’s BVN (Bank Verification Number) and a selfie image to initiate Tier 1 identity verification. Tier 1 unlocks basic transaction limits.

Path parameters

string

required

The customer’s UUID.

Request body

bvn

string

required

The customer’s 11-digit Bank Verification Number. Must contain only digits.

image_url

string

required

A publicly accessible URL to a selfie or portrait photo of the customer.

Example

curl -X POST "https://api.dubupay.com/api/v1/customers/cus_01HXYZ/tier1-verification" \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901",
    "image_url": "https://cdn.example.com/selfies/ada-obi.jpg"
  }'

Submit Tier 2 KYC

POST https://api.dubupay.com/api/v1/customers/:id/tier2-verification Submits full KYC documentation for Tier 2 verification. Tier 2 unlocks higher limits and is required for permanent virtual accounts. You must provide residential address, government-issued identification, and declarations about the customer’s financial profile.

Path parameters

string

required

The customer’s UUID.

Request body

residential_address

object

required

The customer’s current home address.

Show residential_address fields

street_line_1

string

required

Primary street address line.

city

string

required

City name.

subdivision

string

required

State, province, or region.

postal_code

string

required

Postal or ZIP code.

country

string

required

ISO 3166-1 alpha-3 country code (e.g., NGA).

nationality

string

required

ISO 3166-1 alpha-3 country code for the customer’s nationality (e.g., NGA).

birth_date

string

required

Date of birth in YYYY-MM-DD format.

identifying_information

array

required

At least one government-issued identity document.

Show document fields

type

string

required

Document type. One of passport, drivers_license, national_id.

issuing_country

string

required

ISO 3166-1 alpha-3 country code of the issuing country.

number

string

Document number (optional).

expiration

string

Expiry date in YYYY-MM-DD format.

image_front

string

required

URL to the front-side image of the document.

image_back

string

URL to the back-side image of the document (optional).

source_of_funds

string

required

Where the customer’s funds originate. One of: company_funds, ecommerce_reseller, gambling_proceeds, gifts, government_benefits, inheritance, investments_loans, pension_retirement, salary, sale_of_assets_real_estate, savings, someone_elses_funds.

account_purpose

string

required

The intended purpose of the account. One of: charitable_donations, ecommerce_retail_payments, investment_purposes, operating_a_company, other, payments_to_friends_or_family_abroad, personal_or_living_expenses, protect_wealth, purchase_goods_and_services, receive_payment_for_freelancing, receive_salary.

expected_monthly_payments_usd

string

required

Expected monthly USD transaction volume. One of: 0_4999, 5000_9999, 10000_49999, 50000_plus.

acting_as_intermediary

boolean

required

Whether the customer is acting as a payment intermediary on behalf of another party.

employment_status

string

required

Employment status. One of: employed, homemaker, retired, self_employed, student, unemployed.

most_recent_occupation

string

required

Occupation category. One of: BUSINESS_ADMIN, STEM, HEALTHCARE_SOCIAL, EDUCATION_ARTS_MEDIA, SERVICE_PUBLIC_SAFETY, TRADES_LABOR.

documents

array

Optional supporting documents (e.g., proof of address, proof of source of funds).

Show document fields

file

string

required

URL to the supporting document file.

purposes

array

required

Purposes this document satisfies. At least one of: proof_of_address, proof_of_source_of_funds.

Get customer balance

GET https://api.dubupay.com/api/v1/customers/:id/balance Returns the current balance held for a customer across all currencies.

Path parameters

string

required

The customer’s UUID.

Response

data

object

Balance breakdown for the customer.

Show data fields

ngn

string

Current NGN balance as a decimal string.

usd

string

Current USD-equivalent balance as a decimal string.

updated_at

string

ISO 8601 timestamp of the last balance update.

Example

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

Get customer ledger

GET https://api.dubupay.com/api/v1/customers/:id/ledger Returns a paginated transaction history (ledger) for a customer, showing credits and debits over time.

Path parameters

string

required

The customer’s UUID.

Response

data

array

List of ledger entries.

Show entry fields

string

Unique ledger entry ID.

type

string

Entry type, e.g., CREDIT or DEBIT.

amount

string

Transaction amount as a decimal string.

currency

string

Currency code, e.g., NGN.

description

string

Human-readable description of the transaction.

created_at

string

ISO 8601 timestamp.

Example

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

Overview

Auth

Payments

Trading

Commerce

Webhooks

Customers API — manage payment customers

Authentication

Create a customer

Request body

Response

Example

List customers

Query parameters

Example

Get a customer

Path parameters

Example

Update a customer

Path parameters

Request body

Example

Submit Tier 1 KYC

Path parameters

Request body

Example

Submit Tier 2 KYC

Path parameters

Request body

Get customer balance

Path parameters

Response

Example

Get customer ledger

Path parameters

Response

Example

Overview

Auth

Payments

Trading

Commerce

Webhooks

Documentation Index

​Authentication

​Create a customer

​Request body

​Response

​Example

​List customers

​Query parameters

​Example

​Get a customer

​Path parameters

​Example

​Update a customer

​Path parameters

​Request body

​Example

​Submit Tier 1 KYC

​Path parameters

​Request body

​Example

​Submit Tier 2 KYC

​Path parameters

​Request body

​Get customer balance

​Path parameters

​Response

​Example

​Get customer ledger

​Path parameters

​Response

​Example

Authentication

Create a customer

Request body

Response

Example

List customers

Query parameters

Example

Get a customer

Path parameters

Example

Update a customer

Path parameters

Request body

Example

Submit Tier 1 KYC

Path parameters

Request body

Example

Submit Tier 2 KYC

Path parameters

Request body

Get customer balance

Path parameters

Response

Example

Get customer ledger

Path parameters

Response

Example