Virtual Card Webhooks
Webhooks are triggered automatically when events occur on a customer’s virtual card. These allow you to track card lifecycle events such as creation, top-ups, withdrawals, transactions, KYC updates, and more.
📦 Endpoint Setup
Register your webhook URL in the MyBundlePay Dashboard → Developers → Webhooks.
Ensure your server can receive POST requests with Content-Type: application/json.
Every webhook payload includes an event field and a data object containing event-specific details.
Webhook Events
Virtual Card Creation
✅ virtualcard.created.success — Fired when a virtual card is successfully created.
{
"event": "virtualcard.created.success",
"data": {
"id": "c789e3cf-31cd-4680-b820-bca71012f5dc",
"status": "active",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"reference": "CRD_CREATE_b8fed75a2d1e730c",
"createdStatus": "success"
}
}❌ virtualcard.created.failed — Fired when a virtual card creation fails.
{
"event": "virtualcard.created.failed",
"data": {
"id": "908d33f4-e272-4971-8a52-6d06106cdd7e",
"reason": "Something went wrong. Please try again.",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"reference": "CRD_CREATE_fbd95677f8da1ce1"
}
}Virtual Card Top-up
✅ virtualcard.topup.success — Fired when a top-up is successful.
{
"event": "virtualcard.topup.success",
"data": {
"id": "4850584a-bd83-47d5-850c-0026c1ac53f5",
"amount": 300,
"cardId": "84fa6bce-be2c-4d79-9e6a-b111aff0b226",
"status": "success",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"narrative": "Top-up card",
"reference": "4981db52eacb1dd1"
}
}❌ virtualcard.topup.failed — Fired when a top-up fails.
{
"event": "virtualcard.topup.failed",
"data": {
"id": "662337aa-fcb1-4953-8f90-7df9e271248f",
"amount": 969,
"cardId": "fd8156aa-af32-4589-b842-0c5be28bbff8",
"status": "failed",
"companyId": "b4e0ea36-bdb6-4c12-8931-b73f85ab361b",
"narrative": "Top-up card",
"reference": "B7NX9GQOFPZQ"
}
}Virtual Card Withdrawal
✅ virtualcard.withdrawal.success — Fired when a withdrawal succeeds.
{
"event": "virtualcard.withdrawal.success",
"data": {
"status": "success",
"cardId": "692bbb4c-e5af-4ac1-ab9b-dc30c532aa11",
"id": "5272ff4d-6f8d-47e2-b430-4f75654acf14",
"companyId": "45422f21-9a0e-479e-9e10-615556448a78",
"amount": 600,
"reference": "1445ed09a724",
"narrative": "Withdraw from card",
"isTerminated": false
}
}❌ virtualcard.withdrawal.failed — Fired when a withdrawal fails.
{
"event": "virtualcard.withdrawal.failed",
"data": {
"id": "a6c99bef-37a8-4f74-a5d1-dd39c194aca3",
"amount": 500,
"cardId": "fa2c4efe-d683-452b-9e3b-acce99415291",
"status": "failed",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"narrative": "Withdraw from card",
"reference": "71b8e04de49c4f5e",
"isTerminated": false
}
}Virtual Card Transactions
💳 virtualcard.transaction.debit — Fired for debit transactions.
{
"event": "virtualcard.transaction.debit",
"data": {
"id": "68e5dbbe-f8ea-4569-b5bf-aa059c79ad05",
"amount": 400,
"cardId": "5c263ea6-8c1c-0h0l-9bfa-2d5842f068ca",
"reason": null,
"status": "success",
"companyId": "c16a147e-119f-0h0l-88c0-b14d908f9727",
"narrative": "aliexpress",
"reference": "f8d7664ed609"
}
}♻️ virtualcard.transaction.reversed — Fired when a transaction is reversed.
{
"event": "virtualcard.transaction.reversed",
"data": {
"id": "b685a7f7-6758-44c3-8097-67893d02d1ee",
"amount": 100,
"cardId": "17543a28-5916-48a2-ba94-a41887cea6ca",
"reason": null,
"status": "success",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"narrative": "PAYPAL",
"reference": "ea43c6bbb998"
}
}🚫 virtualcard.transaction.declined — Fired when a transaction is declined.
{
"event": "virtualcard.transaction.declined",
"data": {
"id": "5104a031-4fe5-4ff5-812d-5ba0b1658436",
"amount": 330,
"cardId": "736545b8-2eda-48cf-8eff-03f1dfb8514e",
"reason": "No sufficient funds",
"status": "failed",
"companyId": "b4e0ea36-bdb6-4c12-8931-b73f85ab361b",
"narrative": "GOOGLE*ADS2260628213",
"reference": "e3d7b37de816"
}
}🧊 virtualcard.transaction.declined.frozen — Fired when a card is frozen for suspected fraud.
{
"event": "virtualcard.transaction.declined.frozen",
"data": {
"cardId": "b6c010000-2e00-0000-9e00-e7ab0ae000db",
"reason": "Suspected Fraud",
"companyId": "b6c010000-2e00-0000-9e00-e7ab0ae000db",
"reference": "6f42d570ghjj"
}
}⛔ virtualcard.transaction.declined.terminated — Fired when card is terminated due to repeated failed transactions.
{
"event": "virtualcard.transaction.declined.terminated",
"data": {
"cardId": "7ee8a383-c8bc-4b6c-8cb6-f107c0cadac1",
"reason": "Insufficient Funds",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"reference": "4921bba1a6a7edf5",
"balanceBeforeTermination": 90
}
}💵 virtualcard.transaction.authorization.failed — Fired when authorization fails (e.g., insufficient funds).
{
"event": "virtualcard.transaction.authorization.failed",
"data": {
"id": "79454f05-6357-4c82-9f78-6fe7cf983de2",
"amount": 20,
"cardId": "225762c9-3468-404b-bcc0-4d7d6f2d7312",
"reason": "insufficient funds",
"status": "success",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"reference": "84fa1cac8ba1"
}
}🌍 virtualcard.transaction.crossborder — Fired for cross-border charge on USD wallet.
{
"event": "virtualcard.transaction.crossborder",
"data": {
"amount": 103,
"cardId": "d8116cff-7c66-0000-90c9-31c6daea000",
"status": "success",
"companyId": "c16a147e-119f-0000-88c0-b14d908f9727",
"narrative": "METAPAY SN6D",
"chargedAmount": 50
}
}Virtual Card KYC
✅ virtualcard.user.kyc.success — Fired when user KYC is approved.
{
"event": "virtualcard.user.kyc.success",
"data": {
"id": "4efdf2e1-55b1-432d-b343-06adf1b51ce1",
"companyId": "45422f21-9a0e-479e-9e10-615556448a78",
"kycPassed": true,
"customerId": "cc8bfc56-f612-4132-9228-29952d0a5036",
"customerEmail": "khamani.brennus@meshfor.com"
}
}❌ virtualcard.user.kyc.failed — Fired when KYC is rejected.
{
"event": "virtualcard.user.kyc.failed",
"data": {
"id": "11d5c966-60f2-4a11-910f-e51d914b9a0b",
"reason": "Government ID provider currently down. Please try again later.",
"companyId": "246d1cfc-9eeb-4ddd-95d1-5887fe32d941",
"kycPassed": false,
"customerId": "aaf7a252-81e3-4e8a-ae94-9210a3ea313d",
"customerEmail": "bodeseqo@lyft.live"
}
}Virtual Card Termination Refund
{
"event": "virtualcard.transaction.terminated.refund",
"data": {
"id": "a25abd5f-4e32-4d7f-b19d-038fc0c0175c",
"date": "2024-08-04T20:51:57.290Z",
"amount": "173",
"cardId": "19a03284-db8b-42c3-a398-97696e78ecea",
"reason": null,
"status": "success",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"narrative": "Balance refund of 1.73 on terminated card",
"reference": "1aceac348e95"
}
}