Corporate API

A server-to-server API for reselling recharge and bill payments. Everything is JSON over HTTPS, authenticated with an API token issued to you and restricted to your own IP addresses.

Base URL: https://freedata.in

One surface

Authentication

Send your API token on every request. The header form is preferred, because a token in a query string ends up in proxy and web-server access logs:

curl -H "X-Api-Token: <your-token>" \
     "https://freedata.in/api/corp/v1/balance"

Three transports are accepted, in this order of preference:

• X-Api-Token: <token> — recommended
• Authorization: Bearer <token>

IP allowlist

Your account is restricted to the source IP addresses you register with us (individual addresses or CIDR ranges). A call from anywhere else is refused with result code 2428. Tell us before you change egress addresses, or your traffic stops.

Rate limit

Requests are capped per minute per account. Exceeding it returns 429 with result code 123; retry after a short pause.

Errors

A refusal carries a real HTTP status plus a body like:

{"status":"rejected","error":"ip_not_allowed","code":2428,"message":"IP Validation failed."}

Retries and idempotency

Every money endpoint is idempotent on your own reference — urid on recharge, request_id everywhere else. This is the single most important rule in this document.

• If you do not receive a response, retry with the SAME reference. We return the original outcome instead of transacting again. Generating a new reference on a retry is how integrations double-charge their customers.
• Reusing a reference for different details (a different number, operator or amount) is rejected with 2555 Duplicate urid. We will never answer you with a transaction that is not the one you asked about.
• A reference must be unique across your account and at most 64 characters.

Pending is not failure

Status callbacks

Give us an HTTPS URL and we will call it when a transaction reaches its final state (we do not call for pending). Delivery is retried with a growing back-off until your endpoint answers 2xx.

GET https://your-server.example/callback
      ?v=2
      &status=SUCCESS
      &orderid=R2607230429028DB15
      &urid=ABC123
            &amount=100.0000
      &account=9876543210
      &ts=1755400000
      &nonce=3f1c0a9b2e5d4867b1a0c7d9e2f34856
      &hash=<hmac>

Verify hash before trusting a callback. It is an HMAC-SHA256, keyed with your API token, over every parameter we send except hash itself — sorted by key and joined as key=value with &. Build the pre-image from what actually arrived rather than from a fixed list of names, so a field we add later is covered automatically:

$params = $_GET;
unset($params['hash']);
ksort($params, SORT_STRING);

$pairs = [];
foreach ($params as $k => $v) {
    $pairs[] = $k . '=' . $v;
}

$expected = hash_hmac('sha256', implode('&', $pairs), $yourApiToken);
if (!hash_equals($expected, (string) ($_GET['hash'] ?? ''))) {
    http_response_code(403);
    exit;
}

// Freshness: refuse anything outside a five-minute window.
if (abs(time() - (int) ($_GET['ts'] ?? 0)) > 300) {
    http_response_code(403);
    exit;
}

// Replay: refuse a nonce you have already seen inside that window.
if ($youHaveSeen[$_GET['nonce']] ?? false) {
    http_response_code(403);
    exit;
}

// Duplicate delivery: we retry until you answer 2xx, so the SAME orderid may
// legitimately arrive more than once with different ts/nonce. Book it once,
// keyed on orderid.

Service status

Read live from the platform as this page was served. Query it yourself at any time with GET /api/corp/v1/services rather than hardcoding a service list.

"No vendor active" means the endpoints work but nothing is switched on upstream: calls are answered safely and nothing is charged.

Endpoints

Core (v1)

The modern surface for new integrations. JSON in, JSON out, machine-readable string errors alongside a numeric code support can trace.

{
    "status": "success",
    "code": 200,
    "client": "Acme Pvt Ltd",
    "services": [
        {
            "service": "recharge",
            "name": "Mobile & DTH recharge",
            "enabled": true,
            "ready": true,
            "note": null
        }
    ]
}

{
    "status": "success",
    "code": 200,
    "balance": "5000.0000"
}

{
    "page": 1,
    "page_size": 20,
    "total": 4,
    "transactions": [
        {
            "ref": "R2607…",
            "request_id": "ABC123",
            "service": "recharge",
            "account": "9876543219",
            "amount": "10.0000",
            "status": "failed"
        }
    ]
}

Recharge (v1)

Mobile and DTH recharge. Money endpoints are POST; status is GET.

{
    "status": "success",
    "code": 200,
    "order_id": "R2607…",
    "urid": "ABC123",
    "operator_ref": "OP998877",
    "amount": "100.0000",
    "account": "9876543210",
    "balance": "4900.0000",
    "message": "Recharge successful."
}

{
    "status": "success",
    "code": 200,
    "order_id": "R2607…",
    "urid": "ABC123",
    "operator_ref": "OP998877",
    "amount": "100.0000",
    "account": "9876543210",
    "refunded": false
}

Bill payments — BBPS (v1)

Browse the biller directory, render the biller's input form from its customer_params schema, fetch the live bill, then pay. Billers whose fetch_requirement is MANDATORY must be fetched before payment.

{
    "ok": true,
    "amount": "500.00",
    "convenience_fee": "0.00",
    "total": "500.00",
    "charge": "500.00"
}

Operator codes

On /api/corp/v1/* send the code column; on send the Code column. It is accepted on their own surface, so an existing integration keeps working unchanged. Fetch this programmatically from GET /api/corp/v1/operators.

Result codes

The same catalog throughout: code on v1.