Recharges Overview
Direct mobile top-up — how recharge differs from voucher orders, what the wallet guarantees, and the five endpoints that make up the API
Recharges Overview
The Recharge API tops up a real mobile number directly. You name the operator, the number and the amount; Starship prices it against your discount, debits your wallet, and sends the top-up to the operator through its recharge vendor.
Recharge is not a voucher product. There is no catalog SKU, no denomination, no inventory pool and no voucher code at the end of it — the phone's balance is the deliverable.
Recharge is off by default. Every client starts disabled, and the API channel is a separate toggle on top of that. Until your account is enabled you will get 403 FORBIDDEN_ACTION on submit. Ask your Starship contact to enable recharge and the API channel for your client before you start integrating. The operator and charges endpoints are reachable regardless.
The five endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/recharge/operators | GET | List the operators you may recharge, with their capability flags |
/api/v1/recharge/charges | POST | Quote face, discount and payable before committing |
/api/v1/recharges | POST | Place a real-money recharge |
/api/v1/recharges | GET | Page through your recharge history |
/api/v1/recharges/{id} | GET | Read one recharge — the endpoint you poll after a 202 |
How recharge differs from orders
If you have already integrated Orders, the most important thing to know is that recharge inverts the fulfillment rule you learned there.
| Voucher orders | Recharges | |
|---|---|---|
| Source of goods | Inventory cache first, vendor API only on admin approval | No inventory — the vendor call is the product |
| On submit | An inventory miss parks the order PENDING for an admin | The vendor is called automatically, every time |
| What bounds exposure | Admin approval per order | Your pre-funded wallet balance |
| Reversible? | An unfulfilled order can be cancelled and refunded | A completed top-up is irreversible — the balance is on the phone |
| Outcome signal | Webhooks (order.delivered, …) | Polling only — recharge emits no webhooks today |
Recharge auto-fulfills because there is nothing to gate: a top-up cannot be sourced from a pool or fulfilled later from stock. The compensating controls are the pre-funded wallet, the per-client enablement flags, and the duplicate guard — not a per-transaction admin review.
A successful recharge cannot be undone. Once the operator credits the number, the money has left your wallet and the balance is on someone's phone. Treat POST /api/v1/recharges with more caution than an order: validate the number in your own UI, quote it first, and never wire a blind retry loop to it. See the duplicate guard.
Coverage in v1
- India only.
country_codedefaults toINand Indian numbering rules are enforced: exactly 10 digits, first digit6–9. - Mobile only. DTH, datacard and utility bills are not exposed.
- INR only. The debit comes from your INR wallet; a client with no INR wallet gets
404 WALLET_NOT_FOUND. - Whole rupees only.
10.50is rejected outright rather than silently truncated to10— see amount rules.
Integration flow
Fetch the operator catalog
Call GET /api/v1/recharge/operators once and cache it — it is served with a 24-hour cache header. You need the id of the operator your user selected, because Starship never infers the operator from the number.
Quote the price (optional but recommended)
POST /api/v1/recharge/charges returns face, discount_pct, discount and payable without placing anything. Show payable to your user before they confirm.
Submit the recharge
POST /api/v1/recharges with an Idempotency-Key header. You get either a final answer (200 with SUCCESS or FAILED) or a receipt (202 with PROCESSING).
Poll if you got a 202
202 PROCESSING means the wallet is debited and the vendor has not given a verdict yet. Poll GET /api/v1/recharges/{id} until status leaves PROCESSING. See polling cadence.
Lifecycle
The wallet debit commits before the vendor call, so every outcome is recoverable. Only a vendor-confirmed failure reverses the debit automatically — silence never does.
Status reference
status is the field to branch on. Four values are reachable through the client API:
| Status | HTTP on submit | Meaning | Wallet |
|---|---|---|---|
PROCESSING | 202 | Accepted and paid for; no verdict yet | Debited |
SUCCESS | 200 | The operator credited the number | Debited |
FAILED | 200 | The vendor confirmed the recharge did not happen | Credited back automatically |
REVERSED | — | The debit was returned after the fact | Credited back |
PROCESSING is not failure. A timeout, a vendor 500, or an unparseable reply all leave the recharge PROCESSING — because none of them tell us the top-up did not reach the phone. Refunding on silence would hand money back for recharges that actually succeeded. Only a vendor-confirmed failure reverses the debit. Never treat a 202 as a reason to resubmit.
Sub-status
sub_status carries finer detail within a status. It is useful for support conversations and dashboards; do not branch on it — treat status as the contract and sub_status as diagnostic colour.
| Sub-status | Appears with | Meaning |
|---|---|---|
INITIAL | PROCESSING | Row created and wallet debited; vendor not yet called |
VENDOR_SUBMITTED | PROCESSING | Sent to the vendor; no verdict returned |
VENDOR_PENDING | PROCESSING | The vendor explicitly reported "in process" |
OPERATOR_CONFIRMED | SUCCESS | The operator confirmed the credit |
REVERSED | FAILED or REVERSED | Vendor-confirmed failure; debit reversed |
REFUNDED | REVERSED | The debit was returned to your wallet |
NEEDS_REVIEW | PROCESSING | Unresolved past the review threshold, or polling exhausted — Starship staff are alerted; it can still settle |
Legacy status values
Recharge rows predating the client API carry PENDING, DELIVERED, RECHARGED and CANCELLED. You will only encounter these on historical rows. When you filter by status, Starship expands your canonical value to cover them, so ?status=SUCCESS also matches DELIVERED and RECHARGED rows — see the status filter.
Money semantics
- The wallet is debited before the vendor is called, and that debit commits first. This is deliberate: holding a database transaction open across a ten-second vendor call would lock your wallet row for the whole wait.
payable, notface, leaves your wallet.payable = face − discount.faceis what reaches the phone. Your discount does not reduce the top-up the customer receives.- Auto-reversal happens only on a vendor-confirmed failure. Everything else waits for the background settlement job or a support action.
- There is no spend cap or velocity limit. Your pre-funded balance is the ceiling — the only amount check on submit is whether the wallet can cover
payable.
Rate limits
Every recharge endpoint falls under the general client-API rule: 1,000 requests per hour, keyed on your API key, shared with products, wallets and payouts. There is no recharge-specific allowance. See Rate Limits.
This matters most when polling. Use the cadence in Polling cadence rather than a tight loop, or recharge polling will consume the budget your other calls need.