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

string

required

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

string

required

The token to withdraw. Use USDT.

string

required

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

string

required

The recipient wallet address on the specified chain.

Response

object

The created withdrawal.

Show data fields

string

Unique withdrawal ID.

string

Withdrawal amount in USD.

string

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

string

Target blockchain network.

string

Recipient wallet address.

string

Withdrawal status: PROCESSING, SETTLED, or FAILED.

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

number

Page number (1-indexed).

number

Results per page. Up to 100.

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

string

required

Offramp type. One of TEMPORARY or PERMANENT.

object

required

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

Show customer fields

string

UUID of an existing customer. Mutually exclusive with email.

string

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

string

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

string

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

string

required

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

string

required

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

object

required

How proceeds are settled after conversion.

Show settlement fields

string

required

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

string

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

object

Required when mode is NGN_PAYOUT.

Show destination_bank fields

string

required

Account holder name as registered with the bank.

string

required

Bank account number (6–32 characters).

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

string

Filter by type: TEMPORARY or PERMANENT.

string

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

string

Filter by asset: USDC or USDT.

string

Filter by status: ACTIVE, INACTIVE, or EXPIRED.

string

Filter by settlement mode: INTERNAL_BALANCE or NGN_PAYOUT.

number

Page number (1-indexed).

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

string

required

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

string

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

object

Required when type is BANK_ACCOUNT.

Show bank_account fields

string

required

Nigerian bank account number.

string

required

Bank sort code.

string

Account holder name.

object

Required when type is CRYPTO_ADDRESS.

Show crypto_address fields

string

required

Asset. One of USDC or USDT.

string

required

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

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

​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