Authentication
All endpoints require either a Bearer token or an API key.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.
string
required
The customer’s first name. Between 1 and 100 characters.
string
required
The customer’s last name. Between 1 and 100 characters.
Response
boolean
true when the request succeeds.object
The created customer object.
Example
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
number
Maximum number of customers to return. Positive integer, up to 200. Defaults to 20.
string
Pagination cursor from the previous response’s
next_cursor field.string
Filter by exact email address.
Example
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
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
string
Updated first name. Between 1 and 100 characters.
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
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
string
required
The customer’s 11-digit Bank Verification Number. Must contain only digits.
string
required
A publicly accessible URL to a selfie or portrait photo of the customer.
Example
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
object
required
The customer’s current home address.
string
required
ISO 3166-1 alpha-3 country code for the customer’s nationality (e.g.,
NGA).string
required
Date of birth in
YYYY-MM-DD format.array
required
At least one government-issued identity document.
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.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.string
required
Expected monthly USD transaction volume. One of:
0_4999, 5000_9999, 10000_49999, 50000_plus.boolean
required
Whether the customer is acting as a payment intermediary on behalf of another party.
string
required
Employment status. One of:
employed, homemaker, retired, self_employed, student, unemployed.string
required
Occupation category. One of:
BUSINESS_ADMIN, STEM, HEALTHCARE_SOCIAL, EDUCATION_ARTS_MEDIA, SERVICE_PUBLIC_SAFETY, TRADES_LABOR.array
Optional supporting documents (e.g., 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
object
Balance breakdown for the customer.
Example
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
array
List of ledger entries.