Gotter Recharge API

Build your own recharge and bill payment panel, app, or website on top of Gotter Recharge. Every transaction you make through this API flows through the same wallet, commission engine, and telecom/BBPS providers that power the main dashboard — you get your own branded front-end, we handle the backend.

https://gotter.space/api/v1

Authentication

Every request must include two headers: your API key, and an HMAC-SHA256 signature of the request body, signed with your API secret. This proves the request genuinely came from you without ever sending your secret over the network.

Signature formula:

signature = HMAC_SHA256( JSON.stringify(requestBody), apiSecret )

For GET requests (no body), sign the string {} (an empty JSON object) — this must match exactly what the server receives as the parsed body.

const crypto = require('crypto');
const axios = require('axios');

const apiKey = 'bk_xxxxxxxxxxxxxxxx';
const apiSecret = 'your_api_secret';

async function callApi(path, method, body = {}) {
  const bodyStr = JSON.stringify(body);
  const signature = crypto.createHmac('sha256', apiSecret).update(bodyStr).digest('hex');

  const res = await axios({
    url: 'https://gotter.space/api/v1' + path,
    method,
    headers: {
      'X-Api-Key': apiKey,
      'X-Signature': signature,
      'Content-Type': 'application/json',
    },
    data: method === 'GET' ? undefined : body,
  });
  return res.data;
}

# Signature must be computed beforehand (shown here for a GET request, body = {})
SIGNATURE=$(echo -n '{}' | openssl dgst -sha256 -hmac "your_api_secret" | sed 's/^.* //')

curl "https://gotter.space/api/v1/balance" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

<?php
$apiKey = 'bk_xxxxxxxxxxxxxxxx';
$apiSecret = 'your_api_secret';

$body = json_encode(['operatorCode' => 'AT', 'number' => '9876543210', 'amount' => 199]);
$signature = hash_hmac('sha256', $body, $apiSecret);

$ch = curl_init('https://gotter.space/api/v1/recharge');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey,
    'X-Signature: ' . $signature,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
echo $response;

Webhooks

Instead of polling /status/:clientRefId or /giftvouchers/orders/:id, set a webhook URL once from My API and we'll POST a signed notification to it the moment a recharge, bill payment, or gift voucher order resolves to success or failed.

Events

Payload shape

{
  "event": "recharge.success",
  "data": {
    "clientRefId": "TXN1784224715654a0802f85",
    "status": "success",
    "amount": 199,
    "number": "9876543210",
    "providerRefId": "PT0000BXNCYD"
  },
  "sentAt": "2026-07-22T18:41:12.000Z"
}

Gift voucher events carry orderId, referenceId, status, amount, and brandTitle instead — fetch /giftvouchers/orders/:id afterwards to get the actual voucher code/PIN.

Verifying the signature

Every request includes an X-Signature header — always verify it before trusting the payload:

signature = HMAC_SHA256( JSON.stringify(payload), apiSecret )

// Node.js / Express example
const crypto = require('crypto');

app.post('/webhooks/gotter', express.json(), (req, res) => {
  const expected = crypto.createHmac('sha256', apiSecret).update(JSON.stringify(req.body)).digest('hex');
  if (expected !== req.headers['x-signature']) return res.status(401).send('Invalid signature');

  const { event, data } = req.body;
  // ...update your own records based on event/data...

  res.status(200).send('ok'); // acknowledge quickly - do slow work asynchronously
});

🧪 Try it live

Test real API calls right from this page. Your key and secret are used only in your browser to sign requests — they are never sent anywhere except directly to the Gotter Recharge API.

GET/operators

Returns every active operator you can recharge or pay bills for.

Query parameters

Example request

curl "https://gotter.space/api/v1/operators?type=mobile_prepaid" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "operators": [
      { "_id": "64f...", "name": "Airtel Prepaid", "type": "mobile_prepaid", "apiCode": "AT", "minAmount": 10, "maxAmount": 10000, "billFetchRequired": false },
      { "_id": "64f...", "name": "Tata Sky DTH", "type": "dth", "apiCode": "TSKY", "minAmount": 10, "maxAmount": 10000, "billFetchRequired": false },
      { "_id": "64f...", "name": "MSEB Electricity", "type": "electricity", "apiCode": "MSEB", "minAmount": 10, "maxAmount": 50000, "billFetchRequired": true }
    ]
  }
}

Use the short apiCode value (not _id) in every other endpoint below — it's what you pass as operatorCode.

GET/balance

Returns your current wallet balance.

Example request

curl "https://gotter.space/api/v1/balance" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{ "success": true, "data": { "balance": 1590.18 } }

GET/detect-operator

Give it a 10-digit mobile number — it detects the prepaid operator and circle automatically, and returns available recharge plans in the same call. Use this to power a "just type the number" recharge flow.

Query parameters

Example request

curl "https://gotter.space/api/v1/detect-operator?number=9876543210" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "operatorCode": "AT",
    "operatorName": "Airtel Prepaid",
    "circle": "Delhi",
    "plans": [
      { "type": "Unlimited", "details": "Unlimited + 1.5GB/day", "amount": "239", "talktime": "0", "validity": "28" },
      { "type": "Unlimited", "details": "Unlimited + 2GB/day", "amount": "599", "talktime": "0", "validity": "84" }
    ]
  }
}

Plan fields (type, details, amount, talktime, validity) are passed through exactly as the provider returns them - note that amount and validity come back as strings, not numbers.

If plan data isn't available from the provider at that moment, plans comes back as an empty array — the operator detection itself still succeeds, so recharge can proceed with a manually entered amount.

GET/plans

Browse plans directly when you already know the operator (e.g. the retailer picked it manually, or you're re-fetching plans without re-running detection).

Query parameters

Example request

curl "https://gotter.space/api/v1/plans?operatorCode=AT&circle=Delhi" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "plans": [
      { "type": "Unlimited", "details": "Unlimited + 1.5GB/day", "amount": "239", "talktime": "0", "validity": "28" }
    ]
  }
}

GET/fetch-bill

For operators where the biller must confirm a due amount before payment (electricity, water, gas, etc.). Always call this first for such operators — check billFetchRequired from /operators to know which ones need it.

Query parameters

Example request

curl "https://gotter.space/api/v1/fetch-bill?operatorCode=MSEB&number=123456789" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "billFetchRequired": true,
    "dueAmount": 842.50,
    "customerName": "RAHUL KUMAR",
    "billDate": "2026-06-15",
    "dueDate": "2026-07-05",
    "amountConstraint": "exact",
    "minAmount": 10,
    "maxAmount": 50000
  }
}

POST/recharge

Performs a mobile prepaid, postpaid, or DTH recharge. Debits your wallet immediately; refunds automatically if the provider declines.

Body parameters

Example request

SIGNATURE=$(echo -n '{"operatorCode":"AT","number":"9876543210","amount":199}' | openssl dgst -sha256 -hmac "your_api_secret" | sed 's/^.* //')

curl -X POST "https://gotter.space/api/v1/recharge" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"operatorCode":"AT","number":"9876543210","amount":199}'

Example response

{
  "success": true,
  "data": {
    "clientRefId": "TXN1784224715654a0802f85",
    "status": "success",
    "providerRefId": "PT0000BXNCYD",
    "amount": 10
  }
}

status is one of success, failed, pending — poll /status/:clientRefId for pending transactions, or listen for the async resolve on your side by polling periodically.

POST/bill-payment

Pays a bill for Electricity, Gas, Water, FASTag, Broadband, or Landline. Same parameters and response shape as /recharge above.

Example request

SIGNATURE=$(echo -n '{"operatorCode":"MSEB","number":"123456789","amount":842.50}' | openssl dgst -sha256 -hmac "your_api_secret" | sed 's/^.* //')

curl -X POST "https://gotter.space/api/v1/bill-payment" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"operatorCode":"MSEB","number":"123456789","amount":842.50}'

Example response

{
  "success": true,
  "data": {
    "clientRefId": "TXN1784224799231b7104c22",
    "status": "success",
    "providerRefId": "BP0000AKXQLM",
    "amount": 842.50
  }
}

GET/status/:clientRefId

Checks the current status of a transaction using the clientRefId returned from /recharge or /bill-payment.

Example request

curl "https://gotter.space/api/v1/status/TXN1784224715654a0802f85" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "clientRefId": "TXN1784224715654a0802f85",
    "status": "success",
    "amount": 10,
    "providerRefId": "PT0000BXNCYD",
    "commissionEarned": 0.13,
    "createdAt": "2026-07-16T17:58:35.656Z"
  }
}

GET/transactions

Returns your transaction history, paginated.

Example request

curl "https://gotter.space/api/v1/transactions?page=1&limit=20" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "clientRefId": "TXN1784224715654a0802f85",
        "operator": { "name": "Airtel Prepaid", "type": "mobile_prepaid" },
        "number": "9876543210",
        "amount": 199,
        "status": "success",
        "providerRefId": "PT0000BXNCYD",
        "commissionEarned": 2.5,
        "createdAt": "2026-07-16T17:58:35.656Z"
      }
    ],
    "page": 1
  }
}

Gift Vouchers

450+ brand gift cards — Amazon Pay, Myntra, and more — powered by Hubble. All amounts are in ₹.

GET/giftvouchers/brands

Lists gift card brands currently available for you to sell.

Query parameters

Example request

curl "https://gotter.space/api/v1/giftvouchers/brands?search=Amazon&page=1" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "brands": [
      {
        "_id": "66a1e2f9c110",
        "title": "Amazon Pay",
        "denominationType": "FIXED",
        "amountRestrictions": { "denominations": [500, 1000, 5000], "minOrderAmount": 500, "maxOrderAmount": 5000 },
        "thumbnailUrl": "https://...",
        "adminMarkupPercent": 2
      }
    ],
    "page": 1, "totalPages": 3, "total": 112
  }
}

adminMarkupPercent is your margin — credited back to your wallet automatically after a successful order.

GET/giftvouchers/brands/:id

Full detail for one brand — description, denominations, how-to-use steps, and terms & conditions.

Example request

curl "https://gotter.space/api/v1/giftvouchers/brands/66a1e2f9c110" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "brand": {
      "_id": "66a1e2f9c110",
      "title": "Amazon Pay",
      "brandDescription": "Shop millions of products on Amazon.in",
      "category": ["Shopping"],
      "denominationType": "FIXED",
      "amountRestrictions": { "denominations": [500, 1000, 5000], "minOrderAmount": 500, "maxOrderAmount": 5000 },
      "thumbnailUrl": "https://...",
      "howToUseInstructions": [{ "retailModeName": "Online", "instructions": ["Log in to amazon.in", "Go to Gift Cards > Redeem", "Enter the code and PIN"] }],
      "termsAndConditions": ["Valid for 1 year from issue date", "Non-refundable once issued"],
      "adminMarkupPercent": 2
    }
  }
}

POST/giftvouchers/order

Places a gift voucher order. The amount is debited from your wallet immediately; your margin (if any) is credited back once the voucher is issued successfully.

Body parameters

Example request

BODY='{"brandId":"66a1e2f9c110","amount":500,"denominationDetails":[{"denomination":500,"quantity":1}]}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your_api_secret" | sed 's/^.* //')

curl -X POST "https://gotter.space/api/v1/giftvouchers/order" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Example response

{
  "success": true,
  "data": {
    "orderId": "66a1e2f9c110",
    "referenceId": "GVmruhp3trkhnzor",
    "status": "success",
    "amount": 500,
    "vouchers": [
      { "cardNumber": "1234 5678 9012", "cardPin": "4821", "validTill": "2027-07-22", "amount": 500 }
    ]
  }
}

status can be success, processing (poll /giftvouchers/orders/:id until it resolves), or failed (amount is auto-refunded to your wallet).

GET/giftvouchers/orders

Your gift voucher order history, paginated (same page/limit params as transaction history).

Example request

curl "https://gotter.space/api/v1/giftvouchers/orders?page=1&limit=20" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "orders": [
      { "referenceId": "GVmruhp3trkhnzor", "brandTitle": "Amazon Pay", "amount": 500, "status": "success", "createdAt": "2026-07-22T10:15:00.000Z" }
    ],
    "page": 1, "totalPages": 1, "total": 1
  }
}

GET/giftvouchers/orders/:id

Fetches one order's current status and voucher codes (once issued) — use this to poll an order stuck in processing.

Example request

curl "https://gotter.space/api/v1/giftvouchers/orders/66a1e2f9c110" \
  -H "X-Api-Key: bk_xxxxxxxxxxxxxxxx" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

Example response

{
  "success": true,
  "data": {
    "orderId": "66a1e2f9c110",
    "referenceId": "GVmruhp3trkhnzor",
    "brandTitle": "Amazon Pay",
    "amount": 500,
    "status": "success",
    "vouchers": [
      { "cardNumber": "1234 5678 9012", "cardPin": "4821", "validTill": "2027-07-22", "amount": 500 }
    ],
    "createdAt": "2026-07-22T10:15:00.000Z"
  }
}

Error Codes

All error responses follow the same shape: { "success": false, "message": "..." }

Operator Types

Questions or need higher rate limits? Raise a complaint from your dashboard or contact your Admin.