BTCPay Server memungkinkan bisnis online untuk menerima pembayaran cryptocurrency secara langsung, tanpa perantara atau kustodial. Panduan ini akan membimbing kamu melalui proses lengkap pengaturan BTCPay Server dengan dukungan asli untuk pembayaran terlindungi Zcash.
Perdagangan online semakin banyak menerima cryptocurrency. Ini cepat, global, dan bekerja tanpa bank. Hal ini menguntungkan baik bagi pedagang maupun pelanggan. Namun, ada satu detail penting yang sering diabaikan oleh banyak orang.
Saat melakukan pemesanan, pelanggan biasanya memberikan informasi pribadi: nama, alamat pengiriman, dan nomor telepon. Jika pembayaran dilakukan menggunakan blockchain publik - seperti Bitcoin, Ethereum, atau stablecoin di Ethereum atau Tron - transaksi tersebut menjadi terlihat secara permanen untuk dianalisis.
Siapa pun, bahkan tanpa mengetahui apa yang dipesan, dapat:
Ini berarti bahwa satu pembelian saja dapat mengungkap seluruh riwayat keuangan seorang pelanggan.
Dan hal ini juga berlaku sebaliknya. Jika alamat seorang pedagang pernah muncul di on-chain, mereka akan menjadi terekspos. Kompetitor dan pengamat pihak ketiga dapat melacak volume pembayaran, aktivitas pemasok, dan struktur alur bisnis.
BTCPay Server adalah sistem gratis dan terdesentralisasi untuk menerima pembayaran cryptocurrency.
Ini bukan perantara pembayaran dan tidak menyimpan dana apa pun. Semua pembayaran langsung masuk ke dompet merchant.
Ini bisa berupa dompet pribadi atau pengaturan multisig di dalam sebuah organisasi.
Server menangani tugas-tugas koordinasi:
Semuanya berjalan di bawah kendali pemilik toko, tanpa bergantung pada layanan pihak ketiga.
Zcash adalah mata uang kripto yang dibangun di atas zero-knowledge proofs. Ini mendukung model transaksi yang sepenuhnya privat.
Saat menggunakan alamat terlindungi (selanjutnya hanya disebut sebagai "alamat"), pengirim, penerima, dan jumlah transaksi tidak akan terungkap di blockchain.
Bagi toko online, ini berarti:
Seorang pengguna membuat pesanan dan memilih Bitcoin atau USDT sebagai metode pembayaran.
Situs web menghasilkan alamat pembayaran dan menampilkan jumlahnya.
Setelah pembayaran dilakukan, alamat ini disimpan di blockchain dan menjadi publik.
Seorang penyerang hanya perlu menghubungkan satu pesanan ke alamat tersebut untuk mendapatkan visibilitas jangka panjang terhadap seluruh riwayat transaksinya.
Sekarang bayangkan situasi yang sama dengan Zcash.
BTCPay Server menghasilkan alamat terlindungi. Pembeli mengirimkan pembayaran.
Dari perspektif blockchain, tidak ada yang terjadi. Tidak ada data publik untuk dianalisis.
Server menerima konfirmasi, menghubungkannya ke pesanan, dan menyelesaikan prosesnya.
Bagi pihak luar mana pun, terlihat seolah-olah tidak ada yang terjadi.
Semua logika tetap berada di antara toko dan pelanggan - sebagaimana mestinya.
Solusi ini tidak mengorbankan otomatisasi atau kegunaan.
Semuanya bekerja sama seperti pada mata uang kripto lainnya, hanya saja tanpa risiko kebocoran data.
BTCPay Server bertindak sebagai jembatan pemrosesan pembayaran antara platform e-commerce kamu dan blockchain. Berikut adalah cara alur kerjanya:
Pelanggan membuat pesanan di situs web kamu (misalnya WooCommerce, Magento, atau platform apa pun dengan integrasi BTCPay).
Toko meminta invoice pembayaran dari BTCPay Server. Server menghasilkan invoice unik dengan:
u1... - yang secara default menyertakan penerima Orchard terlindungi.Pelanggan melihat halaman pembayaran dan mengirim ZEC ke alamat yang telah disediakan.
BTCPay Server memantau blockchain, memeriksa pembayaran terhadap:
Setelah transaksi terdeteksi dan dikonfirmasi, BTCPay akan memberi tahu toko tersebut.
Pelanggan menerima konfirmasi pembayaran. Secara opsional, server dapat mengirimkan tanda terima melalui email.
Seluruh proses ini terjadi secara otomatis, tanpa perantara atau kustodial.
BTCPay Server tidak menyimpan dana apa pun - ia hanya menghubungkan sistem pesanan ke blockchain secara aman dan privat.
BTCPay Server bukan sebuah dompet dan tidak memerlukan private keys.
Semua dana dikirimkan secara langsung ke dompet merchant. Keamanan dipastikan dengan menggunakan arsitektur berbasis viewing key.
Dompet dibuat sebelumnya.
Merchant menggunakan dompet Zcash yang mendukung viewing key - seperti Zkool atau WalletZingo!.
Daftar lengkap tersedia di ZecHub.wiki.
BTCPay Server terhubung melalui viewing key.
Viewing key adalah kunci read-only: kunci ini dapat mendeteksi pembayaran masuk dan menghasilkan alamat penerima baru,
tetapi tidak dapat membelanjakan dana. Server tidak menyimpan frasa pemulihan atau private key.
Data blockchain diakses melalui server lightwalletd.
Kamu dapat menggunakan node publik seperti https://zec.rocks, atau menjalankan stack Zebra + lightwalletd milikmu sendiri untuk kedaulatan penuh.
Setiap pesanan mendapatkan alamat unik.
Viewing key memungkinkan server untuk menurunkan alamat terlindungi Zcash baru untuk setiap faktur,
sehingga pelacakan pembayaran yang aman dapat dilakukan dan penggunaan ulang alamat dapat dicegah.
Kamu memegang kendali penuh atas dana tersebut.
Bahkan jika server disusupi, tidak ada yang bisa mencuri uangmu - hanya metadata pembayaran yang mungkin terekspos.
Desain ini memisahkan infrastruktur dari kontrol aset.
Kamu dapat memperbarui, melakukan migrasi, atau menginstal ulang BTCPay Server tanpa menempatkan dana apa pun dalam risiko.
Di bagian sebelumnya, kami telah menjelaskan bagaimana BTCPay Server bekerja dengan Zcash dan mengapa hal ini penting untuk pembayaran yang menjaga privasi. Sekarang saatnya untuk mempraktikkannya secara langsung.
Pengaturan persis kamu akan bergantung pada beberapa faktor:
Bab ini mencakup semua skenario konfigurasi saat ini - mulai dari pengaturan minimal hingga penerapan yang sepenuhnya berdaulat.
Kita akan membahas hal-hal berikut:
Mari kita lanjut ke pengaturan yang sebenarnya. Di bagian ini, kita akan menginstal BTCPay Server dengan dukungan Zcash - baik pada VPS baru atau dengan menambahkan dukungan ZEC ke instance yang sudah ada.
Jika kamu sudah menjalankan BTCPay Server (misalnya untuk BTC atau Lightning), kamu tidak perlu menginstal ulang semuanya - cukup aktifkan plugin ZEC.
Kami akan memandu kamu melalui berbagai konfigurasi, mulai dari pengaturan minimal menggunakan lightwalletd node publik hingga instalasi yang sepenuhnya berdaulat dengan full node milikmu sendiri.
Opsi terbaik bergantung pada lokasi server kamu dan seberapa besar kemandirian yang kamu inginkan dari infrastruktur eksternal.
Sebelum melakukan instalasi, pastikan kamu sudah memiliki:
git, docker, dan docker-compose sudah terinstalUntuk menyebarkan BTCPay Server dengan dukungan Zcash, kamu akan membutuhkan hal-hal berikut:
Kami menyarankan penggunaan instalasi minimal dari Ubuntu Server 22.04 LTS.
Penyedia VPS apa pun yang menawarkan alamat IP khusus akan dapat digunakan.
Persyaratan minimum:
Pengaturan ini sudah cukup jika kamu menggunakan lightwalletd untuk Zcash.
Jika kamu berencana menjalankan node full Zcash, kamu akan membutuhkan setidaknya 300 GB ruang disk kosong.
Di dashboard penyedia DNS kamu, buatlah sebuah record A untuk subdomain (misalnya btcpay.example.com) yang mengarah ke alamat IP VPS kamu.
Domain ini akan digunakan untuk mengakses BTCPay Server dari browser
dan untuk membuat sertifikat SSL gratis secara otomatis melalui Let's Encrypt.
Untuk menginstal BTCPay Server, kamu harus terhubung ke VPS milikmu melalui SSH.
Dari terminal kamu, jalankan:
ssh root@YOUR_SERVER_IP
Jika kamu menggunakan macOS, Linux, atau WSL di Windows, SSH sudah tersedia di terminal. Pada Windows biasa, gunakan klien SSH seperti PuTTY.
Buat direktori kerja dan unduh deployment Docker BTCPay Server:
mkdir BTCPayServer
cd BTCPayServer
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
Ganti btcpay.example.com dengan domain kamu yang sebenarnya:
export BTCPAY_HOST="btcpay.example.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_CRYPTO2="zec"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_LIGHTNING="none"
export BTCPAYGEN_CRYPTO3="ltc"
export BTCPAYGEN_CRYPTO4="xmr"
Kamu dapat menambahkan koin baru kapan saja dengan mengekspor variabel yang sesuai dan menjalankan ulang skrip setup:
. ./btcpay-setup.sh -i
Untuk panduan ini, kita hanya akan fokus pada Zcash.
Jalankan skrip pengaturan untuk membangun dan meluncurkan server:
. ./btcpay-setup.sh -i
Skrip ini akan menginstal dependensi, membuat docker-compose.yml, memulai layanan, dan mengonfigurasi systemd.
Proses ini memakan waktu sekitar 5 menit.
Setelah selesai, instansi BTCPay Server kamu akan tersedia di:
https://btcpay.example.com
cd ~/BTCPayServer/btcpayserver-docker
btcpay-down.sh
. ./btcpay-setup.sh -i
Kemudian lanjutkan ke bagian berikutnya untuk mengonfigurasi Zcash di antarmuka web BTCPay Server.
Jika kamu lebih memilih untuk tidak bergantung pada node lightwalletd publik, kamu dapat menjalankan full Zcash node milikmu sendiri bersama dengan lightwalletd di server yang sama.
Ini memberimu otonomi penuh - tanpa ketergantungan eksternal, tidak memerlukan kepercayaan.
Sebuah full node Zcash lengkap (Zebra + lightwalletd) saat ini membutuhkan 300+ GB ruang disk, dan ukurannya terus bertambah.
Rincian:
Tambahkan hal berikut ke pengaturan lingkungan kamu untuk mengaktifkan konfigurasi full node:
export BTCPAYGEN_EXCLUDE_FRAGMENTS="zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="zcash-fullnode"
Ini akan mencakup fragmen zcash-fullnode, yang menjalankan zebrad dan lightwalletd di dalam BTCPay Server.
. ./btcpay-setup.sh -i
Skrip ini akan:
lightwalletd lokalDalam kebanyakan kasus, otonomi penuh tidak diperlukan - dan merchant mungkin tidak ingin menghabiskan waktu dan ruang disk untuk menjalankan Zcash full node.
Secara default, BTCPay Server terhubung ke lightwalletd node publik untuk menangani pembayaran terlindungi tanpa perlu mengunduh seluruh blockchain.
Endpoint default adalah:
https://zec.rocks:443
Namun, kamu dapat mengonfigurasi BTCPay Server untuk terhubung ke node lightwalletd eksternal apa pun, seperti:
https://lightwalletd.example:443
Bagian ini menunjukkan cara melakukannya menggunakan fragmen Docker kustom.
Di dalam direktori proyek BTCPayServer kamu, buatlah sebuah file fragmen kustom:
cd ~/BTCPayServer/btcpayserver-docker
mkdir -p docker-compose-generator/docker-fragments
nano docker-compose-generator/docker-fragments/zcash-lightwalletd.custom.yml
Tambahkan konten berikut:
exclusive:
- zcash
Direktif exclusive memastikan bahwa hanya satu fragmen dengan label yang sama (zcash dalam hal ini) yang dapat aktif pada satu waktu.
Ini mencegah konflik konfigurasi - sebagai contoh, kamu tidak dapat menjalankan fragmen zcash-fullnode dan fragmen eksternal kustom lightwalletd ini secara bersamaan.
Dengan menandainya sebagai exclusive: zcash, BTCPay Server akan secara otomatis menonaktifkan kontainer default zcash-fullnode dan lightwalletd internal, sehingga memungkinkan kamu untuk terhubung ke node eksternal milikmu sendiri sebagai gantinya.
Di terminal:
export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;zcash-lightwalletd.custom"
Buka berkas .env kamu:
nano .env
Tambahkan baris berikut, ganti URL dengan endpoint pilihanmu:
ZCASH_LIGHTWALLETD=https://lightwalletd.example:443
Kamu dapat menggunakan:
https://zec.rocks:443. ./btcpay-setup.sh -i
BTCPay Server akan menerapkan konfigurasi kustom kamu dan terhubung ke lightwalletd node yang ditentukan.
Mulai sekarang, plugin Zcash akan menggunakan endpoint eksternal tersebut untuk menangani transaksi terlindungi.
Ingin menerima pembayaran Zcash sambil menjalankan BTCPay Server pada perangkat rumah — seperti Raspberry Pi 5 atau server lokal lainnya tanpa IP statis?
Kamu dapat mengekspos instans kamu ke internet secara aman menggunakan Cloudflare Tunnel.
Metode ini menghindari port forwarding dan menyembunyikan alamat IP asli kamu dari publik - sambil tetap menjaga server kamu dapat diakses melalui HTTPS.
Ini juga membantu kamu menghindari biaya menyewa VPS, yang sangat ideal jika pembayaran cryptocurrency hanyalah fitur opsional dan bukan inti dari bisnis kamu.
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update
sudo apt install cloudflared
Jika apt install cloudflared gagal, instal .deb yang sesuai sebagai gantinya:
# Raspberry Pi / ARM64
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64.deb
sudo dpkg -i cloudflared.deb
# x86_64
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
cloudflared tunnel login
Perintah ini akan membuka jendela browser. Masuklah dan berikan otorisasi akses ke domain kamu.
Cloudflare akan secara otomatis membuat file credentials dengan sebuah token di server kamu.
btcpay atau apa pun):cloudflared tunnel create btcpay
Ini menghasilkan berkas btcpay.json yang berisi ID tunnel dan kredensial - kamu akan membutuhkannya di langkah berikutnya.
Buat direktori konfigurasi (jika belum ada) dan buka berkas konfigurasi:
sudo mkdir -p /etc/cloudflared
sudo nano /etc/cloudflared/config.yml
Tempelkan konfigurasi berikut:
tunnel: btcpay # your tunnel name
credentials-file: /root/.cloudflared/btcpay.json
ingress:
- hostname: btcpay.example.com # your domain
service: http://127.0.0.1:80
- service: http_status:404
tunnel - nama tunnel yang kamu buat sebelumnyacredentials-file - jalur ke file token yang dihasilkan selama cloudflared tunnel loginhostname - domain kamu yang terdaftar di Cloudflare (misalnya btcpay.example.com)service - alamat lokal dari BTCPay Server kamu (biasanya http://127.0.0.1:80 untuk Nginx)Setelah membuat tunnel, Cloudflare biasanya akan menambahkan record DNS CNAME secara otomatis untuk domain kamu. Hasilnya akan terlihat seperti ini:
btcpay.example.com -> <UUID>.cfargotunnel.com
Jika tidak muncul secara otomatis, tambahkan secara manual:
btcpay<UUID>.cfargotunnel.combtcpay.json kamu atau dengan menjalankan:cloudflared tunnel list
Agar tunnel dapat berjalan secara otomatis saat booting, instal sebagai layanan sistem:
sudo cloudflared service install
Kemudian aktifkan dan jalankan layanannya:
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
Periksa status:
sudo systemctl status cloudflared
Kamu akan melihat pesan seperti Active: active (running) dan konfirmasi bahwa btcpay.example.com sedang online.
Jika kamu hendak menginstal BTCPay Server untuk pertama kalinya, atur domain kamu sebelum menjalankan skrip pengaturan:
export BTCPAY_HOST="btcpay.example.com"
Ini memastikan domain yang benar digunakan saat membuat konfigurasi Nginx dan sertifikat SSL.
Jika BTCPay Server sudah terinstal dan kamu hanya menambahkan tunnel-nya:
cd ~/BTCPayServer/btcpayserver-docker
. ./btcpay-setup.sh -i
Pengaturan ini akan membuat ulang konfigurasi dan menerapkan domain baru. Sekarang kamu seharusnya sudah bisa mengakses server kamu di:
https://btcpay.example.com
Setelah berhasil menyebarkan instance BTCPay Server milikmu, kamu perlu melakukan beberapa konfigurasi dasar melalui antarmuka web admin.
Dokumentasi resmi menyediakan instruksi lengkap dalam bahasa Inggris - di sini, kita akan membahas langkah-langkah penting dan fokus secara khusus pada konfigurasi plugin Zcash.
Kunjungi instansi kamu di:
Plugins -> Browse Plugins
Setelah instalasi, klik Restart Server untuk memuat ulang antarmuka dengan plugin yang aktif.
Setelah menginstal plugin, bagian Zcash baru akan muncul di menu pengaturan.
Zcash -> Settings
Contoh format:
uview184syv9wftwngkay8d...
Kunci-kunci ini mendukung rotasi alamat otomatis, yang berarti:
Kamu dapat menemukan daftar kompatibilitas yang lebih luas di ZecHub -> Dompet.
Setelah semua kolom diisi, klik Simpan.
Selamat - dompet Zcash kamu sekarang telah terhubung ke BTCPay Server.
Mari kita jalankan sebuah pengujian:
Invoices -> Create New
Jika semuanya berfungsi dengan baik - kamu sudah siap untuk mengintegrasikan pembayaran ZEC ke dalam situs web kamu menggunakan API atau plugin CMS.
Setelah dompet Zcash kamu terhubung ke BTCPay Server, kamu dapat mengintegrasikan sistem pembayaran ke dalam situs web kamu.
Ada beberapa cara untuk melakukan ini - mulai dari akses API langsung hingga plugin siap pakai untuk platform CMS populer.
Integrasi API
Ideal untuk situs web atau sistem buatan sendiri tanpa CMS.
Memberikan kamu kontrol penuh atas pembuatan invoice, pelacakan pembayaran, dan notifikasi - semuanya di dalam antarmuka dan logika milikmu sendiri.
Memerlukan pengetahuan pemrograman dasar, jadi tugas ini paling baik ditangani oleh developer kamu.
Plugin CMS
Tersedia untuk platform seperti WooCommerce, PrestaShop, dan lainnya.
Plugin ini memungkinkan kamu menerima pembayaran hanya dalam beberapa menit - tanpa perlu coding.
Tombol Pembayaran atau Iframe
Metode termudah.
Sangat cocok untuk landing page, situs web pribadi, atau situs apa pun di mana kamu hanya ingin menyematkan tautan donasi atau widget checkout.
Jika kamu menggunakan platform kustom (atau tanpa CMS sama sekali), API adalah opsi terbaik.
Ini memberimu fleksibilitas penuh: kamu dapat membuat invoice, melacak statusnya, menerima notifikasi, dan mengontrol pengalaman pengguna sepenuhnya.
Langkah berikutnya: buat kunci API untuk tokomu dan mulailah menggunakan Greenfield API untuk membangun integrasimu.
Untuk mengintegrasikan BTCPay Server dengan situs web atau aplikasi kamu, kamu perlu membuat kunci API.
Masuk ke BTCPay Server dan buka menu pengguna (pojok kanan atas)
Buka API Keys
Klik Create a new API key
Masukkan nama untuk kunci kamu
Di bagian Permissions, aktifkan:
Can create invoiceCan view invoiceCan modify store settings - hanya jika kamu membutuhkan manajemen tingkat tokoKlik Generate. API key pribadi kamu akan ditampilkan - salin dan simpan dengan aman.
Endpoint:
POST /api/v1/stores/{storeId}/invoices
Authorization: token {apiKey}
Content-Type: application/json
Body permintaan:
{
"amount": 5,
"currency": "ZEC",
"checkout": {
"speedPolicy": "HighSpeed",
"paymentMethods": ["Zcash"]
}
}
Response:
Kamu akan menerima objek JSON dengan:
invoiceIdLihat dokumentasi lengkap: Greenfield API – Buat Invoice
Untuk menerima notifikasi waktu nyata saat status faktur berubah (misalnya, saat pembayaran diterima):
POST dari BTCPay ServerPayload webhook dan logika pengulangan dijelaskan dalam dokumentasi webhook resmi.
BTCPay Server mendukung plugin untuk sistem manajemen konten (CMS) yang populer.
Integrasi yang paling matang dan banyak digunakan adalah dengan WordPress + WooCommerce, sehingga memudahkan kamu untuk menerima pembayaran ZEC tanpa perlu menulis kode.
BTCPay Server secara resmi mendukung plugin untuk WooCommerce.
Langkah-langkah untuk integrasi:
WooCommerce -> Settings -> Payments
Kamu juga akan menemukan opsi integrasi CMS lainnya di bagian yang sama pada dokumentasi BTCPay tersebut.
Jika kamu tidak menggunakan CMS dan tidak ingin bekerja dengan API, cara termudah untuk menerima pembayaran ZEC adalah dengan menyematkan tautan pembayaran atau widget secara langsung di situs web kamu.
Metode ini sangat ideal untuk:
https://btcpay.example.com/i/abc123
<a href="https://btcpay.example.com/i/abc123" target="_blank">
Pay with ZEC
</a>
Untuk menampilkan invoice secara langsung di situs kamu, gunakan iframe:
<iframe src="https://btcpay.example.com/i/abc123" width="600" height="350" frameborder="0"></iframe>
Panduan ini memang panjang - tetapi ini hanya mencakup aspek-aspek mendasar dari integrasi pembayaran Zcash dengan BTCPay Server.
Antarmuka BTCPay Server menawarkan jauh lebih banyak fungsionalitas daripada yang telah kami tunjukkan di sini. Beruntungnya, UI ini tersedia dalam berbagai bahasa (termasuk Rusia), sehingga memudahkan kamu untuk menjelajah dan bereksperimen lebih jauh.
BTCPay adalah alat yang sangat fleksibel. Kamu dapat:
BTCPay dibangun sebagai alternatif sumber terbuka untuk penyedia pembayaran terpusat. Jika kamu ingin menerima pembayaran ZEC yang privat tanpa perantara, platform ini sangat layak untuk kamu perhatikan.
Kami mendoakan kesuksesanmu dalam menjelajahi ekosistem BTCPay dan membuat pembayaranmu benar-benar menjadi milikmu sendiri.
Setelah terhubung melalui SSH, perbarui paket sistem kamu dan instal komponen yang diperlukan:
sudo apt update && sudo apt upgrade -y
sudo apt install git curl docker.io docker-compose-plugin -y
sudo systemctl enable docker
Pada Ubuntu 22.04 dan yang lebih baru,
docker-composedari APT sudah usang. Paket yang direkomendasikan adalahdocker-compose-plugin, yang menyediakan perintahdocker compose(perhatikan penggunaan spasi alih-alih tanda hubung).
Lingkungan server kamu sekarang sudah siap untuk menginstal BTCPay Server.