Wallet History
View your paginated balance transaction ledger with filters and summary.
Returns your paginated wallet transaction history — deposits, order deductions, refunds, and manual adjustments. Includes an aggregate summary for the filtered range.
Endpoint
Request Headers
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
X-Api-Key | String | Yes | Your API key. See Authentication. |
Query Parameters
Query Params
| Parameter | Type | Required | Description |
|---|---|---|---|
page | Number | No | Page number (1-based, default: 1). |
limit | Number | No | Items per page (1–100, default: 50). |
type | String | No | Filter: deposit, deduction, refund, adjustment. |
start_date | String | No | Start date (YYYY-MM-DD). |
end_date | String | No | End date (YYYY-MM-DD). Max 90-day range. |
Response
200OK
json
{
"success": true,
"data": {
"transactions": [
{
"transaction_id": "a1b2c3d4-...",
"type": "deposit",
"amount": 29000,
"balance_before": 14500,
"balance_after": 43500,
"description": "Coin Top-up",
"ref_id": "BDO-12345678",
"created_at": "2026-05-14T08:00:00.000Z"
},
{
"transaction_id": "e5f6a7b8-...",
"type": "deduction",
"amount": -725,
"balance_before": 43500,
"balance_after": 42775,
"description": "Order Deduction",
"ref_id": null,
"created_at": "2026-05-14T10:30:00.000Z"
}
],
"summary": {
"total_topup": 29000,
"total_deductions": 725,
"net_change": 28275
}
},
"meta": {
"total": 42,
"page": 1,
"limit": 50,
"total_pages": 1,
"has_more": false
}
}Transaction Types
Type Reference
| Parameter | Required | Description |
|---|---|---|
deposit | No | Balance top-up (positive amount). |
deduction | No | Order charge (negative amount). |
refund | No | Failed order refund (positive amount). |
adjustment | No | Manual admin adjustment. |
Amount Sign Convention
Deductions are always returned as negative numbers (e.g., -725). Deposits and refunds are positive. This lets you render a clean transaction ledger without extra logic.
Example cURL
curl -s "https://[kaybs-domain]/api/v1/wallet-history?page=1&limit=10&type=deposit" \
-H "X-Api-Key: ${KAYBS_API_KEY}"
Example (Node.js)
// Node 18+ (ESM)
const res = await fetch('https://[kaybs-domain]/api/v1/wallet-history?page=1&limit=20', {
headers: { 'X-Api-Key': process.env.KAYBS_API_KEY },
});
const { data, meta } = await res.json();
console.log(`Net change: ₱${data.summary.net_change.toLocaleString('en-PH')}`);