Withdrawals & Offramps API — send funds out

Dubu Pay gives you two ways to move funds out of your merchant account. Withdrawals send USDT directly to an external blockchain wallet address. Offramps convert USDT to NGN and route the proceeds to a Nigerian bank account — either on-the-spot or on a recurring basis for a specific customer. For both, the operation originates from your merchant USDT balance.

Authentication

All endpoints require either a Bearer token or an API key.

Authorization: Bearer <access_token>

X-Api-Key: dubu_sk_live_...

Withdrawals

Create a withdrawal

POST https://api.dubupay.com/api/v1/payments/withdrawals Initiates a USDT withdrawal from your merchant balance to an external wallet address on the specified blockchain network.

This endpoint supports idempotency. Pass an X-Idempotency-Key header to safely retry without creating duplicate withdrawals.

Request body

amount_usd

string

required

The USD-equivalent amount to withdraw, expressed as a decimal string (e.g., "100.00").

token

string

required

The token to withdraw. Use USDT.

chain

string

required

The blockchain network to send on. Supported values: APTOS, BASE, CELO, ETHEREUM, POLYGON, SOLANA, TRON.

destination_address

string

required

The recipient wallet address on the specified chain.

Response

data

object

The created withdrawal.

Show data fields

string

Unique withdrawal ID.

amount_usd

string

Withdrawal amount in USD.

token

string

Token being withdrawn (e.g., USDT).

chain

string

Target blockchain network.

destination_address

string

Recipient wallet address.

status

string

Withdrawal status: PROCESSING, SETTLED, or FAILED.

created_at

string

ISO 8601 creation timestamp.

Example

curl -X POST https://api.dubupay.com/api/v1/payments/withdrawals \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "X-Idempotency-Key: withdrawal-20240101-001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": "250.00",
    "token": "USDT",
    "chain": "TRON",
    "destination_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

List withdrawals

GET https://api.dubupay.com/api/v1/payments/withdrawals Returns a paginated list of withdrawals.

Query parameters

page

number

Page number (1-indexed).

limit

number

Results per page. Up to 100.

status

string

Filter by status. One of PROCESSING, SETTLED, FAILED.

Example

curl "https://api.dubupay.com/api/v1/payments/withdrawals?status=SETTLED&limit=20" \
  -H "X-Api-Key: dubu_sk_live_..."

Get a withdrawal

GET https://api.dubupay.com/api/v1/payments/withdrawals/:id Retrieves a single withdrawal by ID.

Path parameters

string

required

The withdrawal ID.

Example

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

Offramps

Offramps convert USDT (or USDC) received from a blockchain address into NGN and pay it out to a bank account. You can create offramps as TEMPORARY (one-time, for a specific conversion) or PERMANENT (reusable for a customer’s ongoing payouts). For NGN bank payouts, you must supply a rate_id (lock a rate from the Rates endpoint) and destination bank details.

Create an offramp

POST https://api.dubupay.com/api/v1/payments/offramps Creates a new offramp. The body shape varies depending on whether you settle to your internal balance or to an NGN bank account.

This endpoint supports idempotency via the X-Idempotency-Key header.

Request body

type

string

required

Offramp type. One of TEMPORARY or PERMANENT.

customer

object

required

The customer for this offramp. Provide either customer_id or email (with optional name fields).

Show customer fields

customer_id

string

UUID of an existing customer. Mutually exclusive with email.

string

Email address. Used to look up or create a customer record.

first_name

string

Customer first name (used when creating a new customer by email).

last_name

string

Customer last name (used when creating a new customer by email).

chain

string

required

The blockchain network the offramp listens on. One of APTOS, BASE, CELO, ETHEREUM, POLYGON, SOLANA, TRON.

asset

string

required

The crypto asset to accept. One of USDC or USDT.

settlement

object

required

How proceeds are settled after conversion.

Show settlement fields

mode

string

required

Settlement mode. One of INTERNAL_BALANCE (credit your merchant balance in NGN) or NGN_PAYOUT (send NGN directly to a bank account).

rate_id

string

Required when mode is NGN_PAYOUT. A rate ID obtained from GET /payments/rates.

destination_bank

object

Required when mode is NGN_PAYOUT.

Show destination_bank fields

account_name

string

required

Account holder name as registered with the bank.

account_number

string

required

Bank account number (6–32 characters).

bank_code

string

required

Bank sort code (3–16 characters).

Example — settle to internal balance

curl -X POST https://api.dubupay.com/api/v1/payments/offramps \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "X-Idempotency-Key: offramp-ada-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PERMANENT",
    "customer": {
      "customer_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890"
    },
    "chain": "TRON",
    "asset": "USDT",
    "settlement": {
      "mode": "INTERNAL_BALANCE"
    }
  }'

Example — NGN payout to bank account

curl -X POST https://api.dubupay.com/api/v1/payments/offramps \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "X-Idempotency-Key: offramp-payout-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TEMPORARY",
    "customer": {
      "email": "ada.obi@example.com"
    },
    "chain": "SOLANA",
    "asset": "USDC",
    "settlement": {
      "mode": "NGN_PAYOUT",
      "rate_id": "rate_abc123",
      "destination_bank": {
        "account_name": "Ada Obi",
        "account_number": "0123456789",
        "bank_code": "058"
      }
    }
  }'

List offramps

GET https://api.dubupay.com/api/v1/payments/offramps Returns a paginated list of offramps with optional filters.

Query parameters

type

string

Filter by type: TEMPORARY or PERMANENT.

chain

string

Filter by chain: APTOS, BASE, CELO, ETHEREUM, POLYGON, SOLANA, or TRON.

asset

string

Filter by asset: USDC or USDT.

status

string

Filter by status: ACTIVE, INACTIVE, or EXPIRED.

settlement_mode

string

Filter by settlement mode: INTERNAL_BALANCE or NGN_PAYOUT.

page

number

Page number (1-indexed).

limit

number

Results per page. Up to 200.

Example

curl "https://api.dubupay.com/api/v1/payments/offramps?status=ACTIVE&chain=TRON" \
  -H "X-Api-Key: dubu_sk_live_..."

Get an offramp

GET https://api.dubupay.com/api/v1/payments/offramps/:id Retrieves a single offramp by ID.

Path parameters

string

required

The offramp ID.

Example

curl "https://api.dubupay.com/api/v1/payments/offramps/off_01HXYZ" \
  -H "X-Api-Key: dubu_sk_live_..."

Recipients

A recipient is a saved payment destination — a bank account, crypto address, or wire details — that you can reference by ID when creating transfers or offramps. Managing recipients separately lets you avoid re-entering bank details on every payout.

Create a recipient

POST https://api.dubupay.com/api/v1/recipients

Request body

type

string

required

Recipient type. One of BANK_ACCOUNT, CRYPTO_ADDRESS, US_BANK_ACCOUNT, SWIFT_BANK_ACCOUNT.

customer_id

string

UUID of an existing customer to associate with this recipient. Required for US_BANK_ACCOUNT and SWIFT_BANK_ACCOUNT types.

bank_account

object

Required when type is BANK_ACCOUNT.

Show bank_account fields

account_number

string

required

Nigerian bank account number.

bank_code

string

required

Bank sort code.

account_name

string

Account holder name.

crypto_address

object

Required when type is CRYPTO_ADDRESS.

Show crypto_address fields

asset

string

required

Asset. One of USDC or USDT.

chain

string

required

Chain. One of ETHEREUM, BASE, POLYGON, ARBITRUM, OPTIMISM, CELO.

address

string

required

Wallet address.

Example

curl -X POST https://api.dubupay.com/api/v1/recipients \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BANK_ACCOUNT",
    "bank_account": {
      "account_number": "0123456789",
      "bank_code": "058",
      "account_name": "Ada Obi"
    }
  }'

Overview

Auth

Payments

Trading

Commerce

Webhooks

Withdrawals & Offramps API — send funds out

Authentication

Withdrawals

Create a withdrawal

Request body

Response

Example

List withdrawals

Query parameters

Example

Get a withdrawal

Path parameters

Example

Offramps

Create an offramp

Request body

Example — settle to internal balance

Example — NGN payout to bank account

List offramps

Query parameters

Example

Get an offramp

Path parameters

Example

Recipients

Create a recipient

Request body

Example

Overview

Auth

Payments

Trading

Commerce

Webhooks

Documentation Index

​Authentication

​Withdrawals

​Create a withdrawal

​Request body

​Response

​Example

​List withdrawals

​Query parameters

​Example

​Get a withdrawal

​Path parameters

​Example

​Offramps

​Create an offramp

​Request body

​Example — settle to internal balance

​Example — NGN payout to bank account

​List offramps

​Query parameters

​Example

​Get an offramp

​Path parameters

​Example

​Recipients

​Create a recipient

​Request body

​Example

Authentication

Withdrawals

Create a withdrawal

Request body

Response

Example

List withdrawals

Query parameters

Example

Get a withdrawal

Path parameters

Example

Offramps

Create an offramp

Request body

Example — settle to internal balance

Example — NGN payout to bank account

List offramps

Query parameters

Example

Get an offramp

Path parameters

Example

Recipients

Create a recipient

Request body

Example