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:

Parameter	Type	Required	Description
`start_date`	String	False	This is the specific date from which you would like the query to start. The expected date format is YYYY-MM-DD.
`end_date`	String	False	This is the specific end date for the search query. The expected date format is YYYY-MM-DD.
`page`	Number	False	This specifies the page number to retrieve. By default it is `1`.
`limit`	Number	False	This 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:

Field	Data Type	Description
`event`	String	Can 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`
`data`	Object	This is the object containing transaction details: amount, fee, currency, status, reference
`data.amount`	Number	Transaction amount
`data.reference`	Number	Reference
`data.card_reference`	String	Card reference
`data.transaction_reference`	String	Transaction reference
`data.currency`	String	Transaction currency
`data.card_balance`	Number	Card balance
`data.card_acceptor_name`	String	Card acceptor name
`data.card_acceptor_country`	String	Card acceptor country
`data.card_type`	String	The type of card - the only allowed option for now is `virtual`
`data.holder_name`	String	Card holder name
`data.billing`	Object	The object containing the billing details
`data.billing.address1`	String	Billing address line 1
`data.billing.address2`	String	Billing address line 2
`data.billing.city`	String	Billing city
`data.billing.state`	String	Billing state
`data.billing.country`	String	Billing country
`data.billing.zip_code`	String	Billing zip code
`data.expiry`	Date	Card expiry date
`data.brand`	String	Can be any one of `visa` or `mastercard`
`data.first_six`	String	First six characters of card number
`data.last_four`	String	Last four characters of card number
`data.status`	String	Card/Transaction status - Can be one of `pending`, `active`, `suspended`, `terminated`, `expired`, `initiated`, `success`, `settled`, `failed`, `declined`, `reversed`, `processing`, `pendingReversal`, `pendingCompletion`, or `abandoned`
`date`	Date	Transaction 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"
 }
}