> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagpay.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Funds Transfer

> Send money to any Nigerian bank account or between customer wallets using the TagPay Transfer API.

TagPay supports two primary transfer modes: bank transfers to any Nigerian bank account via NIP (NIBSS Instant Payment), and wallet-to-wallet transfers between customers on the same platform. This guide covers both flows, including how to look up account details before initiating a transfer.

## Prerequisites

All transfer endpoints require:

* A valid merchant Bearer token in the `Authorization` header
* NIP access enabled on your merchant account for bank transfers
* Internal transfer access enabled for wallet-to-wallet transfers

Contact [support@tagpay.ng](mailto:support@tagpay.ng) if these features are not yet activated on your account.

***

## Bank transfers

Send funds from your merchant settlement balance to any Nigerian bank account.

### Step 1 — List available banks

Fetch the full list of supported Nigerian banks and their sort codes. You'll need the sort code when initiating a transfer.

```bash cURL theme={null}
curl -X GET https://api.tagpay.ng/v1/transfer/banks \
  -H "Authorization: Bearer <your-token>"
```

```json Response theme={null}
{
  "success": true,
  "data": [
    { "name": "Access Bank", "sortCode": "000014" },
    { "name": "GTBank", "sortCode": "000013" },
    { "name": "Zenith Bank", "sortCode": "000015" }
  ]
}
```

### Step 2 — Resolve account details

Before sending a transfer, verify that the destination account number matches the intended recipient. This prevents failed or misdirected transfers.

```bash cURL theme={null}
curl -X GET "https://api.tagpay.ng/v1/transfer/account/details?accountNumber=0123456789&sortCode=000014" \
  -H "Authorization: Bearer <your-token>"
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "accountName": "JOHN ADEYEMI",
    "accountNumber": "0123456789",
    "bankName": "Access Bank"
  }
}
```

| Query param     | Type   | Required | Description                           |
| --------------- | ------ | -------- | ------------------------------------- |
| `accountNumber` | string | Yes      | 10-digit NUBAN account number         |
| `sortCode`      | string | Yes      | Bank sort code from `/transfer/banks` |

### Step 3 — Initiate the transfer

Send funds from your merchant balance to the verified account using `POST /transfer/bank`.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/transfer/bank \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0123456789",
    "accountName": "JOHN ADEYEMI",
    "sortCode": "000014",
    "amount": 50000,
    "narration": "Payment for services rendered",
    "metadata": {
      "invoiceId": "INV-2026-042"
    }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "reference": "TRF-2026-0408-001",
    "status": "pending",
    "amount": 50000,
    "destinationAccount": "0123456789",
    "destinationBank": "Access Bank",
    "narration": "Payment for services rendered"
  }
}
```

| Field           | Type   | Required | Description                                      |
| --------------- | ------ | -------- | ------------------------------------------------ |
| `accountNumber` | string | Yes      | Destination 10-digit account number              |
| `accountName`   | string | Yes      | Account holder name (from account lookup)        |
| `sortCode`      | string | Yes      | Bank sort code                                   |
| `amount`        | number | Yes      | Amount in kobo                                   |
| `narration`     | string | No       | Description visible on the recipient's statement |
| `metadata`      | object | No       | Arbitrary key-value pairs for your records       |

<Note>
  Always resolve account details before initiating a transfer. The `accountName` you submit is verified against the bank's records during processing.
</Note>

***

## Customer-initiated bank transfer

Use `POST /transfer/bank/customer` to debit a specific customer's wallet and send the funds to a bank account. This is useful for letting customers withdraw to their own external accounts.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/transfer/bank/customer \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "accountNumber": "0123456789",
    "accountName": "JOHN ADEYEMI",
    "sortCode": "000014",
    "amount": 20000,
    "narration": "Withdrawal to Access Bank",
    "reference": "CUST-WDL-2026-001"
  }'
```

| Field           | Type   | Required | Description                        |
| --------------- | ------ | -------- | ---------------------------------- |
| `customerId`    | string | Yes      | The customer whose wallet to debit |
| `accountNumber` | string | Yes      | Destination account number         |
| `accountName`   | string | Yes      | Account holder name                |
| `sortCode`      | string | Yes      | Bank sort code                     |
| `amount`        | number | Yes      | Amount in kobo                     |
| `narration`     | string | No       | Statement narration                |
| `reference`     | string | No       | Your unique transfer reference     |
| `metadata`      | object | No       | Arbitrary key-value pairs          |

***

## Batch bank transfers

Send funds to multiple bank accounts in a single request using `POST /transfer/bank/batch`. The request body is an array of transfer objects.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/transfer/bank/batch \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "accountNumber": "0123456789",
      "accountName": "JOHN ADEYEMI",
      "sortCode": "000014",
      "amount": 50000,
      "narration": "Staff salary - April"
    },
    {
      "accountNumber": "9876543210",
      "accountName": "GRACE NWOSU",
      "sortCode": "000013",
      "amount": 75000,
      "narration": "Staff salary - April"
    }
  ]'
```

Each object in the array accepts the same fields as a single bank transfer. You must include at least one object in the array.

<Warning>
  Batch transfers are processed synchronously. Ensure your account has sufficient balance to cover the total amount across all transactions before submitting.
</Warning>

***

## Wallet-to-wallet transfer

Transfer funds between two customer wallets on your platform using `POST /transfer/wallet-to-wallet`. No interbank processing is involved, so settlements are instant.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/transfer/wallet-to-wallet \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromCustomerId": "cus_abc123",
    "toCustomerId": "cus_def456",
    "amount": 10000
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "reference": "WTW-2026-001",
    "status": "success",
    "amount": 10000,
    "fromCustomerId": "cus_abc123",
    "toCustomerId": "cus_def456"
  }
}
```

| Field            | Type   | Required | Description                  |
| ---------------- | ------ | -------- | ---------------------------- |
| `fromCustomerId` | string | Yes      | Customer ID of the sender    |
| `toCustomerId`   | string | Yes      | Customer ID of the recipient |
| `amount`         | number | Yes      | Amount in kobo               |

<Tip>
  For internal wallet transfers between wallets identified by wallet IDs (rather than customer IDs), use `POST /transfer/wallet`. The body accepts `fromWalletId` and `toWalletId` in place of customer IDs.
</Tip>