Execute Bank Transfer

Send funds to any supported bank account after verifying the recipient. Each transfer requires a unique payment reference for idempotency and reconciliation.

Always verify the recipient’s account before calling transfer(). Funds sent to incorrect accounts may be unrecoverable.

Usage


import { Pay100 } from "@100pay-hq/100pay.js";
 
const client = new Pay100({
  publicKey: "your_public_key",
  secretKey: "your_secret_key",
});
 
const transfer = await client.bankTransfer.transfer({
  beneficiaryBankCode: "044",
  beneficiaryAccountNumber: "1234567890",
  beneficiaryAccountName: "John Doe",
  amount: 50000,                          // Amount in Nigerian Naira (NGN)
  narration: "Payment for services",
  paymentReference: `PAY_${Date.now()}`,  // Must be unique per transfer
  saveBeneficiary: true,
});
 
console.log("Session ID:", transfer.data.transfer.sessionId);
console.log("Status:", transfer.data.transfer.status);

Full Workflow

Get Available Banks

Fetch the bank list to obtain the bank code for your recipient:


const banks = await client.bankTransfer.getBankList();
const targetBank = banks.data.banks.find((b) => b.name?.includes("Access"));

Verify Recipient Account


const verification = await client.bankTransfer.verifyBank({
  bankCode: targetBank.bankCode,
  accountNumber: "1234567890",
});
 
if (!verification.data.verified) {
  throw new Error("Account verification failed");
}

Execute the Transfer


const result = await client.bankTransfer.transfer({
  beneficiaryBankCode: targetBank.bankCode,
  beneficiaryAccountNumber: "1234567890",
  beneficiaryAccountName: verification.data.accountName,
  amount: 50000,
  narration: "Payment for services rendered",
  paymentReference: `PAY_${Date.now()}`,
  saveBeneficiary: true,
});
 
console.log("Transfer initiated:", result.data.transfer.sessionId);

Parameters

Field	Type	Required	Description
`beneficiaryBankCode`	`string`	✅	Bank code from `getBankList()`
`beneficiaryAccountNumber`	`string`	✅	Recipient’s bank account number
`beneficiaryAccountName`	`string`	✅	Recipient’s name — use the name from `verifyBank()`
`amount`	`number`	✅	Amount in Nigerian Naira (NGN)
`narration`	`string`	✅	Transfer description shown on the recipient’s bank statement
`paymentReference`	`string`	✅	A unique reference for this transfer — used for idempotency
`saveBeneficiary`	`boolean`	✅	Whether to save this recipient for future transfers

paymentReference must be unique for each transfer. Use a UUID or timestamp-based ID to avoid conflicts.

Response


{
  "statusCode": 200,
  "message": "Transfer initiated",
  "data": {
    "transfer": {
      "sessionId": "sess_abc123",
      "status": "Processing",
      "amount": 50000,
      "beneficiaryAccountNumber": "1234567890",
      "beneficiaryBankCode": "044",
      "paymentReference": "PAY_1709500000000",
      "narration": "Payment for services rendered",
      "createdAt": "2026-03-03T22:00:00Z"
    }
  }
}

`IBankTransferResponse`

Field	Type	Description
`data.transfer.sessionId`	`string`	Unique session ID for tracking the transfer
`data.transfer.status`	`string`	Initial status: `"Created"`, `"Processing"`, `"Successful"`, `"Failed"`
`data.transfer.amount`	`number`	Transfer amount in NGN
`data.transfer.paymentReference`	`string`	Your unique payment reference
`data.transfer.narration`	`string`	Narration on the bank statement
`data.transfer.createdAt`	`string`	ISO timestamp of transfer creation

Tracking Transfer Status

Transfer status updates are delivered via webhooks. Listen for bank_transfer.debit and bank_transfer.credit events on your webhook endpoint:

"Created" → Transfer is queued
"Processing" → Transfer is being processed by the bank
"Successful" → Funds delivered to recipient
"Failed" → Transfer failed (check webhook payload for reason)

See Webhooks for setup instructions.

Next Steps

List Banks — get bank codes
Verify Account — confirm recipient details first
Webhooks — receive real-time transfer status updates