Midtrans Middleware (CIFO)

Vite + React frontend dan Express backend untuk integrasi pembayaran Midtrans (Core API + Snap) dengan sistem ERP.

Struktur Project

server/     Express backend (single-file: server/index.cjs)
src/        Frontend React (checkout, halaman /pay, dashboard demo)
postman/    Postman collection — seluruh endpoint API
tests/      Script testing manual untuk backend
scripts/    Utility script (mis. fetch-logos.mjs)

Setup

1. Duplikasi file contoh env dan isi nilainya:

cp .env.example .env

Isi .env sesuai kebutuhan — lihat .env.example untuk daftar lengkap variabel beserta penjelasannya (Midtrans key, EXTERNAL_API_KEY, PAYMENT_LINK_SECRET, LOG_BASIC_AUTH_USER/PASS, dll). Generate secret yang kuat dengan:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

2. Install dependencies:

npm install

3. Jalankan backend dan frontend (dua terminal terpisah):

npm run server   # backend Express, default http://localhost:8000
npm run dev      # frontend Vite, default http://localhost:5173

API Backend

Dokumentasi lengkap seluruh endpoint ada di dua tempat:

• Interaktif (Scalar) — buka http://localhost:8000/docs di browser (dilindungi HTTP Basic Auth, kredensial sama dengan /api/logs*, lihat LOG_BASIC_AUTH_USER/LOG_BASIC_AUTH_PASS). Spec mentah tersedia di /openapi.json.
• Postman — import postman/Midtrans-Middleware.postman_collection.json, sudah berisi seluruh route (payment link, charge, snap token, webhook, logs, dev/test endpoints) dikelompokkan per folder.

Detail arsitektur & alur pembayaran ada di server/README.md.

Alat Bantu Operasional

• Log viewer — http://localhost:8000/api/logs/view (dilindungi Basic Auth). Bisa filter per level, cari teks/order_id, dan klik nilai apa pun untuk trace lintas baris log yang berkaitan. Log otomatis dihapus setelah LOG_RETENTION_DAYS (default 30 hari).
• Payment link dibuat lewat POST /api/payment-links (payload langsung order_id/nominal/customer/expire_at) atau POST /createtransaksi (payload ERP mercant_id/item[]).

Catatan Integrasi Midtrans

• Client Key hanya digunakan di frontend (mis. tokenisasi kartu/3DS, Snap.js). Server Key tidak pernah dikirim ke frontend.
• Order pembayaran punya dua alur: (1) link yang dibagikan ke pelanggan (dibuat lewat /createtransaksi atau /api/payment-links, di-resolve oleh halaman /pay/:token), dan (2) checkout langsung dari browser (/api/payments/charge, /api/payments/snap/token) tanpa pra-registrasi — keduanya diberi rate limit untuk mencegah abuse.
• order_id yang mengandung karakter selain alfanumerik/- _ ~ . (mis. :) otomatis disanitasi jadi . sebelum dikirim ke Midtrans.
• Status real-time dapat diimplementasikan via polling (TanStack Query) atau webhook (POST /api/payments/notification) yang meneruskan notifikasi ke ERP.

Struktur Env di Kode Frontend

Akses env melalui modul src/lib/env.ts:

• Env.API_BASE_URL
• Env.MIDTRANS_CLIENT_KEY
• Env.MIDTRANS_ENV

Lisensi

Internal project — CIFO Group.