Webhooks

Introduction

Bitnob emits real-time webhook events that inform your system of all important activities and lifecycle events related to your virtual cards.

Each webhook provides structured data about:

Transaction outcomes (approved, failed, reversed, refunded),

Card lifecycle changes (created, terminated, frozen),

Operational risk events (failed authorizations, fraud flags, cross-border activity).

Webhooks are delivered to your registered callback URL via HTTPS POST requests.

Webhook Structure

All webhook payloads follow the same top-level format:

Webhook Payload Structure

Webhook Categories

category	description
Card Lifecycle	When a card is created, fails to create, or is terminated
Top-Ups & Withdrawals	When a card is loaded or funds are withdrawn
Transaction Activity	Purchases, refunds, declines, reversals, authorization failures
Risk Events	Automated freezes, terminations, MCC restrictions, cross-border use
Refunds on Terminated Cards	Handling of funds after a card is closed

Card Lifecycle Webhooks

virtualcard.created.success

Fired when a virtual card is successfully created.

virtualcard.created.success Payload

virtualcard.created.failed

Fired when card creation fails.

virtualcard.created.failed Payload

Card Funding Webhooks

virtualcard.topup.success

Card top-up (load funds) succeeded.

virtualcard.topup.failed

Top-up failed (e.g. insufficient balance, card status invalid).

virtualcard.topup.success Payload

Card Withdrawal Webhooks

virtualcard.withdrawal.success

A successful withdrawal was made (if enabled).

virtualcard.withdrawal.failed

Withdrawal attempt failed (e.g. below minimum balance, card status invalid).

Transaction Webhooks

virtualcard.transaction.debit

Successful spend or purchase transaction.

virtualcard.transaction.reversed

An authorized transaction was reversed (merchant canceled before settlement).

virtualcard.transaction.refund

Merchant refund after settlement.

Charge related to cross-border transaction applied to the card.

virtualcard.transaction.authorization.failed

Authorization attempt failed due to insufficient funds or card configuration.

Declines & Risk Event Webhooks

virtualcard.transaction.declined

A purchase attempt was declined.

virtualcard.transaction.declined.frozen

Transaction declined due to card being frozen, usually from a fraud rule.

virtualcard.transaction.declined.terminated

Card was auto-terminated after repeated failed attempts (see risk rules in status management).

Refunds After Termination

virtualcard.transaction.terminated.refund

Refund processed for a card that was already terminated. Funds returned to the float or master account.

Best Practices for Handling Webhooks

practice	why it matters
Acknowledge with HTTP 200	Prevent retries and duplication
Log and verify every event	Enables reconciliation and debugging
Use event type (event) to route logic	Cleanly separate card creation, spend, and risk events
Secure your webhook endpoint	Use HMAC signature verification (Bitnob will provide guide)
Make it idempotent	Replaying the same webhook shouldn’t create duplicate logic

Virtual Card Webhooks – Reference Table

event name	category	description
virtualcard.created.success	Card Lifecycle	Card was successfully created and is now active.
virtualcard.created.failed	Card Lifecycle	Card creation failed. Check reason in payload.
virtualcard.topup.success	Top-Up	Card was funded successfully from float/wallet.
virtualcard.topup.failed	Top-Up	Card funding attempt failed.
virtualcard.withdrawal.success	Withdrawal	Cash withdrawal from card succeeded (if supported).
virtualcard.withdrawal.failed	Withdrawal	Withdrawal failed (e.g. limit, balance, status).
virtualcard.transaction.debit	Transaction	A purchase or spend was successful.
virtualcard.transaction.reversed	Transaction	An authorized transaction was canceled by the merchant.
virtualcard.transaction.refund	Transaction	Merchant refunded a completed transaction.
virtualcard.transaction.crossborder	Fee/Charge	Cross-border charge occurred during international use.
virtualcard.transaction.authorization.failed	Transaction	Authorization request failed (e.g. insufficient funds).
virtualcard.transaction.declined	Decline	Transaction declined (generic failure reason provided).
virtualcard.transaction.declined.frozen	Risk	Card was frozen due to flagged activity (fraud rule).
virtualcard.transaction.declined.terminated	Risk	Card was auto-terminated due to multiple failed attempts.
virtualcard.transaction.terminated.refund	Refund	A terminated card received a refund. Funds returned to float.

Next Steps

You can test webhook delivery via the Bitnob API or by manually triggering test events from your dashboard.

Subscribe to sandbox events first to validate your implementation.

For production use, make sure to log all failed deliveries and monitor retry queues.