> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Virtual account deposit webhook

> The virtual_account.deposit.success event: when it fires, what each field means, and how to credit a customer from it exactly once.

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](https://www.bitnob.dev/api-reference/webhooks.md).

## `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.

```json virtual_account.deposit.success theme={null}
{
  "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](https://www.bitnob.dev/api-reference/virtual-accounts/get-account-transactions.md). |
| `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](https://www.bitnob.dev/api-reference/virtual-accounts/get-account-transactions.md), so a missed delivery never becomes a missing credit. |

> [!NOTE]
>
> Mobile-money and temporary accounts also send `lifetime`, `rail`, and `network` inside `data`.

## Handle it once

1. Verify the `x-bitnob-signature` header over the raw body. See [Verify every delivery](https://www.bitnob.dev/api-reference/webhooks.md#verify-every-delivery).
2. Skip the event if you've already processed its `event_id`.
3. Look up which customer owns `data.virtual_account_id`, and credit them `data.amount` kobo in your ledger.
4. 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](https://www.bitnob.dev/api-reference/virtual-accounts/get-account-transactions.md), so a missed delivery never becomes a missing credit.

## Test it in sandbox

Call [Simulate deposit](https://www.bitnob.dev/api-reference/virtual-accounts/simulate-deposit-sandbox.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.