Dokumentasi Self-Hosted

Arsitektur System Self-Hosted

Stack saquone menggunakan pola Open-Core: komponen penerjemah QRIS & listener berlisensi open-source, sedangkan core backend SaaS (matching engine & saldo) berjalan mandiri sebagai container terisolasi.

KLIEN GATEWAY GPL-3.0

Android Listener

Membaca notifikasi aplikasi bank (DANA, BRI, GoPay, Grab) di HP Android lalu mengirimkan payload bertanda tangan HMAC-SHA256.

CORE SERVER Go + Gin

Backend & Matching Engine

Mencocokkan nominal + window waktu transaksi pending di PostgreSQL. Mengubah status order jadi PAID secara instan.

INTEGRASI JSON Webhook

Sistem Kasir / POS Anda

Backend saquone mengirimkan webhook HTTP POST ke server kasir atau website e-commerce Anda saat pembayaran terverifikasi.

Prasyarat Minimum Server

Kebutuhan resource saquone sangat ringan karena dibangun dengan Go murni tanpa cold-start.

Spesifikasi VPS (Cloud Host)

OS: Ubuntu 22.04 LTS / 24.04 LTS atau Debian 12
CPU: 1 vCPU (sudah lebih dari cukup)
RAM: 1 GB RAM (penggunaan rata-rata < 150 MB)
Storage: 20 GB SSD
Rekomendasi: VPS Sumopod region Jakarta (~Rp60.000/bulan)

Perangkat Android Listener

OS Android: Android 7.0 (Nougat) atau lebih baru (SDK 24+)
Akses Izin: Notification Listener Access
Koneksi: Terhubung ke Wi-Fi / Paket Data stabil
Aplikasi Bank: DANA Bisnis, BRI Merchant, GoPay Merchant, atau Grab Merchant aktif

Pilih Mode Deploy

Sesuaikan mode instalasi dengan kebutuhan arsitektur sistem yang Anda bangun.

Full Stack (Backend + Postgres + Dashboard)

Rekomendasi Utama

Menjalankan seluruh layanan saquone: PostgreSQL database, Gin Go API server, dashboard web merchant, generator QRIS dinamis, dan matching engine konfirmasi otomatis.

Langkah-Langkah Deploy Docker Compose

Ikuti 3 langkah mudah berikut untuk menjalankan saquone di server Anda.

1 Buat File Konfigurasi Environment (`.env`)

Simpan file ini di direktori project server Anda (/opt/saquone/.env):

# ==========================================
# saquone Self-Hosted Environment (.env)
# ==========================================

# Port Backend & Mode
PORT=8085
APP_ENV=production

# Database PostgreSQL
BLUEPRINT_DB_HOST=postgres
BLUEPRINT_DB_PORT=5432
BLUEPRINT_DB_DATABASE=saquone
BLUEPRINT_DB_USERNAME=saquone_user
BLUEPRINT_DB_PASSWORD=GantiPasswordKuatAnda123!
BLUEPRINT_DB_SCHEMA=public

# Keamanan Auth & Webhook
JWT_SECRET=GantiDenganRandomSecretJWT_32KarakterAtauLebih
WEBHOOK_SECRET=GantiDenganRandomSecretHMAC_32KarakterAtauLebih

# Cloudflare R2 / S3 Object Storage (Opsional - Gambar QRIS)
# R2_ACCOUNT_ID=account_id_cloudflare
# R2_ACCESS_KEY_ID=access_key
# R2_SECRET_ACCESS_KEY=secret_key
# R2_BUCKET_NAME=saquone-qris

2 Buat File Orchestration (`docker-compose.yml`)

Simpan file ini bersandingan dengan file .env:

version: '3.8'

services:
  # Database PostgreSQL 16
  postgres:
    image: postgres:16-alpine
    container_name: saquone-db
    restart: always
    environment:
      POSTGRES_DB: saquone
      POSTGRES_USER: saquone_user
      POSTGRES_PASSWORD: GantiPasswordKuatAnda123!
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U saquone_user -d saquone"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Core API & Matching Engine Backend (Go)
  backend:
    image: ghcr.io/saquone/backend:latest
    container_name: saquone-backend
    restart: always
    ports:
      - "8085:8085"
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  pgdata:
    driver: local

3 Jalankan Service Stack

Jalankan perintah berikut di terminal VPS Anda untuk mengunduh image dan memulai container:

# Jalankan container di background
docker compose up -d

# Cek status log backend
docker compose logs -f backend

Tips Production SSL: Gunakan Cloudflare Tunnel (cloudflared) atau Nginx Reverse Proxy di depan port 8085 untuk mendapatkan sertifikat HTTPS/TLS otomatis tanpa perlu membuka port ke publik secara langsung.

Setup Android Notification Listener

Aplikasi Android open-source (android-notification-listener, GPL-3.0) bertugas meneruskan notifikasi pembayaran bank dari HP Anda ke backend saquone.

1.
Unduh APK Listener: Dapatkan APK terbaru dari repository resmi di GitHub Releases ↗.
2.
Aktifkan Akses Notifikasi: Buka aplikasi, ikuti panduan onboarding untuk memberikan izin Notification Listener Access di Pengaturan Android HP Anda.
3.
Isi URL Server & Secret: Masukkan URL endpoint backend Anda (https://api.domain-anda.com/notification) dan nilai WEBHOOK_SECRET yang Anda set di file .env.
4.
Optimasi Baterai HP: Matikan opsi Battery Saver / App Optimization untuk aplikasi Saquone Listener di HP Android Anda agar listener tidak dimatikan oleh OS saat HP standby.

Contoh Payload JSON yang Dikirim Listener ke Server:

{
  "package_name": "id.dana",
  "title": "DANA Bisnis",
  "text": "Anda menerima pembayaran sebesar Rp 50.000 dari Ahmad",
  "posted_at": 1787121291
}

Pertanyaan Umum (FAQ)

Apakah saquone memerlukan izin root di HP Android?

Tidak. Aplikasi listener hanya membutuhkan izin standar sistem Android yaitu Notification Listener Access (android.permission.BIND_NOTIFICATION_LISTENER_SERVICE). Tidak memerlukan root sama sekali.

Bagaimana cara menambah aplikasi bank / e-wallet baru?

Katalog gateway saquone bersifat config-driven (catalog/gateways.json). Anda cukup menambahkan pola regex notifikasi baru di katalog server tanpa perlu melakukan build ulang aplikasi Android APK.

Apakah gambar QRIS statis saya aman?

Ya, proses konversi QRIS statis ke dinamis hanya mengekstrak payload teks EMVCo dan mengganti nominal (tag 54) serta CRC16 (tag 63). Identitas merchant dan rekening tujuan Anda tidak pernah diubah.