TeleAccountHub API

Browse live Telegram products, purchase with wallet balance, check order status, and download completed orders — all from one simple REST API.

Authentication

Authenticated endpoints require your API key in the Authorization header.

Authorization: Bearer tgsk_YOUR_API_KEY

Generate your API key inside the Telegram bot from Api Docs → Api Key.

GET /api/v1/catalog/securetd/categories

Returns live product categories and stock counts. No API key is required.

curl https://telenumber.telekartstar.com/api/v1/catalog/securetd/categories

{
  "ok": true,
  "has_purchasable_products": true,
  "message": null,
  "categories": [
    {
      "category_id": 1,
      "category_name": "Asia",
      "total_stock": 53489
    }
  ]
}

GET /api/v1/catalog/securetd/categories/{category_id}/products

Returns live products in a category. Prices are wallet prices shown to customers.

curl https://telenumber.telekartstar.com/api/v1/catalog/securetd/categories/1/products

{
  "ok": true,
  "category_id": 1,
  "products": [
    {
      "product_id": 56,
      "product_name": "Philippines +63",
      "total_stock": 15242,
      "retail_price_usd": 0.7245,
      "wallet_price": "$0.72",
      "wallet_unit_price": "$0.72"
    }
  ]
}

GET /api/v1/balance

Returns the current wallet balance for the API key owner.

curl https://telenumber.telekartstar.com/api/v1/balance \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "balance_usd": 315.56,
  "balance_display": "$315.56"
}

POST /api/v1/securetd/checkout

Purchases a product using wallet balance. The API checks product availability and balance before charging. If checkout fails after balance reservation, the balance is refunded automatically.

curl -X POST https://telenumber.telekartstar.com/api/v1/securetd/checkout \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":2281,"quantity":1,"category_id":86}'

{
  "ok": true,
  "order": {
    "id": 74,
    "order_number": "10094",
    "status": "processing",
    "product_id": 2281,
    "product_name": "Nigeria +234",
    "quantity": 1,
    "download_ready": false
  },
  "local_order_id": 376,
  "charged_usd": 0.299,
  "charged_display": "$0.30"
}

GET /api/v1/securetd/orders/{order_id}

Checks the order status. Use the order id returned by checkout.

curl https://telenumber.telekartstar.com/api/v1/securetd/orders/74 \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY"

{
  "ok": true,
  "order": {
    "id": 74,
    "order_number": "10094",
    "status": "completed",
    "product_id": 2281,
    "product_name": "Nigeria +234",
    "quantity": 1,
    "download_ready": true,
    "download_filename": "order-74.zip"
  }
}

GET /api/v1/securetd/orders/{order_id}/download

Downloads the completed order ZIP. This endpoint returns a file when download_ready is true.

curl -L https://telenumber.telekartstar.com/api/v1/securetd/orders/74/download \
  -H "Authorization: Bearer tgsk_YOUR_API_KEY" \
  -o order-74.zip

Errors

Errors return JSON with ok:false, an error code, and a human-readable message.

{
  "ok": false,
  "error": "invalid_product",
  "message": "This product is no longer available."
}