1. Home
  2. Reseller guides
  3. Connect your top-up website to a supplier order API

Connect your top-up website to a supplier order API

The order flow a reseller website needs — create, get notified by webhook, show status — with the idempotency and error handling that keep you from double-charging customers.

Published · 6 min read

Once a reseller has more than a few dozen orders a day, copying player IDs from chat into a supplier panel stops scaling. The fix is an order API: your website collects the player ID and payment, sends the order to the supplier automatically, and shows the customer a live status. This guide walks through the flow using the RechargeGames Order API; the pattern is the same for any supplier.

The flow in four steps

  1. Customer pays on your site. You now have a product, a player ID, a region, and your own order number.
  2. Your server creates the supplier order with one POST. You get back a supplier order_id and a status of pending.
  3. The supplier tells your server with a signed webhook the moment the order is delivered or failed. (Or your server polls the status every 30–60 seconds — both work.)
  4. Your site shows the customer “Processing → Delivered”, and on failure refunds them.

Nothing here happens in the browser. The API key lives on your server; a key in browser JavaScript is visible to every visitor.

Step 2 in detail: creating the order safely

Start from the supplier’s price list: GET /v1/products returns every pack at your price, each with a product_key. Send that key with the order and you are charged exactly the listed price — no surprises if you built your own price table a day ago.

The other field that matters most is buyer_ref — your own order number. Send it on every create. If your request times out and you retry, the supplier sees the same buyer_ref, returns the existing order, and does not fulfil twice. Without it, one flaky network moment can top up a player two times while you were paid once.

curl -X POST https://api.rechargegame.games/v1/orders \
  -H "X-API-Key: gv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Free Fire 100 Diamonds",
    "product_key": "topup/free-fire/brazil/100 Diamonds",
    "region": "Brazil",
    "player_id": "51234567",
    "buyer_ref": "SHOP-10231"
  }'

Treat both 201 (created) and 200 (already existed) as success. Set a 20-second timeout and retry the same request on network errors.

Put the region in the region field, not in the product name. It keeps the order readable on the supplier side and avoids “Free Fire 520 (BR)” being fulfilled for the wrong server.

Not ready to spend anything? Add "test": true to the order: nothing is charged or delivered, and it completes by itself after about ten seconds, so you can build and check the whole flow first.

Step 3 in detail: webhooks first, polling as the safety net

Set your webhook address once in the supplier dashboard. When an order becomes delivered or failed, the supplier POSTs the order to you, signed so you can check it really came from them. Answer with any 2xx within ten seconds; if you don’t, it is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Use the webhook-id header to ignore a repeat of an event you already handled.

A webhook can still be missed — your server may be down for a day. So keep a slow safety net: a job that checks your local “pending” orders every few minutes with GET /v1/orders/{order_id}. Status reads are not rate-limited, and the status there is always the truth. If you only poll, a sane interval is 30 seconds for the first ten minutes and 60 seconds after that. Stop when the status is delivered or failed — both are terminal.

If you run WordPress or a small PHP shop, a cron job every minute that scans your pending orders is enough. You do not need a queue system until you’re past a few thousand orders a day.

What to show the customer

Keep it to three states and map the API statuses to them:

API statusCustomer seesYour action
pending“Processing — usually under 20 minutes”Wait for the webhook
delivered“Delivered ✓” plus any delivery_note (a code, for code products)Mark paid & done
failed“Could not deliver — refunded” plus a friendly version of failure_reasonRefund the customer; the supplier has already refunded your balance

Show the supplier’s failure_reason only after rewording it. “Region mismatch” should become “This account is not on the Brazil server — please check the region and order again.”

Errors you will actually see

  • 422 invalid_request — your payload is missing a field or a value is too long. The message names the field. Fix your form validation; don’t retry.
  • 422 unknown_product — no price was found for that product, so 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. Show the customer another pack, or hide the pack until the price list shows it again.
  • 402 insufficient_balance — your balance is below the price. Load balance, then retry with the same buyer_ref.
  • 401 invalid_api_key — the key is wrong, disabled or rotated. Alert yourself; don’t retry in a loop.
  • 429 rate_limited — more than 60 order creations in a minute. Back off for a minute. If you hit this in normal operation, you have enough volume to ask for a higher limit.
  • Timeouts — retry with the same buyer_ref. That is exactly what idempotency is for.

A minimal implementation

In Python, the whole integration is two functions:

import os, requests

API = "https://api.rechargegame.games"
KEY = os.environ["GV_API_KEY"]

def create_order(product_key, product, player_id, region, buyer_ref):
    r = requests.post(f"{API}/v1/orders", timeout=20,
        headers={"X-API-Key": KEY},
        json={"product_key": product_key, "product": product,
              "player_id": player_id, "region": region,
              "buyer_ref": buyer_ref})
    r.raise_for_status()
    return r.json()["order_id"]

def status(order_id):
    r = requests.get(f"{API}/v1/orders/{order_id}", timeout=20,
        headers={"X-API-Key": KEY})
    r.raise_for_status()
    return r.json()

Node.js and PHP versions, the webhook format and every error code are on the API page and in the full documentation. To get a key: create a free account and request API access in your dashboard (Profile → API access). We approve it after a quick check; then you create and rotate your key yourself.

← All guides

Ready to start selling?

Open a free account and get wholesale prices from your first order. Questions? Our support team is on Telegram.