11. Payment Gateways & Webhooks

Ringkasan

Aplikasi menyediakan integrasi siap pakai untuk Midtrans (Gateway Pembayaran Lokal Indonesia), Stripe (Gateway Kartu Kredit Global), dan Handler Webhook Lynk.id Payment, serta dilengkapi Simulator Transaksi Side-Drawer untuk pengujian cepat.

Cara Kerja

Kredensial gateway dan status mode (Sandbox vs Produksi) dikelola di IntegrationSettings.

mermaid

sequenceDiagram
    autonumber
    actor Customer
    participant Checkout as Form Pembayaran / Link Lynk.id
    participant PaymentAPI as tRPC paymentRouter / Lynk Webhook
    participant Gateway as Midtrans Snap / Stripe / Lynk.id API
    participant Webhook as Webhook Receiver (/api/webhooks/lynk)
    
    Customer->>Checkout: Selesaikan Pembayaran di Lynk.id / Gateway
    Gateway->>Webhook: Notifikasi Webhook Asinkron payment.received
    Webhook->>Webhook: Validasi Tanda Tangan SHA-256 (X-Lynk-Signature)
    Webhook->>Webhook: Catat Log Aktivitas di Audit Trail & Balas 200 OK

🔗 Integrasi Lynk.id Webhook (Link ID Setup)

Boilerplate ini mendukung penerimaan otomatis callback pembayaran dari Lynk.id berdasarkan spesifikasi API Lynk Webhook resmi.

1. Endpoint Target Webhook

Route Handler: /api/webhooks/lynk

Metode: POST

Content-Type: application/json

2. Rumus Validasi Tanda Tangan SHA-256

Untuk mencegah pemalsuan permintaan (*tampering*), Lynk.id mengirimkan header HTTP X-Lynk-Signature. Endpoint memverifikasi tanda tangan menggunakan SHA-256:

$$\text{signature} = \text{SHA256}(\text{grandTotal} + \text{refId} + \text{message\_id} + \text{secretKey})$$

Keterangan:

grandTotal: Total nominal transaksi (contoh: 75000)

refId: UUID referensi transaksi dari Lynk.id payload

message_id: String ID pesan unik

secretKey: Lynk.id Merchant Key / Secret Anda yang dikonfigurasi di Admin GUI

3. Skema Event Payload (`payment.received`)

Saat pelanggan membayar via Lynk.id, webhook memproses:

Informasi Transaksi: refId, grandTotal, totalItem, discount, createdAt

Informasi Pelanggan: name, email, phone

Rincian Produk: UUID item, judul, harga satuan, jumlah (qty), dan opsi add-on

Simulator Transaksi Side-Drawer

Boilerplate ini dilengkapi dengan Side-Drawer Simulator interaktif yang memungkinkan developer menguji:

Settlement / Sukses: Memicu notifikasi webhook transaksi berhasil.

Pending: Mensimulasikan status menunggu pembayaran.

Deny / Expire / Gagal: Mensimulasikan transaksi ditolak atau kadaluarsa.

Berkas Terkait

src/lib/lynk.ts — Helper validasi tanda tangan SHA-256 Lynk.id

src/app/api/webhooks/lynk/route.ts — Next.js Route Handler Webhook Lynk.id

src/app/api/webhooks/payment/route.ts — Webhook receiver umum

src/server/api/routers/payment.ts — Router transaksi pembayaran & simulator

src/app/(admin)/settings/integration/page.tsx — Panel GUI konfigurasi Payment Gateway & Lynk.id

Tabel Database Terkait

IntegrationSettings — Menyimpan lynkEnabled, lynkMerchantKey, lynkWebhookSecret, midtransServerKey, dan stripeSecretKey

AuditLog — Mencatat seluruh riwayat percobaan transaksi, penerimaan payload webhook, dan status validasi tanda tangan

Catatan & Petunjuk

NOTE

Salin URL Target Webhook Anda (https://domain-anda.com/api/webhooks/lynk) dari menu /settings/integration dan tempelkan ke Pengaturan Webhook Lynk.id Merchant Dashboard Anda untuk mengaktifkan pemrosesan pembayaran otomatis.

TIP

Gunakan tombol Test Lynk.id Signature Algorithm di menu /settings/integration untuk memverifikasi kalkulasi hash SHA-256 secara lokal tanpa harus melakukan transaksi sungguhan.