⚡ Qatch

Konversi Static QRIS menjadi Dynamic QRIS dengan verifikasi pembayaran secara real-time & zero payment gateway fees.

---

💡 Konsep

Normalnya, Static QRIS mengharuskan customer input nominal secara manual, dan merchant harus cek mutasi via aplikasi m-banking/e-wallet untuk memastikan dana masuk. Qatch solve masalah ini:

1. Mem-parsing string Static QRIS dan inject nominal transaksi untuk generate Dynamic QR Code.
2. Menggunakan Android Notification Forwarder untuk intercept incoming payment notification di HP merchant.
3. Mem-forward data notifikasi via HTTP POST ke endpoint webhook sistem ini.
4. Melakukan auto-verification pada payload dan update status transaksi menjadi PAID.

🚀 Fitur Utama

Fitur	Deskripsi
🔁 Dynamic QRIS Generator	Otomatis append nominal + kode unik ke base payload Static QRIS
📡 Real-time Webhook	Endpoint siap menerima POST request dari Android Notification Forwarder
🤖 Auto Verification	Parsing teks notifikasi untuk mencocokkan nominal & update status otomatis
🔑 API Key & HMAC	Autentikasi aman untuk semua akses API
🛡️ Webhook Filtering	Wildcard filter berdasarkan nama app, judul & isi notifikasi
📊 Analytics Dashboard	Chart penggunaan harian, statistik, dan log transaksi terbaru
👥 Multi-user & Roles	Manajemen user dengan role Superadmin dan User biasa
💰 Zero PG Fees	100% self-hosted, bebas biaya admin payment gateway

⚙️ Cara Kerja

Customer scan QR
      │
      ▼
[Qatch] Generate QR dengan nominal spesifik + kode unik
      │         misal: Rp 50.000 → Rp 50.021 (021 = kode unik harian)
      │
      ▼
Customer bayar via e-wallet / m-banking
      │
      ▼
Push notification masuk ke HP merchant
("Dana masuk: Rp 50.021 dari QRIS")
      │
      ▼
[Android Notification Forwarder] intercept & forward ke webhook
      │
      ▼
[Qatch] validasi nominal → status PENDING → PAID ✅

🗺️ API Endpoints

Semua endpoint membutuhkan header x-api-key untuk autentikasi.

Static QRIS

Method	Endpoint	Deskripsi
GET	/api/v1/static-qris	Daftar semua QRIS statis (paginasi)
POST	/api/v1/static-qris	Tambah QRIS statis baru
GET	/api/v1/static-qris/:id	Detail QRIS statis
PUT	/api/v1/static-qris/:id	Update QRIS statis
DELETE	/api/v1/static-qris/:id	Hapus QRIS statis

Dynamic QRIS

Method	Endpoint	Deskripsi
POST	/api/v1/dynamic-qris	Generate Qatch baru
GET	/api/v1/dynamic-qris/:id	Cek status transaksi
PUT	/api/v1/dynamic-qris/:id	Update status manual
POST	/api/v1/dynamic-qris/callback	Webhook untuk notifikasi pembayaran

Webhook Callback Payload

POST /api/v1/dynamic-qris/callback
x-api-key: YOUR_API_KEY

{
  "app_name": "Dana",
  "notification_title": "Dana Masuk",
  "notification_text": "Kamu menerima Rp 50.021 dari QRIS",
  "timestamp_ms": 1720432800000
}

🔧 Tech Stack

• AdonisJS v7 — Backend framework (API, Webhook, Auth)
• Inertia.js + Vue.js 3 — Full-stack SPA tanpa REST overhead
• shadcn/vue — UI Component library
• Chart.js — Visualisasi data dashboard
• Android Notification Forwarder — Notification interceptor di sisi Android

🛠️ Instalasi

Prerequisites

• Node.js >= 20
• NPM atau Yarn
• Database (SQLite untuk development, PostgreSQL/MySQL untuk production)

Langkah Instalasi

# 1. Clone repository
git clone https://github.com/karuhun-developer/qris-dinamis.git
cd qris-dinamis

# 2. Install dependencies
npm install

# 3. Copy file environment
cp .env.example .env

# 4. Generate app key
node ace generate:key

# 5. Jalankan migrasi database
node ace migration:run

# 6. (Opsional) Jalankan seeder
node ace db:seed

# 7. Start development server
npm run dev

⚙️ Konfigurasi Webhook

1. Install Android Notification Forwarder di HP merchant.
2. Login ke dashboard Qatch → menu Webhook & API.
3. Copy URL Webhook yang tersedia.
4. Paste URL tersebut ke konfigurasi Android Notification Forwarder.
5. Atur Listen Apps (contoh: Dana, Gopay, Shopeepay) dan Wildcard filter sesuai kebutuhan.
6. Setiap ada notifikasi pembayaran masuk, status transaksi akan otomatis ter-update.

📁 Struktur Project

├── app/
│   ├── controllers/
│   │   ├── api/v1/          # API Controllers (Static & Dynamic QRIS)
│   │   └── ...              # Web Controllers (Dashboard, Auth, dll)
│   ├── middleware/
│   │   └── api_key_middleware.ts  # Autentikasi via x-api-key
│   ├── models/              # Lucid ORM Models
│   └── services/            # Business logic (QRIS parsing, generation)
├── database/
│   └── migrations/          # Database schema migrations
├── inertia/
│   ├── pages/               # Vue.js pages (Dashboard, QRIS, Webhook, dll)
│   ├── components/          # Reusable Vue components
│   └── layouts/             # Layout templates
└── start/
    ├── routes.ts            # Route definitions
    └── kernel.ts            # Middleware registration

🙌 Inspired By

Project ini terinspirasi dari verssache/qris-dinamis.

📄 Lisensi

MIT License — bebas digunakan dan dimodifikasi.

---

Built with ❤️ by Karuhun Developer