List Recharges API

Returns your recharges, newest first. This is the endpoint for reconciliation, support lookups, and confirming whether a submit you are unsure about actually landed.

Endpoint

GET /api/v1/recharges

Authentication: API Key + Secret required

Results are always scoped to your own client. The client is taken from your authenticated credentials and can never be supplied as a parameter, so there is no way to read another client's recharges.

Request Headers

X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke
X-API-Secret: your-secret-here

Query Parameters

Parameters that other list endpoints accept — currency, type, wallet_id, name — are parsed but not applied here. They will not narrow your results.

Status filter

status takes one of the four client-facing values:

You filter in the canonical vocabulary and Starship expands it to cover historical rows written before the client API existed. ?status=SUCCESS therefore returns everything that actually succeeded, whichever era it was written in.

An unrecognised value is passed through unchanged rather than silently widened, so a typo returns an empty page instead of your whole history.

Search

search matches a recharge if any of these contain the term:

• the recharge id
• the reference_number
• the mobile_number

Matching is case-insensitive and substring-based, so ?search=9876543210 finds every recharge for that number and ?search=9f2c41ab finds a recharge from a partial reference.

Date range

from_date and to_date filter on creation time and take plain dates, not timestamps.

to_date is inclusive of the entire day — to_date=2026-08-25 includes a recharge created at 2026-08-25T23:59:59Z. You do not need to pass the following day to capture the last one.

Response

Success Response

Status Code: 200 OK

Response Headers:

X-Page: 1
X-Per-Page: 50
X-Page-Size: 2
X-Total-Count: 184
X-Total-Pages: 4
X-Has-More: true

Page through on X-Has-More rather than on an empty array — it is one request cheaper and unambiguous.

Response Body:

The body is a bare JSON array. There is no envelope object; pagination lives entirely in the headers.

[
  {
    "id": 84215,
    "reference_number": "c8e14f2b90a742d3ae51b7c93f60d2aa",
    "status": "FAILED",
    "sub_status": "REVERSED",
    "mobile_number": "9876543210",
    "country_code": "IN",
    "operator": "Airtel",
    "circle": "Karnataka",
    "is_prepaid": true,
    "face": 199.00,
    "discount": 4.98,
    "payable": 194.02,
    "currency": "INR",
    "failure_reason": "Invalid recharge amount for this plan",
    "client_reference": "TOPUP-2026-000414",
    "created_at": "2026-08-25T10:32:40Z",
    "updated_at": "2026-08-25T10:32:44Z"
  },
  {
    "id": 84213,
    "reference_number": "9f2c41ab7de4489bb1c0a6f2e8d35471",
    "status": "SUCCESS",
    "sub_status": "OPERATOR_CONFIRMED",
    "mobile_number": "9876543210",
    "country_code": "IN",
    "operator": "Airtel",
    "circle": "Karnataka",
    "is_prepaid": true,
    "face": 199.00,
    "discount": 4.98,
    "payable": 194.02,
    "currency": "INR",
    "vendor_recharge_id": "VR-88213904",
    "operator_txn_id": "AIRTEL-772391884",
    "client_reference": "TOPUP-2026-000412",
    "created_at": "2026-08-25T10:30:00Z",
    "updated_at": "2026-08-25T10:30:07Z"
  }
]

Response Fields

Optional fields are absent from the JSON rather than null. A PROCESSING recharge has no operator_txn_id key at all.

Note the shape difference from submit: the read shape carries country_code, operator, circle, is_prepaid, currency and updated_at, but reports the operator as a display name rather than the numeric operator_id the submit response echoes.

Errors

Reconciliation pattern

The most valuable use of this endpoint is settling the ambiguity after a failed or timed-out submit. If you pass a distinct client_reference on every submit, you can answer "did that one land?" without guessing:

# Did my submit for TOPUP-2026-000412 actually land?
curl -s -X GET "{{host}}/api/v1/recharges?search=9876543210&from_date=2026-08-25" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here" \
  | jq '.[] | select(.client_reference == "TOPUP-2026-000412")'

An empty result means nothing was created and it is safe to submit again. Any result — including a PROCESSING one — means the recharge exists and resubmitting would duplicate it.

Examples

# Most recent 50
curl -X GET "{{host}}/api/v1/recharges" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

# Everything still in flight
curl -X GET "{{host}}/api/v1/recharges?status=PROCESSING" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

# One number's full history
curl -X GET "{{host}}/api/v1/recharges?search=9876543210&limit=100" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

# A calendar month of successful recharges, second page
curl -X GET "{{host}}/api/v1/recharges?status=SUCCESS&from_date=2026-08-01&to_date=2026-08-31&page=2&limit=100" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

Next steps

• Get Recharge — read a single recharge and poll it to completion
• Submit a Recharge — where client_reference is set