Get started with Dubu Pay in minutes

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

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.

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

const response = await fetch('https://api.dubupay.com/api/v1/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    business_name: 'Acme Store',
    email: 'dev@acme.io',
    password: 'supersecret123',
  }),
});
const { data } = await response.json();

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

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.

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

const response = await fetch('https://api.dubupay.com/api/v1/auth/verify-email', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'dev@acme.io', otp: '482910' }),
});
const { data } = await response.json();

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.

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.

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

const response = await fetch('https://api.dubupay.com/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'dev@acme.io', password: 'supersecret123' }),
});
const { data } = await response.json();
const { access_token, refresh_token } = data;

Example response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "eyJhbGci...",
    "merchant": {
      "id": "mch_01j9k2p...",
      "business_name": "Acme Store",
      "email": "dev@acme.io"
    }
  }
}

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

const response = await fetch('https://api.dubupay.com/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'production-server', environment: 'live' }),
});
const { data } = await response.json();
const apiKey = data.key; // store this immediately

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.

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

const response = await fetch('https://api.dubupay.com/api/v1/payments/customers', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Amara',
    last_name: 'Okafor',
    email: 'amara@example.com',
    phone: '+2348012345678',
  }),
});
const { data } = await response.json();
const customerId = data.id;

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

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

const response = await fetch('https://api.dubupay.com/api/v1/payments/onramps', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'dubu_sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer_id: 'cus_9f3b...',
    type: 'TEMPORARY',
    amount: 50000,
  }),
});
const { data } = await response.json();

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.

Get Started

Authentication

Core Concepts

Guides

Account & Security

Get started with Dubu Pay in minutes

Prerequisites

Steps

What’s next

Authentication

API keys

​Prerequisites

​Steps

​What’s next

Authentication

API keys

Prerequisites

Steps

What’s next