From 623daa19b98657e5afddbbff229778c67cc7365a Mon Sep 17 00:00:00 2001
From: "ravproject.dev" <ravialdo.dev@gmail.com>
Date: Tue, 24 Feb 2026 16:45:42 +0700
Subject: [PATCH] docs: Add technical integration guide for Midtrans Gateway
 and Router Hub.

---
 INTEGRASI_TEKNIS.md | 91 +++++++++++++++++++++++++++++++++++++++++++++
 models              |  2 +-
 2 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 INTEGRASI_TEKNIS.md

diff --git a/INTEGRASI_TEKNIS.md b/INTEGRASI_TEKNIS.md
new file mode 100644
index 0000000..9da9825
--- /dev/null
+++ b/INTEGRASI_TEKNIS.md
@@ -0,0 +1,91 @@
+# Panduan Integrasi Teknis: Midtrans Gateway & Router Hub
+
+Dokumen ini menjelaskan arsitektur **Hybrid Gateway** yang menghubungkan aplikasi Anda dengan Midtrans melalui lapisan **Midtrans Router Hub**.
+
+---
+
+## 1. Arsitektur Ecosystem
+
+Sistem ini tidak berdiri sendiri, melainkan menjadi bagian dari ekosistem routing notifikasi:
+
+```mermaid
+graph TD
+    M[Midtrans API] -- 1. Charge Request --> G[Midtrans Gateway]
+    M -- 2. Webhook Notification --> R[Midtrans Router Hub]
+    R -- 3. Forward with Token --> G
+    G -- 4. Update Database --> DB[(Payment DB)]
+```
+
+### Komponen Utama:
+*   **Midtrans Gateway** (Project ini): Menangani pembuatan transaksi (`charge`) dan penyimpanan data pembayaran.
+*   **Midtrans Router Hub**: Bertindak sebagai proxy notifikasi yang meneruskan callback dari Midtrans ke gateway yang tepat berdasarkan project ID.
+
+---
+
+## 2. Pemetaan ID (Mapping)
+
+Penting bagi developer client untuk memahami dua jenis ID yang digunakan:
+
+| ID Field | Tipe | Sumber | Kegunaan |
+| :--- | :--- | :--- | :--- |
+| **`order_id`** | UUID | Database Gateway | Internal Primary Key (digunakan untuk query join). |
+| **`external_id`** | String | Sistem Client | ID Invoice/Referens (misal: `INV-100`). Dikirim ke Midtrans. |
+
+> [!IMPORTANT]
+> Saat memanggil API Gateway, kedua ID ini wajib disertakan dalam payload untuk menjaga integritas data lintas sistem.
+
+---
+
+## 3. Konfigurasi Handshake (Security)
+
+Agar Gateway dapat menerima notifikasi dari **Router Hub**, Anda harus mengonfigurasi token keamanan di file `.env`:
+
+```env
+# Di sisi Gateway (.env)
+ROUTER_CALLBACK_TOKEN=rahasia_token_anda_disini
+```
+
+**Mekanisme Validasi:**
+1. Router Hub akan mengirim header `x-callback-token`.
+2. Gateway akan mencocokkan header tersebut dengan `ROUTER_CALLBACK_TOKEN`.
+3. Jika tidak cocok, Gateway akan menjawab `401 Unauthorized`.
+
+---
+
+## 4. Alur Notifikasi & Validasi Berlapis
+
+Gateway ini menerapkan **Defense in Depth** untuk notifikasi:
+
+1.  **Handshake Token**: Validasi header `x-callback-token` dari Router Hub.
+2.  **Signature Verification**: Memverifikasi `signature_key` Midtrans untuk memastikan data asli (bukan manipulasi Router atau pihak ketiga).
+3.  **Idempotency Check**: Jika status pesanan sudah `PAID` atau `FAILED`, proses update database akan di-*skip* secara otomatis.
+
+---
+
+## 5. API Endpoints
+
+Semua request menggunakan format JSON.
+
+### Pembuatan Transaksi (Manual Charge)
+*   **Bank Transfer**: `POST /api/v1/bank-transfer/:bank` (`bca`, `bni`, `bri`, `mandiri`)
+*   **E-Wallet**: `POST /api/v1/e-wallet/:provider` (`gopay`, `shopeepay`, `qris`)
+
+### Cek Status & Kontrol
+*   **Status Terakhir**: `GET /api/v1/transaction/status/:external_id`
+*   **Refund**: `POST /api/v1/transaction/refund` (Hanya untuk E-Wallet & CC)
+
+---
+
+## 6. Masalah Teknis (Gotchas)
+
+> [!WARNING]
+> **Limitasi Refund Virtual Account**
+> API Midtrans **TIDAK** mendukung refund otomatis untuk Bank Transfer (VA). Jika aplikasi Anda membutuhkan fitur refund VA, maka harus dilakukan secara manual melalui transfer bank dan status diupdate secara manual di database.
+
+### Troubleshooting Notifikasi
+Jika status tidak berubah di Gateway:
+1. Cek log di Router Hub untuk melihat apakah forwarding sukses.
+2. Pastikan `ROUTER_CALLBACK_TOKEN` di Gateway cocok dengan `Secret Key` project di Dashboard Router Hub.
+
+---
+*Dokumentasi ini dirancang agar developer dapat menghubungkan sistem dengan aman dan terarah dalam ekosistem Vibe Coding.*
diff --git a/models b/models
index db19e8c..7e490c9 160000
--- a/models
+++ b/models
@@ -1 +1 @@
-Subproject commit db19e8cdc93e3f651cd107737a53710cf9edfb9d
+Subproject commit 7e490c9f8bd33a3ee4a6a0067ee7ba775a1b8a0e