Panduan Instalasi

Langkah memasang QRIS Gateway v1.2.0 di server kamu sendiri, dari upload file sampai gateway siap menerima pembayaran. Setelah selesai, lihat Dokumentasi API untuk menghubungkan toko atau aplikasi kamu.

Sebelum mulai

Gateway ini memakai API ShopeePay Partner Portal yang tidak resmi.

  • Gateway membaca riwayat transaksi akun merchant ShopeePay kamu memakai token sesi Partner Portal, bukan lewat API pembayaran resmi ShopeePay.
  • Shopee bisa membatasi, menangguhkan, atau menutup akun merchant yang dipakai dengan cara ini. Risiko itu sepenuhnya ada pada pemilik akun.
  • Token sesi bisa berakhir kapan saja (misalnya setelah logout dari portal). Token tidak bisa diperbarui otomatis; gateway memberi tanda di panel admin dan kamu perlu menempel token baru.
  • Shopee bisa mengubah API portal kapan saja tanpa pemberitahuan, sehingga gateway berhenti mendeteksi pembayaran sampai ada pembaruan.
  • Selalu cek mutasi di aplikasi ShopeePay Merchant untuk transaksi bernilai besar, dan jangan pakai gateway ini sebagai satu-satunya pencatatan keuangan.

Siapkan juga: license key dari penjual, akses login ke ShopeePay Partner Portal dari komputer (untuk mengambil token), dan string QRIS statis toko kamu. Satu license berlaku untuk satu domain.

Kebutuhan server

  • PHP 8.3 atau lebih baru (CLI dan web memakai versi yang sama).
  • Ekstensi PHP: pdo_mysql, mbstring, openssl, tokenizer, xml, ctype, fileinfo, curl, dan zip. Wizard memeriksanya otomatis.
  • Database MySQL atau MariaDB.
  • HTTPS dengan sertifikat valid di domain yang dilisensikan.
  • Cron job yang bisa diatur dari panel hosting (menu Cron Jobs). SSH dan queue worker tidak wajib.
  • Akses keluar (outbound HTTPS) ke shopeepay.shopee.co.id dan panel.jowtech.my.id.
  • Jam server tersinkron NTP. Request ke server license ditandatangani dengan timestamp, jadi jam yang meleset bisa membuat validasi license ditolak.

1. Upload file

Upload qris-gateway-shopeepay-v1.2.0.zip lewat File Manager panel hosting, lalu ekstrak. Folder vendor dan aset public/build sudah disertakan, jadi tidak perlu Composer atau Node.js.

DirectAdmin / cPanel (document root public_html)

Pindahkan isi folder qris-gateway-shopeepay hasil ekstrak langsung ke public_html, sehingga public_html/.htaccess, public_html/artisan, dan public_html/public/ berada sejajar. File .htaccess bawaan meneruskan semua request ke public/ dan memblokir akses ke .env, vendor/, storage/, dan file aplikasi lainnya. Di VPS, arahkan document root web server ke folder public/.

  • File yang namanya diawali titik (.htaccess, .env.example) bisa tersembunyi di File Manager. Aktifkan "tampilkan file tersembunyi" dan pastikan keduanya ikut dipindahkan.
  • Mod mod_rewrite harus aktif (default di DirectAdmin dan cPanel).
  • Setelah instalasi, buka https://domain-kamu.com/.env. Hasilnya harus 403 Forbidden. Kalau isinya terlihat, berarti .htaccess tidak terbaca dan aplikasi belum aman dipakai.

2. Buat database

Di panel hosting, buka MySQL Management (DirectAdmin) atau MySQL Databases (cPanel). Buat satu database dan satu user, lalu beri user itu semua hak akses (ALL PRIVILEGES) ke database tersebut. Catat nama database, nama user, dan password-nya. Tabel tidak perlu dibuat sendiri.

3. Wizard instalasi

Buka domain kamu di browser. Pada kunjungan pertama, aplikasi membuat file .env sendiri lengkap dengan APP_KEY dan APP_URL dari domain yang dibuka, lalu mengarahkan ke wizard. Wizard bisa dilanjutkan kapan saja kalau halamannya tertutup.

  1. Kode instalasi — buka File Manager, buka file KODE-INSTALASI.txt di folder aplikasi, lalu salin kodenya (misalnya AB12-CD34) ke halaman instalasi. Kode ini mencegah orang lain mengambil alih instalasi sebelum kamu, dan file-nya terhapus otomatis setelah selesai. Cukup dimasukkan sekali.
  2. Database — wizard memeriksa versi PHP, ekstensi, dan izin folder. Isi host (biasanya localhost), port 3306, nama database, user, dan password. Wizard mengetes koneksi, membuat tabel, lalu menyimpan pengaturannya ke .env.
  3. Lisensi — masukkan license key. Domain dari APP_URL langsung diaktifkan di server license.
  4. Akun admin — buat akun untuk masuk ke panel /admin.
  5. ShopeePay — seret tombol Salin token ShopeePay dari wizard ke bookmark bar browser, login ke ShopeePay Partner Portal di komputer, buka menu Transaksi, lalu klik bookmark itu. Token tersalin otomatis; tempel di wizard dan token dicek dulu ke ShopeePay sebelum disimpan. Cara manual lewat DevTools tetap tersedia di wizard.
  6. QRIS statis — pilih gambar QRIS outlet kamu, dan isinya terbaca otomatis di browser. Lihat cara mendapatkan QRIS statis.
  7. Selesai — wizard menampilkan perintah cron (lihat langkah 4) dan memberi tahu apakah cron sudah berjalan. Setelah itu API key dibuat dan ditampilkan sekali saja. Simpan baik-baik; kalau hilang, buat yang baru di /admin/settings.

Setelah wizard selesai, halaman /install tidak bisa dibuka lagi. Semua pengaturan berikutnya ada di panel /admin: dashboard, daftar pembayaran, pembayaran terlambat, token ShopeePay, pengaturan, dan license.

Jangan pernah mengganti APP_KEY setelah instalasi: license key, QRIS, API key, dan token ShopeePay disimpan terenkripsi dengan kunci ini.

4. Cron job

Wajib. Cron menjalankan scheduler setiap menit: mengecek pembayaran masuk tiap 30 detik (payments:check), membersihkan data lama (payments:prune), memvalidasi license tiap jam (license:check), dan menjalankan antrean webhook serta pembaruan. Tanpa cron, tagihan tidak akan pernah jadi paid.

Buka menu Cron Jobs di panel hosting, buat cron baru dengan jadwal setiap menit (* * * * *), lalu isi perintahnya. Path folder yang benar ditampilkan di langkah terakhir wizard.

Perintah cron
cd /home/user/domains/domain-kamu.com/public_html && php artisan schedule:run >> /dev/null 2>&1

Kalau cron tidak jalan dengan php, pakai path lengkap PHP dari panel hosting, misalnya /usr/local/bin/php atau /opt/alt/php82/usr/bin/php, dan pastikan versinya sama dengan PHP situs.

Instalasi lewat SSH / VPS (opsional)

Kalau lebih suka terminal, langkah wizard database bisa diganti dengan mengisi .env sendiri. Wizard otomatis melewati langkah database kalau DB_DATABASE sudah terisi.

VariabelIsi
APP_URLHarus domain yang dilisensikan, lengkap dengan https. License dicek terhadap host dari APP_URL, bukan dari alamat yang sedang dibuka.
APP_KEYIsi dengan php artisan key:generate, sekali saja.
APP_ENV / APP_DEBUGproduction / false. Debug aktif di server publik bisa membocorkan rahasia di halaman error.
DB_*Koneksi MySQL/MariaDB.
SESSION_DRIVER / CACHE_STOREdatabase setelah database siap (wizard mengubahnya otomatis).
TRUSTED_PROXIESKosongkan kalau pengunjung terhubung langsung. Di belakang Cloudflare isi cloudflare; untuk reverse proxy lain isi alamat IP atau rentangnya, dipisah koma. Tanpa ini semua pengunjung terlihat memakai IP proxy dan berbagi satu batas rate limit.
Contoh di server
cd /var/www/qris-gateway-shopeepay
cp .env.example .env
php artisan key:generate
# isi APP_URL, DB_*, SESSION_DRIVER=database, CACHE_STORE=database di .env
php artisan migrate --force
chmod -R ug+rw storage bootstrap/cache
.env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://pay.toko-kamu.com
APP_TIMEZONE=Asia/Jakarta

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=qris_gateway
DB_USERNAME=qris
DB_PASSWORD=password-database

SESSION_DRIVER=database
CACHE_STORE=database

Di VPS atau Docker, antrean bisa dijalankan oleh queue worker permanen di bawah Supervisor. Kalau begitu, set QUEUE_WORK_IN_SCHEDULER=false supaya cron tidak ikut menjalankan antrean.

/etc/supervisor/conf.d/qris-gateway-shopeepay.conf
[program:qris-gateway-shopeepay-worker]
command=php /var/www/qris-gateway-shopeepay/artisan queue:work --sleep=3 --tries=3 --max-time=3600
user=www-data
autostart=true
autorestart=true
stopwaitsecs=60
redirect_stderr=true
stdout_logfile=/var/www/qris-gateway-shopeepay/storage/logs/worker.log

License key, QRIS statis, dan API key tidak diisi di .env, melainkan lewat wizard. Baris LICENSE_API_SECRET juga tidak perlu ada.

Cara mendapatkan QRIS statis

QRIS statis adalah QRIS outlet yang biasa dipajang di kasir dan bisa dibayar dengan nominal bebas. Gateway menyalin data merchant dari QRIS ini, lalu menambahkan nominal unik untuk setiap tagihan.

  1. Buka aplikasi ShopeePay Merchant (atau Partner Portal) dengan akun yang sama seperti token yang dihubungkan, lalu buka menu QRIS toko dan simpan/unduh gambar QRIS-nya. Screenshot layar QRIS juga bisa.
  2. Atau foto stiker/standee QRIS outlet dari depan, tidak buram, dan seluruh kotak QR terlihat.
  3. Di langkah QRIS statis (atau di /admin/settings), pilih gambar itu. Browser membaca kodenya dan mengisi kolom teks. Gambarnya tidak diupload ke server.
  4. Kalau gambar tidak terbaca, scan QRIS dengan aplikasi pemindai QR mana pun, salin teks hasilnya (diawali 000201), lalu tempel ke kolom teks.

Jangan pakai QRIS dari struk atau tagihan yang sudah berisi nominal (QRIS dinamis); gateway akan menolaknya. Pastikan QRIS-nya milik toko yang sama dengan akun ShopeePay yang dihubungkan, karena pembayaran hanya terdeteksi di akun itu.

Perintah berguna

PerintahFungsi
php artisan license:checkCek status license sekarang juga.
php artisan shopeepay:tokenGanti token ShopeePay dari terminal (alternatif dari /admin/shopeepay).
php artisan shopeepay:checkCek apakah token ShopeePay masih diterima.
php artisan admin:createBuat akun admin baru, mis. kalau lupa password.
php artisan payments:lateTampilkan pembayaran yang masuk setelah tagihannya expired.
php artisan license:deactivateLepas domain ini dari license.
php artisan app:updatePasang versi terbaru, dengan backup dan rollback otomatis. Tambahkan --check untuk hanya mengecek.
php artisan license:diagnoseCek koneksi dan tanda tangan request ke server lisensi.

Memperbarui ke versi baru

Gateway mengecek versi terbaru ke server lisensi. Kalau ada versi baru, dashboard admin menampilkan pemberitahuan, dan pembaruan bisa dipasang dengan satu tombol.

  1. Buka /admin/updates, baca catatan perubahannya, lalu klik Perbarui ke versi ….
  2. Gateway mengunduh paket resmi (link unduhan hanya diberikan untuk license yang aktif di domain ini), memeriksa isinya, membuat backup otomatis, mengaktifkan mode pemeliharaan sebentar, memasang file baru, menjalankan migrasi database, lalu kembali online.
  3. Kalau ada langkah yang gagal, misalnya migrasi database error, gateway otomatis mengembalikan versi sebelumnya dari backup dan menampilkan alasannya di halaman yang sama.

Pembaruan dari panel dijalankan di latar belakang oleh cron (atau queue worker), jadi mulai dalam satu menit setelah tombol diklik. Lewat SSH, pembaruan juga bisa dijalankan langsung:

Pembaruan lewat SSH
php artisan app:update --check   # hanya cek versi terbaru
php artisan app:update           # pasang versi terbaru
  • Yang tidak pernah diubah oleh pembaruan: .env, folder storage/, database, dan favicon situs. Pengaturan, token ShopeePay, dan data tagihan tetap aman. Folder vendor/ disamakan persis dengan versi baru.
  • Backup tiga versi terakhir disimpan di storage/app/updates/backups (kode aplikasi, plus salinan database kalau memakai SQLite). Untuk MySQL, migrasi yang gagal dibatalkan otomatis; tetap disarankan membuat backup database lewat panel hosting sebelum memperbarui.
  • Folder aplikasi harus bisa ditulis oleh user PHP. Di DirectAdmin/cPanel ini sudah terpenuhi kalau file diupload dengan akun hosting yang sama.
  • Versi baru bisa membutuhkan PHP yang lebih baru. Halaman pembaruan memberi tahu kalau versi PHP server belum cukup, dan tombol pembaruan disembunyikan.
  • Kalau situs tertahan di mode pemeliharaan, misalnya karena server mati di tengah pembaruan, jalankan php artisan up, lalu ulangi pembaruan.

Pembaruan manual tetap bisa: ekstrak zip versi baru dan timpa semua file kecuali .env dan storage/, hapus dulu folder vendor/ lama, lalu jalankan php artisan migrate --force.

Masalah umum

PesanSolusi
Database belum disiapkanDB_DATABASE sudah diisi di .env tapi tabelnya belum ada. Jalankan php artisan migrate --force, atau kosongkan DB_DATABASE supaya wizard menampilkan langkah database lagi.
Folder aplikasi belum bisa ditulisLewat File Manager, ubah izin folder aplikasi menjadi 755 serta storage dan bootstrap/cache menjadi 775, lalu muat ulang.
Cron belum terdeteksiPeriksa perintah cron di panel hosting: path folder harus sama persis, jadwal * * * * *, dan versi PHP cron sama dengan PHP situs.
APP_URL belum sesuai / license untuk domain localhostIsi APP_URL=https://domain-kamu.com di .env, lalu jalankan php artisan config:clear. License selalu diaktifkan untuk domain di APP_URL.
Too Many Attempts padahal request sedikit (situs di belakang Cloudflare)Semua pengunjung terlihat memakai IP Cloudflare, jadi berbagi satu batas rate limit. Isi TRUSTED_PROXIES=cloudflare di .env, lalu jalankan php artisan config:clear. Untuk proxy lain, isi alamat IP-nya dipisah koma.
Invalid / Missing request signaturePembeli tidak perlu mengisi secret apa pun; aplikasi sudah membawanya. Hapus baris LICENSE_API_SECRET dari .env kalau ada (nilai lama yang salah akan menimpa bawaan), jalankan php artisan config:clear, lalu cek dengan php artisan license:diagnose. Kalau masih gagal, update ke versi terbaru.
Token ShopeePay ditolakSesi Partner Portal sudah berakhir, misalnya karena logout atau login di perangkat lain. Ambil token baru dari Partner Portal lalu tempel di /admin/shopeepay. Selama token ditolak, pembayaran tidak terdeteksi.
Request timestamp expiredJam server meleset lebih dari 5 menit. Sinkronkan jam server (NTP) atau hubungi hosting.

Pindah domain

License terikat ke satu domain. Sebelum memindahkan gateway, lepas dulu domain lama supaya slot aktivasinya bisa dipakai lagi:

  1. Di domain lama, buka /admin/license lalu klik Lepas license, atau jalankan perintah di bawah. Sejak saat itu tagihan baru ditolak.
  2. Pasang gateway di domain baru dengan langkah di atas, dengan APP_URL berisi domain baru.
  3. Aktifkan license key yang sama lewat wizard /install atau /admin/license.
Lepas license dari terminal
php artisan license:deactivate

Kalau server lama sudah tidak bisa diakses, hubungi penjual untuk melepas domain dari panel license.