API Reference

The Topup Bot API lets you place automated Free Fire diamond top-up orders, track their status, and receive delivery confirmations via webhook. All requests and responses are JSON.

Authentication

Every API request (except /api/v1/register) requires your API key as a Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your API key is issued when your merchant account is approved. Keep it secret — anyone with your key can place orders against your wallet balance.

Create a merchant account

POST/api/v1/register

Public endpoint — no authentication required. Creates a merchant account with status: pending. An admin must approve it before you can log in or place orders.

Field	Type	Notes
`business_name`required	string	Your business or store name
`username`required	string	3-32 chars, letters/numbers/underscore/dot — used to log in at `/dashboard`
`password`required	string	At least 8 characters — used to log in at `/dashboard`
`contact_email`	string	At least one of email / telegram is required
`contact_telegram`	string	Your Telegram username
`unipin_email`	string	Optional — can be added later by admin during approval
`unipin_password`	string	Optional
`unipin_pin`	string	Optional

// Response 200
{
  "success": true,
  "message": "Application submitted. An admin will review it shortly…",
  "api_key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

The api_key is for authenticating API requests only (Bearer token). Dashboard login (/dashboard) uses your username and password, not the API key.

Dashboard login

POST/api/v1/client/login

Logs a merchant into the dashboard portal. Sets an HttpOnly session cookie.

POST /api/v1/client/login
{ "username": "nepaltopup", "password": "••••••••" }

Reveal your API key

GET/api/v1/api-key

Session-authenticated (dashboard cookie) or Bearer token. Returns your current raw API key on demand, so you can copy it into an integration without it being shown anywhere by default.

Create a top-up order

POST/api/v1/topup

Queues a diamond top-up order for automated fulfillment. Rate-limited per your plan's rate_limit_per_min (default 10/min).

Field	Type	Notes
`order_id`required	string	Your own unique order reference
`player_id`required	string	Free Fire player ID to deliver to
`diamond_amount`required	string	e.g. `"115"`, `"weekly"`, `"monthly"`
`callback_url`	string	Webhook URL for delivery confirmation (falls back to your saved default)

POST /api/v1/topup
{
  "order_id": "ORD1001",
  "player_id": "123456789",
  "diamond_amount": "115",
  "callback_url": "https://yoursite.com/webhook"
}

// Response 200
{
  "message": "Order accepted and queued",
  "jobId": "ORD-xxxxxxxx-ORD1001",
  "service_fee_charged": 115,
  "remaining_balance": 4885
}

Get wallet balance

GET/api/v1/balance

Returns your current wallet balance, fee percentage, and webhook secret.

List recent orders

GET/api/v1/orders

Returns your most recent orders (up to 50).

Get order status

GET/api/v1/orders/:orderId

Poll a specific order's fulfillment status by your order_id.

Retry a failed order

POST/api/v1/orders/:orderId/retry

Re-queues a previously failed order for another fulfillment attempt.

Webhook callbacks

When an order completes or fails, Topup Bot sends a signed POST to your callback_url:

// Success
{ "order_id": "ORD1001", "status": "completed", "message": "Delivered 115 diamonds", "receipt_url": "https://…" }

// Failure (credits are automatically refunded)
{ "order_id": "ORD1001", "status": "failed", "message": "…reason…", "receipt_url": null }

Every webhook includes an HMAC-SHA256 signature so you can verify it came from Topup Bot:

x-bot-signature: <hex hmac>
x-signature-sha256: <hex hmac>

// Verify (Node.js example)
const expected = crypto.createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(JSON.stringify(req.body)).digest('hex');
if (expected !== req.headers['x-bot-signature']) throw new Error('Invalid signature');

Webhooks are retried up to 5 times with exponential backoff (15s → 30s → 60s → 120s → 240s) if your endpoint doesn't respond with a 2xx status.

Common error responses

Status	Meaning
`400`	Invalid or missing request fields
`401`	Missing or invalid API key
`402`	Insufficient wallet balance
`403`	Account pending approval / inactive / IP not whitelisted
`409`	Order with this `order_id` already exists
`429`	Rate limit exceeded

Need help integrating? Get in touch via the homepage.