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:

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:

# Di sisi Gateway (.env)
ROUTER_CALLBACK_TOKEN=rahasia_token_anda_disini

Mekanisme Validasi:

Router Hub akan mengirim header x-callback-token.
Gateway akan mencocokkan header tersebut dengan ROUTER_CALLBACK_TOKEN.
Jika tidak cocok, Gateway akan menjawab 401 Unauthorized.

4. Alur Notifikasi & Validasi Berlapis

Gateway ini menerapkan Defense in Depth untuk notifikasi:

Handshake Token: Validasi header x-callback-token dari Router Hub.
Signature Verification: Memverifikasi signature_key Midtrans untuk memastikan data asli (bukan manipulasi Router atau pihak ketiga).
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:

Cek log di Router Hub untuk melihat apakah forwarding sukses.
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.

4.0 KiB Raw Permalink Blame History