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

GET/api/v1/wallet-history

Request Headers

Headers

ParameterTypeRequiredDescription
X-Api-KeyStringYesYour API key. See Authentication.

Query Parameters

Query Params

ParameterTypeRequiredDescription
pageNumberNoPage number (1-based, default: 1).
limitNumberNoItems per page (1–100, default: 50).
typeStringNoFilter: deposit, deduction, refund, adjustment.
start_dateStringNoStart date (YYYY-MM-DD).
end_dateStringNoEnd 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

ParameterRequiredDescription
depositNoBalance top-up (positive amount).
deductionNoOrder charge (negative amount).
refundNoFailed order refund (positive amount).
adjustmentNoManual 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')}`);
PreviousBalanceNextCallbacks