# 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

1. `GET /v1/products` — see what you can order and what it costs you.
2. Your site `POST`s an order → we get an instant alert.
3. The order is created as `pending`, and you receive our `order_id`.
4. We fulfil it, then mark it `delivered` or `failed`.
5. 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:
```json
{ "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)
```

```json
{ "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=…&region=…` 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:
```json
{
  "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`:
```json
{
  "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`

```json
{ "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:

```json
{ "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](https://www.standardwebhooks.com) — 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:

```json
{ "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:

```json
{ "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-Limit` and `X-RateLimit-Remaining`; a `429` carries `Retry-After`
  (seconds).
- **Machine-readable spec:** `GET https://api.rechargegame.games/openapi.json` (the `/v1` API 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`, not `403` — 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`.

```json
{ "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_...
```
```json
{ "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)

1. **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 }
   ```
2. **Send exactly `amount`** USDT over BEP20 to `address` within 20 minutes. Do not round.
   Other tokens or networks cannot be recovered.
3. **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…"}
   ```
4. `GET /v1/deposits/DEP-1A2B3C` → `status`: `pending` → `credited`. `held` means the transfer
   arrived with a different amount and is being checked by hand; `expired` means 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.
