# 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.