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
- Verify the
X-Bitnob-Signatureheader over the raw body. See Verify every delivery. - Skip the event if you’ve already processed its
event_id. - Route on
event. - For
virtual_account.deposit.success, look up which customer or order ownsdata.virtual_account_id, and creditdata.amountin the base units ofdata.currency. - Respond
200. If your own processing fails temporarily, respond with a5xxso the event is retried.
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 sendsvirtual_account.deposit.success. - Mobile money collection: send
"outcome": "success"to credit the expected amount and sendvirtual_account.deposit.success, or"outcome": "failed"to end it unpaid and sendvirtual_account.collection.failed. See Collect mobile money.