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.

5 endpointsBase URL https://api.spirestock.com/api/v1

Every request needs an API key or a session token. Last updated .

On this page (5)

GEThttps://api.spirestock.com/api/v1/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

user_idnumber
Whose wallet. Default: the caller
allstring
1 for every wallet in the workspace
Example request
curl https://api.spirestock.com/api/v1/wallet/balance \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "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
    }
  }
}

GEThttps://api.spirestock.com/api/v1/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).

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

statusstring
all (default), pending, completed (alias approved) or rejected
user_idnumber
One customer
payment_modestring
UPI, NEFT, RTGS, IMPS, Bank Transfer, Cheque or Cash
fromstring
IST day, YYYY-MM-DD or dd/mm/yyyy
tostring
IST day (inclusive)
searchstring
UTR/reference or the customer's name, store name or SAP id contains (max 60 characters)
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 25, max 100 (larger values are clamped)
Example request
curl "https://api.spirestock.com/api/v1/wallet/recharge-requests?status=pending" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "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
  }
}

POSThttps://api.spirestock.com/api/v1/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

amountstringrequired
Rupees, for example 1500 or 750.50
payment_modestringrequired
UPI, NEFT, RTGS, IMPS, Bank Transfer, Cheque or Cash (case-insensitive)
utr_referencestring
Required except for Cash. Aliases reference, utr
notesstring
Up to 500 characters
receipt_media_idstring
Media id of a receipt the caller uploaded
Example request
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
{
  "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
  }
}

POSThttps://api.spirestock.com/api/v1/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

idnumberrequired
Request id
Example request
curl -X POST https://api.spirestock.com/api/v1/wallet/recharge-requests/6/approve \
  -H "Authorization: Bearer YOUR_TOKEN"
Example response
{
  "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"
    }
  }
}

POSThttps://api.spirestock.com/api/v1/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

idnumberrequired
Request id

Request body

reasonstringrequired
Why it was rejected, 3-500 characters
Example request
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
{
  "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"
    }
  }
}