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 |
---|---|---|
| String | Can be any one of:
|
| Object | This is the object containing transaction details: amount, fee, currency, status, reference |
| Number | Transaction amount |
| Number | Reference |
| String | Card reference |
| String | Transaction reference |
| String | Transaction currency |
| Number | Card balance |
| String | Card acceptor name |
| String | Card acceptor country |
| String | The type of card - the only allowed option for now is |
| String | Card holder name |
| Object | The object containing the billing details |
| String | Billing address line 1 |
| String | Billing address line 2 |
| String | Billing city |
| String | Billing state |
| String | Billing country |
| String | Billing zip code |
| Date | Card expiry date |
| String | Can be any one of |
| String | First six characters of card number |
| String | Last four characters of card number |
| String | Card/Transaction status - Can be one of |
| 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"
}
}
Updated 12 days ago