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"
}
}
Updated over 1 year ago