Virtual Cards Webhooks
Virtual card webhooks are fired when a customers perform any virtual card action.
Virtual Cards Top
Virtual Card Top-up Success
This is a webhook that is fired when a virtual card 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"
}
}
Virtual Card Top-up Failed
This is a webhook that is fired when a virtual card 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 Cards Withdrawal
Virtual Card Withdrawal Success
This is a webhook that is fired when there is a successful withdrawal on a virtual card
{
"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
}
}
Virtual Card Withdrawal Fail
This is a webhook that is fired when virtual card 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 Cards Transaction
Virtual Card Transaction Debit
This is a webhook that is fired when there is a debit transaction on a virtual card
{
"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"
}
}
Virtual Card Withdrawal Fail
This is a webhook that is fired when virtual card 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 Cards Transaction
Virtual Card Transaction Debit
This is a webhook that is fired when there is a debit transaction on a virtual card
{
"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"
}
}
Virtual Card Transaction Reversed
This is a webhook that is fired when there is a reversed transaction on a virtual card
{
"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"
}
}
Virtual Card Transaction Declined
This is a webhook that is fired when a purchase attempt 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"
}
}
"Virtual Card Transaction Declined Frozen",
This webhook is triggered when a card is frozen due to insufficient funds, resulting in a declined authorization.
{
"event": "virtualcard.transaction.declined.frozen",
"data": {
"cardId": "b6c010000-2e00-0000-9e00-e7ab0ae000db",
"reason": "Suspected Fraud",
"companyId": "b6c010000-2e00-0000-9e00-e7ab0ae000db",
"reference": "6f42d570ghjj"
}
}
Virtual Card Transaction Declined Termination
This is a webhook that is fired when a virtual card is terminated for multiple failed transactions due to insufficient
{
"updatedAt": "2023-12-07T13:15:54.926Z",
"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
}
}
Virtual Card Transaction Authorization Failed
This is a webhook that is fired when a transaction on a virtual card fails due to insufficient fund
{
"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"
}
}
Virtual Card Transaction Crossborder
This is a webhook that is fired when there is a cross-border payment charge on your 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 Created Success
This is a webhook that is fired when virtual card is created successfully
{
"event": "virtualcard.created.success",
"data": {
"id": "7357a387-1157-45a1-9eb5-440a7018a458",
"status": "active",
"companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
"reference": "c12d5d0add692ba2",
"createdStatus": "success"
}
}
Virtual Card KYC
Virtual Card KYC Success
This is a webhook that is fired when a virtual card user's 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"
}
}
Virtual Card KYC Failed
This is a webhook that is fired when a virtual card user's KYC is rejected
{
"event": "virtualcard.user.kyc.failed",
"data": {
"id": "11d5c966-60f2-4a11-910f-e51d914b9a0b",
"reason": "Oops.. we're having issues verifying your ID at the moment, it's our fault not yours, the Government ID provider for this service is currently down. Please try again after some time, or try using another ID type..",
"companyId": "246d1cfc-9eeb-4ddd-95d1-5887fe32d941",
"kycPassed": false,
"customerId": "aaf7a252-81e3-4e8a-ae94-9210a3ea313d",
"customerEmail": "bodeseqo@lyft.live"
}
}
Virtual Card Transaction Terminated Refund
This is a webhook that is fired when a virtual card transaction is terminated it receives a 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"
}
}