Dokumentasi API H2H Gempay

1. Alur integrasi yang disarankan

1. 01 Buat key sandbox Simpan username dan secret yang hanya ditampilkan sekali.
2. 02 Uji autentikasi Panggil endpoint balance dengan signature yang benar.
3. 03 Ambil price-list Simpan SKU, harga role, status produk, dan definisi field tujuan.
4. 04 Uji tiga status Gunakan ref_id sandbox untuk hasil sukses, gagal, dan pending.
5. 05 Pasang callback Verifikasi HMAC dari raw body dan tetap sediakan polling status.
6. 06 Buat key produksi Isi saldo, batasi IP server, lalu lakukan transaksi nominal kecil.

2. Koneksi, kredensial, dan autentikasi

sign = md5(username + secret + ref_id)

// Tidak memakai titik dua, pipe, spasi, atau newline di antara nilai.
// Contoh sumber hash:
gmp_1234abcdSECRET_ANDAorder-20260802-0001

3. Contoh kode klien

Simpan kredensial di environment variable server. Fungsi berikut dapat dipakai untuk semua endpoint; payload khusus endpoint ditambahkan pada argumen terakhir.

<?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');
$rc = $result['data']['rc'];

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();
}

const result = await gempayRequest('balance', 'balance-20260802-0001');
console.log(result.data.rc, result.data.balance);

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

4. Referensi endpoint

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

{
  "data": {
    "username": "gmp_1234abcd",
    "balance": 500000,
    "rc": "00",
    "message": "Transaksi sukses"
  }
}

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

{
  "data": {
    "username": "gmp_1234abcd",
    "price_list": [{
      "buyer_sku_code": "ml-86",
      "product_name": "Mobile Legends 86 Diamonds",
      "category": "Mobile Legends",
      "supplier": "digiflazz",
      "input_fields": [
        {"key":"user_id","label":"User ID","type":"numeric","required":true,"min":5,"max":20,"options":[]},
        {"key":"zone_id","label":"Zone ID","type":"numeric","required":true,"min":1,"max":10,"options":[]}
      ],
      "customer_no_format": null,
      "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": "HASIL_MD5",
  "buyer_sku_code": "ml-86",
  "tujuan": {
    "user_id": "123456789",
    "zone_id": "1234"
  }
}

{
  "data": {
    "ref_id": "order-20260802-0001",
    "status": "Pending",
    "buyer_sku_code": "ml-86",
    "customer_no": "1234567891234",
    "price": 21000,
    "balance": 479000,
    "sn": null,
    "created_at": "2026-08-02T13:30:00+07:00",
    "rc": "03",
    "message": "Transaksi pending"
  }
}

{
  "username": "gmp_1234abcd",
  "ref_id": "order-20260802-0001",
  "sign": "HASIL_MD5_UNTUK_REF_ID_YANG_SAMA"
}

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

5. Membentuk field tujuan dengan benar

Jangan menebak atau menggabungkan ID sendiri. Untuk setiap SKU, baca input_fields dari price-list lalu kirim object tujuan dengan key yang sama. Server yang akan memvalidasi dan menyusun nomor tujuan supplier.

Aturan ini juga berlaku untuk produk Foxygamestore. Produk Foxy memakai SKU publik berawalan FX-, tetapi bentuk tujuan tetap selalu mengikuti input_fields yang dikembalikan price-list.

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

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

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

Field bertipe select mempunyai daftar nilai sah pada properti options. Field numeric tetap dikirim sebagai string agar nol di depan tidak hilang. Jangan mengubah digit tujuan.

6. Membaca respons dan response code

Semua payload API dibungkus oleh object data. Simpan minimal ref_id, rc, status, price, sn, dan respons mentah yang sudah Anda redaksi untuk kebutuhan rekonsiliasi.

Nilai status publik adalah Sukses, Pending, atau Gagal. Gunakan rc sebagai keputusan utama karena pesannya dapat berubah untuk memberi konteks supplier.

7. Timeout, retry, dan idempotensi

Idempotensi berlaku per key: request transaction dengan ref_id yang sama akan mengembalikan transaksi pertama dan tidak membuat order atau debit kedua. Untuk status pending, polling awal setiap 5 detik lalu perlambat menjadi 10–30 detik. Callback mempercepat pembaruan, tetapi endpoint status tetap menjadi sumber pemulihan.

8. Menguji dengan key sandbox

Sandbox tidak mendebit saldo, tidak membuat order penjualan, dan tidak menghubungi supplier. Produk, harga role, validasi tujuan, response envelope, idempotensi, dan callback tetap mengikuti bentuk produksi.

Mode melekat pada key dan tidak dapat diubah. Setelah semua cabang lolos, buat key produksi baru dan ulangi smoke test dengan nominal kecil.

9. Menerima dan memverifikasi callback

Jika callback HTTPS diatur pada key, server mengirim POST application/json ketika hasil tersedia. Callback tidak memakai envelope data. Balas status HTTP 2xx secepat mungkin setelah signature valid dan payload tersimpan.

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",
  "created_at": "2026-08-02T13:30:00+07:00",
  "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 berdasarkan ref_id, lalu balas 200.

import crypto from 'node:crypto';

app.post('/gempay/callback',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const received = req.get('X-Gempay-Signature') ?? '';
    const expected = crypto
      .createHmac('sha256', process.env.GEMPAY_API_SECRET)
      .update(req.body)
      .digest('hex');

    const valid = received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
    if (!valid) return res.sendStatus(401);

    const payload = JSON.parse(req.body.toString('utf8'));
    // Upsert berdasarkan ref_id.
    return res.sendStatus(200);
  }
);

10. Praktik keamanan wajib

11. Troubleshooting

12. Checklist sebelum go-live

Checklist ini berjalan di browser dan tidak disimpan. Gunakan sebagai pemeriksaan sebelum memindahkan traffic nyata.