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 two ways to move money out: a withdrawal sends USDT directly to an on-chain wallet address, and an offramp converts USDT back to NGN and pays out to a Nigerian bank account. This guide covers both flows, including how to create recipients you can reuse across multiple transfers.

​
USDT withdrawals

A withdrawal moves USDT from your merchant balance to any external wallet address on a supported chain.

​
Initiate a withdrawal

curl -X POST https://api.dubupay.com/api/v1/payments/withdrawals \
  -H "X-Api-Key: dubu_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: unique-key-for-this-request" \
  -d '{
    "amount_usd": "50.00",
    "token": "USDT",
    "chain": "TRON",
    "destination_address": "TYour_TRON_wallet_address_here"
  }'
Request fields:
FieldTypeRequiredDescription
amount_usdstringYesAmount in USD to withdraw (e.g. "50.00")
tokenstringYesToken to send (e.g. "USDT")
chainstringYesDestination chain. Supported: APTOS, BASE, CELO, ETHEREUM, POLYGON, SOLANA, TRON
destination_addressstringYesOn-chain wallet address for the recipient
Always pass X-Idempotency-Key with a unique value per withdrawal. If the request times out and you retry, the same key prevents a duplicate withdrawal from being created.
Response: 
{
  "success": true,
  "data": {
    "id": "wdraw_01hx8ka2qr3st4uv5wx6ef",
    "status": "PENDING",
    "amount_usd": "50.00",
    "token": "USDT",
    "chain": "TRON",
    "destination_address": "TYour_TRON_wallet_address_here",
    "created_at": "2024-11-01T10:00:00.000Z"
  }
}

​
Check withdrawal status

curl https://api.dubupay.com/api/v1/payments/withdrawals/wdraw_01hx8ka2qr3st4uv5wx6ef \
  -H "X-Api-Key: dubu_sk_live_your_api_key"

{
  "success": true,
  "data": {
    "id": "wdraw_01hx8ka2qr3st4uv5wx6ef",
    "status": "SETTLED",
    "amount_usd": "50.00",
    "token": "USDT",
    "chain": "TRON",
    "destination_address": "TYour_TRON_wallet_address_here",
    "tx_hash": "0xdef456...",
    "settled_at": "2024-11-01T10:03:11.000Z"
  }
}
Withdrawal statuses:
StatusMeaning
PENDINGWithdrawal created, awaiting processing
SUBMITTEDSubmitted to the blockchain
SETTLEDTransaction confirmed on-chain
FAILEDWithdrawal could not be completed

​
Offramps — convert USDT to NGN

An offramp converts USDT to NGN and pays out to a Nigerian bank account. You need to provide the recipient’s bank details either inline or via a pre-created recipient.

​
Initiate an offramp

curl -X POST https://api.dubupay.com/api/v1/payments/offramps \
  -H "X-Api-Key: dubu_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: unique-key-for-this-offramp" \
  -d '{
    "type": "TEMPORARY",
    "customer": {
      "email": "amara@example.com",
      "first_name": "Amara",
      "last_name": "Okafor"
    },
    "chain": "TRON",
    "asset": "USDT",
    "settlement": {
      "mode": "NGN_PAYOUT",
      "rate_id": "rate_01hx8kb2qr3st4uv5wx6gh",
      "destination_bank": {
        "account_name": "Amara Okafor",
        "account_number": "0123456789",
        "bank_code": "044"
      }
    }
  }'
Key request fields:
FieldTypeRequiredDescription
typestringYesTEMPORARY or PERMANENT
customer.customer_idstring—Existing customer ID (required if no email)
customer.emailstring—Customer email (required if no customer_id)
chainstringYesChain from which USDT will be sent
assetstringYesUSDT or USDC
settlement.modestringYesNGN_PAYOUT to bank, or INTERNAL_BALANCE to credit your ledger
settlement.rate_idstringYes (NGN_PAYOUT)Rate ID obtained from GET /payments/rates
settlement.destination_bankobjectYes (NGN_PAYOUT)Bank account details for the NGN payout
Fetch the current exchange rate before creating an offramp: GET /payments/rates. The rate_id from the response is time-limited, so use it promptly.
Response: 
{
  "success": true,
  "data": {
    "id": "offramp_01hx8kc2qr3st4uv5wx6ij",
    "type": "TEMPORARY",
    "status": "ACTIVE",
    "chain": "TRON",
    "asset": "USDT",
    "deposit_address": "TReceiving_address_for_USDT",
    "settlement": {
      "mode": "NGN_PAYOUT",
      "destination_bank": {
        "account_name": "Amara Okafor",
        "account_number": "0123456789",
        "bank_code": "044"
      }
    },
    "created_at": "2024-11-01T10:10:00.000Z"
  }
}
The deposit_address is the on-chain address where USDT should be sent to trigger the NGN payout.

​
Check offramp status

curl https://api.dubupay.com/api/v1/payments/offramps/offramp_01hx8kc2qr3st4uv5wx6ij \
  -H "X-Api-Key: dubu_sk_live_your_api_key"
Offramp statuses: ACTIVE, INACTIVE, EXPIRED

​
List all offramps

curl "https://api.dubupay.com/api/v1/payments/offramps?status=ACTIVE&asset=USDT" \
  -H "X-Api-Key: dubu_sk_live_your_api_key"
You can filter by type, chain, asset, status, and settlement_mode.

​
Fetch the exchange rate

Before creating an offramp with NGN_PAYOUT, get the current rate and lock it: 
curl "https://api.dubupay.com/api/v1/payments/rates" \
  -H "X-Api-Key: dubu_sk_live_your_api_key"
Rate IDs expire. Use the rate_id in your offramp request within the validity window returned by the rates endpoint. Creating an offramp with an expired rate ID will fail.