Funds Transfer

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 [email protected] 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.

cURL

curl -X GET https://api.tagpay.ng/v1/transfer/banks \
  -H "Authorization: Bearer <your-token>"

Response

{
  "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.

cURL

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

Response

{
  "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.

cURL

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"
    }
  }'

Response

{
  "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

Always resolve account details before initiating a transfer. The accountName you submit is verified against the bank’s records during processing.

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.

cURL

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.

cURL

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.

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

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.

cURL

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
  }'

Response

{
  "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

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.

Get Started

Core Concepts

Guides

Prerequisites

Bank transfers

Step 1 — List available banks

Step 2 — Resolve account details

Step 3 — Initiate the transfer

Customer-initiated bank transfer

Batch bank transfers

Wallet-to-wallet transfer

​Prerequisites

​Bank transfers

​Step 1 — List available banks

​Step 2 — Resolve account details

​Step 3 — Initiate the transfer

​Customer-initiated bank transfer

​Batch bank transfers

​Wallet-to-wallet transfer

Prerequisites

Bank transfers

Step 1 — List available banks

Step 2 — Resolve account details

Step 3 — Initiate the transfer

Customer-initiated bank transfer

Batch bank transfers

Wallet-to-wallet transfer