Charges API
Preview what a recharge will cost — face, discount and payable — without placing anything
Charges API
Returns the price breakdown for a prospective recharge: the face value, your discount, and what your wallet would be debited. Nothing is placed and no money moves.
Use it to show a price before the user commits. It is optional — submit prices the recharge server-side regardless — but it lets you show an accurate number first.
Endpoint
POST /api/v1/recharge/chargesAuthentication: API Key + Secret required
It is a POST rather than a GET because pricing is per-client and dynamic. For the same reason the response is never cached.
Request
curl -X POST https://api.starshiprewards.com/api/v1/recharge/charges \
-H "X-API-Key: <your-api-key>" \
-H "X-API-Secret: <your-api-secret>" \
-H "Content-Type: application/json" \
-d '{
"operator_id": 1,
"amount": 199
}'Body
| Field | Type | Required | Description |
|---|---|---|---|
operator_id | number | Yes | From GET /api/v1/recharge/operators |
amount | number | string | Yes | Face value in whole rupees. Must be greater than zero |
amount accepts a JSON number or a string and is parsed exactly — money never passes through a float. "199" and 199 are equivalent.
Whole rupees only. 199.50 is rejected with a 400, not rounded and not truncated. Our vendor truncates fractional rupees, so we refuse the request rather than let the amount silently change under you.
Response
200 OK
{
"face": 199.00,
"discount_pct": 2.50,
"discount": 4.98,
"payable": 194.02
}| Field | Type | Description |
|---|---|---|
face | number | The recharge amount that reaches the operator — what the subscriber receives |
discount_pct | number | Your resolved discount percentage |
discount | number | face * discount_pct / 100, rounded to 2 decimal places |
payable | number | face - discount. What your wallet would be debited |
All money fields are returned to 2 decimal places.
The subscriber always receives the full face amount. The discount is your margin on the transaction, not a reduction in what gets recharged.
Pricing rules
discount_pctis resolved per client and per operator. Two operators can price differently for the same account.- The rate can change without notice. Do not hardcode it — call this endpoint, or read the
discountandpayablereturned by submit. - If no discount is configured for your account,
discount_pctis0andpayableequalsface. Pricing fails safe rather than guessing a rate.
This is a quote, not a hold
The response reserves nothing. It does not check your wallet balance, does not run the duplicate guard, and does not lock the price.
A 200 here does not mean the recharge will succeed. Between the quote and the submit, any of these can still refuse it:
- Insufficient wallet balance
- The duplicate guard
- A client, channel or operator guard
- The global kill-switch
Always treat the payable on the submit response as authoritative for reconciliation.
Validation
The operator is validated before a price is quoted, so you never receive a plausible-looking quote for an operator that cannot actually be recharged.
Errors
| Status | Message | Cause |
|---|---|---|
400 | operator_id is required | Missing or zero operator_id |
400 | amount must be greater than zero | Zero or negative amount |
400 | amount must be a whole rupee | Fractional amount, e.g. 199.50 |
400 | unknown operator_id | No such operator, or the operator is inactive |
400 | invalid request body | Malformed JSON |
401 | — | Missing or invalid API credentials |
500 | — | Pricing could not be resolved. Retry with backoff |
Next
Submit a recharge — place the real thing.