# Panduan Instalasi QRIS Payment Gateway

Sistem polling mutasi QRIS dari orderkuota.com dengan admin panel, multi-akun, dan fallback relay/proxy.

---

## Daftar Isi
- [Replit (Workspace)](#1-replit-workspace)
- [VPS (Ubuntu/Debian)](#2-vps-ubuntudebian)
- [cPanel (Shared Hosting)](#3-cpanel-shared-hosting)
- [Konfigurasi Environment](#konfigurasi-environment)
- [Relay PHP](#relay-php)
- [Endpoint API](#endpoint-api)
- [FAQ](#faq)

---

## 1. Replit (Workspace)

Cara tercepat, tidak perlu setup apapun.

### Langkah-langkah

1. **Fork / import project** ke Replit
2. Buka tab **Secrets** (ikon kunci di sidebar kiri)
3. Tambahkan secrets berikut:

   | Key | Value | Keterangan |
   |-----|-------|------------|
   | `RELAY_URL` | `https://domain-anda.com/relay.php` | URL relay di cPanel (opsional) |
   | `ADMIN_PASSWORD` | password pilihan anda | Password untuk `/admin.html` |

4. Klik **Run** — server otomatis jalan di port 5000
5. Akses admin panel: `https://nama-repl.replit.dev/admin.html`

### Catatan Replit
- Server jalan selama tab Replit terbuka (free tier)
- Untuk 24/7 gunakan **Replit Deployments** (berbayar) — klik tombol **Deploy**
- Cache tersimpan di folder `cache/` dan `accounts.json`

---

## 2. VPS (Ubuntu/Debian)

### Syarat
- Ubuntu 20.04+ atau Debian 11+
- Node.js 18+ 
- RAM minimal 512 MB

### Langkah-langkah

#### A. Install Node.js
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node --version  # pastikan v20.x
```

#### B. Upload / clone project
```bash
# Opsi 1: Clone dari git
git clone https://github.com/username/repo.git qris-gateway
cd qris-gateway

# Opsi 2: Upload manual via SCP
scp -r ./project/ user@ip:/home/user/qris-gateway/
cd /home/user/qris-gateway
```

#### C. Install dependencies
```bash
npm install
```

#### D. Buat file environment
```bash
nano .env
```
Isi dengan:
```
PORT=5000
RELAY_URL=https://domain-anda.com/relay.php
ADMIN_PASSWORD=password_rahasia_anda
```

#### E. Install dotenv (agar `.env` terbaca)
```bash
npm install dotenv
```
Tambahkan di baris pertama `server.js`:
```js
require('dotenv').config();
```

#### F. Jalankan dengan PM2 (auto-restart)
```bash
sudo npm install -g pm2
pm2 start server.js --name qris-gateway
pm2 startup       # jalankan perintah yang muncul
pm2 save
```

#### G. Cek status
```bash
pm2 status
pm2 logs qris-gateway
```

#### H. Nginx reverse proxy (opsional, untuk domain/SSL)
```bash
sudo apt install -y nginx certbot python3-certbot-nginx

sudo nano /etc/nginx/sites-available/qris
```
Isi:
```nginx
server {
    server_name domain-anda.com;
    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
    }
}
```
```bash
sudo ln -s /etc/nginx/sites-available/qris /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo certbot --nginx -d domain-anda.com  # SSL gratis
```

---

## 3. cPanel (Shared Hosting)

> cPanel biasanya tidak support Node.js langsung. Gunakan fitur **Node.js App** jika tersedia (Namecheap, Hostinger, dll).

### Syarat
- cPanel dengan fitur **Setup Node.js App**
- Node.js 18+ tersedia

### Langkah-langkah

#### A. Upload file project
1. Buka **File Manager** di cPanel
2. Masuk ke folder `home/username/` (bukan `public_html`)
3. Buat folder baru, misal `qris-gateway`
4. Upload semua file project (kecuali `node_modules/`)

#### B. Setup Node.js App
1. Buka **Setup Node.js App** di cPanel
2. Klik **Create Application**
3. Isi form:
   - **Node.js version**: pilih 18 atau 20
   - **Application mode**: Production
   - **Application root**: `qris-gateway` (folder yang tadi dibuat)
   - **Application URL**: subdomain atau path
   - **Application startup file**: `server.js`
4. Klik **Create**

#### C. Install dependencies
Di halaman Node.js App, klik **Run NPM Install** atau masuk via SSH:
```bash
cd ~/qris-gateway
npm install
```

#### D. Set environment variables
Di halaman Node.js App, scroll ke **Environment Variables**, tambahkan:
- `RELAY_URL` = `https://domain-anda.com/relay.php`
- `ADMIN_PASSWORD` = password pilihan anda

#### E. Start aplikasi
Klik tombol **Start** di halaman Node.js App.

#### F. Upload relay.php ke public_html
1. Salin file `relay.php` dari project
2. Upload ke `public_html/relay.php`
3. Set `RELAY_URL` di environment ke `https://domain-anda.com/relay.php`

---

## Konfigurasi Environment

| Variable | Default | Keterangan |
|----------|---------|------------|
| `PORT` | `5000` | Port server |
| `RELAY_URL` | _(kosong)_ | URL relay.php di hosting lain |
| `ADMIN_PASSWORD` | `admin` | **Wajib diganti!** Password admin panel |

---

## Relay PHP

File `relay.php` berfungsi sebagai perantara request ke orderkuota jika IP server diblokir.

### Upload ke cPanel
1. Buka **File Manager** → `public_html/`
2. Upload file `relay.php` dari project
3. Pastikan URL `https://domain.com/relay.php` bisa diakses publik

### Tes relay
```
https://domain.com/relay.php
```
Harus muncul: `{"error":"no body"}` atau response dari orderkuota.

---

## Endpoint API

| Endpoint | Method | Keterangan |
|----------|--------|------------|
| `/` | GET | Halaman login akun |
| `/admin.html` | GET | Admin panel |
| `/health` | GET | Status server |
| `/accounts` | GET | Daftar akun aktif |
| `/mutasi/:username` | GET | Data mutasi QRIS |
| `/check/:username?amount=NOMINAL` | GET | Cek pembayaran |
| `/auth/login` | POST | Login (kirim OTP) |
| `/auth/verify` | POST | Verifikasi OTP → simpan token |
| `/auth/token` | POST | Simpan token langsung |

### Parameter `/check`
| Parameter | Default | Keterangan |
|-----------|---------|------------|
| `amount` | — | Nominal (format: `50000`, `50.000`, atau `50,000`) |
| `window` | `3600` | Rentang waktu cek dalam detik (default 1 jam) |
| `ref` | — | Filter keterangan pembayaran (opsional) |

**Contoh:**
```
/check/tokosaya?amount=50000
/check/tokosaya?amount=50.000&window=300
/check/tokosaya?amount=150000&window=600&ref=ORDER123
```

**Response paid:**
```json
{
  "status": "paid",
  "transaction": {
    "nominal": 50000,
    "keterangan": "DANA / 08123*****",
    "tanggal": "07/06/2026 10:10:40",
    "brand": "DANA"
  }
}
```

**Response pending (dengan hint):**
```json
{
  "status": "pending",
  "hint": "Ada transaksi Rp50.000 pada 07/06/2026 08:00:00 tapi diluar window 3600s — coba tambahkan &window=86400"
}
```

---

## Strategi Polling

Atur di **Admin Panel → Pengaturan Polling**:

| Opsi | Nama | Cocok untuk |
|------|------|-------------|
| 0 | Paralel Serentak | Semua akun poll bersamaan (default) |
| 1 | Stagger | Jeda antar request, lebih natural ke server |
| 2 | Relay Per Akun | Setiap akun pakai relay berbeda |
| 3 | Proxy Per Akun | Distribusi proxy Indonesia per akun |
| 4 | Interval Panjang + Stagger | Poll jarang + jeda, paling aman |

### Smart Tier-Skip
- Setelah N kali direct diblokir berturut-turut → skip direct otomatis
- Setelah N kali relay gagal → skip relay otomatis
- Recovery: coba kembali setiap 5 menit secara otomatis
- Status realtime terlihat di **Admin Panel → tab Akun**

---

## FAQ

**Q: Muncul "469 Blocked" di log?**  
A: IP server diblokir oleh orderkuota. Aktifkan relay/proxy di Pengaturan Polling, atau upload `relay.php` ke cPanel.

**Q: Token tersimpan tapi tidak di-poll?**  
A: Token dari halaman publik butuh persetujuan admin. Buka `/admin.html` dan klik **Approve**.

**Q: `/check` selalu pending padahal ada transaksi?**  
A: Cek field `hint` di response — kemungkinan transaksi ada tapi di luar window waktu. Tambahkan `&window=86400` untuk window 24 jam.

**Q: Bagaimana menambah akun tanpa OTP?**  
A: Login ke admin panel → isi form **Tambah Akun** di bagian bawah tab Akun. Token langsung aktif tanpa perlu approve.

**Q: Data mutasi tidak update?**  
A: Cek log server. Jika semua tier gagal (direct+relay+proxy), berarti tidak ada jalur aktif yang berhasil.