BTCPay Server із підтримкою Zcash: повний посібник зі встановлення та інтеграції
BTCPay Server дозволяє онлайн-бізнесам приймати криптовалютні платежі безпосередньо, без посередників чи кастодіанів. У цьому посібнику ви пройдете весь процес налаштування BTCPay Server із нативною підтримкою shielded-платежів Zcash.
Ця документація зосереджена на інтеграції Zcash у ваш екземпляр BTCPay Server.
Вона підтримує як конфігурації з повним вузлом (Zebra), так і конфігурації на основі lightwalletd.
Зміст
Чому варто використовувати BTCPay Server із Zcash
Онлайн-комерція дедалі частіше приймає криптовалюту. Це швидко, глобально й працює без банків. Це вигідно як продавцям, так і покупцям. Але є важлива деталь, яку багато хто не помічає.
Під час оформлення замовлення клієнт зазвичай надає особисту інформацію: ім’я, адресу доставки та номер телефону. Якщо оплата здійснюється через публічний блокчейн — наприклад, Bitcoin, Ethereum або стейблкоїни в мережах Ethereum чи Tron, — транзакція назавжди стає видимою для аналізу.
Будь-хто, навіть не знаючи, що саме було замовлено, може:
- побачити, коли і скільки було сплачено
- простежити, звідки надійшли кошти і куди вони були відправлені
- пов’язати криптовалютну адресу з реальною людиною, якщо є бодай якась точка кореляції (наприклад, злитий email або ім’я одержувача доставки)
Це означає, що одна-єдина покупка може розкрити всю фінансову історію клієнта.
І це працює і в зворотному напрямку. Якщо адреса продавця коли-небудь з’являлася ончейн, він стає вразливим до спостереження. Конкуренти та сторонні спостерігачі можуть відстежувати обсяги платежів, активність постачальників і структуру бізнес-потоків.
Поєднання BTCPay Server і Zcash може розв’язати цю проблему.
BTCPay Server — це безкоштовна й децентралізована система для приймання криптовалютних платежів.
Вона не є платіжним посередником і не зберігає жодних коштів. Усі платежі надходять безпосередньо на гаманець продавця.
Це може бути особистий гаманець або multisig-конфігурація в межах організації.
Сервер виконує координаційні завдання:
- генерує унікальну адресу для кожного замовлення
- відстежує надходження платежу й пов’язує його із замовленням
- видає квитанції та сповіщення
- надає клієнту інтерфейс для оплати
Усе працює під контролем власника магазину, без залежності від сторонніх сервісів.
Zcash — це криптовалюта, побудована на доказах з нульовим розголошенням. Вона підтримує повністю приватну модель транзакцій.
Під час використання shielded-адрес (далі просто “адреси”) відправник, одержувач і сума транзакції не розкриваються в блокчейні.
Для онлайн-магазинів це означає:
- Покупець може здійснити платіж, не розкриваючи свою фінансову історію
- Продавець отримує оплату, не розкриваючи свою адресу, обсяг продажів чи структуру транзакцій
- Жоден зовнішній спостерігач не може пов’язати платіж із замовленням або з даними клієнта
Практичний приклад
Користувач оформлює замовлення і обирає Bitcoin або USDT як спосіб оплати.
Вебсайт генерує платіжну адресу та показує суму.
Після здійснення платежу ця адреса зберігається в блокчейні й стає публічною.
Зловмиснику достатньо пов’язати одне замовлення з цією адресою, щоб надовго отримати видимість усієї її історії транзакцій.
А тепер уявіть ту саму ситуацію із Zcash.
BTCPay Server генерує shielded-адресу. Покупець надсилає платіж.
З точки зору блокчейна нічого не відбувається. Немає публічних даних для аналізу.
Сервер отримує підтвердження, пов’язує його із замовленням і завершує процес.
Для будь-кого ззовні це виглядає так, ніби нічого не сталося.
Уся логіка залишається між магазином і клієнтом — саме так, як і має бути.
Це рішення не жертвує ані автоматизацією, ані зручністю використання.
Усе працює так само, як і з іншими криптовалютами, просто без ризику витоків даних.
Як працює BTCPay Server
BTCPay Server виступає містком для обробки платежів між вашою e-commerce платформою та блокчейном. Ось як працює цей процес:
-
Клієнт оформлює замовлення на вашому вебсайті (наприклад, WooCommerce, Magento або будь-якій платформі з інтеграцією BTCPay).
-
Магазин запитує платіжний рахунок у BTCPay Server. Сервер генерує унікальний рахунок із:
- Сумою замовлення
- Таймером зворотного відліку
- Zcash Unified Address (UA) — наприклад,
u1... — яка за замовчуванням містить Orchard (shielded) receiver.
-
Клієнт бачить сторінку оплати та надсилає ZEC на вказану адресу.
-
BTCPay Server відстежує блокчейн, перевіряючи платіж за:
- Очікуваною сумою
- Адресою отримання
- Часовою міткою рахунка
-
Щойно транзакцію виявлено та підтверджено, BTCPay сповіщає магазин.
-
Клієнт отримує підтвердження оплати. За бажання сервер може надіслати квитанцію електронною поштою.
Увесь цей процес відбувається автоматично, без посередників чи кастодіанів.
BTCPay Server не зберігає жодних коштів — він лише безпечно й приватно з’єднує систему замовлень із блокчейном.
Де зберігаються кошти? Хто контролює приватні ключі?
BTCPay Server не є гаманцем і не потребує приватних ключів.
Усі кошти надходять безпосередньо на гаманець продавця. Безпека забезпечується завдяки архітектурі на основі viewing key.
Як це працює
-
Гаманець створюється заздалегідь.
Продавець використовує гаманець Zcash, який підтримує Viewing Key — наприклад, Zkool або Zingo! Wallet.
Повний список доступний на ZecHub.wiki.
-
BTCPay Server підключається через viewing key.
Viewing key — це ключ лише для читання: він може виявляти вхідні платежі та генерувати нові адреси отримання,
але не може витрачати кошти. Сервер не зберігає seed-фрази чи приватні ключі.
-
Дані блокчейна отримуються через сервер lightwalletd.
Ви можете використовувати публічний вузол, такий як https://zec.rocks, або запустити власний стек Zebra + lightwalletd для повного суверенітету.
-
Кожне замовлення отримує унікальну адресу.
Viewing key дозволяють серверу виводити нові shielded-адреси Zcash для кожного рахунка,
забезпечуючи безпечне відстеження платежів і запобігаючи повторному використанню адрес.
-
Ви зберігаєте повний контроль над коштами.
Навіть якщо сервер буде скомпрометований, ніхто не зможе вкрасти ваші гроші — може бути розкрита лише метаінформація про платежі.
Такий дизайн відокремлює інфраструктуру від контролю над активами.
Ви можете оновлювати, переносити або перевстановлювати BTCPay Server, не наражаючи жодні кошти на ризик.
Як налаштувати BTCPay Server для приймання Zcash
У попередніх розділах ми пояснили, як BTCPay Server працює із Zcash і чому це важливо для платежів зі збереженням приватності. Тепер час перейти до практики.
Ваша точна конфігурація залежатиме від кількох чинників:
- Чи вже маєте ви екземпляр BTCPay Server?
- Ви хочете використовувати публічний lightwalletd чи запустити власний повний вузол?
- Сервер працюватиме на VPS чи вдома?
Цей розділ охоплює всі актуальні сценарії конфігурації — від мінімальних налаштувань до повністю суверенних розгортань.
Ми розглянемо таке:
- Як розгорнути все з нуля на VPS, включно з повним вузлом (Zebra)
- Як запустити BTCPay Server вдома, приховуючи свою IP-адресу за допомогою Cloudflare Tunnel
- Як увімкнути та налаштувати підтримку Zcash у вебінтерфейсі BTCPay Server
- Як інтегрувати BTCPay із вашим вебсайтом або онлайн-магазином
Розгортання BTCPay Server із підтримкою Zcash
Перейдемо до фактичного налаштування. У цьому розділі ми встановимо BTCPay Server із підтримкою Zcash — або на новому VPS, або шляхом додавання підтримки ZEC до вже наявного екземпляра.
Якщо у вас BTCPay Server уже працює (наприклад, для BTC чи Lightning), перевстановлювати все не потрібно — достатньо просто увімкнути плагін ZEC.
Ми розглянемо різні конфігурації — від мінімальних налаштувань із використанням публічного вузла lightwalletd до повністю суверенних інсталяцій із власним повним вузлом.
Найкращий варіант залежить від місця розміщення вашого сервера та від того, наскільки ви хочете бути незалежними від зовнішньої інфраструктури.
Офіційна документація плагіна:
https://github.com/btcpay-zcash/btcpayserver-zcash-plugin
Попередження — один гаманець на один екземпляр:
Плагін Zcash використовує один спільний гаманець для всіх магазинів у екземплярі BTCPay.
Якщо ви хостите кілька незалежних магазинів на одному екземплярі, вони використовуватимуть той самий гаманець Zcash.
Використовуйте окремі екземпляри, якщо вам потрібна сувора ізоляція гаманців.
Рекомендована конфігурація VPS
Перед встановленням переконайтеся, що у вас є:
- VPS з Ubuntu 22.04+
- Доменне ім’я, яке вказує на IP-адресу вашого сервера (через DNS)
- Встановлені
git, docker і docker-compose
- SSH-доступ до сервера
Підготовка сервера (прихована частина)
Натисніть, щоб розгорнути
Щоб розгорнути BTCPay Server із підтримкою Zcash, вам знадобиться таке:
1. VPS з Ubuntu 22.04 або новішою
Ми рекомендуємо використовувати мінімальну інсталяцію Ubuntu Server 22.04 LTS.
Підійде будь-який VPS-провайдер, який надає виділену IP-адресу.
Мінімальні вимоги:
- 2 ядра CPU
- 4 ГБ RAM
- 40 ГБ дискового простору
Цієї конфігурації достатньо, якщо ви використовуєте lightwalletd для Zcash.
Якщо ви плануєте запускати повний вузол Zcash, вам знадобиться щонайменше 300 ГБ вільного дискового простору.
2. Доменне ім’я, яке вказує на ваш сервер
У панелі керування вашого DNS-провайдера створіть запис A для субдомену
(наприклад, btcpay.example.com), який вказуватиме на IP-адресу вашого VPS.
Цей домен використовуватиметься для доступу до BTCPay Server із браузера
та для автоматичного створення безкоштовного SSL-сертифіката через Let's Encrypt.
3. SSH-доступ до сервера
Щоб установити BTCPay Server, ви маєте підключитися до свого VPS через SSH.
У терміналі виконайте:
ssh root@YOUR_SERVER_IP
Якщо ви користуєтеся macOS, Linux або WSL на Windows, SSH уже доступний у терміналі.
У звичайному Windows використовуйте SSH-клієнт, наприклад PuTTY.
4. Встановіть Git, Docker і Docker Compose
Після підключення через SSH оновіть системні пакети та встановіть потрібні компоненти:
Code-highlight
sudo apt update && sudo apt upgrade -y
sudo apt install git curl docker.io docker-compose-plugin -y
sudo systemctl enable docker
У Ubuntu 22.04 і новіших версіях docker-compose із APT застарілий.
Рекомендований пакет — , який надає команду (зверніть увагу на пробіл замість дефіса).
Крок 1: Клонування репозиторію
Створіть робочу директорію та завантажте Docker-розгортання BTCPay Server:
Code-highlight
mkdir BTCPayServer
cd BTCPayServer
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
Крок 2: Експортування змінних середовища
Замініть btcpay.example.com на ваш реальний домен:
Code-highlight
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"
Якщо ви плануєте пізніше додати Monero або Litecoin, можете включити їх уже зараз:
Code-highlight
export BTCPAYGEN_CRYPTO3="ltc"
export BTCPAYGEN_CRYPTO4="xmr"
Ви можете додавати нові монети будь-коли, експортувавши відповідні змінні та повторно запустивши скрипт налаштування:
. ./btcpay-setup.sh -i
У цьому посібнику ми зосередимося лише на Zcash.
Крок 3: Запуск інсталятора
Запустіть скрипт налаштування, щоб зібрати та запустити сервер:
. ./btcpay-setup.sh -i
Скрипт встановить залежності, згенерує docker-compose.yml, запустить служби та налаштує systemd.
Це займає приблизно 5 хвилин.
Після завершення ваш екземпляр BTCPay Server буде доступний за адресою:
https://btcpay.example.com
Якщо ви змінюєте наявну інсталяцію (наприклад, додаєте ZEC), обов’язково зупиніть і перезапустіть сервер із новими налаштуваннями:
Code-highlight
cd ~/BTCPayServer/btcpayserver-docker
btcpay-down.sh
. ./btcpay-setup.sh -i
Після цього перейдіть до наступного розділу, щоб налаштувати Zcash у вебінтерфейсі BTCPay Server.
Запуск власного повного вузла Zcash
Якщо ви волієте не покладатися на публічні вузли lightwalletd, ви можете розгорнути власний повний вузол Zcash разом із lightwalletd на тому ж сервері.
Це дає вам повну автономію — жодних зовнішніх залежностей і жодної потреби довіряти комусь.
Крок 1: Переконайтеся, що маєте достатньо дискового простору
Повний вузол Zcash (Zebra + lightwalletd) наразі потребує понад 300 ГБ дискового простору, і ця потреба продовжує зростати.
Розбивка:
- База даних блокчейна Zebra: ~260-270 ГБ
- Індексація lightwalletd: ~15-20 ГБ
Рекомендований обсяг сховища:
- 400 ГБ+, якщо сервер використовується лише для платежів Zcash
- 800 ГБ+, якщо сервер також запускає BTCPay Server, PostgreSQL, Nginx тощо
В ідеалі використовуйте SSD/NVMe диск ємністю 1 ТБ, особливо якщо не плануєте регулярно очищати дані.
Крок 2: Встановіть змінні середовища
Додайте таке до налаштування вашого середовища, щоб активувати конфігурацію повного вузла:
Code-highlight
export BTCPAYGEN_EXCLUDE_FRAGMENTS="zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="zcash-fullnode"
Це підключить фрагмент zcash-fullnode, який запускає і zebrad, і lightwalletd всередині BTCPay Server.
Крок 3: Повторно запустіть інсталятор
. ./btcpay-setup.sh -i
Скрипт:
- Завантажить Docker-образи для Zebra і lightwalletd
- Налаштує служби всередині стека BTCPay
- Пов’яже плагін Zcash із локальним екземпляром
lightwalletd
Повна синхронізація блокчейна може тривати кілька днів, особливо на VPS-серверах із невеликими ресурсами.
Поки синхронізацію не буде завершено, shielded-платежі будуть недоступні.
Підключення до зовнішнього вузла lightwalletd
У більшості випадків повна автономія не є обов’язковою — і продавці можуть не захотіти витрачати час і дисковий простір на запуск повного вузла Zcash.
За замовчуванням BTCPay Server підключається до публічного вузла lightwalletd, щоб обробляти shielded-платежі без завантаження всього блокчейна.
Типова адреса за замовчуванням:
https://zec.rocks:443
Однак ви можете налаштувати BTCPay Server так, щоб він підключався до будь-якого зовнішнього вузла lightwalletd, наприклад:
https://lightwalletd.example:443
У цьому розділі показано, як це зробити за допомогою спеціального Docker-фрагмента.
Повний приклад конфігурації з усіма змінними середовища доступний у репозиторії плагіна.
Нижче наведено мінімальну робочу конфігурацію.
Крок 1: Створіть спеціальний Docker-фрагмент
У директорії вашого проєкту BTCPayServer створіть файл спеціального фрагмента:
Code-highlight
cd ~/BTCPayServer/btcpayserver-docker
mkdir -p docker-compose-generator/docker-fragments
nano docker-compose-generator/docker-fragments/zcash-lightwalletd.custom.yml
Додайте такий вміст:
Code-highlight
exclusive:
- zcash
Директива exclusive гарантує, що одночасно може бути активним лише один фрагмент із тим самим ярликом (zcash у цьому випадку).
Це запобігає конфліктам конфігурації — наприклад, ви не можете одночасно запускати фрагмент zcash-fullnode і цей спеціальний зовнішній фрагмент lightwalletd.
Позначивши його як exclusive: zcash, BTCPay Server автоматично вимкне типовий zcash-fullnode і внутрішні контейнери lightwalletd, дозволяючи вам натомість підключитися до власного зовнішнього вузла.
Крок 2: Встановіть змінні середовища
У терміналі:
Code-highlight
export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;zcash-lightwalletd.custom"
Крок 3: Вкажіть адресу зовнішнього вузла
Відкрийте файл .env:
nano .env
Додайте такий рядок, замінивши URL на вибрану вами адресу:
ZCASH_LIGHTWALLETD=https://lightwalletd.example:443
Ви можете використовувати:
- Публічний вузол, наприклад
https://zec.rocks:443
- Власний self-hosted вузол, розгорнутий окремо від BTCPay Server
Якщо зовнішній lightwalletd стане недоступним або перевантаженим, shielded-платежі перестануть працювати.
Для критично важливих сервісів обирайте стабільну й перевірену адресу (наприклад, типовий zec.rocks).
Хочете self-host lightwalletd?
Ви можете використати docker-compose.lwd.yml із репозиторію Zebra.
Попередження: Ця конфігурація офіційно не документована й потребує ручного налаштування TLS, пробросу портів і конфігурації firewall — рекомендується лише для досвідчених користувачів.
Крок 4: Повторно запустіть інсталятор
. ./btcpay-setup.sh -i
BTCPay Server застосує вашу спеціальну конфігурацію та підключиться до вказаного вузла lightwalletd.
Відтепер плагін Zcash використовуватиме цю зовнішню адресу для обробки shielded-транзакцій.
Хостинг BTCPay Server вдома через Cloudflare Tunnel
Хочете приймати платежі в Zcash, хостячи BTCPay Server на домашньому пристрої — наприклад, Raspberry Pi 5 або будь-якому локальному сервері без статичної IP-адреси?
Ви можете безпечно відкрити доступ до свого екземпляра з інтернету за допомогою Cloudflare Tunnel.
Цей метод дозволяє уникнути пробросу портів і приховує вашу реальну IP-адресу від публіки, водночас зберігаючи доступність сервера через HTTPS.
Він також допомагає вам уникнути витрат на оренду VPS, що ідеально, якщо криптовалютні платежі є додатковою функцією, а не основою вашого бізнесу.
Крок 1: Встановіть Cloudflare Tunnel
- Створіть обліковий запис на cloudflare.com і додайте свій домен.
- На вашому домашньому сервері встановіть Cloudflare Tunnel за допомогою офіційного репозиторію пакетів Cloudflare:
Code-highlight
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
Якщо apt install cloudflared не спрацьовує, натомість установіть відповідний .deb:
Code-highlight
# 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
Code-highlight
# x86_64
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
- Пройдіть автентифікацію в Cloudflare:
cloudflared tunnel login
Ця команда відкриє вікно браузера. Увійдіть і надайте доступ до вашого домену.
Cloudflare автоматично створить на вашому сервері файл credentials із токеном.
- Створіть новий тунель (ви можете назвати його
btcpay або як завгодно інакше):
cloudflared tunnel create btcpay
Це згенерує файл btcpay.json, який містить ID тунелю та облікові дані — він знадобиться вам на наступному кроці.
Крок 2: Створіть файл конфігурації тунелю
Створіть директорію конфігурації (якщо її ще не існує) і відкрийте файл конфігурації:
Code-highlight
sudo mkdir -p /etc/cloudflared
sudo nano /etc/cloudflared/config.yml
Вставте таку конфігурацію:
Code-highlight
tunnel: btcpay # назва вашого тунелю
credentials-file: /root/.cloudflared/btcpay.json
ingress:
- hostname: btcpay.example.com # ваш домен
service: http://127.0.0.1:80
- service: http_status:404
Пояснення:
tunnel - назва тунелю, який ви створили ранішеcredentials-file - шлях до файла токена, згенерованого під час cloudflared tunnel loginhostname - ваш домен, зареєстрований у Cloudflare (наприклад, btcpay.example.com)service - локальна адреса вашого BTCPay Server (зазвичай http://127.0.0.1:80 для Nginx)
Cloudflare безпечно проксіюватиме трафік до вашого локального сервера, не розкриваючи вашу домашню IP-адресу.
Крок 3: Додайте DNS-запис для вашого тунелю
Після створення тунелю Cloudflare зазвичай автоматично додає DNS-запис CNAME для вашого домену. Він має виглядати так:
btcpay.example.com -> <UUID>.cfargotunnel.com
Якщо він не з’явиться автоматично, додайте його вручну:
- Перейдіть до своєї панелі керування Cloudflare
- Відкрийте розділ DNS
- Додайте новий запис CNAME:
Цей запис гарантує, що всі запити до btcpay.example.com маршрутизуються через Cloudflare Tunnel, приховуючи вашу реальну IP-адресу від публіки.
Крок 4: Увімкніть автоматичний запуск тунелю разом із системою
Щоб тунель автоматично запускався під час завантаження, встановіть його як системну службу:
sudo cloudflared service install
Потім увімкніть і запустіть службу:
Code-highlight
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
Перевірте статус:
sudo systemctl status cloudflared
Ви маєте побачити повідомлення на кшталт Active: active (running) і підтвердження, що btcpay.example.com доступний онлайн.
Відтепер тунель запускатиметься автоматично після кожного перезавантаження, а ваш BTCPay Server буде публічно доступний — без пробросу портів і без розкриття вашої реальної IP-адреси.
Крок 5: Завершіть налаштування BTCPay Server
Якщо ви збираєтеся встановлювати BTCPay Server уперше, задайте свій домен перед запуском скрипта налаштування:
export BTCPAY_HOST="btcpay.example.com"
Це гарантує, що правильний домен буде використано під час генерації конфігурації Nginx і SSL-сертифікатів.
Якщо BTCPay Server уже встановлено і ви просто додаєте тунель:
Code-highlight
cd ~/BTCPayServer/btcpayserver-docker
. ./btcpay-setup.sh -i
Налаштування перегенерує конфіги й застосує новий домен.
Тепер ви маєте змогу отримати доступ до свого сервера за адресою:
https://btcpay.example.com
Незалежно від того, використовуєте ви публічний lightwalletd чи власний повний вузол, це не впливає на тунель.
Має значення лише те, що BTCPay Server локально слухає на 127.0.0.1:80.
Налаштування плагіна Zcash у вебінтерфейсі BTCPay Server
Важливо для конфігурацій із кількома магазинами:
Гаманець Zcash, який налаштовується тут, є глобальним для екземпляра. Усі магазини використовуватимуть цей гаманець, якщо ви не запустите окремі екземпляри BTCPay.
Після успішного розгортання вашого екземпляра BTCPay Server вам потрібно буде виконати базове налаштування через вебінтерфейс адміністратора.
Офіційна документація містить повні інструкції англійською мовою — тут ми розглянемо основні кроки й зосередимося саме на налаштуванні плагіна Zcash.
Крок 1: Увійдіть до вебінтерфейсу
Відкрийте свій екземпляр за адресою:
[https://btcpay.example.com](https://btcpay.example.com)
- Введіть логін і пароль адміністратора.
- Якщо ви входите вперше, вам буде запропоновано створити обліковий запис.
- Перший обліковий запис, який ви зареєструєте, автоматично отримає права адміністратора.
Крок 2: Встановіть плагін Zcash
- У головному меню перейдіть до:
Plugins -> Browse Plugins
- Знайдіть плагін Zcash (ZEC). За потреби скористайтеся рядком пошуку.
- Натисніть Install і підтвердьте.
Повторіть цей процес для будь-яких інших альткоїнів, які ви ввімкнули під час налаштування сервера.
Після встановлення натисніть Restart Server, щоб перезавантажити інтерфейс з активними плагінами.
Крок 3: Підключіть свій гаманець через Viewing Key
Після встановлення плагіна в меню налаштувань з’явиться новий розділ Zcash.
- Перейдіть до:
Zcash -> Settings
- Вставте свій Unified Full Viewing Key (UFVK) — BTCPay виведе Unified Address для кожного рахунка й виявлятиме вхідні shielded-платежі.
Примітка: Застарілі viewing key Sapling підтримуються, але щоб використовувати Orchard/Unified Address, вам слід надати UFVK.
Приклад формату:
uview184syv9wftwngkay8d...
- Введіть значення в полі Block height
- Перше налаштування з новим гаманцем (нова seed-фраза): введіть поточну висоту блоку Zcash (її можна перевірити на 3xpl.com/zcash) — це пришвидшить початкове сканування.
- Міграція на тому самому сервері зі застарілої конфігурації лише з Sapling на Unified Address / Orchard: залиште це поле порожнім.
- Перенесення вашого магазину на новий сервер із тим самим гаманцем/UFVK: за бажання можна ввести birth height — приблизну висоту блоку першого оплаченого замовлення вашого магазину (зіставте дату замовлення на 3xpl, щоб звузити сканування). Якщо не впевнені — залиште поле порожнім.
Не всі гаманці вже підтримують експорт Unified Full Viewing Key (UFVK).
Рекомендовані варіанти:
– Zkool
– Zingo! Wallet (версія для ПК)
В обох застосунках шукайте експорт UFVK у розділі резервного копіювання/експорту.
Ці ключі підтримують автоматичну ротацію адрес, а це означає:
- Кожен клієнт отримує унікальну платіжну адресу
- Ви бачите єдиний, зведений баланс
Ширший список сумісності ви знайдете на ZecHub -> Wallets.
Щойно всі поля буде заповнено, натисніть Save.
Протестуйте свій потік платежів у ZEC
Вітаємо — ваш гаманець Zcash тепер підключено до BTCPay Server.
Тепер проведімо тест:
- Перейдіть до:
Invoices -> Create New
- Згенеруйте тестовий рахунок на невелику суму в ZEC.
- Надішліть кошти з іншого гаманця (не того, який підключено до BTCPay).
- Щойно транзакцію буде виявлено, сторінка рахунка покаже візуальне святкування.
- Переконайтеся, що статус рахунка зміниться на Paid.
Якщо все працює — ви готові інтегрувати платежі в ZEC на свій вебсайт за допомогою API або CMS-плагінів.
Інтеграція BTCPay Server із вашим вебсайтом
Після того як ваш гаманець Zcash підключено до BTCPay Server, ви можете інтегрувати платіжну систему у свій вебсайт.
Для цього є кілька способів — від прямого доступу через API до готових плагінів для популярних CMS-платформ.
Варіанти інтеграції
-
Інтеграція через API
Ідеально підходить для вебсайтів із кастомною розробкою або систем без CMS.
Дає вам повний контроль над створенням рахунків, відстеженням платежів і сповіщеннями — усе в межах вашого власного інтерфейсу та логіки.
Потребує базових навичок програмування, тому це завдання найкраще доручити вашому розробнику.
-
CMS-плагіни
Доступні для таких платформ, як WooCommerce, PrestaShop та інших.
Ці плагіни дозволяють приймати платежі всього за кілька хвилин — без потреби писати код.
-
Кнопка оплати або Iframe
Найпростіший метод.
Ідеально підходить для лендингів, персональних сайтів або будь-якого сайту, де ви просто хочете вбудувати посилання для донату чи віджет checkout.
Інтеграція через API
Якщо ви використовуєте кастомну платформу (або взагалі без CMS), API — це найкращий варіант.
Він дає вам повну гнучкість: ви можете створювати рахунки, відстежувати їхній статус, отримувати сповіщення та повністю контролювати користувацький досвід.
Примітка: Навіть деякі CMS-плагіни використовують API «під капотом», тому створення API-ключа часто є першим обов’язковим кроком, незалежно від способу інтеграції.
Наступний крок: згенеруйте API-ключ для свого магазину й почніть використовувати Greenfield API для побудови вашої інтеграції.
Створення API-ключа
Щоб інтегрувати BTCPay Server із вашим вебсайтом або застосунком, вам потрібно згенерувати API-ключ.
-
Увійдіть у BTCPay Server і відкрийте меню користувача (правий верхній кут)
-
Перейдіть до API Keys
-
Натисніть Create a new API key
-
Введіть назву для свого ключа
-
У розділі Permissions увімкніть:
Can create invoiceCan view invoice- (Необов’язково)
Can modify store settings - лише якщо вам потрібне керування на рівні магазину
-
Натисніть Generate. Ваш персональний API-ключ буде показано — скопіюйте його та зберігайте в безпечному місці.
Цей ключ надає доступ до рахунків вашого магазину.
Не діліться ним публічно і не розкривайте його в клієнтському коді.
Приклад: створення рахунка через API
Endpoint:
Code-highlight
POST /api/v1/stores/{storeId}/invoices
Authorization: token {apiKey}
Content-Type: application/json
Тіло запиту:
Code-highlight
{
"amount": 5,
"currency": "ZEC",
"checkout": {
"speedPolicy": "HighSpeed",
"paymentMethods": ["Zcash"]
}
}
Відповідь:
Ви отримаєте JSON-об’єкт із:
invoiceId- URL для оплати, який ви можете вбудувати на свій вебсайт або надіслати клієнту
Дивіться повну документацію:
Greenfield API – Create Invoice
Налаштування webhook (необов’язково)
Щоб отримувати сповіщення в реальному часі, коли змінюються статуси рахунків (наприклад, коли платіж отримано):
- Перейдіть до налаштувань вашого магазину -> Webhooks
- Додайте URL вашого backend endpoint, який оброблятиме
POST-запити від BTCPay Server
- BTCPay автоматично надсилатиме сповіщення, коли рахунок буде оплачено або коли його термін дії спливе
Webhook payloads і логіка повторних спроб описані в офіційній документації щодо webhook.
Приклади інтеграцій для різних мов програмування доступні в документації BTCPay і репозиторіях GitHub.
Інтеграція з CMS
BTCPay Server підтримує плагіни для популярних систем керування контентом (CMS).
Найзріліша й найпоширеніша інтеграція — з WordPress + WooCommerce, що дозволяє легко приймати платежі в ZEC без написання коду.
WooCommerce (WordPress)
BTCPay Server офіційно підтримує плагін для WooCommerce.
Кроки інтеграції:
- Встановіть плагін BTCPay for WooCommerce з каталогу плагінів WordPress або з GitHub.
- У панелі адміністратора WordPress перейдіть до:
WooCommerce -> Settings -> Payments
- Знайдіть BTCPay у списку та натисніть Set up
- Введіть URL вашого BTCPay Server і дотримуйтесь інструкцій з авторизації
(рекомендується автоматичне створення API-ключа)
- Увімкніть спосіб оплати та збережіть налаштування
Детальні інструкції, відеоуроки та посібники з усунення несправностей доступні в документації плагіна.
У тому ж розділі документації BTCPay ви також знайдете інші варіанти інтеграції з CMS.
Кнопка оплати або Iframe (CMS чи API не потрібні)
Якщо ви не використовуєте CMS і не хочете працювати з API, найпростіший спосіб приймати платежі в ZEC — це вбудувати посилання на оплату або віджет безпосередньо на вашому вебсайті.
Цей метод ідеально підходить для:
- Лендингів
- Портфоліо-сайтів
- Блогів або статичних сторінок
- Проєктів без backend-сервера
Варіант 1: Кнопка оплати (посилання)
- У BTCPay Server вручну створіть рахунок у розділі Invoices
- Скопіюйте посилання для оплати, наприклад:
[https://btcpay.example.com/i/abc123](https://btcpay.example.com/i/abc123)
- Додайте посилання до свого HTML:
Code-highlight
<a href="https://btcpay.example.com/i/abc123" target="_blank">
Оплатити в ZEC
</a>
Варіант 2: Вбудований рахунок (Iframe)
Щоб показати рахунок безпосередньо на вашому сайті, використайте iframe:
<iframe src="https://btcpay.example.com/i/abc123" width="600" height="350" frameborder="0"></iframe>
Ви можете стилізувати кнопку або контейнер iframe відповідно до дизайну вашого сайту — BTCPay Server дозволяє гнучко налаштовувати тему сторінки рахунка.
Висновок
Цей посібник вийшов довгим — але він охоплює лише базові аспекти інтеграції платежів Zcash із BTCPay Server.
Інтерфейс BTCPay Server пропонує набагато більше функцій, ніж ми показали тут. На щастя, UI доступний кількома мовами (зокрема російською), що робить подальше дослідження та експерименти простими.
BTCPay — це надзвичайно гнучкий інструмент. Ви можете:
- Хостити кілька незалежних магазинів на одному екземплярі
- Визначати власні ролі та дозволи для членів команди — від перегляду замовлень до повного адміністрування
- Використовувати власні домени та брендинг
- Налаштовувати webhook, резервні гаманці й навіть доступ через Tor
- Конфігурувати розширені параметри, як-от податкові правила, коди знижок, кастомізацію сторінки checkout, обмеження методів оплати тощо
BTCPay був створений як open-source альтернатива централізованим платіжним провайдерам. Якщо ви хочете приймати приватні платежі в ZEC без посередників, ця платформа безумовно заслуговує на вашу увагу.
Бажаємо вам успіху в дослідженні екосистеми BTCPay і в тому, щоб зробити свої платежі по-справжньому вашими.
Ресурси
