Documentation
Virtual Cards Webhook

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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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.

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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.

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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.

JSON
{
  "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"
  }
}