BTCPay Server с поддержкой Zcash: полное руководство по установке и интеграции
BTCPay Server позволяет онлайн-бизнесу принимать криптовалютные платежи напрямую, без посредников и кастодианов. Это руководство проведёт вас через весь процесс настройки BTCPay Server с нативной поддержкой защищённых платежей Zcash.
Эта документация посвящена интеграции Zcash в ваш экземпляр BTCPay Server.
Поддерживаются как полноузловые конфигурации (Zebra), так и конфигурации на базе lightwalletd.
Содержание
Почему стоит использовать BTCPay Server с Zcash
Онлайн-торговля всё чаще принимает криптовалюту. Это быстро, глобально и работает без банков. Это выгодно и продавцам, и покупателям. Но есть важная деталь, которую многие упускают.
При оформлении заказа клиент обычно предоставляет личную информацию: имя, адрес доставки и номер телефона. Если оплата производится через публичный блокчейн — такой как Bitcoin, Ethereum или стейблкоины в сетях Ethereum или Tron, — транзакция становится навсегда доступной для анализа.
Любой человек, даже не зная, что именно было заказано, может:
- увидеть, когда и сколько было оплачено
- отследить, откуда пришли средства и куда они ушли
- связать криптовалютный адрес с реальным человеком, если существует хоть какая-то точка корреляции (например, утёкший email или имя для доставки)
Это означает, что одна единственная покупка может раскрыть всю финансовую историю клиента.
И это работает и в обратную сторону. Если адрес продавца хоть раз появился в блокчейне, он становится уязвимым для наблюдения. Конкуренты и сторонние наблюдатели могут отслеживать объёмы платежей, активность поставщиков и структуру бизнес-потоков.
Комбинация BTCPay Server и Zcash может решить эту проблему.
BTCPay Server — это бесплатная и децентрализованная система для приёма криптовалютных платежей.
Это не платёжный посредник и не хранитель средств. Все платежи идут напрямую на кошелёк продавца.
Это может быть личный кошелёк или multisig-конфигурация внутри организации.
Сервер выполняет координационные задачи:
- генерирует уникальный адрес для каждого заказа
- отслеживает поступление платежа и связывает его с заказом
- выдаёт квитанции и уведомления
- предоставляет клиенту интерфейс оплаты
Всё работает под контролем владельца магазина, без зависимости от сторонних сервисов.
Zcash — это криптовалюта, построенная на доказательствах с нулевым разглашением. Она поддерживает полностью приватную модель транзакций.
При использовании защищённых адресов (далее просто «адресов») отправитель, получатель и сумма транзакции не раскрываются в блокчейне.
Для интернет-магазинов это означает:
- Покупатель может совершить оплату, не раскрывая свою финансовую историю
- Продавец получает платёж, не раскрывая свой адрес, объём продаж или структуру транзакций
- Ни один внешний наблюдатель не может связать платёж с заказом или с данными клиента
Практический пример
Пользователь оформляет заказ и выбирает Bitcoin или USDT в качестве способа оплаты.
Сайт генерирует платёжный адрес и показывает сумму.
После совершения платежа этот адрес сохраняется в блокчейне и становится публичным.
Злоумышленнику достаточно связать один заказ с этим адресом, чтобы получить долгосрочную видимость всей его истории транзакций.
А теперь представьте ту же ситуацию с Zcash.
BTCPay Server генерирует защищённый адрес. Покупатель отправляет платёж.
С точки зрения блокчейна ничего не происходит. Нет публичных данных для анализа.
Сервер получает подтверждение, связывает его с заказом и завершает процесс.
Для любого постороннего это выглядит так, будто ничего не произошло.
Вся логика остаётся между магазином и клиентом — как и должно быть.
Это решение не жертвует ни автоматизацией, ни удобством использования.
Всё работает так же, как и с другими криптовалютами, только без риска утечки данных.
Как работает BTCPay Server
BTCPay Server выступает платёжным мостом между вашей платформой электронной коммерции и блокчейном. Вот как работает этот процесс:
-
Клиент оформляет заказ на вашем сайте (например, WooCommerce, Magento или любой другой платформе с интеграцией BTCPay).
-
Магазин запрашивает платёжный инвойс у BTCPay Server. Сервер генерирует уникальный инвойс с:
- Суммой заказа
- Таймером обратного отсчёта
- Zcash Unified Address (UA) — например,
u1... — который по умолчанию включает Orchard (защищённый) приёмник.
-
Клиент видит страницу оплаты и отправляет ZEC на указанный адрес.
-
BTCPay Server отслеживает блокчейн, проверяя платёж по:
- Ожидаемой сумме
- Адресу получения
- Временной метке инвойса
-
Как только транзакция обнаружена и подтверждена, BTCPay уведомляет магазин.
-
Клиент получает подтверждение оплаты. При желании сервер может отправить квитанцию по email.
Весь этот процесс происходит автоматически, без посредников и кастодианов.
BTCPay Server не хранит никакие средства — он просто безопасно и приватно соединяет систему заказов с блокчейном.
Где хранятся средства? Кто контролирует приватные ключи?
BTCPay Server не является кошельком и не требует приватных ключей.
Все средства поступают напрямую в кошелёк продавца. Безопасность обеспечивается благодаря архитектуре на основе viewing key.
Как это работает
-
Кошелёк создаётся заранее.
Продавец использует Zcash-кошелёк, поддерживающий viewing keys, — например, Zkool или Zingo! Wallet.
Полный список доступен на ZecHub.wiki.
-
BTCPay Server подключается через viewing key.
Viewing key — это ключ только для чтения: он может обнаруживать входящие платежи и генерировать новые адреса получения,
но не может тратить средства. Сервер не хранит seed-фразы или приватные ключи.
-
Данные блокчейна доступны через сервер lightwalletd.
Вы можете использовать публичный узел, такой как https://zec.rocks, или запустить собственный стек Zebra + lightwalletd для полного суверенитета.
-
Для каждого заказа создаётся уникальный адрес.
Viewing key позволяют серверу выводить новые защищённые адреса 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-серверах с ограниченными ресурсами.
Пока синхронизация не завершена, защищённые платежи будут недоступны.
Подключение к внешнему узлу lightwalletd
Во многих случаях полная автономия не требуется — и продавцы могут не захотеть тратить время и дисковое пространство на запуск полного узла Zcash.
По умолчанию BTCPay Server подключается к публичному узлу lightwalletd, чтобы обрабатывать защищённые платежи без загрузки всего блокчейна.
Конечная точка по умолчанию:
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 станет недоступен или перегружен, защищённые платежи перестанут работать.
Для критически важных сервисов выбирайте стабильную и проверенную конечную точку (например, zec.rocks по умолчанию).
Хотите самостоятельно разместить lightwalletd?
Вы можете использовать docker-compose.lwd.yml из репозитория Zebra.
Предупреждение: Эта конфигурация официально не документирована и требует ручной настройки TLS, проброса портов и конфигурации файрвола — рекомендуется только для опытных пользователей.
Шаг 4: Повторно запустите установщик
. ./btcpay-setup.sh -i
BTCPay Server применит вашу пользовательскую конфигурацию и подключится к указанному узлу lightwalletd.
С этого момента плагин Zcash будет использовать эту внешнюю конечную точку для обработки защищённых транзакций.
Размещение 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 обычно автоматически добавляет CNAME DNS-запись для вашего домена. Она должна выглядеть так:
btcpay.example.com -> <UUID>.cfargotunnel.com
Если она не появилась автоматически, добавьте её вручную:
- Перейдите в Cloudflare Dashboard
- Откройте раздел 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 для каждого инвойса и обнаруживать входящие защищённые платежи.
Примечание: Устаревшие viewing key Sapling поддерживаются, но для использования Orchard/Unified Addresses вам следует предоставить UFVK.
Пример формата:
uview184syv9wftwngkay8d...
- Введите значение в поле высоты блока
- Первичная настройка с новым кошельком (новая seed-фраза): введите текущую высоту блока Zcash (её можно посмотреть на 3xpl.com/zcash) — это ускорит начальное сканирование.
- Миграция на том же сервере с устаревшей конфигурации только Sapling на Unified Addresses / 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
Самый простой способ.
Отлично подходит для лендингов, персональных сайтов или любых сайтов, где вы просто хотите встроить ссылку для пожертвований или виджет оплаты.
Интеграция через 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-конечной точки, которая будет обрабатывать
POST-запросы от BTCPay Server
- BTCPay будет автоматически отправлять уведомления, когда инвойс оплачен или истёк
Форматы payload webhook и логика повторных попыток описаны в официальной документации по 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
- Конфигурировать расширенные параметры, такие как налоговые правила, коды скидок, кастомизация страницы оформления заказа, ограничения способов оплаты и многое другое
BTCPay был создан как open-source-альтернатива централизованным платёжным провайдерам. Если вы хотите принимать приватные платежи в ZEC без посредников, эта платформа определённо заслуживает вашего внимания.
Желаем вам успехов в изучении экосистемы BTCPay и в том, чтобы ваши платежи действительно принадлежали вам.
Ресурсы
