📖 Panduan & Contoh Integrasi API (PHP & JS)

<?php
/**
 * Contoh Pembuatan QRIS di PHP (cURL murni tanpa dependensi)
 */

$serverUrl = "https://pg.gscon.net"; // Ganti dengan URL Payment Hub Anda
$apiKey    = "mk_live_xxxxxxxxx";                // Ganti dengan X-API-KEY Toko Anda
$secretKey = "sk_live_xxxxxxxxx";                // Ganti dengan SECRET_KEY Toko Anda

// 1. Susun Data Pesanan
$orderData = [
    "partner_reference_no" => "ORD-" . time(), // Order ID unik toko Anda
    "amount"               => 50000,            // Nominal belanja (Rp 50.000)
    "customer_name"        => "Budi Santoso",
    "customer_phone"       => "08123456789",
    "customer_email"       => "[email protected]",
    "expired_minutes"      => 60,
    "fee_type"             => "CUSTOMER"        // "CUSTOMER" atau "MERCHANT"
];

$jsonBody = json_encode($orderData);

// 2. Format Timestamp ISO-8601 UTC
$timestamp = gmdate("Y-m-d\TH:i:s\Z");

// 3. Buat Signature HMAC-SHA256
$stringToSign = $timestamp . ":" . $jsonBody;
$signature = hash_hmac("sha256", $stringToSign, $secretKey);

// 4. Eksekusi Request cURL
$ch = curl_init("$serverUrl/api/v1/payment/qris");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "X-API-KEY: $apiKey",
        "X-SIGNATURE: $signature",
        "X-TIMESTAMP: $timestamp"
    ],
    CURLOPT_POSTFIELDS     => $jsonBody,
    CURLOPT_TIMEOUT        => 30
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 201 && isset($result['success']) && $result['success']) {
    $data = $result['data'];
    $invoiceRef  = $data['reference_no'];   // ID Invoice Gateway (GSN-xxx)
    $qrString    = $data['qr_content'];     // String EMVCo QRIS GS
    $qrImageUrl  = $data['qr_image_url'];   // URL Gambar QRIS Siap Render
    $qrDataUrl   = $data['qr_data_url'];    // Base64 Data Image
    $totalAmount = $data['total_amount'];   // Total Tagihan Pembeli

    echo "✅ QRIS Berhasil Dibuat!\n";
    echo "Invoice: $invoiceRef\n";
    echo "Total Bayar: Rp " . number_format($totalAmount, 0, ',', '.') . "\n";
    echo "URL Gambar QR: $qrImageUrl\n";
} else {
    echo "❌ Gagal Membuat QRIS: " . ($result['message'] ?? $response) . "\n";
}
?>

const axios = require('axios');
const crypto = require('crypto');

/**
 * Contoh Pembuatan QRIS di Node.js (Axios + Crypto)
 */
async function createQrisPayment() {
  const serverUrl = 'https://pg.gscon.net';
  const apiKey    = 'mk_live_xxxxxxxxx'; // X-API-KEY Toko Anda
  const secretKey = 'sk_live_xxxxxxxxx'; // SECRET_KEY Toko Anda

  // 1. Data Pesanan
  const orderData = {
    partner_reference_no: `ORD-${Date.now()}`,
    amount: 50000,
    customer_name: 'Budi Santoso',
    customer_phone: '08123456789',
    customer_email: '[email protected]',
    expired_minutes: 60,
    fee_type: 'CUSTOMER' // 'CUSTOMER' (beban pembeli) atau 'MERCHANT' (ditanggung toko)
  };

  const jsonBody = JSON.stringify(orderData);

  // 2. Timestamp ISO-8601 UTC
  const timestamp = new Date().toISOString();

  // 3. Signature HMAC-SHA256
  const stringToSign = `${timestamp}:${jsonBody}`;
  const signature = crypto.createHmac('sha256', secretKey).update(stringToSign).digest('hex');

  try {
    const response = await axios.post(`${serverUrl}/api/v1/payment/qris`, orderData, {
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': apiKey,
        'X-SIGNATURE': signature,
        'X-TIMESTAMP': timestamp
      },
      timeout: 15000
    });

    const { data } = response.data;
    console.log('✅ QRIS Berhasil Dibuat!');
    console.log('Invoice Ref :', data.reference_no);
    console.log('Total Bayar :', data.total_amount);
    console.log('QR Image URL:', data.qr_image_url);
    return data;
  } catch (error) {
    console.error('❌ Gagal Buat QRIS:', error.response?.data || error.message);
  }
}

createQrisPayment();

// Contoh Pemanggilan via Fetch API (Di Backend JS / Serverless Function)
async function requestQris() {
  const serverUrl = 'https://pg.gscon.net';
  const apiKey = 'mk_live_xxxxxxxxx';
  const secretKey = 'sk_live_xxxxxxxxx';

  const payload = {
    partner_reference_no: 'ORD-' + Date.now(),
    amount: 50000,
    customer_name: 'Budi Santoso',
    fee_type: 'CUSTOMER'
  };

  const jsonString = JSON.stringify(payload);
  const timestamp = new Date().toISOString();

  // Catatan: Pembuatan Signature HMAC disarankan dilakukan di backend server
  // agar SECRET_KEY tidak terekspos di browser client.
  const signature = await generateHmacSha256(timestamp + ':' + jsonString, secretKey);

  const res = await fetch(`${serverUrl}/api/v1/payment/qris`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': apiKey,
      'X-SIGNATURE': signature,
      'X-TIMESTAMP': timestamp
    },
    body: jsonString
  });

  const result = await res.json();
  if (result.success) {
    console.log('QRIS Ready:', result.data);
    // Tampilkan QR Code ke layar: result.data.qr_image_url
  }
}

<!-- Halaman Pembayaran Checkout (checkout.html / bayar.php) -->
<div style="text-align: center; max-width: 400px; margin: 40px auto; padding: 24px; border: 1px solid #ddd; border-radius: 16px; font-family: sans-serif;">
  <h3>Scan QRIS untuk Membayar</h3>
  <p style="color: #666; font-size: 14px;">Buka aplikasi GoPay, OVO, Dana, BCA, atau Mobile Banking Anda.</p>

  <!-- Gambar QRIS dari Payment Hub -->
  <div style="background: #fff; padding: 12px; display: inline-block; border-radius: 12px; margin: 16px 0;">
    <img id="qris-image" src="https://pg.gscon.net/api/v1/payment/render-qr/GSN-xxxxxx" alt="QRIS" width="220" height="220">
  </div>

  <h2 id="total-bayar" style="color: #10B981; margin: 0 0 8px;">Rp 50.850</h2>
  <div id="payment-status-badge" style="color: #F59E0B; font-weight: 600; font-size: 13px;">⏳ Menunggu Pembayaran...</div>
</div>

<script>
  const invoiceRef = "GSN-xxxxxx"; // Ganti dengan nomor invoice transaksi
  const serverUrl = "https://pg.gscon.net";

  // Auto-polling status transaksi setiap 3 detik
  const pollInterval = setInterval(async () => {
    try {
      const res = await fetch(`${serverUrl}/api/v1/payment/status/${invoiceRef}`);
      const json = await res.json();

      if (json.success && json.data.status === 'PAID') {
        clearInterval(pollInterval);
        document.getElementById('payment-status-badge').innerText = '✅ Pembayaran Berhasil!';
        document.getElementById('payment-status-badge').style.color = '#10B981';
        
        alert('🎉 Terima kasih! Pembayaran Anda telah diterima.');
        window.location.href = '/success.html'; // Redirect ke halaman sukses toko Anda
      }
    } catch (err) {
      console.error('Polling error:', err);
    }
  }, 3000);
</script>

<?php
/**
 * File: webhook.php (Ditaruh di server toko Anda, misal: https://tokoanda.com/webhook.php)
 */

$secretKey = "sk_live_xxxxxxxxx"; // Ganti dengan SECRET_KEY Toko Anda

// 1. Ambil Raw Payload JSON dan Headers
$rawPayload = file_get_contents('php://input');
$headers    = getallheaders();

$incomingTimestamp = $headers['X-TIMESTAMP'] ?? $headers['x-timestamp'] ?? '';
$incomingSignature = $headers['X-SIGNATURE'] ?? $headers['x-signature'] ?? '';

// 2. Hitung Expected Signature HMAC-SHA256
$stringToSign = $incomingTimestamp . ":" . $rawPayload;
$expectedSignature = hash_hmac('sha256', $stringToSign, $secretKey);

// 3. Verifikasi Keaslian Notifikasi
if (!hash_equals($expectedSignature, $incomingSignature)) {
    http_response_code(401);
    echo json_encode(["status" => "ERROR", "message" => "Invalid Signature"]);
    exit;
}

// 4. Decode Data Notifikasi
$data = json_decode($rawPayload, true);

if ($data && $data['event'] === 'PAYMENT_SUCCESS' && $data['status'] === 'PAID') {
    $orderId            = $data['partner_reference_no']; // ID Order toko Anda
    $invoiceRef         = $data['reference_no'];        // ID Invoice Gateway
    $amount             = $data['amount'];              // Nominal asli belanja
    $feeAmount          = $data['fee_amount'];          // Biaya fee gateway
    $feeChargedTo       = $data['fee_charged_to'];      // "CUSTOMER" atau "MERCHANT"
    $netAmount          = $data['net_amount'];          // Bersih yang diterima toko
    $paymentDate        = $data['payment_date'];

    // DATA IDENTITAS PEMBELI & KETERANGAN PESANAN
    $customerName       = $data['customer']['name'] ?? 'Pelanggan';
    $customerPhone      = $data['customer']['phone'] ?? '';
    $customerEmail      = $data['customer']['email'] ?? '';
    $customerKeterangan = $data['customer']['keterangan'] ?? '';

    // 5. UPDATE STATUS ORDER DI DATABASE TOKO ANDA
    // Contoh query database toko Anda:
    // mysqli_query($conn, "UPDATE orders SET status = 'PAID', note = '$customerKeterangan', payment_date = NOW() WHERE order_id = '$orderId'");

    // 6. Wajib Balas HTTP 200 OK ke Payment Hub
    http_response_code(200);
    echo json_encode([
        "status"      => "OK",
        "message"     => "Webhook processed successfully",
        "order_id"    => $orderId,
        "received_at" => date('Y-m-d H:i:s')
    ]);
    exit;
}

http_response_code(400);
echo json_encode(["status" => "IGNORED", "message" => "Event is not PAYMENT_SUCCESS"]);
?>

const express = require('express');
const crypto = require('crypto');
const app = express();

// Gunakan express.raw atau express.json
app.use(express.json());

const SECRET_KEY = 'sk_live_xxxxxxxxx'; // Ganti dengan SECRET_KEY Toko Anda

/**
 * Endpoint Receiver Webhook di Server Toko Anda
 * POST /api/payment-notification
 */
app.post('/api/payment-notification', async (req, res) => {
  try {
    const timestamp = req.headers['x-timestamp'];
    const incomingSignature = req.headers['x-signature'];
    const payload = req.body;

    // 1. Verifikasi Signature HMAC-SHA256
    const rawBody = JSON.stringify(payload);
    const stringToSign = `${timestamp}:${rawBody}`;
    const expectedSignature = crypto.createHmac('sha256', SECRET_KEY).update(stringToSign).digest('hex');

    if (incomingSignature !== expectedSignature) {
      console.warn('⚠️ Webhook ditolak: Signature tidak valid!');
      return res.status(401).json({ status: 'ERROR', message: 'Invalid Signature' });
    }

    // 2. Proses Notifikasi Pembayaran Sukses
    if (payload.event === 'PAYMENT_SUCCESS' && payload.status === 'PAID') {
      const orderId = payload.partner_reference_no;
      const invoiceRef = payload.reference_no;
      const netPayout = payload.net_amount;

      console.log(`✅ [Payment Received] Order ${orderId} LUNAS! Payout Bersih: Rp ${netPayout}`);

      // 3. Update Database Toko Anda disini:
      // await db.query("UPDATE orders SET status = 'PAID' WHERE order_id = ?", [orderId]);

      // 4. Balas HTTP 200 OK
      return res.status(200).json({
        status: 'OK',
        message: 'Payment notification received and processed',
        order_id: orderId
      });
    }

    return res.status(200).json({ status: 'IGNORED', message: 'Non-payment event' });
  } catch (error) {
    console.error('Webhook error:', error);
    return res.status(500).json({ status: 'ERROR', message: error.message });
  }
});

app.listen(8080, () => {
  console.log('Toko Webhook Server running on port 8080');
});