Referensi

Plugin & integrasi

Plugin WooCommerce dan node n8n untuk menerima QRIS tanpa menulis kode.

6 menit bacaDiperbarui 2 Nov 2026

WooCommerce

Plugin FQris for WooCommerce menambahkan metode bayar "QRIS (FQris)" di checkout klasik dan Checkout Block, kompatibel dengan HPOS. Status order diperbarui otomatis lewat webhook FQris.

Unduh fqris-for-woocommerce-0.1.0.zip, plugin versi 0.1.0 dalam bentuk berkas zip.

WordPress 6.4 atau lebih baru, WooCommerce 8.3 atau lebih baru, PHP 8.1 atau lebih baru, dan mata uang toko Rupiah (IDR). Untuk mata uang lain, metode bayar ini tidak muncul di checkout. Kamu juga butuh akun FQris dengan API key.

Pasang dan atur

1
Unggah dan aktifkan plugin Di dasbor WordPress buka Plugin, Tambah Baru, Unggah Plugin, pilih zip, klik Pasang Sekarang, lalu Aktifkan. Pastikan WooCommerce sudah aktif.
2
Atur mata uang ke Rupiah Buka WooCommerce, Pengaturan, Umum, lalu pilih Rupiah Indonesia (IDR). QRIS hanya menerima rupiah bulat, jadi atur jumlah desimal harga menjadi 0.
3
Buat API key Di dasbor FQris buat API key. Mode test diawali fq_test_, mode live diawali fq_live_.
4
Daftarkan webhook endpoint Di dasbor FQris tambahkan webhook endpoint dengan URL https://domain-tokomu/?wc-api=fqris dan event payment.paid, payment.expired, payment.refunded. Salin webhook secret (whsec_...) yang ditampilkan. URL yang tepat juga tertulis di halaman pengaturan metode bayar.
5
Isi pengaturan metode bayar Buka WooCommerce, Pengaturan, Pembayaran, QRIS (FQris). Centang Aktifkan, pilih Mode, lalu isi API key dan webhook secret untuk mode itu. Kamu juga bisa mengatur kedaluwarsa, status order setelah dibayar (Diproses atau Selesai), dan pembatalan order saat kedaluwarsa. Simpan.
6
Uji di mode test Coba satu pesanan: pilih QRIS (FQris) di checkout, lalu simulasikan pembayaran dari dasbor FQris. Order harus berubah menjadi "Diproses" dan muncul catatan "Dibayar via QRIS (FQris)".
7
Pindah ke live Setelah yakin, buat API key dan webhook endpoint mode live, isi kolom live, lalu ubah Mode ke Live.

Perilaku

Saat pembeli membayar, webhook membuat order lunas otomatis. Plugin mengambil ulang payment dengan API key tokomu dan tidak mempercayai isi body webhook begitu saja.

Pembeli yang menekan "Buat pesanan" lagi untuk order yang sama diarahkan ke QR yang sama selama payment-nya belum hampir kedaluwarsa, jadi tidak terbentuk pembayaran ganda dari klik berulang.

Pembayaran ganda tidak dilunasi diam-diam

Bila order yang sudah lunas menerima pembayaran dari payment lain, plugin hanya menambahkan catatan dan tidak mengubah statusnya. Bila nominal payment tidak sama dengan total order, order dipindah ke status Ditahan (on-hold) dengan catatan. Periksa dulu, lalu refund lewat dasbor FQris bila memang ganda.

Event mode test diabaikan di toko live

Bila Mode plugin adalah Live, event mode test diabaikan dan tidak menyentuh order. Event live pada toko yang masih mode test tetap diproses karena itu uang nyata.

Bila order tidak menjadi lunas setelah pembeli membayar, periksa bahwa URL webhook persis https://domain-tokomu/?wc-api=fqris, webhook secret sama dengan di plugin, dan situsmu bisa diakses dari internet. Log tersimpan di WooCommerce, Status, Log, dengan sumber fqris.

n8n

Node komunitas n8n untuk FQris membuat payment, payment link, invoice, dan catatan refund dari workflow, serta menjalankan workflow saat FQris mengirim webhook.

Node n8n segera tersedia

Paket n8n-nodes-fqris sedang disiapkan untuk terbit di npm. Sementara itu, pakai node HTTP Request di n8n dengan contoh cURL dari Quickstart: semua endpoint bisa dipanggil langsung lewat HTTP.

Setelah terbit, pasang di n8n lewat Settings, Community Nodes, Install, isi n8n-nodes-fqris, lalu muat ulang n8n. Node "FQris" dan "FQris Trigger" muncul di panel node. Butuh Node.js 20 atau lebih baru.

Buat credential "FQris API" dengan API Key (fq_live_ atau fq_test_). Base URL bawaannya https://api.fqris.id; ubah hanya untuk API staging atau self-hosted. Credential ini tidak meminta webhook secret.

Operasi node FQris

Payment: Create Payment, Get Payment, List Payments, Cancel Payment. Payment Link: Create Payment Link. Invoice: Create Invoice, Send Invoice. Refund: Record Refund. Jumlah uang selalu bilangan bulat rupiah.

Record Refund hanya mencatat refund di FQris; uang tetap kamu kirim sendiri ke pembeli. List Payments mengikuti paginasi sampai habis bila Return All dinyalakan.

FQris Trigger

FQris Trigger memulai workflow saat FQris mengirim event, misalnya payment.paid atau payment.expired. Saat workflow diaktifkan, node mendaftarkan webhook endpoint di FQris sendiri dengan URL webhook n8n dan event yang kamu pilih, lalu menghapusnya saat workflow dinonaktifkan. Kamu tidak perlu menyalin webhook secret: node menyimpannya dan memverifikasi signature setiap permintaan.

URL n8n harus publik untuk mode live, karena FQris menolak URL localhost. Untuk uji lokal pakai API key fq_test_ atau tunnel HTTPS.

Idempotency Key

Operasi yang membuat atau mengubah data (Create Payment, Cancel Payment, Create Payment Link, Create Invoice, Send Invoice, Record Refund) mengirim Idempotency Key otomatis, jadi Retry On Fail bawaan n8n aman. Bila kamu mengisi Idempotency Key sendiri di Options dan node memproses lebih dari satu item, node menambahkan akhiran nomor item supaya tiap item punya key berbeda.

Apakah halaman ini membantu?