PaymentQu Hub v1.0 • Unified Payment Gateway HMAC-SHA256 Secured ⚡ Auto-Routing Ready

Dokumentasi API & Panduan Integrasi Pengembang

Solusi integrasi satu pintu (Unified API) untuk seluruh sistem transaksi internal dan mitra. Hub secara otomatis mengelola autentikasi, enkripsi signature B2B, dan perutean dinamis ke payment gateway upstream (Xendit, Eduloka, dll.) dengan payload yang seragam tanpa perlu mengubah kode aplikasi Anda.

Base API: https://paymenthub.daqu.id/api

Download Postman Collection

Alur Cepat Integrasi

4 Langkah Cepat Menghubungkan Aplikasi Anda

Estimasi waktu integrasi: ± 10 menit

Ambil Kredensial

Dapatkan Client Key & Client Secret dari menu API Keys di Portal.

Buat Transaksi

Panggil endpoint /virtual-account atau /qris dengan payload standar.

Pasang Webhook

Terima callback saat pelanggan lunas, verifikasi signature HMAC, dan balas dengan {"received":true}.

✓

Uji di Simulator

Gunakan Virtual Account Simulator di portal untuk simulasi pelunasan instan tanpa uang riil.

Bahasa Contoh:

1. Auto-Routing 2. Otentikasi 3. Virtual Account 4. QRIS Dinamis 5. Disbursement 6. Webhook 7. SDK Helper PHP 8. Kode Error

Konsep Arsitektur: Satu Payload Seragam & HUB Auto-Routing

Mekanisme orkestrasi perutean pembayaran otomatis tanpa vendor-lockin di sisi klien.

PaymentQu Hub menerapkan paradigma Unified Payment Interface. Sistem internal aplikasi tenant Anda tidak perlu repot membuat adaptor atau logika bercabang untuk setiap provider:

Diagram Alur Integrasi Hub

[ Aplikasi Mitra / Tenant ]  (Kirim format payload JSON standar)
          │
          │  POST /api/v1/payments/virtual-account (Header: X-Tenant-Key)
          ▼
┌────────────────────────────────────────────────────────┐
│                   PAYMENTQU HUB                        │
│  1. Verifikasi API Key & Signature Integritas           │
│  2. Deteksi Provider Aktif Tenant: [ XENDIT / EDULOKA ] │
│  3. Transformasi Payload & Penerusan Otomatis           │
└──────────────────────────────────┬─────────────────────┘
                                   │
              ┌────────────────────┴────────────────────┐
              ▼                                         ▼
   [ Gateway Xendit ]                         [ Gateway Eduloka ]
              │                                         │
              └────────────────────┬────────────────────┘
                                   │ (Callback Inbound)
                                   ▼
┌────────────────────────────────────────────────────────┐
│                   PAYMENTQU HUB                        │
│  • Normalisasi Notifikasi & Enkripsi Webhook Signature  │
│  • Pengiriman Idempoten dengan Exponential Retry (5x)   │
└──────────────────────────────────┬─────────────────────┘
                                   │
                                   ▼  POST https://mitra.com/api/callback
                    [ Webhook Endpoint Anda ]

📦 Satu Payload Seragam

Sistem internal mengirimkan format JSON yang sama persis tanpa parameter vendor apapun seperti "provider".

🔀 HUB Auto-Routing

HUB mendeteksi provider aktif tenant secara otomatis. Jika Super Admin mengganti provider upstream saat maintenance, kode tenant tetap berjalan normal 100%.

🛡️ Webhook Idempoten

Notifikasi pelunasan distandarisasi dengan tanda tangan HMAC-SHA256 dan retry otomatis 5 kali jika server Anda sedang offline atau overload.

Otentikasi & Pembuatan Request Signature

Mekanisme verifikasi identitas dan integritas payload setiap panggilan API.

Setiap permintaan ke API dilindungi oleh otentikasi API Key dan sangat disarankan menyertakan header signature integritas payload untuk mencegah manipulasi data di jaringan publik.

Headers Wajib & Rekomendasi

Nama Header	Status	Contoh Nilai	Deskripsi
X-Tenant-Key	Wajib	pq_live_edutech_demo_12345	Client key unik tenant Anda (bisa juga via `Authorization: Bearer ...`).
Content-Type	Wajib (POST)	application/json	Format body request.
X-Signature	Rekomendasi	HMAC-SHA256(RawBody, ClientSecret)	Signature integritas payload untuk mencegah tampering.

Formula Kalkulasi Signature HMAC-SHA256 di Berbagai Bahasa:

signature_generator

# Bash / Terminal (Menggunakan openssl) BODY='{"reference_id":"INV-001","amount":150000}' CLIENT_SECRET="pq_sec_edutech_secret_key_889900aabbcc" SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$CLIENT_SECRET" | sed 's/^.* //') echo "Signature: $SIGNATURE"

Virtual Account (Multi-Bank)

Penerbitan nomor Virtual Account otomatis untuk BCA, Mandiri, BNI, BRI, Permata, BSI, dll.

HUB Auto-Routed

GET /api/v1/payments/banks

Mendapatkan daftar bank aktif tenant

Gunakan endpoint ini untuk mengisi opsi dropdown rekening transfer di halaman checkout aplikasi Anda.

Request: List Bank

curl -X GET "https://paymenthub.daqu.id/api/v1/payments/banks" \ -H "X-Tenant-Key: pq_live_edutech_demo_12345"

POST /api/v1/payments/virtual-account

Menerbitkan nomor VA baru

Field	Tipe	Status	Deskripsi & Contoh
reference_id	string	Wajib	ID unik transaksi/invoice dari sistem Anda (misal: `INV-2026-1001`).
bank_code	string	Wajib	Kode bank tujuan. Contoh: `014` (BCA), `008` (Mandiri), `009` (BNI).
amount	number	Wajib	Nominal tagihan dalam Rupiah (min. 1000). Contoh: `150000`.
customer_name	string	Wajib	Nama pemilik tagihan yang akan muncul di layar ATM / M-Banking.
customer_email	string	Opsional	Email pelanggan untuk bukti notifikasi.
expires_in_minutes	number	Opsional	Masa berlaku VA dalam menit (default: 1440 / 24 jam).

Request Body

curl -X POST "https://paymenthub.daqu.id/api/v1/payments/virtual-account" \ -H "X-Tenant-Key: pq_live_edutech_demo_12345" \ -H "Content-Type: application/json" \ -d '{ "reference_id": "INV-2026-1001", "bank_code": "014", "amount": 150000, "customer_name": "Budi Santoso", "customer_email": "budi@example.com", "description": "Tagihan Kursus Online", "expires_in_minutes": 1440 }'

201 CREATED Response Data

{
  "success": true,
  "message": "Virtual account generated successfully.",
  "data": {
    "transaction_id": "9d9082bc-69cb-419b-bc24...",
    "reference_id": "INV-2026-1001",
    "payment_method": "VIRTUAL_ACCOUNT",
    "bank_code": "014",
    "bank_name": "BCA",
    "va_number": "88089912345678",
    "amount": 150000.0,
    "status": "UNPAID",
    "expires_at": "2026-10-12T10:00:00+07:00",
    "how_to_pay": [
      "Buka m-BCA atau ATM BCA",
      "Pilih menu Transfer > Virtual Account",
      "Masukkan nomor 88089912345678"
    ]
  }
}

GET /api/v1/payments/virtual-account/{referenceId}

Lakukan pengecekan status manual secara berkala jika webhook belum diterima atau saat pengguna menekan tombol "Cek Pembayaran".

QRIS Dinamis (Dynamic QR MPM)

Mendukung GoPay, OVO, ShopeePay, DANA, LinkAja, BCA Mobile, dan seluruh aplikasi QRIS nasional.

Semua e-Wallet & Bank

POST /api/v1/payments/qris

Generate QR code dinamis per invoice

Request Body

curl -X POST "https://paymenthub.daqu.id/api/v1/payments/qris" \ -H "X-Tenant-Key: pq_live_edutech_demo_12345" \ -H "Content-Type: application/json" \ -d '{ "reference_id": "ORDER-QR-001", "amount": 75000, "customer_name": "Dewi Sartika", "expires_in_minutes": 30 }'

201 CREATED Response QRIS

{
  "success": true,
  "data": {
    "transaction_id": "b1f893fa-3321-4d1a...",
    "reference_id": "ORDER-QR-001",
    "payment_method": "QRIS",
    "amount": 75000.0,
    "qr_content": "00020101021226600016ID.CO.QRIS...",
    "qr_image_url": "https://api.qrserver.com/v1/create-qr-code/...",
    "expires_at": "2026-10-11T21:15:00+07:00"
  }
}

Tips Render Tampilan QRIS di Frontend:

Anda dapat langsung menampilkan gambar QR dengan tag <img src="data.qr_image_url" alt="QRIS" />, atau merender string mentah data.qr_content memakai library QR canvas lokal seperti qrcode.js atau react-qr-code.

Transfer Dana / Disbursement Antar Bank

Inquiry nama pemilik rekening & payout dana otomatis secara realtime.

POST /v1/payments/disbursement/inquiry

Validasi nama pemilik rekening penerima sebelum mengirim uang untuk mencegah salah transfer.

{
  "partner_reference_no": "INQ-001",
  "bank_code": "014",
  "beneficiary_account_number": "1234567890",
  "amount": 250000
}

POST /v1/payments/disbursement

Eksekusi pencairan saldo / transfer dana langsung ke rekening bank tujuan.

{
  "reference_id": "PAYOUT-001",
  "bank_code": "014",
  "beneficiary_account_number": "1234567890",
  "beneficiary_name": "DR. AGUS SALIM",
  "amount": 250000,
  "remarks": "Honor Pengajar"
}

Integrasi Webhook (Notifikasi Pelunasan)

Menerima dan memproses status pelunasan transaksi secara asinkron dan terenkripsi.

Exponential Backoff Retry (5x)

Ketika pelanggan menyelesaikan pembayaran via ATM, M-Banking, atau e-Wallet, PaymentQu Hub secara otomatis mengirimkan panggilan HTTP POST ke Webhook URL server Anda.

Headers yang Dikirim ke Server Anda:

X-PaymentQu-Event: va.paid (atau qris.paid, disbursement.completed)

X-PaymentQu-Timestamp: 2026-10-11T21:15:20+07:00

X-PaymentQu-Signature: HMAC-SHA256(RawBody, WebhookSecret)

Format Payload Webhook (JSON):

Event: va.paid

{
  "event": "va.paid",
  "timestamp": "2026-10-11T21:15:20+07:00",
  "data": {
    "transaction_id": "9d9082bc-69cb-419b-bc24-8141bf1103c8",
    "reference_id": "INV-2026-1001",
    "payment_method": "VIRTUAL_ACCOUNT",
    "bank_code": "014",
    "va_number": "88089912345678",
    "amount": 150000.0,
    "net_amount": 147500.0,
    "status": "PAID",
    "paid_at": "2026-10-11T21:15:18+07:00"
  }
}

Verifikasi Keamanan Webhook Signature:

Webhook Verification Code

# Simulasi uji terima webhook via cURL curl -X POST "https://serveranda.com/api/payment/webhook" \ -H "Content-Type: application/json" \ -H "X-PaymentQu-Event: va.paid" \ -H "X-PaymentQu-Signature: EXPECTED_HMAC_SHA256" \ -d '{"event":"va.paid","data":{"reference_id":"INV-2026-1001","status":"PAID"}}'

Aturan Wajib Respon Webhook:

Endpoint server Anda WAJIB mengembalikan response HTTP 200 OK dengan JSON {"received": true} dalam kurun waktu < 5 detik. Jika respon timeout atau non-2xx, Hub otomatis menjadwalkan retry 5 kali (Percobaan ke-1: langsung, ke-2: 1 menit, ke-3: 5 menit, ke-4: 15 menit, ke-5: 1 jam).

Helper SDK Internal: `PaymentQuClient`

Integrasi instan 3 baris kode untuk aplikasi berbasis Laravel / PHP.

Untuk sistem internal berbasis Laravel, gunakan dependency injection class bawaan App\Support\PaymentQuClient. Class ini mengotomatiskan signing HMAC, penyusunan header autentikasi, serta normalisasi respon:

app/Http/Controllers/CheckoutController.php

use App\Support\PaymentQuClient;
use Illuminate\Http\Request;

class CheckoutController extends Controller
{
    // 1. Generate Virtual Account Instan
    public function checkout(PaymentQuClient $paymentQu)
    {
        $va = $paymentQu->createVirtualAccount([
            'reference_id' => 'INV-2026-1001',
            'bank_code'    => '014', // BCA
            'amount'       => 150000,
            'customer_name' => 'Budi Santoso',
        ]);

        // Ambil nomor VA: $va['data']['va_number'] => "88089912345678"
        return response()->json($va);
    }

    // 2. Handler Webhook Terverifikasi
    public function handleWebhook(Request $request, PaymentQuClient $paymentQu)
    {
        $isValid = $paymentQu->verifyWebhookSignature(
            $request->getContent(),
            $request->header('X-PaymentQu-Signature')
        );

        if (! $isValid) {
            return response()->json(['error' => 'Invalid signature'], 401);
        }

        // Eksekusi status pesanan ke PAID di database
        return response()->json(['received' => true]);
    }
}

Daftar Kode Error & Panduan Pemecahan Masalah

Kompilasi kode error standar beserta langkah penanganan cepat.

HTTP Status	Error Code	Penyebab Masalah	Solusi & Tindakan
401 Unauthorized	AUTH_MISSING_CREDENTIALS	Header `X-Tenant-Key` tidak disertakan.	Kirimkan header otentikasi di setiap request Anda.
401 Unauthorized	AUTH_INVALID_KEY	Client key salah atau status dinonaktifkan.	Periksa menu API Credentials di portal tenant Anda.
401 Unauthorized	AUTH_INVALID_SIGNATURE	Header `X-Signature` tidak cocok dengan body.	Hitung ulang hash HMAC-SHA256 menggunakan raw JSON string dan Client Secret yang tepat.
403 Forbidden	TENANT_INACTIVE	Akun tenant disuspend oleh Super Admin.	Hubungi pengelola PaymentQu Hub untuk mengaktifkan akun.
403 Forbidden	IP_NOT_ALLOWED	IP pemanggil tidak ada dalam IP Whitelist.	Daftarkan alamat IP publik server Anda di portal tenant.
422 Unprocessable	VALIDATION_FAILED	Parameter request tidak lengkap atau tidak valid.	Periksa key `errors` pada JSON respon untuk rincian field.
502 Bad Gateway	GATEWAY_ERROR	Upstream payment gateway menolak request.	Periksa deskripsi error provider upstream atau coba beberapa saat lagi.

Tersalin ke clipboard!