Gateway API

Gateway API reference

The Gateway service is the reseller integration layer for top-ups, bill payments, refunds, and order lookups. All business endpoints use POST with JSON bodies that include client credentials.

Base URL: http://localhost:3105/api/v1 Open Swagger UI

Authentication

Every request must include api_key, timestamp, and signature in the JSON body. Credentials are validated on every call; there are no auth headers.

Field	Type	Required	Description
`api_key`	string	Yes	Shop API key issued by GamzTopup
`timestamp`	integer	Yes	Unix timestamp in seconds; must be within ±5 minutes of server time
`signature`	string	Yes	MD5 hex digest of `secret_key + timestamp` (no separator)

IP whitelist required. The caller IP must be registered in the shop's whitelist. An empty whitelist blocks all requests until IPs are configured in the reseller console.

const crypto = require('crypto');

const SECRET_KEY = process.env.GAMZ_SECRET_KEY;
const timestamp = Math.floor(Date.now() / 1000);
const signature = crypto
  .createHash('md5')
  .update(SECRET_KEY + timestamp)
  .digest('hex');

const body = {
  api_key: process.env.GAMZ_API_KEY,
  timestamp,
  signature,
  // ...endpoint-specific fields
};

const res = await fetch('{{BASE_URL}}/balance', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(body),
});
const json = await res.json();

Response format

Successful responses are wrapped in a uniform envelope. HTTP status codes reflect errors (401, 403, 404, 400, etc.) with the same JSON shape.

Success

{
  "status": "success",
  "message": "success",
  "data": { ... }
}

Error

{
  "status": "error",
  "data": null,
  "message": "Invalid credentials"
}

balance

POST{{BASE_URL}}/balance

Get wallet balance

Returns the authenticated shop wallet balance (available and held funds).

Request body

Send as application/json via POST to the endpoint above.

Field	Type	Required	Description
`api_key`	string	Yes	Shop API key issued by GamzTopup
`timestamp`	integer	Yes	Unix timestamp in seconds; must be within ±5 minutes of server time
`signature`	string	Yes	MD5 hex digest of `secret_key + timestamp` (no separator)

Example request

{
  "api_key": "ak_24276e47fb892460",
  "timestamp": 1783321239,
  "signature": "f7f4b12685a2a2b6bd18103fa4a24d27"
}

Response

Field	Type	Required	Description
`shop`	string	No	Shop code
`currency`	string	No	Wallet currency (e.g. THB)
`available`	number	No	Spendable balance
`held`	number	No	Funds reserved for in-flight orders

Example response

{
  "status": "success",
  "message": "success",
  "data": {
    "shop": "demo",
    "currency": "THB",
    "available": 50000,
    "held": 150
  }
}

POST{{BASE_URL}}/service

List provider services

Paginated catalog of enabled provider services (games, billers, top-up products).

Request body

Send as application/json via POST to the endpoint above.

Field	Type	Required	Description
`api_key`	string	Yes	Shop API key issued by GamzTopup
`timestamp`	integer	Yes	Unix timestamp in seconds; must be within ±5 minutes of server time
`signature`	string	Yes	MD5 hex digest of `secret_key + timestamp` (no separator)
`page`	integer	No	Page number (default 1, minimum 1)
`limit`	integer	No	Items per page (default 20, max 100)
`category`	enum	No	Filter by category: MTOPUP \| CASHCARD \| GTOPUP \| BILLPAY
`company_id`	string	No	Filter by company id, e.g. MLBB

Example request

{
  "api_key": "ak_24276e47fb892460",
  "timestamp": 1783321239,
  "signature": "f7f4b12685a2a2b6bd18103fa4a24d27",
  "category": "GTOPUP",
  "page": 1,
  "limit": 20
}

Response

Field	Type	Required	Description
`items`	array	No	List of provider services
`items[].category`	enum	No	MTOPUP \| CASHCARD \| GTOPUP \| BILLPAY
`items[].company_id`	string	No	Provider company / product code
`items[].company_name`	string	No	Display name
`items[].fee`	number	No	Service fee
`items[].minimum_amount`	number \| null	No	Minimum top-up amount
`items[].maximum_amount`	number \| null	No	Maximum top-up amount
`items[].refundable`	boolean \| null	No	Whether refunds are supported
`items[].denomination`	object \| null	No	Fixed denominations when applicable
`meta.page`	integer	No	Current page
`meta.limit`	integer	No	Page size
`meta.total`	integer	No	Total matching items
`meta.total_pages`	integer	No	Total pages

Example response

{
  "status": "success",
  "message": "success",
  "data": {
    "items": [
      {
        "category": "GTOPUP",
        "company_id": "MLBB",
        "company_name": "Mobile Legends",
        "fee": 0,
        "minimum_amount": 10,
        "maximum_amount": 10000,
        "refundable": false,
        "denomination": null
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}

orders

POST{{BASE_URL}}/orders/payment

Place payment / top-up

Charges the shop wallet and submits a top-up or bill payment to the upstream provider.

Request body

Send as application/json via POST to the endpoint above.

Field	Type	Required	Description
`api_key`	string	Yes	Shop API key issued by GamzTopup
`timestamp`	integer	Yes	Unix timestamp in seconds; must be within ±5 minutes of server time
`signature`	string	Yes	MD5 hex digest of `secret_key + timestamp` (no separator)
`provider`	enum	No	Upstream provider (default WEPAY)
`type`	enum	Yes	Payment type: billpay \| mtopup \| gtopup \| cashcard
`pay_to_company`	string	Yes	Provider company / product code (e.g. TRMV, MLBB)
`pay_to_ref1`	string	Yes	Phone number, bill account, or game id
`pay_to_amount`	number	Yes	Amount to charge (positive)
`pay_to_ref2`	string	No	Reference 2 — required by some billpay services
`pay_to_ref3`	string	No	Reference 3 — required by some billpay services
`pay_to_barcode1`	string	No	Barcode number for barcode-based bill payments
`dest_ref`	string	Yes	Your unique order reference (alphanumeric, max 20 chars)
`resp_url`	string	No	Result callback URL. Required unless the shop has a callback_url configured

Example request

{
  "api_key": "ak_24276e47fb892460",
  "timestamp": 1783321239,
  "signature": "f7f4b12685a2a2b6bd18103fa4a24d27",
  "type": "gtopup",
  "pay_to_company": "MLBB",
  "pay_to_ref1": "1234567890",
  "pay_to_amount": 100,
  "dest_ref": "ORD20260708001"
}

Response

Field	Type	Required	Description
`status`	enum	No	SUCCESS \| PENDING \| FAILED
`providerRef`	string	No	Provider transaction id when available
`errorCode`	string	No	Provider error code on failure
`errorMessage`	string	No	Human-readable error on failure
`raw`	object	No	Raw provider response payload

Example response

{
  "status": "success",
  "message": "success",
  "data": {
    "status": "PENDING",
    "providerRef": "987654321",
    "raw": {}
  }
}

POST{{BASE_URL}}/orders/refund

Refund order

Requests a refund from the provider for a previously placed order. Wallet is credited on success.

Request body

Send as application/json via POST to the endpoint above.

Field	Type	Required	Description
`api_key`	string	Yes	Shop API key issued by GamzTopup
`timestamp`	integer	Yes	Unix timestamp in seconds; must be within ±5 minutes of server time
`signature`	string	Yes	MD5 hex digest of `secret_key + timestamp` (no separator)
`provider`	enum	No	Upstream provider (default WEPAY)
`type`	enum	No	Original payment type: billpay \| mtopup \| gtopup \| cashcard
`transaction_id`	string	Yes	Provider transaction id returned when the order was placed
`dest_ref`	string	Yes	Order reference used when the order was placed (alphanumeric, max 20 chars)
`pay_to_company`	string	Yes	Provider company code used in the original payment
`new_msisdn`	string	No	New phone number for services that transfer credit to a new number
`resp_url`	string	No	Result callback URL. Required unless the shop has a callback_url configured

Example request

{
  "api_key": "ak_24276e47fb892460",
  "timestamp": 1783321239,
  "signature": "f7f4b12685a2a2b6bd18103fa4a24d27",
  "transaction_id": "987654321",
  "dest_ref": "ORD20260708001",
  "pay_to_company": "MLBB"
}

Response

Field	Type	Required	Description
`status`	enum	No	SUCCESS \| PENDING \| FAILED
`providerRef`	string	No	Provider refund reference when available
`errorCode`	string	No	Provider error code on failure
`errorMessage`	string	No	Human-readable error on failure
`raw`	object	No	Raw provider response payload

Example response

{
  "status": "success",
  "message": "success",
  "data": {
    "status": "SUCCESS",
    "providerRef": "REF123456",
    "raw": {}
  }
}

POST{{BASE_URL}}/orders/status

Get order status

Looks up a single order by your dest_ref reference.

Request body

Send as application/json via POST to the endpoint above.

Field	Type	Required	Description
`api_key`	string	Yes	Shop API key issued by GamzTopup
`timestamp`	integer	Yes	Unix timestamp in seconds; must be within ±5 minutes of server time
`signature`	string	Yes	MD5 hex digest of `secret_key + timestamp` (no separator)
`dest_ref`	string	Yes	Order reference used when the order was placed

Example request

{
  "api_key": "ak_24276e47fb892460",
  "timestamp": 1783321239,
  "signature": "f7f4b12685a2a2b6bd18103fa4a24d27",
  "dest_ref": "ORD20260708001"
}

Response

Field	Type	Required	Description
`dest_ref`	string	No	Your order reference
`type`	string	No	Payment type (lowercase)
`pay_to_company`	string	No	Provider company code
`target`	string	No	Phone / account / game id
`status`	enum	No	PENDING \| SENT \| SUCCESS \| FAILED \| REFUNDED \| CANCELLED
`amount`	number	No	Order amount
`currency`	string	No	Currency code
`transaction_id`	string \| null	No	Provider transaction id
`message`	string \| null	No	Result message from provider
`failure_reason`	string \| null	No	Failure reason when status is FAILED
`created_at`	string	No	ISO 8601 creation timestamp
`completed_at`	string \| null	No	ISO 8601 completion timestamp

Example response

{
  "status": "success",
  "message": "success",
  "data": {
    "dest_ref": "ORD20260708001",
    "type": "gtopup",
    "pay_to_company": "MLBB",
    "target": "1234567890",
    "status": "SUCCESS",
    "amount": 100,
    "currency": "THB",
    "transaction_id": "987654321",
    "message": null,
    "failure_reason": null,
    "created_at": "2026-07-08T02:30:00.000Z",
    "completed_at": "2026-07-08T02:30:05.000Z"
  }
}

POST{{BASE_URL}}/orders/history

Order history

Paginated list of orders for the authenticated shop with optional filters.

Request body

Send as application/json via POST to the endpoint above.

Field	Type	Required	Description
`api_key`	string	Yes	Shop API key issued by GamzTopup
`timestamp`	integer	Yes	Unix timestamp in seconds; must be within ±5 minutes of server time
`signature`	string	Yes	MD5 hex digest of `secret_key + timestamp` (no separator)
`page`	integer	No	Page number (default 1, minimum 1)
`limit`	integer	No	Items per page (default 20, max 100)
`status`	enum	No	Filter by status: PENDING \| SENT \| SUCCESS \| FAILED \| REFUNDED \| CANCELLED
`dest_ref`	string	No	Filter by your order reference
`date_from`	string	No	Orders created at or after (ISO 8601 date)
`date_to`	string	No	Orders created at or before (ISO 8601 date)

Example request

{
  "api_key": "ak_24276e47fb892460",
  "timestamp": 1783321239,
  "signature": "f7f4b12685a2a2b6bd18103fa4a24d27",
  "status": "SUCCESS",
  "page": 1,
  "limit": 20,
  "date_from": "2026-07-01",
  "date_to": "2026-07-31"
}

Response

Field	Type	Required	Description
`items`	array	No	Order records (same shape as order status response)
`meta`	object	No	Pagination metadata (page, limit, total, total_pages)

Example response

{
  "status": "success",
  "message": "success",
  "data": {
    "items": [
      {
        "dest_ref": "ORD20260708001",
        "type": "gtopup",
        "pay_to_company": "MLBB",
        "target": "1234567890",
        "status": "SUCCESS",
        "amount": 100,
        "currency": "THB",
        "transaction_id": "987654321",
        "message": null,
        "failure_reason": null,
        "created_at": "2026-07-08T02:30:00.000Z",
        "completed_at": "2026-07-08T02:30:05.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}

webhooks

POST{resp_url}

Order result callback

When the upstream provider confirms an async payment or refund, GamzTopup relays the result to the resp_url you supplied on /orders/payment or /orders/refund (or your shop callback_url when resp_url is omitted). Only final statuses are delivered, best-effort with no retry — poll orders/status if you never receive one.

Callback payload

Posted to your resp_url as application/x-www-form-urlencoded.

Field	Type	Required	Description
`dest_ref`	string	Yes	Your order reference, as sent when the payment or refund was placed
`transaction_id`	string	No	Provider transaction id
`status`	integer	Yes	Result code — 2 means success, anything else is a failure
`sms`	string	No	Human-readable result message
`operator_trxnsid`	string	No	Upstream operator transaction id, when available

Example request

dest_ref=ORD20260708001&transaction_id=987654321&status=2&sms=Top-up+successful&operator_trxnsid=OP1234567

Your response

Return HTTP 200 to acknowledge. The response body isn't read.

GamzTopup Gateway API

Authentication

Response format

balance

Get wallet balance

Request body

Response

List provider services

Request body

Response

orders

Place payment / top-up

Request body

Response

Refund order

Request body

Response

Get order status

Request body

Response

Order history

Request body

Response

webhooks

Order result callback

Callback payload

Your response