Reseller API documentation

The SHOP2TOPUP reseller API is a JSON REST API for selling game top-ups, game recharges and voucher codes from your own shop, storefront or bot. This reference documents every public endpoint, its parameters and its responses.

Base URL and transport

Every path in this reference is relative to the base URL below. Requests and responses are JSON over HTTPS, amounts are strings so no float rounding can creep in, and every timestamp is UTC in ISO 8601.

https://shop2topup.com/api/endpoints/v1

Authentication

Every request carries one header. The key pair is issued from the API Access page of your reseller panel and can be restricted to an IP allowlist; a call from any other address is rejected with IP_NOT_ALLOWED before it reaches any business logic.

Request header

Authorization: Bearer <keyId>.<secret>

A first call

Nothing to install. Swap in your own key and this returns live catalog data.

Request - cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Response conventions

Every response carries a boolean success field, so one branch separates the happy path from every failure.
Failures return an error object with a stable code, a human message and optional details. Branch on the code, never on the message.
Money is always a decimal string such as "0.950000" in USD. Do not parse it into a binary float before you compare or sum it.
List endpoints return a pagination object with page, limit, total and total_pages.
Order creation is idempotent on the order_id UUID you supply, so a retry can never charge twice.

Error response

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

Reference sections

CatalogThe catalog is a three-level tree: big categories hold categories, categories hold subcategories, and a subcategory is the item you actually buy. These endpoints let you mirror that tree into your own database and price an item immediately before you order it.Player validationPlayer validation resolves an in-game account before any money moves. It confirms the identifier exists for that product, returns the in-game name so your buyer can check it, and surfaces the region so a cross-region order is rejected early instead of failing after payment.OrdersOrders are created with a UUID you generate. That UUID is the idempotency key: replaying it returns the original order instead of charging twice. Status is then read back per order, in batches of up to fifty, or as a paginated list.Account & authEvery request carries one header. GET /account is the endpoint you call to prove a key works, read the wallet balance your orders draw from, and confirm the account is enabled before you start a batch run.Error codesEvery failure returns a stable machine-readable code alongside the HTTP status. Branch on the code, never on the message text: messages are written for humans and may be reworded, while codes are part of the contract.

Rate limits

Limits are per account on a rolling window. The catalog, order and account endpoints carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a throttled call answers 429 with a Retry-After header. Player validation is metered by your daily player-check quota instead: it sends no X-RateLimit headers and reports the quota inside the 429 body.

Route	Requests	Window	Counted per
GET /catalog/* (all five)	5000	60s	per account
POST /orders/create	5000	60s	per account
GET /orders/:orderId	3	60s	per account + order id
POST /orders/batch	2	60s	per account
GET /orders	2	60s	per account
GET /account	60	60s	per account
POST /player/validate	daily player-check quota	24h	per account (no X-RateLimit headers)

Webhooks

Order outcomes are pushed to an HTTPS endpoint you register, signed with HMAC-SHA256 over the raw body. The event list, header list, payload shape and a verification snippet are documented on the API overview page.

Read the webhook payload and signature reference

New to the platform? Start with the game top-up API overview for resellers, or read the SHOP2TOPUP reseller programme overview for how the partner account works.