101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# 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.*
|