Submit a Recharge

Places a real recharge on a real phone. Your wallet is debited and the request goes to the operator immediately.

Endpoint

POST /api/v1/recharges

Authentication: API Key + Secret required Idempotency-Key: required

Request headers

A missing key returns 400 IDEMPOTENCY_KEY_REQUIRED; a key under 8 characters returns 400 IDEMPOTENCY_KEY_TOO_SHORT.

Request

curl -X POST https://api.starshiprewards.com/api/v1/recharges \
  -H "X-API-Key: <your-api-key>" \
  -H "X-API-Secret: <your-api-secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rch_9f2c1d84_1755500000" \
  -d '{
    "mobile_number": "9876543210",
    "operator_id": 1,
    "amount": 199,
    "client_reference": "TOPUP-2026-0042"
  }'

Body

Response

The status code carries meaning. Read it before the body.

202 Accepted — the case to design for

{
  "id": 84213,
  "reference_number": "RCH-84213-2X9F",
  "status": "PROCESSING",
  "sub_status": "VENDOR_SUBMITTED",
  "mobile_number": "9876543210",
  "operator_id": 1,
  "face": 199.00,
  "discount": 4.98,
  "payable": 194.02,
  "vendor_recharge_id": "JRI-77120043",
  "client_reference": "TOPUP-2026-0042",
  "created_at": "2026-08-19T09:14:22Z"
}

200 OK — settled immediately

{
  "id": 84214,
  "reference_number": "RCH-84214-B7KQ",
  "status": "SUCCESS",
  "sub_status": "OPERATOR_CONFIRMED",
  "mobile_number": "9876543210",
  "operator_id": 1,
  "face": 199.00,
  "discount": 4.98,
  "payable": 194.02,
  "vendor_recharge_id": "JRI-77120044",
  "operator_txn_id": "AIRTEL8891203344",
  "client_reference": "TOPUP-2026-0042",
  "created_at": "2026-08-19T09:15:02Z"
}

A FAILED response has the same shape with status: "FAILED" and a failure_reason. A FAILED recharge is still HTTP 200 — the API request succeeded; the recharge did not.

Response fields

Duplicates

A repeat of the same (mobile_number, amount) from your account inside a Starship-configured window is refused with 409:

{
  "error": {
    "message": "a matching recharge was submitted recently; resend with force=true if the repeat is intended"
  }
}

This guard exists so a retry storm cannot turn one intent into two irreversible recharges.

When a 409 is correct behaviour: your first call actually landed and you are re-sending after a timeout. Do not force it — call GET /api/v1/recharges and find the existing recharge.

When to use force: the repeat is genuinely intended — a user deliberately topping the same number up twice.

{
  "mobile_number": "9876543210",
  "operator_id": 1,
  "amount": 199,
  "force": true
}

force vs Idempotency-Key

They solve different problems and you need both.

A retry with the same Idempotency-Key replays the original response. A retry with a new key is a new request and will hit the duplicate guard — which is exactly what should happen.

Circles

Some operator/vendor mappings require a telecom circle, because the vendor validates operator and location together. Where that applies, omitting circle_id returns a 400.

There is no public circles endpoint in v1 — request the circle id list from your account manager for the operators you cover. BSNL and MTNL are the usual cases.

Errors

Each failure maps to a distinct status so you can tell "retry later" from "this will never work".

Integration checklist

1. Generate a unique Idempotency-Key per recharge intent — and reuse it for retries of that same intent
2. Send client_reference so you can find the recharge later without our id
3. Branch on the HTTP status first, then on status
4. Treat 202 as "poll", never as "failed"
5. Store id and reference_number from every response, including failures
6. Reconcile against payable, not against face
7. Back off on 503 — it is transient by design

Next

List and get recharges — poll a PROCESSING recharge and reconcile.