midtrans-gateway/DEVELOPER_GUIDE.md

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.