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

string

required

Transfer currency. One of NGN or USD.

string

required

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

string

required

Your unique reference for this transfer. Used for reconciliation.

string

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

object

Inline destination details. Mutually exclusive with recipient_id.

Show destination fields

string

required

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

object

Required when type is BANK_ACCOUNT (Nigerian domestic transfer).

Show bank_account fields

string

required

Nigerian bank account number.

string

required

Bank sort code.

string

Account holder name.

object

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

Show us_bank_account fields

string

required

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

string

required

US bank account number.

string

required

ABA routing number.

string

required

Name of the bank. Up to 256 characters.

string

required

Account type. One of checking or savings.

string

required

Payout method. One of ach or wire.

object

required

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

object

Required when type is SWIFT_BANK_ACCOUNT. For international wire transfers.

Show swift_bank_account fields

string

required

Full legal name. Up to 256 characters.

string

required

Owner type. One of individual or business.

string

required

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

string

required

International Bank Account Number.

string

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

string

Bank name. Up to 256 characters.

string

required

Relationship category. One of client, parent_company, subsidiary, supplier.

array

required

At least one purpose. Values: intra_group_transfer, invoice_for_goods_and_services.

string

required

Brief description of your business activity.

object

required

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

object

required

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

object

Identifies the customer on whose behalf you are sending this transfer.

Show on_behalf_of fields

string

required

UUID of the customer.

Response

object

The created transfer.

Show data fields

string

Unique transfer ID.

string

Transfer currency (NGN or USD).

string

Transfer amount as a decimal string.

string

Your provided reference.

string

Transfer status: PROCESSING, SETTLED, or FAILED.

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

number

Page number (1-indexed).

number

Results per page. Up to 100.

string

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

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

object

Current merchant balance details.

Show data fields

string

Available USDT balance as a decimal string.

string

USDT amount locked in pending operations.

string

Always USDT.

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

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

number

Page number (1-indexed).

number

Results per page.

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

object

Funding details for your merchant account.

Show data fields

array

List of funding addresses across supported chains.

Show address fields

string

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

string

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

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