61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
# 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.
|