Virtual account deposit webhook

Money arriving in a virtual account isn’t something you initiate, so there’s no response to read it from. Bitnob sends virtual_account.deposit.success to your webhook URL when a transfer lands, normally within 10 minutes of the sender’s transfer. The funds credit your company NGN balance, not a per-customer balance. Signature verification, retries, and source IPs work the same way as every other Bitnob webhook. They’re covered on Webhooks.

`virtual_account.deposit.success`

Fired when a transfer into one of your virtual accounts is confirmed. Use it to mark an order paid, release goods, or credit the customer in your own ledger.

virtual_account.deposit.success

{
  "event": "virtual_account.deposit.success",
  "event_id": "c5efb1ec-2912-4619-90f7-93b5172fd712",
  "data": {
    "amount": "5000000",
    "currency": "NGN",
    "transaction_id": "1fcda02a-8af6-4019-bef9-2a9dfacae4a3",
    "ledger_transaction_id": "1fcda02a-8af6-4019-bef9-2a9dfacae4a3",
    "provider_transaction_id": "ad2c9abb-4a1e-470a-835c-228778fc17f0",
    "reference": "DEP_fce659bd60fe7b7",
    "virtual_account_id": "01a061d3-68c0-7ce6-80a5-af2cb46308bc"
  }
}

Field	Type	Description
`event`	string	Always `virtual_account.deposit.success` for this event. Route on this value.
`event_id`	UUID	Unique per event. Use it as an idempotency key so a redelivered event isn’t credited twice.
`data.amount`	string	Amount deposited, as an integer string in kobo. `"5000000"` is ₦50,000.00.
`data.currency`	string	Currency of the deposit. `NGN` for Nigerian virtual accounts.
`data.virtual_account_id`	UUID	The account the money landed in. Use it to attribute the deposit to one of your customers.
`data.transaction_id`	UUID	The transaction for this deposit. Matches `transaction_id` on Get account transactions.
`data.ledger_transaction_id`	UUID	Same value as `transaction_id`. Use `transaction_id` in new integrations.
`data.provider_transaction_id`	UUID	Identifier from the upstream bank partner. Quote it when you raise a query about a specific transfer.
`data.reference`	string	Reference for the deposit. Matches the transaction returned by Get account transactions, so a missed delivery never becomes a missing credit.

Mobile-money and temporary accounts also send lifetime, rail, and network inside data.

Handle it once

Verify the x-bitnob-signature header over the raw body. See Verify every delivery.
Skip the event if you’ve already processed its event_id.
Look up which customer owns data.virtual_account_id, and credit them data.amount kobo in your ledger.
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 transfer. Each call credits a fixed ₦10,000 ("1000000" kobo), up to ₦100,000 per hour, and fires this event to the webhook URL set in your sandbox dashboard.

Get started

Bitcoin

Stablecoins

Trading

Payouts

Card issuing

Virtual accounts

Virtual account deposit webhook

`virtual_account.deposit.success`

Handle it once

Test it in sandbox

​virtual_account.deposit.success

​Handle it once

​Test it in sandbox

`virtual_account.deposit.success`

Handle it once

Test it in sandbox