73 lines
3.1 KiB
Markdown
73 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
|
|
```
|
|
|
|
2) Install dependencies:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3) Jalankan backend dan frontend (dua terminal terpisah):
|
|
|
|
```bash
|
|
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`](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.
|