---
title: "Wallet & Recharge Requests API — SpireStock REST API"
description: "Read customer wallet balances, file recharge requests with a UTR or receipt, and approve or reject them from the review queue."
source: https://developers.spirestock.com/api-reference/wallet
---

# Wallet & Recharge Requests API

Read customer wallet balances, file recharge requests with a UTR or receipt, and approve or reject them from the review queue.

Base URL: `https://api.spirestock.com/api/v1`. Every request needs an API key (`X-API-Key`) or a session token (`Authorization: Bearer`); see https://developers.spirestock.com/api-reference/auth.

## Endpoints

- [GET /wallet/balance](https://developers.spirestock.com/api-reference/wallet#get-wallet-balance)
- [GET /wallet/recharge-requests](https://developers.spirestock.com/api-reference/wallet#get-wallet-recharge-requests)
- [POST /wallet/recharge-requests](https://developers.spirestock.com/api-reference/wallet#post-wallet-recharge-requests)
- [POST /wallet/recharge-requests/{id}/approve](https://developers.spirestock.com/api-reference/wallet#post-wallet-recharge-requests-id-approve)
- [POST /wallet/recharge-requests/{id}/reject](https://developers.spirestock.com/api-reference/wallet#post-wallet-recharge-requests-id-reject)

## GET /wallet/balance

The caller's wallet (or user_id's; customer tokens always get their own), created on first read, with the last 10 completed transactions and pending_requests (count and amount of recharge requests awaiting review). With all=1: every wallet in the workspace, highest balance first, each with its user; needs the Amount to be paid (12) list grant, and customers get 403. Not paged. Balances are decimal strings.

Access: API key `read` scope; any staff user, for their own records.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | number | no | Whose wallet. Default: the caller |
| `all` | string | no | 1 for every wallet in the workspace |

**Example request**

```bash
curl https://api.spirestock.com/api/v1/wallet/balance \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "wallet": {
      "id": 7,
      "organization_id": 6,
      "user_id": 51896,
      "balance": "1500.00",
      "auto_debit_enabled": true,
      "low_balance_threshold": "100.00",
      "last_recharged_at": "2026-10-22T08:45:58.733Z",
      "status": 1,
      "createdAt": "2026-10-22T08:44:08.294Z",
      "updatedAt": "2026-10-22T08:45:58.733Z"
    },
    "transactions": [
      {
        "id": 6,
        "organization_id": 6,
        "wallet_id": 7,
        "user_id": 51896,
        "type": "recharge",
        "amount": "1500.00",
        "balance_after": "1500.00",
        "reference_type": "recharge_request",
        "reference_id": null,
        "payment_mode": "UPI",
        "payment_gateway_id": null,
        "notes": "Paid at the bank counter",
        "status": "completed",
        "utr_reference": "UTR000000001",
        "receipt_media_id": null,
        "receipt_url": null,
        "requested_by": 51896,
        "approved_by": 51897,
        "rejected_by": null,
        "reviewed_at": "2026-10-22T08:45:58.732Z",
        "reject_reason": null,
        "createdAt": "2026-10-22T08:45:58.667Z",
        "updatedAt": "2026-10-22T08:45:58.734Z"
      }
    ],
    "pending_requests": {
      "count": 0,
      "amount": 0
    }
  }
}
```

## GET /wallet/recharge-requests

Recharge requests, newest first. Reviewers see every request; customers and staff without the grant see only their own. summary gives count and amount per status under the same filters (ignoring status) and payment_modes the accepted modes. Each row carries the requesting user and reviewed_by_name. Not cached.

Access: API key `read` scope; staff need Amount to be paid (12) — list (without it, only their own records).

Paged (page and limit): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | all (default), pending, completed (alias approved) or rejected |
| `user_id` | number | no | One customer |
| `payment_mode` | string | no | UPI, NEFT, RTGS, IMPS, Bank Transfer, Cheque or Cash |
| `from` | string | no | IST day, YYYY-MM-DD or dd/mm/yyyy |
| `to` | string | no | IST day (inclusive) |
| `search` | string | no | UTR/reference or the customer's name, store name or SAP id contains (max 60 characters) |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 25, max 100 (larger values are clamped) (default 25) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/wallet/recharge-requests?status=pending" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 7,
      "organization_id": 6,
      "wallet_id": 7,
      "user_id": 51896,
      "type": "recharge",
      "amount": "750.50",
      "balance_after": null,
      "reference_type": "recharge_request",
      "reference_id": null,
      "payment_mode": "NEFT",
      "payment_gateway_id": null,
      "notes": null,
      "status": "rejected",
      "utr_reference": "UTR000000001",
      "receipt_media_id": null,
      "receipt_url": null,
      "requested_by": 51896,
      "approved_by": null,
      "rejected_by": 51897,
      "reviewed_at": "2026-10-22T08:45:58.743Z",
      "reject_reason": "Reference not found in bank statement",
      "createdAt": "2026-10-22T08:45:58.698Z",
      "updatedAt": "2026-10-22T08:45:58.743Z",
      "user": {
        "id": 51896,
        "first_name": "Sample",
        "last_name": "User A",
        "store_name": null,
        "emp_sap_id": "EMP-001",
        "primary_contact_number": "9876500010"
      },
      "reviewed_by_name": "Sample Reviewer"
    }
  ],
  "summary": {
    "pending": {
      "count": 0,
      "amount": 0
    },
    "completed": {
      "count": 1,
      "amount": 1500
    },
    "rejected": {
      "count": 1,
      "amount": 750.5
    }
  },
  "payment_modes": [
    "UPI",
    "NEFT"
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "limit": 2,
    "total_pages": 1
  }
}
```

## POST /wallet/recharge-requests

File a recharge request for the caller's own wallet; it is stored as pending and does not change the balance until a reviewer approves it. amount Rs.1 to Rs.5,00,000 with at most 2 decimals. A UTR or reference (5-40 letters, digits, - or /, stored upper-case) is required for every mode except Cash and must not already be pending or approved (409). Send JSON, or multipart/form-data with the receipt image as file.

Access: API keys cannot call this endpoint; any staff user, for their own records.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | string | yes | Rupees, for example 1500 or 750.50 |
| `payment_mode` | string | yes | UPI, NEFT, RTGS, IMPS, Bank Transfer, Cheque or Cash (case-insensitive) |
| `utr_reference` | string | no | Required except for Cash. Aliases reference, utr |
| `notes` | string | no | Up to 500 characters |
| `receipt_media_id` | string | no | Media id of a receipt the caller uploaded |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/wallet/recharge-requests \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "1500", "payment_mode": "UPI", "utr_reference": "UTR000000001" }'
```

**Example response**

```json
{
  "response_code": 201,
  "message": "Recharge request submitted. Your wallet will be credited once it is verified.",
  "data": {
    "id": 6,
    "organization_id": 6,
    "wallet_id": 7,
    "user_id": 51896,
    "type": "recharge",
    "amount": "1500.00",
    "balance_after": null,
    "reference_type": "recharge_request",
    "payment_mode": "UPI",
    "utr_reference": "UTR000000001",
    "receipt_media_id": null,
    "receipt_url": null,
    "notes": "Paid at the bank counter",
    "status": "pending",
    "requested_by": 51896,
    "updatedAt": "2026-10-22T08:45:58.667Z",
    "createdAt": "2026-10-22T08:45:58.667Z",
    "reference_id": null,
    "payment_gateway_id": null,
    "approved_by": null,
    "rejected_by": null,
    "reviewed_at": null,
    "reject_reason": null
  }
}
```

## POST /wallet/recharge-requests/{id}/approve

Approve a pending request: the wallet is credited under a row lock, the request becomes completed with balance_after, and the customer is notified. Nobody can review their own request (403); a request already decided is 409. In this response balance_after and wallet.balance are numbers.

Access: API keys cannot call this endpoint; staff need Amount to be paid (12) — edit.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | number | yes | Request id |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/wallet/recharge-requests/6/approve \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example response**

```json
{
  "response_code": 200,
  "message": "Rs.1500 credited to the wallet",
  "data": {
    "request": {
      "id": 6,
      "organization_id": 6,
      "wallet_id": 7,
      "user_id": 51896,
      "type": "recharge",
      "amount": "1500.00",
      "balance_after": 1500,
      "reference_type": "recharge_request",
      "reference_id": null,
      "payment_mode": "UPI",
      "payment_gateway_id": null,
      "notes": "Paid at the bank counter",
      "status": "completed",
      "utr_reference": "UTR000000001",
      "receipt_media_id": null,
      "receipt_url": null,
      "requested_by": 51896,
      "approved_by": 51897,
      "rejected_by": null,
      "reviewed_at": "2026-10-22T08:45:58.732Z",
      "reject_reason": null,
      "createdAt": "2026-10-22T08:45:58.667Z",
      "updatedAt": "2026-10-22T08:45:58.734Z"
    },
    "wallet": {
      "id": 7,
      "organization_id": 6,
      "user_id": 51896,
      "balance": 1500,
      "auto_debit_enabled": true,
      "low_balance_threshold": "100.00",
      "last_recharged_at": "2026-10-22T08:45:58.733Z",
      "status": 1,
      "createdAt": "2026-10-22T08:44:08.294Z",
      "updatedAt": "2026-10-22T08:45:58.733Z"
    }
  }
}
```

## POST /wallet/recharge-requests/{id}/reject

Reject a pending request with a reason (3-500 characters). The balance is untouched and the customer is notified. A request already decided is 409.

Access: API keys cannot call this endpoint; staff need Amount to be paid (12) — edit.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | number | yes | Request id |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | yes | Why it was rejected, 3-500 characters |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/wallet/recharge-requests/7/reject \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Reference not found in bank statement" }'
```

**Example response**

```json
{
  "response_code": 200,
  "message": "Recharge request rejected",
  "data": {
    "request": {
      "id": 7,
      "organization_id": 6,
      "wallet_id": 7,
      "user_id": 51896,
      "type": "recharge",
      "amount": "750.50",
      "balance_after": null,
      "reference_type": "recharge_request",
      "reference_id": null,
      "payment_mode": "NEFT",
      "payment_gateway_id": null,
      "notes": null,
      "status": "rejected",
      "utr_reference": "UTR000000001",
      "receipt_media_id": null,
      "receipt_url": null,
      "requested_by": 51896,
      "approved_by": null,
      "rejected_by": 51897,
      "reviewed_at": "2026-10-22T08:45:58.743Z",
      "reject_reason": "Reference not found in bank statement",
      "createdAt": "2026-10-22T08:45:58.698Z",
      "updatedAt": "2026-10-22T08:45:58.743Z"
    }
  }
}
```
