Card Events and Webhook

The Card Events log captures the various events that occur during the lifecycle of a card.

To get the events on a virtual card, make a GET request to:

{{baseurl}}/api/i/cards/:card_reference/events

This API also accepts some request parameters. For example, {{baseurl}}/api/v1/cards/:card_reference/events?start_date=2023-04-06&end_date=2023-04-07 would return the card events between 6 April 2023 and 7 April 2023.

Here are some of the parameters you can include on your request:

ParameterTypeRequiredDescription
start_dateStringFalseThis is the specific date from which you would like the query to start. The expected date format is YYYY-MM-DD.
end_dateStringFalseThis is the specific end date for the search query. The expected date format is YYYY-MM-DD.
pageNumberFalseThis specifies the page number to retrieve. By default it is 1.
limitNumberFalseThis is the maximum number of events that should be retrieved at once.

The response to this request would look like this:

{
    "status": true,
    "message": "Card events retrieved successfully",
    "data": {
        "data": [
            {
                "reference": "CE-VnIHJswJIlOSHYUH",
                "event": "Creation",
                "reason": "Card creation",
                "creator": "Merchant",
                "date": "2023-04-06T15:33:54.000Z"
            },
            {
                "reference": "CE-VnIHJswJIlOSHYUH",
                "event": "Funding",
                "reason": "Card funding",
                "creator": "Merchant",
                "date": "2023-04-06T15:49:56.000Z"
            },
            {
                "reference": "CE-VnIHJswJIlOSHYUH",
                "event": "Funding",
                "reason": "Card funding",
                "creator": "Merchant",
                "date": "2023-04-06T15:50:08.000Z"
            },
            {
                "reference": "CE-VnIHJswJIlOSHYUH",
                "event": "Funding",
                "reason": "Card funding",
                "creator": "Merchant",
                "date": "2023-04-06T15:50:17.000Z"
            },
            {
                "reference": "CE-VnIHJswJIlOSHYUH",
                "event": "deactivation",
                "reason": "Fraudulent activities",
                "creator": "John Doe",
                "date": "2023-04-07T04:18:18.000Z"
            },
            {
                "reference": "CE-VnIHJswJIlOSHYUH",
                "event": "activation",
                "reason": "Cleared of fraud charges",
                "creator": "John Doe",
                "date": "2023-04-07T04:20:09.000Z"
            },
            {
                "reference": "CE-VnIHJswJIlOSHYUH",
                "event": "termination",
                "reason": "Cleared of fraud charges",
                "creator": "John Doe",
                "date": "2023-04-07T04:21:14.000Z"
            }
        ],
        "paging": {
            "total_items": 7,
            "page_size": 10,
            "current": 1,
            "count": 7
        }
    }
}

Webhook Events

Generally, webhook request or responses for virtual cards will include any of the following:

FieldData TypeDescription
eventStringCan be any one of card.creation.success, card.funding.success, card.active, card.suspended , card.terminated, card.expired, card.transaction.success, card.transaction.reversed or card.transaction.chargeback.initiated
dataObjectThis is the object containing transaction details: amount, fee, currency, status, reference
data.amountNumberTransaction amount
data.referenceNumberReference
data.card_referenceStringCard reference
data.transaction_referenceStringTransaction reference
data.currencyStringTransaction currency
data.card_balanceNumberCard balance
data.card_acceptor_nameStringCard acceptor name
data.card_acceptor_countryStringCard acceptor country
data.card_typeStringThe type of card - the only allowed option for now is virtual
data.holder_nameStringCard holder name
data.billingObjectThe object containing the billing details
data.billing.address1StringBilling address line 1
data.billing.address2StringBilling address line 2
data.billing.cityStringBilling city
data.billing.stateStringBilling state
data.billing.countryStringBilling country
data.billing.zip_codeStringBilling zip code
data.expiryDateCard expiry date
data.brandStringCan be any one of visa or mastercard
data.first_sixStringFirst six characters of card number
data.last_fourStringLast four characters of card number
data.statusStringCard/Transaction status - Can be one of pending, active, suspended, terminated, expired, initiated, success, settled, failed, declined, reversed, processing, pendingReversal, pendingCompletion, or abandoned
dateDateTransaction Date

Webhook Notifications for Card Transaction

Webhook notifications are sent to your application after a card transaction. An example of a notification response for a successful transaction would look like:

{
 "event": "card.active",
 "data": {
   "reference": "webhook unique reference",
   "card_reference": "876eeb6f-f6cb-562f-a5e8-48d91dec7999",
   "transaction_reference": "TX-8EtDYNlTlqp5EwuuDD9susN00TtIsETbxrhiE",
   "amount": 89,
   "currency": "USD",
   "card_acceptor_name": "Viola stores",
   "card_acceptor_country": "NG",
   "card_balance": 253,
   "status": "success",
   "date": "2000-11-11T10:00:00"
 }
}