> ## 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.

# Transfers API — move funds between accounts

> Send NGN or USD to bank accounts, manage your merchant USDT balance, and retrieve funding information for depositing into your Dubu Pay account.

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).

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

### Request body

<ParamField body="currency" type="string" required>
  Transfer currency. One of `NGN` or `USD`.
</ParamField>

<ParamField body="amount" type="string" required>
  Transfer amount as a decimal string (e.g., `"5000.00"`).
</ParamField>

<ParamField body="reference" type="string" required>
  Your unique reference for this transfer. Used for reconciliation.
</ParamField>

<ParamField body="recipient_id" type="string">
  UUID of a saved recipient. Mutually exclusive with `destination`. See [Recipients](/api-reference/payments/withdrawals#recipients).
</ParamField>

<ParamField body="destination" type="object">
  Inline destination details. Mutually exclusive with `recipient_id`.

  <Expandable title="destination fields">
    <ParamField body="type" type="string" required>
      Destination type. One of `BANK_ACCOUNT`, `US_BANK_ACCOUNT`, or `SWIFT_BANK_ACCOUNT`.
    </ParamField>

    <ParamField body="bank_account" type="object">
      Required when `type` is `BANK_ACCOUNT` (Nigerian domestic transfer).

      <Expandable title="bank_account fields">
        <ParamField body="account_number" type="string" required>
          Nigerian bank account number.
        </ParamField>

        <ParamField body="bank_code" type="string" required>
          Bank sort code.
        </ParamField>

        <ParamField body="account_name" type="string">
          Account holder name.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="us_bank_account" type="object">
      Required when `type` is `US_BANK_ACCOUNT`. Supports ACH and wire payouts.

      <Expandable title="us_bank_account fields">
        <ParamField body="account_owner_name" type="string" required>
          Full legal name of the account owner. Up to 256 characters.
        </ParamField>

        <ParamField body="account_number" type="string" required>
          US bank account number.
        </ParamField>

        <ParamField body="routing_number" type="string" required>
          ABA routing number.
        </ParamField>

        <ParamField body="bank_name" type="string" required>
          Name of the bank. Up to 256 characters.
        </ParamField>

        <ParamField body="account_type" type="string" required>
          Account type. One of `checking` or `savings`.
        </ParamField>

        <ParamField body="payout_scheme" type="string" required>
          Payout method. One of `ach` or `wire`.
        </ParamField>

        <ParamField body="address" type="object" required>
          Account owner's address. Requires at least `country` (ISO 3166-1 alpha-3).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="swift_bank_account" type="object">
      Required when `type` is `SWIFT_BANK_ACCOUNT`. For international wire transfers.

      <Expandable title="swift_bank_account fields">
        <ParamField body="account_owner_name" type="string" required>
          Full legal name. Up to 256 characters.
        </ParamField>

        <ParamField body="account_owner_type" type="string" required>
          Owner type. One of `individual` or `business`.
        </ParamField>

        <ParamField body="account_country" type="string" required>
          ISO 3166-1 alpha-3 country code of the account.
        </ParamField>

        <ParamField body="iban" type="string" required>
          International Bank Account Number.
        </ParamField>

        <ParamField body="bic" type="string">
          Bank Identifier Code (SWIFT/BIC). Optional but recommended.
        </ParamField>

        <ParamField body="bank_name" type="string">
          Bank name. Up to 256 characters.
        </ParamField>

        <ParamField body="category" type="string" required>
          Relationship category. One of `client`, `parent_company`, `subsidiary`, `supplier`.
        </ParamField>

        <ParamField body="purpose_of_funds" type="array" required>
          At least one purpose. Values: `intra_group_transfer`, `invoice_for_goods_and_services`.
        </ParamField>

        <ParamField body="short_business_description" type="string" required>
          Brief description of your business activity.
        </ParamField>

        <ParamField body="address" type="object" required>
          Account owner's address. Requires at least `country` (ISO 3166-1 alpha-3).
        </ParamField>

        <ParamField body="bank_address" type="object" required>
          Beneficiary bank's address. Requires at least `country` (ISO 3166-1 alpha-3).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="on_behalf_of" type="object">
  Identifies the customer on whose behalf you are sending this transfer.

  <Expandable title="on_behalf_of fields">
    <ParamField body="customer_id" type="string" required>
      UUID of the customer.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="data" type="object">
  The created transfer.

  <Expandable title="data fields">
    <ResponseField name="id" type="string">
      Unique transfer ID.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Transfer currency (`NGN` or `USD`).
    </ResponseField>

    <ResponseField name="amount" type="string">
      Transfer amount as a decimal string.
    </ResponseField>

    <ResponseField name="reference" type="string">
      Your provided reference.
    </ResponseField>

    <ResponseField name="status" type="string">
      Transfer status: `PROCESSING`, `SETTLED`, or `FAILED`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example — Nigerian bank transfer

```bash theme={null}
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

```bash theme={null}
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

<ParamField query="page" type="number">
  Page number (1-indexed).
</ParamField>

<ParamField query="limit" type="number">
  Results per page. Up to 100.
</ParamField>

<ParamField query="status" type="string">
  Filter by status. One of `PROCESSING`, `SETTLED`, `FAILED`.
</ParamField>

<ParamField query="currency" type="string">
  Filter by currency. One of `NGN` or `USD`.
</ParamField>

### Example

```bash theme={null}
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

<ParamField path="id" type="string" required>
  The transfer ID.
</ParamField>

### Example

```bash theme={null}
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

<ResponseField name="data" type="object">
  Current merchant balance details.

  <Expandable title="data fields">
    <ResponseField name="available" type="string">
      Available USDT balance as a decimal string.
    </ResponseField>

    <ResponseField name="pending" type="string">
      USDT amount locked in pending operations.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Always `USDT`.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the last balance update.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
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).

<Note>
  Supports idempotency via the `X-Idempotency-Key` header.
</Note>

#### Request body

<ParamField body="amount_usd" type="string" required>
  The USD amount to transfer, as a decimal string (e.g., `"500.00"`).
</ParamField>

#### Example

```bash theme={null}
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

<ParamField query="page" type="number">
  Page number (1-indexed).
</ParamField>

<ParamField query="limit" type="number">
  Results per page.
</ParamField>

<ParamField query="status" type="string">
  Filter by status. One of `PENDING`, `COMPLETED`, `FAILED`.
</ParamField>

#### Example

```bash theme={null}
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

<ResponseField name="data" type="object">
  Funding details for your merchant account.

  <Expandable title="data fields">
    <ResponseField name="addresses" type="array">
      List of funding addresses across supported chains.

      <Expandable title="address fields">
        <ResponseField name="chain" type="string">
          Blockchain network (e.g., `TRON`, `SOLANA`).
        </ResponseField>

        <ResponseField name="asset" type="string">
          Asset to send (e.g., `USDT`).
        </ResponseField>

        <ResponseField name="address" type="string">
          Deposit wallet address for this chain and asset.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/payments/merchant/funding" \
  -H "X-Api-Key: dubu_sk_live_..."
```