List & Get Recharges

Two read endpoints. GET /api/v1/recharges/:id is what you poll after a 202 PROCESSING; GET /api/v1/recharges is what you use for reconciliation and support lookups.

Both are scoped to your own account. Neither is cached — a cached response would hide the very transition you are waiting for.

Get a recharge

GET /api/v1/recharges/:id

Authentication: API Key + Secret required

Request

curl -X GET https://api.starshiprewards.com/api/v1/recharges/84213 \
  -H "X-API-Key: <your-api-key>" \
  -H "X-API-Secret: <your-api-secret>"

Response

200 OK

{
  "id": 84213,
  "reference_number": "RCH-84213-2X9F",
  "status": "SUCCESS",
  "sub_status": "OPERATOR_CONFIRMED",
  "mobile_number": "9876543210",
  "country_code": "IN",
  "operator": "Airtel",
  "circle": "Delhi NCR",
  "is_prepaid": true,
  "face": 199.00,
  "discount": 4.98,
  "payable": 194.02,
  "currency": "INR",
  "vendor_recharge_id": "JRI-77120043",
  "operator_txn_id": "AIRTEL8891203344",
  "client_reference": "TOPUP-2026-0042",
  "created_at": "2026-08-19T09:14:22Z",
  "updated_at": "2026-08-19T09:14:51Z"
}

Fields

Errors

Polling a PROCESSING recharge

This is the endpoint's main job. After a 202, poll until status leaves PROCESSING.

POST /api/v1/recharges  →  202  status=PROCESSING
                             │
                             ▼
        GET /api/v1/recharges/84213   (every few seconds)
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   SUCCESS              FAILED               REVERSED
   wallet debited       wallet credited      wallet credited
   final                back, final          back, final

Recommended cadence

The general /api/v1/ rate limit is 1000 requests/hour per API key and recharge has no dedicated allowance, so a tight poll loop will exhaust your budget for every other endpoint too. Back off.

Because recharge emits no webhooks, polling is the only mechanism available for resolving PROCESSING today.

List recharges

GET /api/v1/recharges

Authentication: API Key + Secret required

Returns your recharges, newest first. Scoped to your account — the client is taken from your authenticated credentials and can never be supplied as a parameter.

Query parameters

The status filter takes the canonical value and transparently matches legacy stored values too, so ?status=SUCCESS also returns older rows recorded as DELIVERED or RECHARGED.

Request

curl -X GET "https://api.starshiprewards.com/api/v1/recharges?status=PROCESSING&limit=25" \
  -H "X-API-Key: <your-api-key>" \
  -H "X-API-Secret: <your-api-secret>"

Response

200 OK — a bare JSON array of the same objects returned by the detail endpoint. Pagination lives in the response headers, not in the body.

[
  {
    "id": 84214,
    "reference_number": "RCH-84214-B7KQ",
    "status": "SUCCESS",
    "sub_status": "OPERATOR_CONFIRMED",
    "mobile_number": "9876543210",
    "country_code": "IN",
    "operator": "Airtel",
    "is_prepaid": true,
    "face": 199.00,
    "discount": 4.98,
    "payable": 194.02,
    "currency": "INR",
    "created_at": "2026-08-19T09:15:02Z"
  }
]

An empty result is [], not an error.

Pagination headers

Finding a recharge after a timeout

If a submit timed out and you do not know whether it landed, do not resubmit. In order of preference:

1. Retry with the same Idempotency-Key — within 24 hours this replays the original response, including the recharge id.

2. Search by your reference — GET /api/v1/recharges?search=TOPUP-2026-0042 if you sent it as client_reference.

   search matches recharge id, reference_number and mobile_number. It does not match client_reference. To find a recharge by your own reference, search the mobile number and match client_reference in the results.

3. Search by number and date — ?search=9876543210&from_date=2026-08-19, then match on face and created_at.

Only submit again once you have confirmed no matching recharge exists.

Reconciliation

• Reconcile your ledger against payable, not face. payable is what left your wallet
• FAILED and REVERSED recharges have been credited back — do not double-count them as spend
• reference_number is the stable key to quote to Starship support
• Wallet movements themselves are visible through the Transactions API