# 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 (UUID). |
| **`external_id`** | String | Sistem Client | ID Invoice/Referens (misal: `INV-100`). |
| **`PROJECT_ID`** | String | Env Gateway | Suffix unik (misal: `proj_1768277934546`). |

### Mekanisme Suffix Order ID
Gateway ini secara otomatis menggabungkan `external_id` dan `PROJECT_ID` saat mengirim data ke Midtrans.
*   **Contoh:** Jika `external_id` adalah `INV-1001` dan `PROJECT_ID` adalah `proj_123`, maka ID yang terdaftar di Midtrans adalah `INV-1001-proj_123`.

> [!TIP]
> **Mengapa menggunakan Suffix?**
> Suffix ini sangat krusial bagi **Midtrans Router Hub**. Ketika Router menerima notifikasi dari Midtrans, ia akan membaca bagian akhir dari `order_id` untuk menentukan ke gateway mana notifikasi tersebut harus diteruskan.

> [!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.*