Recharge Overview

The Recharge API places real-money mobile recharges on Indian phone numbers: prepaid top-ups and postpaid bill payments. The amount is debited from your pre-funded Starship wallet, and the recharge is sent to the operator immediately.

How recharge differs from voucher orders

This is the single most important thing to understand before integrating, because it is the opposite of how Orders behave.

Recharge auto-fulfils by design. There is no inventory to check and no admin gate on the individual transaction. The controls that replace that gate are the guards and the pre-funded wallet, which caps your total exposure to float you have already transferred to us.

Availability

Recharge is off by default for every client. Before your API calls will succeed, Starship must enable recharge for your account, and enable the API channel specifically. Contact your account manager to be switched on.

Two consequences for your integration:

• A 403 from these endpoints is usually a configuration answer, not a bad request. See the error table.
• Sandbox enablement and production enablement are separate. Being live in sandbox does not mean you are live in production.

Scope of v1

Why you must name the operator

Mobile Number Portability means a number's series no longer identifies its operator, and our vendor exposes no detect endpoint. So operator_id is required on every submit and is validated against our catalog. Fetch valid ids from GET /api/v1/recharge/operators.

The five endpoints

Typical integration flow

1. GET  /api/v1/recharge/operators     → cache the operator list
2. POST /api/v1/recharge/charges       → show the user what it costs (optional)
3. POST /api/v1/recharges              → place it (Idempotency-Key required)
     ├── 200 + status SUCCESS          → done, operator confirmed
     ├── 200 + status FAILED           → wallet already credited back
     └── 202 + status PROCESSING       → not settled yet, go to 4
4. GET  /api/v1/recharges/:id          → poll until status leaves PROCESSING

Status lifecycle

PROCESSING ──→ SUCCESS      (operator confirmed — final, irreversible)
     │
     ├───────→ FAILED       (wallet credited back — final)
     │
     └───────→ REVERSED     (settled then reversed — wallet credited back)

Status values

Some historical rows carry legacy status values (PENDING, DELIVERED, RECHARGED, CANCELLED). The API normalises these onto the four canonical values above, and the status query filter accepts the canonical value and matches the legacy rows too.

Sub-status

Every recharge also carries a sub_status giving finer detail within the status. Treat it as diagnostic, not as control flow — branch on status.

Access guards

Every submit runs a chain of guards before your wallet is touched. Each failure maps to a distinct HTTP status so you can tell "try again later" from "this will never work".

The wallet balance check is the only amount gate. There are no per-transaction caps, no daily spend limits and no velocity limits, because the wallet is pre-funded and is therefore its own ceiling.

The duplicate guard

A repeat of the same (mobile_number, amount) from your account inside a configurable window is refused with 409. The window is a Starship-side setting, not a value you send.

That guard exists so a network retry storm cannot turn one intent into two irreversible recharges. A genuine repeat top-up is legitimate, so the escape hatch is "force": true — see Submit a recharge.

Pricing

Recharge pricing is a per-client discount off face value:

payable = face - (face * discount_pct / 100)

Your discount_pct is resolved per client and per operator and can change without notice, so do not hardcode it. Call POST /api/v1/recharge/charges when you need to show a price, and read the authoritative payable off the submit response.

If Starship has no discount configured, the rate is 0 and you pay face value — pricing fails safe rather than guessing.

Webhooks

Rate limits

Recharge endpoints have no dedicated rate-limit rule. They fall under the general /api/v1/ limit of 1000 requests per hour, keyed by API key. Your account may carry a different configured limit — see Rate Limits.

When polling a PROCESSING recharge, back off rather than tight-looping: a poll every few seconds for the first minute, then progressively slower, will comfortably stay inside the limit.

Next steps

1. Operators API — get a valid operator_id
2. Charges API — preview the price
3. Submit a recharge — place it
4. List and get recharges — poll and reconcile