Wallet

Base path: /api/wallet

Every user account has an in-app wallet. The wallet can be used to pay for bookings without a third-party gateway.

Endpoints

GET /api/wallet [Auth required]

Get the authenticated user's wallet balance and recent transaction history.

Response 200:

{
  "balance": "1250.00",
  "transactions": {
    "data": [
      {
        "id": 1,
        "type": "topup",
        "amount": "1000.00",
        "balance_after": "1000.00",
        "reference_type": null,
        "reference_id": null,
        "description": "Wallet top-up via eSewa",
        "created_at": "2025-06-01 10:00:00"
      },
      {
        "id": 2,
        "type": "debit",
        "amount": "700.00",
        "balance_after": "300.00",
        "reference_type": "booking",
        "reference_id": 42,
        "description": "Payment for booking BK-2025-0042",
        "created_at": "2025-06-15 08:30:00"
      },
      {
        "id": 3,
        "type": "credit",
        "amount": "950.00",
        "balance_after": "1250.00",
        "reference_type": null,
        "reference_id": null,
        "description": "Refund for booking BK-2025-0039",
        "created_at": "2025-06-12 14:00:00"
      }
    ]
  }
}

POST /api/wallet/topup [Auth required]

Add funds to the wallet via a payment gateway.

Request body:

{
  "amount": 1000.00,
  "method": "esewa",
  "return_url": "myapp://wallet/topup-return"
}

Field	Type	Required	Description
`amount`	numeric	Yes	Amount to add (NPR)
`method`	string	Yes	`esewa`, `khalti`, `fonepay`
`return_url`	string	No	Deep-link URL for redirect after payment

Response 201: WalletTransactionResource

{
  "data": {
    "id": 5,
    "type": "topup",
    "amount": "1000.00",
    "balance_after": "2250.00",
    "reference_type": null,
    "reference_id": null,
    "description": "Wallet top-up via eSewa",
    "created_at": "2025-06-20 09:00:00"
  }
}

WalletTransactionResource — Field Reference

Field	Type	Notes
`id`	integer
`type`	string	`topup`, `debit`, `credit`
`amount`	decimal string	Always positive
`balance_after`	decimal string	Wallet balance after this transaction
`reference_type`	string or null	`booking`, `indoor`, etc.
`reference_id`	integer or null	ID of the linked record
`description`	string or null	Human-readable summary
`created_at`	datetime string

Transaction Types

Type	Description
`topup`	User added funds
`debit`	Funds spent on a booking/service
`credit`	Refund credited to wallet

Tips for Mobile Devs

Always show balance prominently in the payment screen so the user knows if they have enough funds.
After a successful top-up, refresh the wallet balance.
To pay via wallet, set method: "wallet" in POST /api/payments/initiate — no WebView redirect is needed; the response will be a completed payment directly.