Skip to main content
Money arriving in a virtual account isn’t something you can read from an API response, so Bitnob tells you with a webhook. Two events cover NGN virtual accounts and KES and UGX mobile money collections: Every delivery has the same envelope, {"event_id", "event", "data"}. Each one is signed: the X-Bitnob-Signature header is an HMAC-SHA512 of the raw request body, keyed with your webhook secret. Verification, retries, and source IPs work the same way as every other Bitnob webhook, and are covered on Webhooks.

virtual_account.deposit.success

Fired when a transfer into one of your NGN virtual accounts is confirmed, normally within 10 minutes of the sender’s transfer, or when a payer approves a mobile money collection. The funds credit your company balance in that currency, not a per-customer balance. Use it to mark an order paid, release goods, or credit the customer in your own ledger.
virtual_account.deposit.success
Mobile money collections also send lifetime, rail, and network inside data.

virtual_account.collection.failed

Fired when a mobile money collection closes without being paid, either because it expired or because the payer didn’t complete the payment. Nothing is credited. Use it to mark the order unpaid, or to ask the payer again with a new collection and a new reference. To see why the collection ended, fetch it with Get virtual account. It has status: "closed" and failure_reason set. This event is only sent for mobile money collections.

Handle it once

  1. Verify the X-Bitnob-Signature header over the raw body. See Verify every delivery.
  2. Skip the event if you’ve already processed its event_id.
  3. Route on event.
  4. For virtual_account.deposit.success, look up which customer or order owns data.virtual_account_id, and credit data.amount in the base units of data.currency.
  5. Respond 200. If your own processing fails temporarily, respond with a 5xx so the event is retried.
Reconcile on a schedule with Get account transactions, so a missed delivery never becomes a missing credit.

Test it in sandbox

Call Simulate deposit instead of waiting on a real payment. Events go to the webhook URL set in your sandbox dashboard.
  • NGN virtual account: each call credits a fixed ₦10,000 ("1000000" kobo), up to ₦100,000 per hour, and sends virtual_account.deposit.success.
  • Mobile money collection: send "outcome": "success" to credit the expected amount and send virtual_account.deposit.success, or "outcome": "failed" to end it unpaid and send virtual_account.collection.failed. See Collect mobile money.