Wallets API

Get Wallet Balance

GET /v1/wallets/{customerId}/balance

Response:

{
  "success": true,
  "data": {
    "customerId": "cust_abc123",
    "balance": 1500,
    "lifetimeEarned": 3000,
    "lifetimeSpent": 1500
  }
}

Credit Points

POST /v1/wallets/{customerId}/credit

Request Body:

{
  "amount": 500,
  "reason": "Purchase reward",
  "metadata": {
    "orderId": "ord_123"
  }
}

Field	Type	Required	Description
amount	number	Yes	Points to credit (positive integer)
reason	string	Yes	Human-readable reason
metadata	object	No	Custom transaction data

Debit Points

POST /v1/wallets/{customerId}/debit

Request Body:

{
  "amount": 200,
  "reason": "Reward redemption"
}

Returns 400 if insufficient balance.

Transaction History

GET /v1/wallets/{customerId}/transactions

Query Parameters:

Parameter	Type	Description
page	number	Page number
limit	number	Items per page
type	string	Filter: credit or debit

Response:

{
  "success": true,
  "data": [
    {
      "id": "txn_abc123",
      "type": "credit",
      "amount": 500,
      "balance": 1500,
      "reason": "Purchase reward",
      "metadata": {"orderId": "ord_123"},
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}