Get Virtual Account Debit History
Retrieve a list of all debit (deduction) transactions performed on a virtual account.
The Get Virtual Account Debit History endpoint returns a list of all debit (deduction) transactions performed on a virtual account.
Use this endpoint to:
- Show wallet spending history to users
- Reconcile deductions against internal orders
- Audit balance changes
- Investigate disputes or support cases
GET /v2/virtual-accounts/{virtual_account_id}/debits
Host: api.chapa.co
| Name | Required | Description |
|---|
Authorization | Yes | Bearer <PRIVATE_API_KEY> |
Content-Type | No | application/json |
| Parameter | Required | Description |
|---|
virtual_account_id | Yes | Unique virtual account identifier |
| Parameter | Type | Description |
|---|
from | string | Start date (ISO8601) filter |
to | string | End date (ISO8601) filter |
page | integer | Page number (default: 1) |
per_page | integer | Records per page (default: 20) |
merchant_reference | string | Filter by merchant reference |
GET https://api.chapa.co/v2/virtual-accounts/VA_ABC123456/debits?per_page=20&page=1
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
{
"status": "success",
"message": "Debit history retrieved successfully",
"data": {
"items": [
{
"debit_reference": "DEB_TRX_123456",
"merchant_reference": "DEB_001",
"amount": 3000,
"currency": "ETB",
"reason": "Payment for order ORD_99887",
"meta": {
"order_id": "ORD_99887",
"customer_id": "CUST_12345"
},
"balance_before": 12500,
"balance_after": 9500,
"created_at": "2025-11-07T13:20:00Z"
}
],
"pagination": {
"next_cursor": null,
"prev_cursor": null,
"limit": 20,
"has_more": false
}
}
}
| Field | Type | Description |
|---|
debit_reference | string | Unique debit transaction reference |
merchant_reference | string | Merchant-generated reference (if provided) |
amount | number | Amount deducted |
currency | string | Currency |
reason | string | Reason or description |
meta | object | Custom metadata |
balance_before | number | Balance before debit |
balance_after | number | Balance after debit |
created_at | string | Timestamp |
| Field | Type | Description |
|---|
next_cursor | string | Cursor token for next page |
prev_cursor | string | Cursor token for previous page |
limit | integer | Number of items returned |
has_more | boolean | Whether more results exist |
- Filter by date range for better performance
- Store
debit_reference for reconciliation
- Use
meta.order_id to link to internal transactions
- Provide export options (CSV) in dashboards if needed
| HTTP | Error Code | Description |
|---|
| 404 | NOT_FOUND | Virtual account not found |
| 500 | PROCESSING_FAILED | Failed to fetch debit history |
