Get Recharge API

Returns one of your recharges. This is the endpoint you poll after a 202 PROCESSING from submit, and the one to quote from when raising a support ticket.

Endpoint

GET /api/v1/recharges/{id}

Authentication: API Key + Secret required

Path Parameters

Request Headers

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

Response

Success Response

Status Code: 200 OK

{
  "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"
}

The response shape is identical to one element of List Recharges — see that page for the full field table.

Optional fields are absent from the JSON rather than null. A PROCESSING recharge has no operator_txn_id, no failure_reason and often no vendor_recharge_id key at all. Read defensively.

Polling cadence

A 202 PROCESSING means Starship holds the recharge and is waiting on the vendor. Two things can settle it:

1. The vendor pushes a status update. This is the fast path and can arrive within seconds or minutes.
2. A background job polls the vendor's status API. Following the vendor's own timing rule, the first check happens roughly 15 minutes after the recharge was placed, then roughly every 30 minutes after that.

Because of that second mechanism, a recharge that has not been pushed cannot change before the ~15-minute mark. Polling it every second in the first minute produces fifteen minutes of identical responses and spends your rate-limit budget for nothing.

Recommended schedule

That schedule costs about 20 requests per recharge in the worst case, against a budget of 1,000 per hour shared with every other endpoint. Multiply by your concurrency before deciding to poll more aggressively.

When it stops changing

A recharge is flagged sub_status: "NEEDS_REVIEW" while remaining PROCESSING when it has been unresolved longer than the review threshold (30 minutes by default), or when background polling gives up after roughly 20 attempts. Starship staff are alerted at that point.

NEEDS_REVIEW does not mean the recharge has stopped: it can still settle automatically. Keep polling at the slow cadence and raise it with Starship, quoting the reference_number.

Reading the outcome

Branch on status only. sub_status is diagnostic detail whose values may be extended, and failure_reason is a vendor string passed through verbatim — useful to display and log, never safe to match on.

Errors

Examples

# Read one recharge
curl -X GET "{{host}}/api/v1/recharges/84213" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

# Just the status
curl -s -X GET "{{host}}/api/v1/recharges/84213" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here" \
  | jq '{id, status, sub_status, operator_txn_id, failure_reason}'

Polling until the status settles, with the recommended backoff:

RECHARGE_ID=84213
for delay in 60 60 60 60 60 300 300 300 300 300 900 900; do
  status=$(curl -s -X GET "{{host}}/api/v1/recharges/${RECHARGE_ID}" \
    -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
    -H "X-API-Secret: your-secret-here" | jq -r '.status')

  echo "status: ${status}"
  [ "$status" != "PROCESSING" ] && break

  sleep "$delay"
done

If the loop exits still PROCESSING, escalate with the reference_number — do not submit again.

Next steps

• List Recharges — find a recharge when you do not have its id
• Submit a Recharge — the three outcomes explained