Skip to Content
đź‘‹ Welcome to 100Pay Developers
DocsWebhooksBank Transfer Events

Bank Transfer Events

EventTrigger
bank_transfer.debitAn outgoing bank transfer you initiated changed status
bank_transfer.creditAn incoming bank transfer was received into one of your accounts

bank_transfer.debit — Outgoing Transfer

Fired when you initiate a transfer via the transfer API and again on each provider status update. One event fires per status transition (Created, Processing, Successful, Failed) — the dedupe reference is <paymentReference>:<status>.

interface BankTransferDebitWebhook {
  eventType: "bank_transfer.debit";
  eventRef: string;          // "<reference>:<status>" — unique per transition
  transactionId: string;
  reference: string;         // your payment reference, e.g. "TXF-1700000000000-ab12-cd34"
  amount: number;
  timestamp: string;
  transaction: {             // the full wallet ledger transaction
    _id: string;
    transactionHash: string;
    transactionSignature: string;
    status: "successful" | "pending" | "failed";
    type: "debit";
    amount: string;
    symbol: string;          // e.g. "NGN"
    category: string;
    accountId: string;
    appId: string;
    from: string;            // your business name
    to: string;              // "RECIPIENT NAME / accountNumber"
  };
  data: {                    // provider transfer details
    type: "Outwards";
    sessionId: string;
    paymentReference: string;
    provider: string;        // e.g. "NIBSS"
    providerChannel: string; // e.g. "NIP"
    destinationInstitutionCode: string;
    creditAccountName: string;
    creditAccountNumber: string;
    debitAccountName: string;
    narration: string;
    amount: number;
    fees: number;
    vat: number;
    stampDuty: number;
    status: "Created" | "Processing" | "Successful" | "Failed";
  };
}

Example

{
  "eventType": "bank_transfer.debit",
  "eventRef": "TXF-1700000000000-ab12-cd34:Successful",
  "transactionId": "665f1c2e8b6a4a0012a4d940",
  "reference": "TXF-1700000000000-ab12-cd34",
  "amount": 50,
  "timestamp": "2026-03-12T14:45:46.995Z",
  "transaction": {
    "_id": "665f1c2e8b6a4a0012a4d940",
    "transactionHash": "090000000000000000000000000000",
    "transactionSignature": "pre-1700000000000-xxxxxxxxx-debit-JOHN DOE / 0123456789-My Business",
    "status": "successful",
    "type": "debit",
    "amount": "50",
    "symbol": "NGN",
    "category": "uncategorized",
    "accountId": "665f0aa18b6a4a0012a4d100",
    "appId": "62ee5dbfb029b7002d5b7453",
    "from": "My Business",
    "to": "JOHN DOE / 0123456789"
  },
  "data": {
    "type": "Outwards",
    "sessionId": "090000000000000000000000000000",
    "paymentReference": "TXF-1700000000000-ab12-cd34",
    "provider": "NIBSS",
    "providerChannel": "NIP",
    "destinationInstitutionCode": "100004",
    "creditAccountName": "JOHN DOE",
    "creditAccountNumber": "0123456789",
    "debitAccountName": "ACME TECHNOLOGIES LIMITED / CURRENT",
    "narration": "Payment for consulting services",
    "amount": 50,
    "fees": 10,
    "vat": 0.75,
    "stampDuty": 0,
    "status": "Successful"
  }
}

Status lifecycle

data.statusMeaning
CreatedTransfer accepted and queued — not yet final
ProcessingSubmitted to the interbank network, awaiting confirmation
SuccessfulFunds delivered to the recipient
FailedTransfer failed — funds are reversed to your wallet

Do not treat the first bank_transfer.debit event as final — it usually arrives with data.status: "Created". Wait for the Successful (or Failed) transition, or verify with the transfer verification API.

bank_transfer.credit — Incoming Transfer

Fired when a bank deposit is received and credited to your wallet.

interface BankTransferCreditWebhook {
  eventType: "bank_transfer.credit";
  transferId: string;
  amount: number;
  currency: string;          // e.g. "NGN"
  timestamp: string;
  transaction: {             // the full wallet ledger credit transaction
    _id: string;
    transactionHash: string;
    status: "successful";
    type: "credit";
    amount: string;
    symbol: string;
    category: string;
    accountId: string;
    appId: string;
    from: string;
    to: string;
  };
  data: {                    // provider details (sender info)
    sessionId: string;
    debitAccountName: string;   // sender name
    creditAccountNumber: string;
    narration: string;
    fees: number;
    status: string;
  };
}

Example

{
  "eventType": "bank_transfer.credit",
  "transferId": "665f1c2e8b6a4a0012a4d950",
  "amount": 25000,
  "currency": "NGN",
  "timestamp": "2026-03-12T15:05:00.000Z",
  "transaction": {
    "_id": "665f1c2e8b6a4a0012a4d950",
    "transactionHash": "100000000000000000000000000001",
    "status": "successful",
    "type": "credit",
    "amount": "25000",
    "symbol": "NGN",
    "category": "fiatDeposit",
    "accountId": "665f0aa18b6a4a0012a4d100",
    "appId": "62ee5dbfb029b7002d5b7453",
    "from": "JANE SMITH",
    "to": "9876543210"
  },
  "data": {
    "sessionId": "100000000000000000000000000001",
    "debitAccountName": "JANE SMITH",
    "creditAccountNumber": "9876543210",
    "narration": "Transfer from Jane",
    "fees": 0,
    "status": "Completed"
  }
}

Sensitive provider fields (internal client/account identifiers, sender account numbers on debits) are stripped from data before delivery.

Last updated on
WebhooksCustomer Events