Gempay H2H API Documentation

1. Recommended integration flow

1. 01 Create a sandbox keyStore the username and one-time secret securely.
2. 02 Test authenticationCall the balance endpoint with a valid signature.
3. 03 Fetch the price listStore SKUs, role-based prices, availability, and destination field definitions.
4. 04 Test all three statesUse sandbox ref_id values that produce success, failed, and pending results.
5. 05 Configure callbacksVerify the raw-body HMAC and keep status polling as a fallback.
6. 06 Create a production keyFund your balance, restrict server IPs, and run a small transaction.

2. Connection, credentials, and authentication

sign = md5(username + secret + ref_id)

// Do not add colons, pipes, spaces, or newlines between values.
// Example hash source:
gmp_1234abcdYOUR_SECRETorder-20260802-0001

3. Client code examples

Keep credentials in server environment variables. The helper below works with every endpoint; add endpoint-specific fields through the final argument.

<?php

function gempayRequest(string $endpoint, string $refId, array $payload = []): array
{
    $baseUrl = getenv('GEMPAY_API_BASE_URL');
    $username = getenv('GEMPAY_API_USERNAME');
    $secret = getenv('GEMPAY_API_SECRET');
    $body = array_merge($payload, [
        'username' => $username,
        'ref_id' => $refId,
        'sign' => md5($username.$secret.$refId),
    ]);

    $curl = curl_init($baseUrl.'/'.$endpoint);
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 20,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
    ]);
    $raw = curl_exec($curl);
    if ($raw === false) throw new RuntimeException(curl_error($curl));

    return json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
}

$result = gempayRequest('balance', 'balance-20260802-0001');

import { createHash } from 'node:crypto';

async function gempayRequest(endpoint, refId, payload = {}) {
  const baseUrl = process.env.GEMPAY_API_BASE_URL;
  const username = process.env.GEMPAY_API_USERNAME;
  const secret = process.env.GEMPAY_API_SECRET;
  const sign = createHash('md5')
    .update(username + secret + refId, 'utf8')
    .digest('hex');

  const response = await fetch(`${baseUrl}/${endpoint}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...payload, username, ref_id: refId, sign }),
    signal: AbortSignal.timeout(20_000),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

curl --request POST 'https://www.genztopup.com/api/v1/balance' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "gmp_1234abcd",
    "ref_id": "balance-20260802-0001",
    "sign": "YOUR_MD5_RESULT"
  }'

4. Endpoint reference

{
  "username": "gmp_1234abcd",
  "ref_id": "balance-20260802-0001",
  "sign": "YOUR_MD5_RESULT"
}

{
  "username": "gmp_1234abcd",
  "ref_id": "pricelist-20260802-0001",
  "sign": "YOUR_MD5_RESULT"
}

{
  "data": {
    "price_list": [{
      "buyer_sku_code": "ml-86",
      "product_name": "Mobile Legends 86 Diamonds",
      "input_fields": [
        {"key":"user_id","type":"numeric","required":true,"min":5,"max":20,"options":[]},
        {"key":"zone_id","type":"numeric","required":true,"min":1,"max":10,"options":[]}
      ],
      "price": 21000,
      "buyer_product_status": true,
      "seller_product_status": true,
      "unlimited_stock": true,
      "stock": 0,
      "multi": true,
      "start_cut_off": null,
      "end_cut_off": null
    }],
    "rc": "00",
    "message": "Transaksi sukses"
  }
}

{
  "username": "gmp_1234abcd",
  "ref_id": "order-20260802-0001",
  "sign": "YOUR_MD5_RESULT",
  "buyer_sku_code": "ml-86",
  "tujuan": {"user_id": "123456789", "zone_id": "1234"}
}

{
  "username": "gmp_1234abcd",
  "ref_id": "ml-check-20260804-0001",
  "sign": "YOUR_MD5_RESULT",
  "user_id": "106101371",
  "zone_id": "2540"
}

5. Building destination fields correctly

Never guess or concatenate identifiers yourself. For each SKU, read input_fields from the price list and send a tujuan object with matching keys. The server validates and constructs the supplier destination.

"tujuan": {
  "customer_no": "081234567890"
}

"tujuan": {
  "user_id": "123456789",
  "zone_id": "1234"
}

"tujuan": {
  "user_id": "123456789",
  "server": "os_asia"
}

A select field lists valid values in options. Send numeric fields as strings to preserve leading zeroes. Never alter destination digits.

6. Responses and response codes

API payloads use a data envelope. Store at least ref_id, rc, status, price, and sn, plus a redacted raw response for reconciliation.

Public status values remain Sukses, Pending, or Gagal. Use rc as the primary decision field.

7. Timeout, retries, and idempotency

Idempotency is scoped per key. Replaying a transaction ref_id returns the first transaction without another order or debit. Poll pending transactions every 5 seconds initially, then slow to 10-30 seconds.

8. Testing with a sandbox key

Sandbox does not debit balance, create sales orders, or contact suppliers. Validation, response envelopes, idempotency, and callbacks follow the production contract.

A key's mode cannot change. After all branches pass, create a new production key and run a small smoke test.

9. Receiving and verifying callbacks

When a callback HTTPS URL is configured, Gempay sends POST application/json. Callbacks do not use the data envelope. Return HTTP 2xx quickly after verifying and storing the payload.

X-Gempay-Signature: HMAC_SHA256_HEX
Content-Type: application/json

{
  "ref_id": "order-20260802-0001",
  "status": "Sukses",
  "buyer_sku_code": "ml-86",
  "customer_no": "1234567891234",
  "price": 21000,
  "balance": 479000,
  "sn": "SN-123456789",
  "rc": "00",
  "message": "Transaksi sukses"
}

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_GEMPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $rawBody, getenv('GEMPAY_API_SECRET'));

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
// Upsert by ref_id, then return 200.

10. Mandatory security practices

11. Troubleshooting

12. Go-live checklist

This browser-only checklist is not saved. Use it before moving real traffic.