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.

Dubu Pay gives you a fully managed payment and trading experience through a single REST API. By the end of this guide you will have a working merchant account, a live API key, a customer record, and a virtual bank account ready to receive NGN payments.
All API requests use the base URL https://api.dubupay.com/api/v1. Responses follow the shape { "success": true, "data": { ... } } for successful requests.

​
Prerequisites

  • A valid business email address
  • Node.js 18+ or any HTTP client (the examples below use cURL and the native fetch API)

​
Steps

1

Register your merchant account

Send a POST request to /auth/register with your business name, email, and a password of at least eight characters.Request body
​
business_name
string
required
Your legal business or trading name. Minimum two characters.
​
email
string
required
The email address you will use to sign in to Dubu Pay.
​
password
string
required
A password of at least eight characters.
curl --request POST \
  --url https://api.dubupay.com/api/v1/auth/register \
  --header 'Content-Type: application/json' \
  --data '{
    "business_name": "Acme Store",
    "email": "dev@acme.io",
    "password": "supersecret123"
  }'
Example response
{
  "success": true,
  "data": {
    "id": "mch_01j9k2p...",
    "business_name": "Acme Store",
    "email": "dev@acme.io",
    "is_verified": false,
    "created_at": "2025-09-01T10:00:00.000Z"
  }
}
2

Verify your email address

After registering, Dubu Pay sends a six-digit OTP to your email. Submit it to /auth/verify-email to activate your account.
​
email
string
required
The email address you registered with.
​
otp
string
required
The six-digit numeric code sent to your inbox.
curl --request POST \
  --url https://api.dubupay.com/api/v1/auth/verify-email \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "dev@acme.io",
    "otp": "482910"
  }'
Example response
{
  "success": true,
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "eyJhbGci..."
  }
}
If your OTP expires before you can use it, call POST /auth/resend-otp with your email to request a new one.
3

Log in and obtain tokens

Log in to receive an access token (valid for 15 minutes) and a refresh token (valid for 7 days). You need the access token to complete onboarding steps in the dashboard and to create your first API key.
​
email
string
required
Your registered email address.
​
password
string
required
Your account password.
curl --request POST \
  --url https://api.dubupay.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "dev@acme.io",
    "password": "supersecret123"
  }'
Example response
{
  "success": true,
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "eyJhbGci...",
    "merchant": {
      "id": "mch_01j9k2p...",
      "business_name": "Acme Store",
      "email": "dev@acme.io"
    }
  }
}
4

Create an API key

For server-side integrations, API keys are more convenient than short-lived JWT tokens. Create one now using the access token from the previous step.
The full API key is returned only once at creation time. Copy it immediately and store it in a secret manager or environment variable. You cannot retrieve it again.
​
name
string
required
A human-readable label for this key, such as "production-server" or "staging". Maximum 100 characters.
​
environment
string
"sandbox" (default) or "live". Sandbox keys have the prefix dubu_sk_test_; live keys have dubu_sk_live_.
curl --request POST \
  --url https://api.dubupay.com/api/v1/api-keys \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "production-server",
    "environment": "live"
  }'
Example response
{
  "success": true,
  "data": {
    "id": "3f7a1c2e-...",
    "name": "production-server",
    "key_prefix": "dubu_sk_live_AbCdEf",
    "environment": "live",
    "created_at": "2025-09-01T10:05:00.000Z",
    "key": "dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345"
  }
}
From this point on, pass the API key in the X-Api-Key header instead of a Bearer token.
5

Create your first customer

Before issuing a virtual bank account, you need a customer record. Customers represent the end-users who will send payments to you.
curl --request POST \
  --url https://api.dubupay.com/api/v1/payments/customers \
  --header 'X-Api-Key: dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Amara",
    "last_name": "Okafor",
    "email": "amara@example.com",
    "phone": "+2348012345678"
  }'
Example response
{
  "success": true,
  "data": {
    "id": "cus_9f3b...",
    "first_name": "Amara",
    "last_name": "Okafor",
    "email": "amara@example.com",
    "phone": "+2348012345678",
    "created_at": "2025-09-01T10:06:00.000Z"
  }
}
6

Issue a virtual bank account

With a customer ID in hand, create a virtual bank account (onramp) so your customer can send an NGN payment. Use TEMPORARY type for a one-time payment with a locked exchange rate and a 25-minute expiry, or PERMANENT type for a reusable account (requires customer BVN).
curl --request POST \
  --url https://api.dubupay.com/api/v1/payments/onramps \
  --header 'X-Api-Key: dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cus_9f3b...",
    "type": "TEMPORARY",
    "amount": 50000
  }'
Example response
{
  "success": true,
  "data": {
    "id": "onr_7d2a...",
    "type": "TEMPORARY",
    "status": "ACTIVE",
    "amount": 50000,
    "currency": "NGN",
    "account_number": "0123456789",
    "bank_name": "Wema Bank",
    "account_name": "DUBUPAY / ACME STORE",
    "expires_at": "2025-09-01T10:31:00.000Z",
    "created_at": "2025-09-01T10:06:00.000Z"
  }
}
Share the account_number and bank_name with your customer. When they transfer funds, a deposit record is created and progresses through the statuses PENDING_FX → PENDING_WITHDRAWAL → SETTLED.

​
What’s next

Authentication

Understand JWT tokens, API keys, and when to use each.

API keys

Create, list, revoke, and delete API keys for your integration.