Virtual Cards Webhooks

Virtual card webhooks are fired when a customers perform any virtual card action.

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 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": "[email protected]"
  }
}

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": "[email protected]"
  }
}

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 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 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 Authorization Failed Termination

This is a webhook that is fired when the user is charged for card termination due to insufficient fund

{
  "event": "virtualcard.authorization.failed.termination",
  "data": {
    "status": "success",
    "cardId": "b0fd1b23-bc2c-44d7-9db9-b0d9f1bcf77d",
    "id": "6949f20a-ea19-4585-8a73-06f2dd537613",
    "companyId": "7e366e9f-bf52-46e9-9c18-f1fb46091151",
    "amount": 100,
    "reference": "odlWrYUnuMKo8SL"
  }
}