RechargeGames Order API — Integration Guide
Base URL: https://api.rechargegame.games
Authentication: include X-API-Key: <your key> on every request. The API is for reseller
accounts. Resellers create, replace and revoke their own key in the dashboard (Profile → API
access); the raw key is shown once. A key can be created, replaced or revoked 3 times an hour in
total — after that, wait up to an hour. A key on an account that is not a reseller gets 403
resellers_only — contact us to be upgraded and the same key works again.
This guide is always current at https://api.rechargegame.games/docs — that address (and the bare API address) take you straight here.
How it works
GET /v1/products— see what you can order and what it costs you.- Your site
POSTs an order → we get an instant alert. - The order is created as
pending, and you receive ourorder_id. - We fulfil it, then mark it
deliveredorfailed. - We push the result to your webhook (or your site polls the
order_id).
Want to try it without spending anything? Send "test": true — see Test mode.
Quick start
1. Verify your key
GET /v1/ping
Response:
{ "ok": true, "buyer": "YourShopName" }
2. See what you can order — GET /v1/products
GET /v1/products → a small index of games (slug, name, kind, regions, product count)
GET /v1/products?game=free-fire → that game's regions and packs, at YOUR price
GET /v1/products?kind=giftcard → the index, gift cards only (kind: topup | giftcard)
GET /v1/products?all=true → everything (about 1.6 MB — cache it)
{ "currency": "USDT", "categories": [ { "slug": "free-fire", "name": "Free Fire", "kind": "topup",
"groups": [ { "slug": "brazil", "products": [
{ "name": "100 Diamonds", "price": 0.94, "delivery": "player_id",
"product_key": "topup/free-fire/brazil/100 Diamonds" } ] } ] } ] }
Send the product_key in POST /v1/orders and you are charged exactly that price. An order
whose product text matches no catalog line is accepted unpriced and charged when we deliver
— use product_key and you always know the price up front. Prices change; refresh the list
every few hours (the response is cacheable for 5 minutes). A pack we have marked out of stock stays in the list with "out_of_stock": true, and an order for it is refused with 409 out_of_stock (nothing is created or charged).
Only products we can price are listed. delivery is player_id (we top up an account) or
code (we return a code in delivery_note). GET /v1/region-check?game=…&uid=…®ion=… checks
a player ID against a region for supported games (no key needed, 20 checks/min per IP).
3. Submit an order
POST /v1/orders
Content-Type: application/json
X-API-Key: gv_live_...
Body:
{
"product": "Free Fire 1000 diamonds",
"region": "EU",
"quantity": 1,
"player_id": "51234567",
"buyer_ref": "SHOP-10231"
}
Fields:
| Field | Required | Notes |
|---|---|---|
product |
yes | The product name. Must match a priced product (or send product_key) — an unpriced product is refused with 422. Max 500 chars |
buyer_ref |
no | YOUR order ID — strongly recommended (makes retries safe). Max 200 |
region |
no | e.g. EU, MENA, LATAM. Max 100 |
quantity |
no | 1–999, default 1 |
player_id |
no | Player / account ID to top up. Max 200 |
server_id |
no | Server ID (required for some games like Mobile Legends). Max 200 |
note |
no | Any note for the seller. Max 1000 |
extra |
no | JSON object for any additional fields you want recorded (max 4 KB of JSON) |
product_key |
recommended | Catalog key from GET /v1/products — the exact, unambiguous way to say what you want (see Balance and deposits) |
test |
no | true = test order, see Test mode. Default false |
Response 201:
{
"order_id": "ORD-7K3M9Q",
"buyer_ref": "SHOP-10231",
"status": "pending",
"product": "Free Fire 1000 diamonds",
"region": "EU",
"quantity": 1,
"player_id": "51234567",
"server_id": null,
"note": null,
"delivery_note": null,
"failure_reason": null,
"created_at": "2026-08-17T18:36:33.722773Z",
"updated_at": "2026-08-17T18:36:33.722773Z"
}
If you send the same buyer_ref again, you get 200 with the existing order — no
duplicate alert, no double fulfil. This makes retries on network errors safe.
Treat both 200 and 201 as success.
No price, no order. If we cannot find a price for what you asked for — a name that is not in
the catalog, an ambiguous name, a misspelling — nothing is created and nothing is charged; you get
422 with the code unknown_product. Take the product_key from GET /v1/products instead of
typing names. In a batch, that line alone comes back as an error and the others still go through.
4. Check order status
GET /v1/orders/ORD-7K3M9Q
X-API-Key: gv_live_...
Prefer a webhook (below) so you don't have to poll. If you do poll, this endpoint drives the status shown to your customer. Statuses:
| Status | Meaning |
|---|---|
pending |
Received, not yet fulfilled |
delivered |
Fulfilled — check delivery_note for any code or confirmation |
failed |
Could not be fulfilled — see failure_reason |
delivered and failed are terminal; stop polling once an order reaches one. If you poll,
every 30–60 seconds is plenty.
5. List your orders, or look up many at once
GET /v1/orders?status=pending
GET /v1/orders?since=1723900000
GET /v1/orders?limit=50
GET /v1/orders?ids=ORD-7K3M9Q,ORD-2B81FE → these orders only (max 100)
GET /v1/orders?buyer_ref=SHOP-10231,SHOP-10232 → by YOUR order ids (max 100)
since is a Unix timestamp. limit defaults to 100, max 500. Newest first. ids and
buyer_ref can be combined (and with status); an id that isn't yours or doesn't exist is
simply left out, never an error. This replaces one request per order when you reconcile.
6. Many orders in one call — POST /v1/orders/batch
{ "orders": [
{ "product_key": "topup/free-fire/brazil/100 Diamonds", "player_id": "512349871", "buyer_ref": "SHOP-10231" },
{ "product_key": "topup/free-fire/brazil/100 Diamonds", "player_id": "448120937", "buyer_ref": "SHOP-10232" } ] }
Up to 25 orders. Every order needs its own buyer_ref, unique inside the batch — that is
what makes re-sending the whole batch after a timeout safe (lines already placed come back as
existing, nothing is charged twice). The answer is always 200 when the request itself is
valid, with one result per line:
{ "results": [ { "index": 0, "buyer_ref": "SHOP-10231", "http_status": 201, "result": "created", "order": { … } },
{ "index": 1, "buyer_ref": "SHOP-10232", "http_status": 402, "result": "error",
"error": { "code": "insufficient_balance", "message": "…" } } ],
"summary": { "created": 1, "existing": 0, "failed": 1 }, "balance_usdt": "47.18" }
Lines succeed or fail on their own — one short of balance never cancels the others. Each line
counts against the 60-orders-per-minute limit. A malformed batch (more than 25, a line without a
buyer_ref, duplicate refs) is rejected whole with 422 and nothing is created.
7. Webhooks — we tell you when an order is done
Set your address in the dashboard (Profile → Webhook). It must be a public https:// address.
When an order becomes delivered or failed we POST it to you. Nothing is sent when an order is
created. Use Send test in the dashboard to check your endpoint.
Format: Standard Webhooks — official libraries exist for most
languages. Headers: webhook-id (the same on every retry — use it to ignore duplicates),
webhook-timestamp (unix seconds of this attempt), webhook-signature (v1,<base64 HMAC-SHA256>
over "{webhook-id}.{webhook-timestamp}.{raw body}", key = the base64 part of your whsec_…
secret). Reject anything older than ~5 minutes. Body:
{ "type": "order.delivered", "id": "evt_3f9c…", "created_at": "2026-10-01T10:22:31.5Z",
"data": { …the same JSON as GET /v1/orders/{order_id}… } }
Events: order.delivered, order.failed, webhook.test. Answer any 2xx within 10 seconds.
Anything else (or no answer) is retried after 1 min, 5 min, 30 min, 2 h and 6 h, then dropped —
the order itself is unaffected and GET /v1/orders/{id} always tells the truth, so keep a slow
reconciliation poll as a safety net. Redirects are not followed.
8. Test mode — try everything for free
Add "test": true to POST /v1/orders (or to a line of a batch). A test order costs nothing, is
never delivered by anyone, and sends no alert to us. It shows "test": true, and the price a real
order would have cost, then completes by itself after about 10 seconds as delivered with a
dummy code (TEST-… in delivery_note) — firing your webhook exactly like a real order. A test
order for a product we cannot price gets the same 422 unknown_product a live one would. Send a
player_id starting with fail and it ends as failed instead, so you can test that path too.
Test orders use their own space for buyer_ref: the same buyer_ref can be used for a test and
a live order without clashing. Don't start a live buyer_ref with test:.
Error responses
All errors — including validation errors — have the same shape:
{ "error": { "code": "invalid_api_key", "message": "Invalid or disabled API key" } }
| HTTP | Code | Meaning |
|---|---|---|
| 401 | missing_api_key |
No X-API-Key header sent |
| 401 | invalid_api_key |
Wrong key or disabled account |
| 403 | resellers_only |
The API is for reseller accounts — contact us to be upgraded |
| 404 | not_found |
Order does not exist (or belongs to another buyer) |
| 400 | invalid_status |
Bad status filter value |
| 422 | invalid_request |
Validation error — the message names the field |
| 422 | unknown_product |
No price found for that product — nothing was created. Use a product_key from GET /v1/products |
| 409 | out_of_stock |
That pack is out of stock right now — nothing was created or charged. Choose another pack or try again later |
| 400 | too_many |
More than 100 ids / buyer_ref in one lookup |
| 402 | insufficient_balance |
Balance below the price — nothing was created; load balance and retry with the same buyer_ref |
| 404 | not_found |
Also: unknown game on /v1/products |
| 429 | rate_limited |
More than 60 orders/min — wait Retry-After seconds and retry |
Conventions
- HTTPS only — plain HTTP is not served.
- No trailing slash — use
/v1/orders, not/v1/orders/(the latter 307-redirects, which some HTTP clients mishandle on POST). - Timestamps are ISO 8601 UTC with microseconds, always ending in
Z(2026-08-17T18:36:33.722773Z). Use a real ISO parser, not a fixed-length substring. - Rate limit is 60 order creations/min per key. Status reads are not limited. Order
responses carry
X-RateLimit-LimitandX-RateLimit-Remaining; a429carriesRetry-After(seconds). - Machine-readable spec:
GET https://api.rechargegame.games/openapi.json(the/v1API only) — import it into Postman or a code generator. - Set a ~20s timeout on requests and retry with the same
buyer_ref.
Security notes
- Call the API from your server, never from a browser. Browser requests are blocked by design (no CORS allowance) — anything in a browser exposes your key to your own customers. Keep it in an environment variable.
- Keep your API key secret. If it leaks, contact us immediately — we will rotate it.
- Your key scopes all lookups to your orders only. Requesting another buyer's order
returns
404, not403— you learn nothing about whether it exists.
Balance and deposits (prepaid wallet)
Every buyer has a prepaid USDT balance. Orders are charged when they are created; a failed order is refunded automatically.
Pricing an order
Add product_key to POST /v1/orders to be charged the catalog price at that moment:
"product_key": "topup/free-fire/brazil/100 Diamonds"
The key is <kind>/<category slug>/<region slug>/<product name> exactly as shown on the
public site (https://rechargegame.games/en/wholesale/free-fire/brazil). Without a
product_key, a free-text product + region that matches exactly one catalog line is
priced too; anything else is refused with 422 unknown_product — nothing is created.
Responses now include price_usdt and, when charged at creation, balance_after.
{ "error": { "code": "insufficient_balance", "message": "Balance 3.10 USDT is below the price 4.09 USDT — load balance first",
"price_usdt": "4.09", "balance_usdt": "3.10" } }
HTTP 402 — nothing was created; load balance and retry with the same buyer_ref.
Check the balance
GET /v1/balance
X-API-Key: gv_live_...
{ "balance_usdt": "121.41", "balance_micro": 121410000,
"ledger": [ { "at": 1789674209.1, "kind": "order_debit", "amount": "-4.09", "balance_after": "121.41", "ref": "ORD-7K3M9Q", "note": "Free Fire 520 Diamonds" } ] }
Load balance (USDT, BEP20 only)
- Create a deposit request — you get the exact amount to send (normally the amount you
asked for). The amount matches the money to your request; posting the hash in step 3
confirms it is yours.
POST /v1/deposits {"amount": 50}json { "intent_id": "DEP-1A2B3C", "status": "pending", "amount": "50.00", "requested": "50.00", "address": "0x13d578ec05da61fb6a795c4ffec13cefada48496", "network": "BEP20 (BNB Smart Chain)", "token": "USDT", "expires_at": 1789675409.0, "seconds_left": 1200 } - Send exactly
amountUSDT over BEP20 toaddresswithin 20 minutes. Do not round. Other tokens or networks cannot be recovered. - Wait — the chain is watched every 45 seconds; your balance is credited after about
20 block confirmations (under a minute). Or paste the hash to have it checked now:
POST /v1/deposits/DEP-1A2B3C/claim {"tx_hash": "0x…64 hex…"} GET /v1/deposits/DEP-1A2B3C→status:pending→credited.heldmeans the transfer arrived with a different amount and is being checked by hand;expiredmeans no transfer matched within the window (a late transfer is still matched for 30 more minutes).
Limits: min 5 USDT, max 5,000 per request, 5 requests per 10 minutes, 20 hash checks per 10 minutes.
The deposit page
Prefer not to integrate? Ask us on Telegram for your personal deposit link
(https://rechargegame.games/account/deposit?t=gv_dep_…). It shows your balance and recent
activity and walks through the same steps. The link is a deposit-only credential: it can
create and check deposits and read the balance, nothing else. Keep it private; ask us to
rotate it if it leaks. The same token links your Telegram account to the bot
(/start gv_dep_…) for /deposit, /hash and /balance.
The order page (no integration needed)
Don't want to build against the API at all? Ask us for your personal order link
(https://rechargegame.games/account/order?t=gv_ord_…). It's a page, not a chat: search the
catalog, pick a pack, enter the player ID, and it places the order and debits your balance
immediately — the same price and the same debit as POST /v1/orders, just without typing
into Telegram. Recent orders and their status show underneath.
This is a different, separate token from the deposit link — deliberately. The deposit link can only fund your balance; the order link can spend it. A leaked deposit link is harmless (worst case, someone deposits money for you); a leaked order link could place orders against your balance, so treat it like a password. Rotating one never invalidates the other. Ask us for either link, or both; we can issue a new one any time you need to rotate it.