Transfers API — move funds between accounts

Transfers let you push funds from your merchant account to external bank accounts — either Nigerian domestic accounts, US bank accounts via ACH or wire, or international accounts via SWIFT. You can also move your merchant USDT balance to a registered destination and query your funding details. Every transfer requires either a saved recipient_id or an inline destination object — not both.

Authentication

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

Authorization: Bearer <access_token>

X-Api-Key: dubu_sk_live_...

Create a transfer

POST https://api.dubupay.com/api/v1/payments/transfers Initiates a fund transfer in NGN or USD to an external bank account. Provide exactly one of recipient_id (reference a saved recipient) or destination (inline account details).

This endpoint supports idempotency via Idempotency-Key or X-Idempotency-Key headers. Use this to safely retry on network failures.

Request body

currency

string

required

Transfer currency. One of NGN or USD.

amount

string

required

Transfer amount as a decimal string (e.g., "5000.00").

reference

string

required

Your unique reference for this transfer. Used for reconciliation.

recipient_id

string

UUID of a saved recipient. Mutually exclusive with destination. See Recipients.

destination

object

Inline destination details. Mutually exclusive with recipient_id.

Show destination fields

type

string

required

Destination type. One of BANK_ACCOUNT, US_BANK_ACCOUNT, or SWIFT_BANK_ACCOUNT.

bank_account

object

Required when type is BANK_ACCOUNT (Nigerian domestic transfer).

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.

us_bank_account

object

Required when type is US_BANK_ACCOUNT. Supports ACH and wire payouts.

Show us_bank_account fields

account_owner_name

string

required

Full legal name of the account owner. Up to 256 characters.

account_number

string

required

US bank account number.

routing_number

string

required

ABA routing number.

bank_name

string

required

Name of the bank. Up to 256 characters.

account_type

string

required

Account type. One of checking or savings.

payout_scheme

string

required

Payout method. One of ach or wire.

address

object

required

Account owner’s address. Requires at least country (ISO 3166-1 alpha-3).

swift_bank_account

object

Required when type is SWIFT_BANK_ACCOUNT. For international wire transfers.

Show swift_bank_account fields

account_owner_name

string

required

Full legal name. Up to 256 characters.

account_owner_type

string

required

Owner type. One of individual or business.

account_country

string

required

ISO 3166-1 alpha-3 country code of the account.

iban

string

required

International Bank Account Number.

bic

string

Bank Identifier Code (SWIFT/BIC). Optional but recommended.

bank_name

string

Bank name. Up to 256 characters.

Response

data

object

The created transfer.

Show data fields

string

Unique transfer ID.

currency

string

Transfer currency (NGN or USD).

amount

string

Transfer amount as a decimal string.

reference

string

Your provided reference.

status

string

Transfer status: PROCESSING, SETTLED, or FAILED.

created_at

string

ISO 8601 creation timestamp.

Example — Nigerian bank transfer

curl -X POST https://api.dubupay.com/api/v1/payments/transfers \
  -H "X-Api-Key: dubu_sk_live_..." \
  -H "Idempotency-Key: transfer-ref-20240101" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "amount": "50000.00",
    "reference": "PAY-20240101-001",
    "destination": {
      "type": "BANK_ACCOUNT",
      "bank_account": {
        "account_number": "0123456789",
        "bank_code": "058",
        "account_name": "Ada Obi"
      }
    }
  }'

Example — transfer using a saved recipient

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": "20000.00",
    "reference": "PAY-20240101-002",
    "recipient_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

List transfers

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

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.

currency

string

Filter by currency. One of NGN or USD.

Example

curl "https://api.dubupay.com/api/v1/payments/transfers?status=SETTLED&currency=NGN" \
  -H "X-Api-Key: dubu_sk_live_..."

Get a transfer

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

Path parameters

string

required

The transfer ID.

Example

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

Merchant balance

Get merchant balance

GET https://api.dubupay.com/api/v1/payments/merchant/balance Returns your current merchant USDT balance — the funds available to fund withdrawals, transfers, and offramps.

Response

data

object

Current merchant balance details.

Show data fields

available

string

Available USDT balance as a decimal string.

pending

string

USDT amount locked in pending operations.

currency

string

Always USDT.

updated_at

string

ISO 8601 timestamp of the last balance update.

Example

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

Move merchant balance

POST https://api.dubupay.com/api/v1/payments/merchant/balance/transfer Moves a specified amount of your merchant USDT balance (for example, to fund an onchain settlement or top up a wallet).

Supports idempotency via the X-Idempotency-Key header.

Request body

amount_usd

string

required

The USD amount to transfer, as a decimal string (e.g., "500.00").

Example

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

List balance transfers

GET https://api.dubupay.com/api/v1/payments/merchant/balance/transfers Returns a paginated history of merchant balance movements.

Query parameters

page

number

Page number (1-indexed).

limit

number

Results per page.

status

string

Filter by status. One of PENDING, COMPLETED, FAILED.

Example

curl "https://api.dubupay.com/api/v1/payments/merchant/balance/transfers?status=COMPLETED" \
  -H "X-Api-Key: dubu_sk_live_..."

Merchant funding

Get funding information

GET https://api.dubupay.com/api/v1/payments/merchant/funding Returns the deposit addresses and instructions you need to fund your merchant USDT balance from external sources.

Response

data

object

Funding details for your merchant account.

Show data fields

addresses

array

List of funding addresses across supported chains.

Show address fields

chain

string

Blockchain network (e.g., TRON, SOLANA).

asset

string

Asset to send (e.g., USDT).

address

string

Deposit wallet address for this chain and asset.

Example

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

Overview

Auth

Payments

Trading

Commerce

Webhooks

Transfers API — move funds between accounts

Authentication

Create a transfer

Request body

Response

Example — Nigerian bank transfer

Example — transfer using a saved recipient

List transfers

Query parameters

Example

Get a transfer

Path parameters

Example

Merchant balance

Get merchant balance

Response

Example

Move merchant balance

Request body

Example

List balance transfers

Query parameters

Example

Merchant funding

Get funding information

Response

Example

​Authentication

​Create a transfer

​Request body

​Response

​Example — Nigerian bank transfer

​Example — transfer using a saved recipient

​List transfers

​Query parameters

​Example

​Get a transfer

​Path parameters

​Example

​Merchant balance

​Get merchant balance

​Response

​Example

​Move merchant balance

​Request body

​Example

​List balance transfers

​Query parameters

​Example

​Merchant funding

​Get funding information

​Response

​Example

Authentication

Create a transfer

Request body

Response

Example — Nigerian bank transfer

Example — transfer using a saved recipient

List transfers

Query parameters

Example

Get a transfer

Path parameters

Example

Merchant balance

Get merchant balance

Response

Example

Move merchant balance

Request body

Example

List balance transfers

Query parameters

Example

Merchant funding

Get funding information

Response

Example