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.complete

Fired when a virtual card is successfully created and active.

virtualcard.created.complete Payload

virtualcard.created.failed

Fired when card creation fails.

virtualcard.terminated.refund

Remaining balance refunded after card termination.

virtualcard.regularized

Card regularized after compliance or balance adjustment.

virtualcard.expiration

Card has expired and can no longer be used.

Card Funding Webhooks

virtualcard.topup.complete

Card top-up (load funds) succeeded.

virtualcard.topup.complete Payload

virtualcard.topup.failed

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

Card Withdrawal Webhooks

virtualcard.withdrawal.complete

A successful withdrawal was made from the card.

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.credit

Credit applied to the card.

virtualcard.transaction.authorization

Authorization hold placed by merchant.

virtualcard.transaction.settlement

Merchant settled a previously authorized transaction.

virtualcard.transaction.verification

Zero-amount authorization to verify card is active.

virtualcard.transaction.pre-auth.approved

Pre-authorization approved by the card network.

virtualcard.transaction.reversed

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

virtualcard.transaction.refund

Merchant refund after settlement.

virtualcard.transaction.crossborder

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

virtualcard.transaction.contactless

Contactless (NFC/tap) payment processed.

virtualcard.transaction.terminated.refund

Refund to a terminated card. Funds returned to the float or master account.

Declines & Risk Event Webhooks

virtualcard.transaction.declined

A purchase attempt was declined.

virtualcard.transaction.declined.charge

Fired when a decline rule violation fee is charged to your USD wallet, or when a card is terminated due to reaching the violation threshold. See the Decline Rule Policy for full details.

virtualcard.transaction.declined.charge Payload

virtualcard.transaction.declined.frozen

Transaction declined because the card is frozen, usually from a fraud rule.

virtualcard.transaction.declined.terminated

Transaction declined because the card has been terminated.

virtualcard.transaction.authorization.failed

Authorization attempt failed due to insufficient funds or card configuration.

virtualcard.transaction.issuerexpiration

Transaction declined due to issuer expiration.

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.complete	Card Lifecycle	Card was successfully created and is now active.
virtualcard.created.failed	Card Lifecycle	Card creation failed. Check reason in payload.
virtualcard.terminated.refund	Card Lifecycle	Remaining balance refunded after card termination.
virtualcard.regularized	Card Lifecycle	Card regularized after compliance or balance adjustment.
virtualcard.expiration	Card Lifecycle	Card has expired.
virtualcard.topup.complete	Top-Up	Card was funded successfully.
virtualcard.topup.failed	Top-Up	Card funding attempt failed.
virtualcard.withdrawal.complete	Withdrawal	Withdrawal from card completed.
virtualcard.withdrawal.failed	Withdrawal	Withdrawal failed (e.g. limit, balance, status).
virtualcard.transaction.debit	Transaction	A purchase or spend was successful.
virtualcard.transaction.credit	Transaction	Credit applied to the card.
virtualcard.transaction.authorization	Transaction	Authorization hold placed by merchant.
virtualcard.transaction.settlement	Transaction	Merchant settled a previously authorized transaction.
virtualcard.transaction.verification	Transaction	Zero-amount authorization to verify card is active.
virtualcard.transaction.pre-auth.approved	Transaction	Pre-authorization approved by the card network.
virtualcard.transaction.reversed	Transaction	Merchant canceled a pending transaction.
virtualcard.transaction.refund	Transaction	Merchant refunded a completed transaction.
virtualcard.transaction.crossborder	Transaction	Cross-border charge during international use.
virtualcard.transaction.contactless	Transaction	Contactless (NFC/tap) payment processed.
virtualcard.transaction.terminated.refund	Transaction	Refund to a terminated card, credited to float.
virtualcard.transaction.declined	Decline	Transaction declined.
virtualcard.transaction.declined.charge	Decline	Decline rule violation fee charged.
virtualcard.transaction.declined.frozen	Decline	Transaction declined because card is frozen.
virtualcard.transaction.declined.terminated	Decline	Transaction declined because card is terminated.
virtualcard.transaction.authorization.failed	Decline	Authorization attempt failed.
virtualcard.transaction.issuerexpiration	Decline	Transaction declined due to issuer expiration.

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.