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.

The Dubu Pay payments system covers every step of moving money: receiving NGN from customers via virtual bank accounts, tracking each incoming deposit through its settlement lifecycle, withdrawing USDT to external wallets, converting USDT back to NGN via offramps, and moving funds between accounts with transfers. All payments functionality lives under the /payments path of the API.

​
Payment flow overview

​
Onramps

An onramp is the API term for a virtual bank account used to receive NGN. When a customer pays into an onramp, Dubu Pay automatically converts the NGN to USDT and records the result as a deposit. See NGN virtual bank accounts for the full breakdown of temporary vs permanent accounts. 
curl -X POST https://api.dubupay.com/api/v1/payments/onramps \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TEMPORARY",
    "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "rate_id": "rate_01HZ...",
    "amount": 50000,
    "settlement": {
      "mode": "INTERNAL_BALANCE",
      "asset": "USDT"
    }
  }'

​
Deposits

A deposit is created automatically when a customer pays into a virtual account. You do not create deposits directly — you retrieve and monitor them. Each deposit has a type of either NGN_DEPOSIT or CRYPTO_DEPOSIT, and moves through a status lifecycle until it either settles or fails. Deposit status lifecycle:
StatusDescription
PENDINGDeposit received and queued for processing.
COMPLETEDDeposit has settled successfully. USDT has been credited.
FAILEDProcessing failed. No funds were moved.
FLAGGEDFlagged for compliance review. Settlement is paused.
REVERSEDA completed deposit has been reversed. Credited USDT has been debited back.
Virtual account deposits expose fine-grained processing states (PENDING_FX, PENDING_WITHDRAWAL, SETTLED) on the deposit record itself. The GET /payments/deposits list endpoint uses the higher-level status values shown above. Use webhooks to receive real-time status transitions.
curl "https://api.dubupay.com/api/v1/payments/deposits?status=COMPLETED&type=NGN_DEPOSIT" \
  -H "X-Api-Key: dubu_sk_live_..."
You can filter deposits by type, onramp_id, offramp_id, status, and date range (from / to as ISO 8601 timestamps).

​
Withdrawals

A withdrawal moves USDT from your merchant balance to an external blockchain address. You specify the amount, token, chain, and destination address. 
curl -X POST https://api.dubupay.com/api/v1/payments/withdrawals \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": "100.00",
    "token": "USDT",
    "chain": "TRON",
    "destination_address": "TXyz..."
  }'
Supported chains for withdrawals: APTOS, BASE, CELO, ETHEREUM, POLYGON, SOLANA, TRON.
Withdrawals are irreversible once submitted. Verify the destination address and chain before calling this endpoint. Dubu Pay cannot recover funds sent to the wrong address.

​
Offramps

An offramp accepts USDT and converts it back to NGN, either crediting your internal balance or sending the NGN directly to a Nigerian bank account. You choose the settlement mode when creating the offramp.
Settlement modeDescription
INTERNAL_BALANCEConverted NGN is held in your Dubu Pay account.
NGN_PAYOUTConverted NGN is sent to a specified Nigerian bank account. Requires a rate_id and destination_bank.
curl -X POST https://api.dubupay.com/api/v1/payments/offramps \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TEMPORARY",
    "customer": { "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
    "chain": "TRON",
    "asset": "USDT",
    "settlement": {
      "mode": "NGN_PAYOUT",
      "rate_id": "rate_01HZ...",
      "destination_bank": {
        "account_name": "Ada Lovelace",
        "account_number": "0123456789",
        "bank_code": "058"
      }
    }
  }'
Offramp type is either TEMPORARY (expires) or PERMANENT (no expiry). You can filter listed offramps by type, chain, asset, status, and settlement_mode.

​
Transfers

A transfer moves funds to a bank account. Dubu Pay supports three destination types depending on the currency and recipient:
TypeCurrencyDescription
BANK_ACCOUNTNGNNigerian domestic bank transfer. Provide account_number and bank_code.
US_BANK_ACCOUNTUSDUS ACH or wire transfer. Provide routing number, account number, and payout_scheme.
SWIFT_BANK_ACCOUNTUSDInternational SWIFT/IBAN transfer. Provide IBAN, BIC, account owner details, and purpose_of_funds.
Each transfer requires a unique reference string you provide for idempotency. You can optionally associate a transfer with a customer using on_behalf_of.customer_id. 
curl -X POST https://api.dubupay.com/api/v1/payments/transfers \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "amount": "50000",
    "reference": "txn_ref_abc123",
    "destination": {
      "type": "BANK_ACCOUNT",
      "bank_account": {
        "account_number": "0123456789",
        "bank_code": "058",
        "account_name": "Ada Lovelace"
      }
    }
  }'
Transfer statuses are PROCESSING, SETTLED, and FAILED.
Always store your reference in your own database before calling POST /transfers. If the network request times out, you can use the reference to check whether the transfer was created rather than accidentally duplicating it.

​
Merchant balance

Your merchant balance is the aggregated USDT held across all settled deposits, minus withdrawals and transfers. You can retrieve it at any time, transfer a portion of it to the trading engine, or list all past balance transfers. 
# Get current balance
curl https://api.dubupay.com/api/v1/payments/merchant/balance \
  -H "X-Api-Key: dubu_sk_live_..."

# Transfer balance to trading
curl -X POST https://api.dubupay.com/api/v1/payments/merchant/balance/transfer \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": "500.00"}'

​
Exchange rates

Before creating a temporary onramp or an NGN_PAYOUT offramp, you need a rate_id. Fetch the current NGN-to-USDT and NGN-to-USDC exchange rates from: 
curl https://api.dubupay.com/api/v1/payments/rates \
  -H "X-Api-Key: dubu_sk_live_..."
The response includes both the rate and a rate_id you pass when creating a temporary onramp or NGN_PAYOUT offramp. Rates are time-limited — fetch a fresh rate close to the moment you create the account.
For temporary onramps, the rate is locked at creation time. For permanent onramps, the live rate at the moment of each deposit is used. Always fetch the latest rate immediately before creating a temporary account to give your customer the most accurate amount.

​
Sandbox testing

In test mode, incoming deposits will not occur automatically. Use the sandbox endpoint to simulate an NGN deposit against any existing onramp: 
curl -X POST https://api.dubupay.com/api/v1/payments/sandbox/deposits \
  -H "X-Api-Key: dubu_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "onramp_id": "onramp_01HZ...",
    "should_flag": false
  }'
Set should_flag: true to simulate a flagged deposit and test your compliance handling logic.
The sandbox deposits endpoint only works with test API keys (dubu_sk_test_...). Calls with live keys will return an error.

​
Payouts

Payouts are the outbound counterpart to deposits — they represent USDT or NGN being paid out as a result of a withdrawal or transfer. Payouts are read-only; you list them to track settlement status.
StatusDescription
PROCESSINGPayout is in progress.
SETTLEDPayout has completed and funds have reached the destination.
FAILEDPayout could not be completed.

​
Endpoint overview

MethodPathDescription
GET/payments/ratesGet current NGN→USDT and NGN→USDC exchange rates
POST/payments/onrampsCreate a virtual bank account (onramp)
GET/payments/onrampsList onramps
GET/payments/onramps/:idGet a specific onramp
GET/payments/depositsList deposits
GET/payments/deposits/:idGet a specific deposit
POST/payments/sandbox/depositsSimulate a deposit in test mode
POST/payments/withdrawalsInitiate a USDT withdrawal
GET/payments/withdrawalsList withdrawals
GET/payments/withdrawals/:idGet a specific withdrawal
POST/payments/offrampsCreate an offramp
GET/payments/offrampsList offramps
GET/payments/offramps/:idGet a specific offramp
POST/payments/transfersCreate a bank transfer
GET/payments/transfersList transfers
GET/payments/transfers/:idGet a specific transfer
GET/payments/payoutsList payouts
GET/payments/payouts/:idGet a specific payout
GET/payments/merchant/balanceGet merchant USDT balance
POST/payments/merchant/balance/transferMove balance to the trading engine
GET/payments/merchant/balance/transfersList balance transfers
GET/payments/merchant/fundingGet merchant funding details