# Midtrans Gateway Developer Guide

Dokumen ini berisi informasi krusial yang harus dipahami oleh developer yang akan memelihara atau mengembangkan project ini di masa depan.

## 1. Arsitektur & Pemetaan ID
Project ini menggunakan pemetaan ID yang unik untuk menjembatani sistem internal dengan Midtrans.

- **`order_id` (UUID)**: Ini adalah Primary Key (UUID) dari tabel `trans_orders`. Digunakan sebagai referensi internal di database kita.
- **`external_id` (String)**: Ini adalah string unik (misal: `INV-123`) yang dikirimkan ke Midtrans sebagai `order_id` mereka.
- **PENTING**: Saat menerima Webhook/Callback dari Midtrans, kita mencari data berdasarkan `external_id` terlebih dahulu untuk menemukan UUID internalnya.

## 2. Environment Variables (.env)
Pastikan variabel berikut terkonfigurasi:
- `MIDTRANS_SERVER_KEY` & `MIDTRANS_CLIENT_KEY`: Kredensial dari dashboard Midtrans.
- `MIDTRANS_IS_PRODUCTION`: `false` untuk Sandbox, `true` untuk Production.
- `MIDTRANS_EXPIRY_DURATION` & `MIDTRANS_EXPIRY_UNIT`: Mengontrol waktu kadaluarsa transaksi.
- `DB_*`: Konfigurasi database untuk Sequelize.

## 2. Fitur Utama

### Penanganan Webhook (Idempotensi)
Logika di `NotificationService` sudah dilengkapi dengan pengecekan status:
- Jika status di database sudah `PAID` atau `FAILED` dan Webhook mengirimkan status yang sama, sistem akan **mengabaikan (skip)** proses update untuk menghindari beban database ganda.

### Kontrol Kadaluarsa (Expiration)
Waktu kadaluarsa diatur secara terpusat melalui file `.env`:
- `MIDTRANS_EXPIRY_DURATION`: Nilai angka (default: 1).
- `MIDTRANS_EXPIRY_UNIT`: Satuan waktu (`hour`, `minute`, `day`).
- Implementasi menggunakan `custom_expiry` (Core API) dan `expiry` (Snap API).

## 3. Batasan API Midtrans (Gotchas)

> [!WARNING]
> **Refund API Limitations**
> Fitur refund melalui API Midtrans memiliki batasan berdasarkan metode pembayaran:
> - **Mendukung Refund API**: Credit Card, GoPay, QRIS, ShopeePay.
> - **TIDAK Mendukung Refund API**: Bank Transfer (VA Mandiri, BCA, BNI, BRI, dll). Untuk VA, refund harus dilakukan secara manual melalui transfer langsung ke pelanggan. Jika dipaksakan via API, Anda akan mendapatkan error **412 Precondition Failed**.

## 4. Database & Migrasi
Project ini menggunakan **Sequelize ORM**.
- **`models/migration.js`**: File ini adalah kernel untuk me-load semua model database. Ia memiliki logika fallback untuk mencari file konfigurasi database di beberapa lokasi (`db.config.js` atau `app/config/database.js`).
- Semua model didefinisikan di folder root `models/`.

## 5. Menambah Metode Pembayaran Baru
Jika ingin menambah metode pembayaran baru (misal: Alfagift):
1. Buat folder baru di `app/modules/[nama-metode]`.
2. Implementasikan `Service` yang memanggil `midtransCore.getCoreApi().charge(parameter)`.
3. Gunakan `paymentLogger.log(response, payload)` setelah memanggil API untuk sinkronisasi database.
4. Daftarkan route baru di `index.js`.

## 6. Struktur Folder & Kode
- `app/core/`: Inisialisasi SDK Midtrans.
- `app/modules/`: Logika per modul pembayaran (Bank Transfer, E-Wallet, dll).
- `models/migration.js`: Loader model Sequelize.
- `helpers/response.helper.js`: Standarisasi format JSON response.

## 5. Tips Pengembangan
- Gunakan **Midtrans Sandbox** untuk testing.
- Selalu periksa `signature_key` di `NotificationService` untuk memastikan request Webhook benar-benar datang dari Midtrans.
- Jika melakukan cleanup kode, jangan hapus baris `require` di bagian atas file Controller/Service karena itu krusial untuk dependensi modul.