Skip to main content

​
Batch bank transfer

POST /transfer/bank/batch Sends multiple bank transfers in a single request, debiting your merchant settlement wallet for each transaction. Transfers are processed sequentially — each transfer is attempted individually and may succeed, fail (with automatic reversal), or enter a pending state for background retry. The response includes separate accepted and rejected arrays so you can identify which transfers succeeded and which failed without having to query each transaction individually.
Ensure you resolve each beneficiary account with GET /transfer/account/details before submitting. Transfers to unverified accounts may be rejected by the NIP network. Funds for rejected or reversed transfers are returned to your merchant wallet automatically.

​
Request

​
Authorization
string
required
Bearer token. Requires MANAGE_TRANSFER permission.
The request body is a JSON array of transfer objects. At least one item is required.
​
[].amount
number
required
Transfer amount in kobo for this item. Must be greater than 0.
​
[].sortCode
string
required
Bank sort code for the beneficiary. Obtain valid codes from GET /transfer/banks.
​
[].accountNumber
string
required
Beneficiary account number.
​
[].accountName
string
required
Beneficiary account name as resolved by GET /transfer/account/details.
​
[].narration
string
Transfer narration visible to the beneficiary.

​
Response

​
status
boolean
true on success.
​
message
string
"Transaction has been successfully completed."
​
data
object

​
Examples

curl -X POST https://api.tagpay.ng/v1/transfer/bank/batch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "amount": 5000000,
      "sortCode": "000013",
      "accountNumber": "0123456789",
      "accountName": "OKONKWO AMAKA",
      "narration": "Salary May 2024"
    },
    {
      "amount": 3000000,
      "sortCode": "000016",
      "accountNumber": "3012345678",
      "accountName": "CHIDI EZE",
      "narration": "Bonus payment"
    },
    {
      "amount": 1500000,
      "sortCode": "000004",
      "accountNumber": "2098765432",
      "accountName": "NGOZI ADAEZE",
      "narration": "Freelance payment"
    }
  ]'
Response
{
  "status": true,
  "message": "Transaction has been successfully completed.",
  "data": {
    "reference": "BATCH-20240501-TXN-XYZ001",
    "all": [
      {
        "amount": 5000000,
        "sortCode": "000013",
        "accountNumber": "0123456789",
        "accountName": "OKONKWO AMAKA",
        "narration": "Salary May 2024",
        "charges": 5000,
        "vat": 375,
        "total": 5005375,
        "reference": "TXN-20240501-A1B2C3",
        "bankName": "GUARANTY TRUST BANK"
      },
      {
        "amount": 3000000,
        "sortCode": "000016",
        "accountNumber": "3012345678",
        "accountName": "CHIDI EZE",
        "narration": "Bonus payment",
        "charges": 5000,
        "vat": 375,
        "total": 3005375,
        "reference": "TXN-20240501-D4E5F6",
        "bankName": "FIRST BANK OF NIGERIA"
      },
      {
        "amount": 1500000,
        "sortCode": "000004",
        "accountNumber": "2098765432",
        "accountName": "NGOZI ADAEZE",
        "narration": "Freelance payment",
        "charges": 5000,
        "vat": 375,
        "total": 1505375,
        "reference": "TXN-20240501-G7H8I9",
        "bankName": "UNITED BANK FOR AFRICA"
      }
    ],
    "accepted": [
      {
        "amount": 5000000,
        "reference": "TXN-20240501-A1B2C3",
        "accountName": "OKONKWO AMAKA",
        "accountNumber": "0123456789",
        "metadata": {
          "transactionReference": "NIP-20240501-001",
          "responseMessage": "Approved"
        }
      },
      {
        "amount": 3000000,
        "reference": "TXN-20240501-D4E5F6",
        "accountName": "CHIDI EZE",
        "accountNumber": "3012345678",
        "metadata": {
          "transactionReference": "NIP-20240501-002",
          "responseMessage": "Approved"
        }
      }
    ],
    "rejected": [
      {
        "amount": 1500000,
        "reference": "TXN-20240501-G7H8I9",
        "accountName": "NGOZI ADAEZE",
        "accountNumber": "2098765432",
        "reason": "Transaction failed. Unable to resolve recipient details",
        "metadata": {
          "responseMessage": "Beneficiary account not found"
        }
      }
    ]
  }
}

​
CSV bulk customer transfer

POST /wallet/bulk-csv-customer-transfer Sends bank transfers to multiple recipients by uploading a CSV file. Each row in the CSV becomes a separate bank transfer debited from your merchant wallet. Processing is asynchronous.
This endpoint uses multipart form upload. The file field name must be list. Processing may take several minutes depending on the size of the file.

​
Request

​
Authorization
string
required
Bearer token.
​
Content-Type
string
required
multipart/form-data
​
list
file
required
CSV file containing transfer instructions. One transfer per row.

​
Examples

curl -X POST https://api.tagpay.ng/v1/wallet/bulk-csv-customer-transfer \
  -H "Authorization: Bearer <token>" \
  -F "list=@/path/to/transfers.csv"

​
CSV bulk wallet transfer

POST /wallet/bulk-csv-wallet-transfer Similar to CSV bulk customer transfer, but transfers funds between customer wallets rather than to external bank accounts. Each row specifies source and destination wallet account numbers.

​
Request

​
Authorization
string
required
Bearer token.
​
Content-Type
string
required
multipart/form-data
​
list
file
required
CSV file containing wallet-to-wallet transfer instructions. The file field name must be list.

​
Examples

curl -X POST https://api.tagpay.ng/v1/wallet/bulk-csv-wallet-transfer \
  -H "Authorization: Bearer <token>" \
  -F "list=@/path/to/wallet-transfers.csv"

​
Batch status tracking

After submitting a batch transfer, monitor the status of individual transactions using the reference values returned in the accepted array. Use your webhook endpoint to receive real-time updates. Webhook events fired after batch processing:
EventDescription
bank_transferFired for each individual bank transfer that completes (success or failure)
batch_merchant_bank_transferFired once for the entire batch when all transfers have been resolved
Transaction statuses:
StatusDescription
successTransfer completed and funds credited to beneficiary
pendingTransfer submitted to the payment network; awaiting confirmation. Automatically retried
failedTransfer failed definitively; funds reversed to your merchant wallet
Store the data.reference (batch reference) and all individual reference values from data.accepted immediately. You’ll need these to reconcile your records if webhook delivery is delayed or you need to query transaction history.

​
Error responses

HTTP StatusDescription
400Insufficient merchant wallet balance for the total batch amount
400Daily transaction limit exceeded
400Merchant wallet is inactive
400Empty batch — at least one transfer item required
400Lien restriction on account — contact support
401Missing or invalid authentication token
403NIP transfers not enabled on this account
400 Insufficient Balance
{
  "status": false,
  "message": "Insufficient available balance for this transaction."
}
400 Daily Limit
{
  "status": false,
  "message": "Daily transaction limit exceeded.."
}