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

JSON

{
  "event": "virtualcard.transaction.debit",
  "data": {
    "id": "68e5dbbe-f8ea-4569-b5bf-aa059c79ad05",
    "cardId": "5c263ea6-8c1c-0h0l-9bfa-2d5842f068ca",
    "companyId": "c16a147e-119f-0h0l-88c0-b14d908f9727",
    "reference": "f8d7664ed609",
    "narrative": "aliexpress",
    "status": "success",
    "reason": null,
    "amount": 40
  }
}

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",
    "cardId": "17543a28-5916-48a2-ba94-a41887cea6ca",
    "companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
    "reference": "ea43c6bbb998",
    "narrative": "PAYPAL",
    "status": "success",
    "reason": null,
    "amount": 100,
  }
}

Virtual Card Transaction Declined

This is a webhook that is fired when a purchase attempt is declined

JSON

{
  "event": "virtualcard.transaction.declined",
  "data": {
    "cardId": "736545b8-2eda-48cf-8eff-03f1dfb8514e",
    "companyId": "b4e0ea36-bdb6-4c12-8931-b73f85ab361b",
    "id": "5104a031-4fe5-4ff5-812d-5ba0b1658436",
    "narrative": "GOOGLE*ADS2260628**",
    "reason": "No sufficient funds",
    "reference": "e3d7b37de816",
    "status": "failed",
    "amount": 330,
  }
}

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",
    "customerId": "cc8bfc56-f612-4132-9228-29952d0a5036",
    "customerEmail": "ade.hannah@jmail.com",
    "kycPassed": true,
  }
}

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": {
    "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..",
    "customerId": "aaf7a252-81e3-4e8a-ae94-9210a3ea313d",
    "companyId": "246d1cfc-9eeb-4ddd-95d1-5887fe32d941",
    "id": "11d5c966-60f2-4a11-910f-e51d914b9a0b",
    "customerEmail": "bodeseqo@lyft.live",
    "kycPassed": false,
  }
}

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": {
    "companyId": "45422f21-9a0e-479e-9e10-615556448a78",
    "cardId": "692bbb4c-e5af-4ac1-ab9b-dc30c532aa11",
    "id": "5272ff4d-6f8d-47e2-b430-4f75654acf14",
    "narrative": "Withdraw from card",
    "reference": "1445ed09a724",
    "isTerminated": false,
    "status": "success",
    "amount": 600,
  }
}

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",
    "cardId": "fa2c4efe-d683-452b-9e3b-acce99415291",
    "companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
    "narrative": "Withdraw from card",
    "reference": "71b8e04de49c4f5e",
    "isTerminated": false,
    "status": "failed",
    "amount": 500,
  }
}

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",
    "cardId": "84fa6bce-be2c-4d79-9e6a-b111aff0b226",
    "companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
    "reference": "4981db52eacb1dd1",
    "narrative": "Top-up card",
    "status": "success",
    "amount": 300,
  }
}

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",
    "cardId": "fd8156aa-af32-4589-b842-0c5be28bbff8",
    "companyId": "b4e0ea36-bdb6-4c12-8931-b73f85ab361b",
    "reference": "B7NX9GQOFPZQ",
    "narrative": "Top-up card",
    "status": "failed",
    "amount": 9698,
  }
}

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",
    "companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
    "reference": "4921bba1a6a7edf5",
    "reason": "Insufficient Funds",
    "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

JSON

{
  "event": "virtualcard.transaction.authorization.failed",
  "data": {
    "id": "79454f05-6357-4c82-9f78-6fe7cf983de2",
    "cardId": "225762c9-3468-404b-bcc0-4d7d6f2d7312",
    "companyId": "c16a147e-119f-4de4-88c0-b14d908f9727",
    "reason": "insufficient funds",
    "reference": "84fa1cac8ba1",
    "status": "success",
    "amount": 2,
  }
}

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": {
    "companyId": "c16a147e-119f-0000-88c0-b14d908f9727",
    "cardId": "d8116cff-7c66-0000-90c9-31c6daea000",
    "narrative": "METAPAY SN6D",
    "status": "success",
    "chargedAmount": 50,
    "amount": 103,
  }
}

Virtual Accounts Webhook Beneficiaries Webhook