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:

Field

Data Type

Description

event

String

Can be any one of: issuing.card_authorization.settled or issuing.chargeback.success or issuing.transaction_refund.success or issuing.transaction_reversal.success or issuing.card_creation.success or issuing.card_creation.failed or issuing.card_funding.success or issuing.card_funding.failed or issuing.card_withdrawal.success or issuing.card_withdrawal.failed or issuing.card.expired or issuing.card_suspension.success or issuing.card_suspension.failed or issuing.card_activation.success or issuing.card_activation.failed or issuing.card_termination.success or issuing.card_termination.failed

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

Card Authorization Webhook

{
 "event": "issuing.card_authorization.settled",
 "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": "settled",
   "type": "card_transaction",
   "date": "2000-11-11T10:00:00"
 }
}