Submit Recharge API

Places a real recharge. This endpoint debits your wallet and calls the recharge vendor automatically — there is no admin approval step and no inventory to fall back on.

Endpoint

POST /api/v1/recharges

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

Request Headers

X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke
X-API-Secret: your-secret-here
Content-Type: application/json
Idempotency-Key: rch_a4f9c21e_1740000000

A missing or malformed Idempotency-Key is rejected before the request reaches the recharge logic, with its own error shape:

{
  "error": {
    "code": "IDEMPOTENCY_KEY_REQUIRED",
    "message": "Idempotency-Key header is required for this operation",
    "details": "Include a unique Idempotency-Key header (8-256 characters) to prevent duplicate requests. Use a UUID or unique transaction ID from your system. Example: Idempotency-Key: ord_abc123_1705689660"
  }
}

Keys shorter than 8 characters return IDEMPOTENCY_KEY_TOO_SHORT; keys longer than 256 return IDEMPOTENCY_KEY_TOO_LONG.

Request Body

Minimal request

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

Complete request schema

{
  "mobile_number": "9876543210",
  "operator_id": 1,
  "amount": 199,
  "circle_id": 12,
  "is_postpaid": false,
  "is_special": false,
  "country_code": "IN",
  "nickname": "DadsPhone",
  "client_reference": "TOPUP-2026-000412",
  "force": false
}

Field descriptions

The mobile number is never reshaped

mobile_number must be digits only. +91 98765 43210, 98765-43210 and (987) 654-3210 are all rejected with 400.

Separators are not stripped, and a country prefix is not detected and removed. Silently reshaping a phone number risks recharging a different number than you meant, so a malformed number is refused rather than repaired. Normalise in your own code before you submit.

For India the number must be exactly 10 digits and begin 6, 7, 8 or 9 — the mobile range of India's national numbering plan. Landlines and short codes are rejected.

Amount must be whole rupees

amount accepts a JSON number or a string and is parsed as an exact decimal. It must be a whole rupee: 199.50 is rejected with 400.

The vendor truncates fractional input, so accepting 199.50 would debit ₹199.50 from your wallet and credit ₹199 to the phone. Rounding it ourselves would be equally wrong — you asked for something that cannot be delivered, so the API says so.

There is no maximum amount. Your pre-funded wallet balance is the only ceiling; the sole amount check is whether the wallet covers payable.

Circles

A telecom circle is the regional licence area of an Indian mobile number. Most operators do not need it — send the request without circle_id and it works.

Some operators do. Where the vendor validates operator and region together, circle_id becomes mandatory and omitting it returns 400 with circle_id is required for this operator.

The three outcomes

A submit that passes the guards always produces one of three results. Every one of them means the wallet has already been debited.

Starship waits up to 10 seconds for the vendor, so a submit request can legitimately take that long. Past the deadline it stops waiting and returns 202 — the deadline is a limit on our patience, never a verdict on the recharge.

The duplicate guard

Before any money moves, Starship checks whether the same client, the same mobile number and the same amount were submitted inside a recent window (5 minutes by default). If so, the request is refused with 409 RESOURCE_CONFLICT and nothing is debited.

The guard exists because recharge is irreversible. It converts the most common integration bug — a retry storm on a request that already succeeded — from a double top-up into a clean rejection.

Note what it keys on: client, number and amount. Topping up different numbers rapidly is unaffected, so bulk flows do not trip it.

Getting a deliberate repeat through

A genuine second top-up of the same number for the same amount is legitimate. Set force: true to skip the guard:

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

Response

Success Response

Status Code: 200 OK (SUCCESS or FAILED) or 202 Accepted (PROCESSING)

{
  "id": 84213,
  "reference_number": "9f2c41ab7de4489bb1c0a6f2e8d35471",
  "status": "SUCCESS",
  "sub_status": "OPERATOR_CONFIRMED",
  "mobile_number": "9876543210",
  "operator_id": 1,
  "face": 199.00,
  "discount": 4.98,
  "payable": 194.02,
  "vendor_recharge_id": "VR-88213904",
  "operator_txn_id": "AIRTEL-772391884",
  "client_reference": "TOPUP-2026-000412",
  "created_at": "2026-08-25T10:30:00Z"
}

Response Fields

Fields marked "omitted" are absent from the JSON entirely rather than present and null. Do not assume the key exists.

A 202 response

{
  "id": 84214,
  "reference_number": "3b7d05e9c1a24f6f8e2b9017dcaa4d83",
  "status": "PROCESSING",
  "sub_status": "VENDOR_SUBMITTED",
  "mobile_number": "9876543210",
  "operator_id": 1,
  "face": 199.00,
  "discount": 4.98,
  "payable": 194.02,
  "created_at": "2026-08-25T10:31:12Z"
}

A confirmed failure

{
  "id": 84215,
  "reference_number": "c8e14f2b90a742d3ae51b7c93f60d2aa",
  "status": "FAILED",
  "sub_status": "REVERSED",
  "mobile_number": "9876543210",
  "operator_id": 1,
  "face": 199.00,
  "discount": 4.98,
  "payable": 194.02,
  "failure_reason": "Invalid recharge amount for this plan",
  "created_at": "2026-08-25T10:32:40Z"
}

failure_reason is passed through from the vendor without rewriting. It is useful to display and to log, but it is not a stable enum — never branch on its text.

Errors

Every error below is returned before any money moves, except where noted.

400 — your request

401 / 403 / 404 / 409 / 503

The two 403 enablement errors are the ones you are most likely to see on day one: recharge is off by default for every client, and the API channel is a second, separate toggle.

Retrying safely

Every resubmit after a 400, 404, 409 or 503 must use a new Idempotency-Key. The original key replays the stored error for 24 hours, and reusing it with a changed body (for example, adding force: true) returns 422 E_IDEMPOTENCY_KEY_REUSED. A concurrent request with the same key returns 409 E_IDEMPOTENCY_IN_FLIGHT.

A 500 is the ambiguous case: the wallet debit may have committed before the failure. Do not resubmit on reflex. Call GET /api/v1/recharges?search=<mobile_number>&from_date=<today> and look for your client_reference in the results to check whether a row already exists for this attempt. Resubmit only if none does.

Passing a distinct client_reference on every submit makes this check trivial, and is the single most useful habit for operating this endpoint.

Examples

# Prepaid top-up
curl -X POST "{{host}}/api/v1/recharges" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rch_a4f9c21e_1740000000" \
  -d '{
    "mobile_number": "9876543210",
    "operator_id": 1,
    "amount": 199,
    "client_reference": "TOPUP-2026-000412"
  }'

# Postpaid bill payment
curl -X POST "{{host}}/api/v1/recharges" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rch_b71d02fa_1740000120" \
  -d '{
    "mobile_number": "9876543210",
    "operator_id": 1,
    "amount": 649,
    "is_postpaid": true,
    "client_reference": "BILL-2026-000087"
  }'

# Operator that requires a circle
curl -X POST "{{host}}/api/v1/recharges" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rch_c93e5518_1740000240" \
  -d '{
    "mobile_number": "9876543210",
    "operator_id": 7,
    "amount": 99,
    "circle_id": 12
  }'

# Deliberate repeat — only after a human confirms it
curl -X POST "{{host}}/api/v1/recharges" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rch_d04a6629_1740000360" \
  -d '{
    "mobile_number": "9876543210",
    "operator_id": 1,
    "amount": 199,
    "force": true
  }'

Next steps

• Get Recharge — poll a PROCESSING recharge to its outcome
• List Recharges — reconcile submits against your own records
• Idempotency Guide — how the Idempotency-Key header behaves