One integration for payments, cards, bills and payouts.
MyBundlePay gives developers a clean payment gateway, virtual account funding, payout rails, card issuing tools, bill payments, webhooks and merchant-ready checkout experiences.
API Test Console
Test the current endpoint directly from the documentation. Secret keys stay inside this browser session.
Enter your test key, review the sample body for this page, then send a request.
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": "[email protected]"
}
}❌ 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": "[email protected]"
}
}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"
}
}