Get Virtual Account Credit History
Retrieve a list of all credit (deposit) transactions performed on a virtual account.
The Credit History endpoint returns a list of all credit (deposit) transactions performed on a virtual account.
Use this endpoint to:
- Show wallet top-up history to users
- Reconcile deposits with your internal funding records
- Audit balance changes and trace funding sources
- Investigate customer support issues
GET /v2/virtual-accounts/{virtual_account_id}/credits
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/credits?per_page=20&page=1
Authorization: Bearer CHAPA_TEST_xxxxxxxxxxxxx
{
"status": "success",
"message": "Credit history retrieved successfully",
"data": {
"items": [
{
"deposit_reference": "DEP_TRX_987654",
"merchant_reference": "DEP_001",
"amount": 5000,
"currency": "ETB",
"reason": "Wallet top-up",
"meta": {
"order_id": "ORD_99887",
"customer_id": "CUST_12345"
},
"balance_before": 7500,
"balance_after": 12500,
"created_at": "2025-11-07T13:10:00Z"
}
],
"pagination": {
"next_cursor": null,
"prev_cursor": null,
"limit": 20,
"has_more": false
}
}
}
| Field | Type | Description |
|---|
deposit_reference | string | Unique deposit transaction reference |
merchant_reference | string | Merchant-generated reference (if provided) |
amount | number | Amount credited |
currency | string | Currency |
reason | string | Reason or description |
meta | object | Custom metadata |
balance_before | number | Balance before credit |
balance_after | number | Balance after credit |
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 | Items returned |
has_more | boolean | Whether more results exist |
- Filter by date range for faster results
- Use
merchant_reference and Idempotency-Key when depositing to prevent duplicates
- Store
deposit_reference for reconciliation
- Use
meta to connect deposits to your internal objects (order_id, customer_id, etc.)
| HTTP | Error Code | Description |
|---|
| 404 | NOT_FOUND | Virtual account not found |
| 500 | PROCESSING_FAILED | Failed to fetch credit history |
