BTCPay Server with Zcash Support: Full Installation and Integration Guide

BTCPay Server allows online businesses to accept cryptocurrency payments directly, without intermediaries or custodians. This guide walks you through the complete process of setting up BTCPay Server with native support for Zcash shielded payments.

⚠️ This documentation focuses on integrating Zcash into your BTCPay Server instance.
It supports both full node (Zebra) and lightwalletd-based setups.

Table of Contents

• Why Use BTCPay Server with Zcash
• How BTCPay Server Works
• Where Are Funds Stored? Who Controls the Private Keys?
• How to Set Up BTCPay Server for Accepting Zcash
  • Deploying BTCPay Server with Zcash Support
  • Running Your Own Zcash Full Node (Zebra + Lightwalletd)
  • Connecting to an External lightwalletd Node (Custom Configuration)
  • Hosting BTCPay Server at Home with Cloudflare Tunnel
• Configuring the Zcash Plugin in the BTCPay Server Web Interface
• Integrating BTCPay Server with Your Website
  • API Integration
    • Generating an API Key
    • Example: Creating an Invoice via API
    • Setting Up a Webhook
  • CMS Integration
  • Payment Button or Iframe
• Conclusion
• Resources

Why Use BTCPay Server with Zcash

Online commerce increasingly accepts cryptocurrency. It’s fast, global, and works without banks. This benefits both merchants and customers. But there’s an important detail that many overlook.

When placing an order, the customer typically provides personal information: name, shipping address, and phone number. If the payment is made using a public blockchain — such as Bitcoin, Ethereum, or stablecoins on Ethereum or Tron — the transaction becomes permanently visible for analysis.

Anyone, even without knowing what was ordered, can:

• see when and how much was paid
• trace where the funds came from and where they went
• link a cryptocurrency address to a real person if there’s any point of correlation (for example, a leaked email or shipping name)

This means that a single purchase may reveal a customer’s entire financial history.

And it works the other way as well. If a merchant’s address has ever appeared on-chain, they become exposed. Competitors and third-party observers can track payment volumes, supplier activity, and the structure of business flows.

The combination of BTCPay Server and Zcash can solve this.

BTCPay Server is a free and decentralized system for receiving cryptocurrency payments.
It is not a payment intermediary and does not hold any funds. All payments go directly to the merchant’s wallet.
This can be a personal wallet or a multisig setup within an organization.

The server handles coordination tasks:

• generates a unique address for each order
• tracks when payment is received and links it to the order
• issues receipts and notifications
• provides a payment interface for the customer

Everything runs under the control of the store owner, without relying on third-party services.

Zcash is a cryptocurrency built on zero-knowledge proofs. It supports a fully private transaction model.
When using shielded addresses (hereafter simply called “addresses”), the sender, the recipient, and the transaction amount are not revealed on the blockchain.

For online stores, this means:

• The buyer can complete the payment without revealing their financial history
• The seller receives payment without exposing their address, sales volume, or transaction structure
• No external observer can link the payment to the order or to customer data

Practical Example

A user places an order and selects Bitcoin or USDT as the payment method.
The website generates a payment address and displays the amount.
After the payment is made, this address is stored on the blockchain and becomes public.
An attacker only needs to link one order to the address to gain long-term visibility into its entire transaction history.

Now imagine the same situation with Zcash.
BTCPay Server generates a shielded address. The buyer sends the payment.
From the blockchain’s perspective, nothing happens. There is no public data to analyze.
The server receives confirmation, links it to the order, and completes the process.

For any outsider, it looks like nothing occurred.
All logic remains between the store and the customer — as it should.

This solution doesn’t compromise automation or usability.
Everything works the same as with other cryptocurrencies, just without the risk of data leaks.

How BTCPay Server Works

BTCPay Server acts as a payment processing bridge between your e-commerce platform and the blockchain. Here's how the flow works:

1. The customer places an order on your website (e.g. WooCommerce, Magento, or any platform with BTCPay integration).

2. The store requests a payment invoice from BTCPay Server. The server generates a unique invoice with:

   • The order amount
   • A countdown timer
   • A Zcash address (e.g. a shielded zs... address)

3. The customer sees the payment page and sends ZEC to the provided address.

4. BTCPay Server monitors the blockchain, checking the payment against:

   • The expected amount
   • The receiving address
   • The invoice timestamp

5. Once the transaction is detected and confirmed, BTCPay notifies the store.

6. The customer receives a payment confirmation. Optionally, the server can send a receipt via email.

This entire process happens automatically, with no intermediaries or custodians.
BTCPay Server does not hold any funds — it simply connects the order system to the blockchain securely and privately.

Where Are Funds Stored? Who Controls the Private Keys?

BTCPay Server is not a wallet and does not require private keys.
All funds go directly to the merchant’s wallet. Security is ensured by using a viewing key-based architecture.

How It Works

• The wallet is created in advance.
  The merchant uses a Zcash wallet that supports viewing keys — such as YWallet or Zingo! Wallet .
  A full list is available at ZecHub.wiki .

• BTCPay Server connects via a viewing key.
  A viewing key is a read-only key: it can detect incoming payments and generate new receiving addresses,
  but it cannot spend funds. The server does not store seed phrases or private keys.

• Blockchain data is accessed through a lightwalletd server.
  You can use a public node like https://zec.rocks, or run your own Zebra + lightwalletd stack for full sovereignty.

• Each order gets a unique address.
  Viewing keys allow the server to derive new Zcash shielded addresses for every invoice,
  enabling secure payment tracking and preventing address reuse.

• You retain full control over the funds.
  Even if the server is compromised, no one can steal your money — only payment metadata could be exposed.

This design separates infrastructure from asset control.
You can update, migrate, or reinstall BTCPay Server without putting any funds at risk.

How to Set Up BTCPay Server for Accepting Zcash

In the previous sections, we explained how BTCPay Server works with Zcash and why it matters for privacy-preserving payments. Now it’s time to get hands-on.

Your exact setup will depend on several factors:

• Do you already have a BTCPay Server instance?
• Do you want to use a public lightwalletd or run your own full node?
• Will the server run on a VPS or at home?

This chapter covers all current configuration scenarios — from minimal setups to fully sovereign deployments.

We’ll walk through the following:

• How to deploy everything from scratch on a VPS, including the full node (Zebra)
• How to run BTCPay Server at home while keeping your IP hidden using Cloudflare Tunnel
• How to enable and configure Zcash support inside the BTCPay Server web interface
• How to integrate BTCPay with your website or online store

Deploying BTCPay Server with Zcash Support

Let’s move on to the actual setup. In this section, we’ll install BTCPay Server with Zcash support — either on a fresh VPS or by adding ZEC support to an existing instance.

If you already have BTCPay Server running (e.g. for BTC or Lightning), you don’t need to reinstall everything — just enable the ZEC plugin.

We’ll walk through various configurations, from minimal setups using a public lightwalletd node to fully sovereign installations with your own full node.
The best option depends on your server location and how much independence you want from external infrastructure.

🧭 Official plugin documentation:
https://github.com/btcpay-zcash/btcpayserver-zcash-plugin

Recommended VPS Configuration

Before installing, make sure you have:

• A VPS with Ubuntu 22.04+
• A domain name pointing to your server’s IP address (via DNS)
• git, docker, and docker-compose installed
• SSH access to the server

Preparing Your Server (hidden part)

ssh root@YOUR_SERVER_IP

sudo apt update && sudo apt upgrade -y
sudo apt install git curl docker.io docker-compose-plugin -y
sudo systemctl enable docker

Step 1: Clone the Repository

Create a working directory and download the BTCPay Server Docker deployment:

mkdir BTCPayServer
cd BTCPayServer
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

Step 2: Export Environment Variables

Replace btcpay.example.com with your actual domain:

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"

💡 If you plan to add Monero or Litecoin later, you can include them now:

export BTCPAYGEN_CRYPTO3="ltc"
export BTCPAYGEN_CRYPTO4="xmr"

You can add new coins at any time by exporting the appropriate variables and rerunning the setup script:

. ./btcpay-setup.sh -i

For this guide, we’ll focus on Zcash only.

Step 3: Run the Installer

Run the setup script to build and launch the server:

. ./btcpay-setup.sh -i

The script will install dependencies, generate the docker-compose.yml, start services, and configure systemd. This takes about 5 minutes.

Once complete, your BTCPay Server instance will be available at:

https://btcpay.example.com

💡 If you’re modifying an existing installation (e.g. adding ZEC), be sure to stop and restart the server with new settings:

cd ~/BTCPayServer/btcpayserver-docker
btcpay-down.sh
. ./btcpay-setup.sh -i

Then proceed to the next section to configure Zcash in the BTCPay Server web interface.

Running Your Own Zcash Full Node (Zebra + Lightwalletd)

If you prefer not to rely on public lightwalletd nodes, you can deploy your own full Zcash node along with Lightwalletd on the same server.
This gives you full autonomy — no external dependencies, no trust required.

Step 1: Ensure Sufficient Disk Space

A full Zcash node (Zebra + Lightwalletd) currently requires 300+ GB of disk space, and it continues to grow.

Breakdown:

• The Zebra blockchain database: ~260–270 GB
• Lightwalletd indexing: ~15–20 GB

Recommended storage:

• 400 GB+ if the server is used only for Zcash payments
• 800 GB+ if the server also runs BTCPay Server, PostgreSQL, Nginx, etc.

💡 Ideally use an SSD/NVMe disk with 1 TB capacity, especially if you don’t plan to prune data regularly.

Step 2: Set Environment Variables

Append the following to your environment setup to activate the full node configuration:

export BTCPAYGEN_EXCLUDE_FRAGMENTS="zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="zcash-fullnode"

This will include the zcash-fullnode fragment, which launches both zebrad and lightwalletd inside BTCPay Server.

Step 3: Re-run the Installer

. ./btcpay-setup.sh -i

The script will:

• Download the Docker images for Zebra and Lightwalletd
• Set up the services inside the BTCPay stack
• Link the Zcash plugin to the local lightwalletd instance

⏳ Full blockchain sync may take several days, especially on low-resource VPS servers. Until synchronization completes, shielded payments will not be available.

Connecting to an External lightwalletd Node (Custom Configuration)

In most cases, full autonomy isn’t required — and merchants may not want to spend time and disk space running a full Zcash node.
By default, BTCPay Server connects to a public lightwalletd node to handle shielded payments without downloading the entire blockchain.

The default endpoint is:

https://zec.rocks:443

However, you can configure BTCPay Server to connect to any external lightwalletd node, such as:

https://lightwalletd.example:443

This section shows how to do that using a custom Docker fragment.

💡 A complete config example with all environment variables is available in the plugin repository .
The steps below show a minimal working setup.

Step 1: Create a Custom Docker Fragment

In your BTCPayServer project directory, create a custom fragment file:

cd ~/BTCPayServer/btcpayserver-docker
mkdir -p docker-compose-generator/docker-fragments
nano docker-compose-generator/docker-fragments/zcash-lightwalletd.custom.yml

Add the following content:

exclusive:
- zcash

The exclusive directive ensures that only one fragment with the same label (zcash in this case) can be active at a time. This prevents configuration conflicts — for example, you cannot run both the zcash-fullnode fragment and this custom external lightwalletd fragment simultaneously. By marking it as exclusive: zcash, BTCPay Server will automatically disable the default zcash-fullnode and internal lightwalletd containers, allowing you to connect to your own external node instead.

Step 2: Set Environment Variables

In the terminal:

export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;zcash-lightwalletd.custom"

Step 3: Define the External Node Address

Open your .env file:

nano .env

Add the following line, replacing the URL with your chosen endpoint:

ZCASH_LIGHTWALLETD=https://lightwalletd.example:443

You can use:

• A public node, such as https://lightwalletd.zcash-infra.com
• Your own self-hosted node, deployed separately from BTCPay Server

⚠️ If the external lightwalletd becomes unavailable or overloaded, shielded payments will fail. For critical services, choose a stable and proven endpoint (like the default zec.rocks).

💡 Want to self-host lightwalletd? You can use the docker-compose.lwd.yml from the Zebra repository . Warning: This setup is not officially documented and requires manual TLS setup, port forwarding, and firewall configuration — recommended for advanced users only.

Step 4: Re-run the Installer

. ./btcpay-setup.sh -i

BTCPay Server will apply your custom config and connect to the specified lightwalletd node.

From now on, the Zcash plugin will use that external endpoint for handling shielded transactions.

Hosting BTCPay Server at Home with Cloudflare Tunnel

Want to accept Zcash payments while hosting BTCPay Server on a home device — like a Raspberry Pi 5 or any local server without a static IP?
You can securely expose your instance to the internet using Cloudflare Tunnel.

This method avoids port forwarding and hides your real IP address from the public — while keeping your server accessible over HTTPS.

It also helps you avoid the cost of renting a VPS, which is ideal if cryptocurrency payments are an optional feature rather than the core of your business.

Step 1: Install Cloudflare Tunnel

1. Create an account at cloudflare.com and add your domain.
2. On your home server, install Cloudflare Tunnel:

sudo apt update
sudo apt install cloudflared --legacy

3. Authenticate with Cloudflare:

cloudflared tunnel login

This command will open a browser window. Log in and authorize access to your domain. Cloudflare will automatically create a credentials file with a token on your server.

4. Create a new tunnel (you can name it btcpay or anything else):

cloudflared tunnel create btcpay

This generates a btcpay.json file containing the tunnel ID and credentials — you’ll need it in the next step.

Step 2: Create Tunnel Configuration File

Create the configuration directory (if it doesn’t exist) and open the config file:

sudo mkdir -p /etc/cloudflared
sudo nano /etc/cloudflared/config.yml

Paste the following configuration:

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

Explanation:

• tunnel — name of the tunnel you created earlier
• credentials-file — path to the token file generated during cloudflared tunnel login
• hostname — your domain registered with Cloudflare (e.g. btcpay.example.com)
• service — local address of your BTCPay Server (usually http://127.0.0.1:80 for Nginx)

💡 Cloudflare will proxy traffic securely to your local server, without exposing your home IP.

Step 3: Add a DNS Record for Your Tunnel

After creating the tunnel, Cloudflare will usually automatically add a CNAME DNS record for your domain. It should look like this:

btcpay.example.com → <UUID>.cfargotunnel.com

If it doesn’t appear automatically, add it manually:

1. Go to your Cloudflare Dashboard
2. Navigate to the DNS section
3. Add a new CNAME record:
   • Name: btcpay
   • Target: <UUID>.cfargotunnel.com
     You can find the exact value in your btcpay.json file or by running:

     cloudflared tunnel list
     

   • Proxy status: Enabled (orange cloud)

💡 This record ensures that all requests to btcpay.example.com are routed through the Cloudflare Tunnel, hiding your real IP address from the public.

Step 4: Enable Tunnel on System Startup

To make the tunnel run automatically at boot, install it as a system service:

sudo cloudflared service install

Then enable and start the service:

sudo systemctl enable cloudflared
sudo systemctl start cloudflared

Check the status:

sudo systemctl status cloudflared

You should see a message like Active: active (running) and confirmation that btcpay.example.com is online.

✅ From now on, the tunnel will start automatically on every reboot, and your BTCPay Server will be publicly accessible — without port forwarding and without exposing your real IP.

Step 5: Finalize BTCPay Server Setup

If you're about to install BTCPay Server for the first time, set your domain before running the setup script:

export BTCPAY_HOST="btcpay.example.com"

This ensures the correct domain is used when generating the Nginx configuration and SSL certificates.

If BTCPay Server is already installed and you're just adding the tunnel:

cd ~/BTCPayServer/btcpayserver-docker
. ./btcpay-setup.sh -i

The setup will regenerate configs and apply the new domain. You should now be able to access your server at:

https://btcpay.example.com

💡 Whether you're using a public lightwalletd or your own full node, this does not affect the tunnel. All that matters is that BTCPay Server is listening on 127.0.0.1:80 locally.

Configuring the Zcash Plugin in the BTCPay Server Web Interface

After successfully deploying your BTCPay Server instance, you’ll need to perform some basic configuration via the admin web interface.
The official documentation provides full instructions in English — here, we'll walk through the essential steps and focus specifically on configuring the Zcash plugin.

Step 1: Log in to the Web Interface

Visit your instance at:

[https://btcpay.example.com](https://btcpay.example.com)

• Enter your administrator login and password.
• If this is your first time logging in, you’ll be prompted to create an account.
• The first account you register will automatically be assigned admin privileges.

Step 2: Install the Zcash Plugin

1. In the main menu, go to:

Plugins → Browse Plugins

2. Locate the Zcash (ZEC) plugin. Use the search bar if needed.
3. Click Install and confirm.

💡 Repeat this process for any other altcoins you enabled during server configuration.

After installation, click Restart Server to reload the interface with the active plugins.

Step 3: Connect Your Wallet via Viewing Key

After installing the plugin, a new Zcash section will appear in the settings menu.

1. Go to:

Zcash → Settings

2. Paste your viewing key — this allows BTCPay to detect incoming shielded payments.

   Example format:

zxviewtestsapling1q0hl2...

3. Enter the current Zcash block height — syncing will begin from this block to speed up initialization and skip unnecessary transaction history.

💡 Not all Zcash wallets currently support viewing key export.
Recommended options:

• YWallet
• Zingo! Wallet

In both apps, you’ll find viewing keys in the backup section.
In Zingo!, make sure to use the Sapling viewing key — this is the type supported by BTCPay Server.

These keys support automatic address rotation, meaning:

• Every customer gets a unique payment address
• You see a single, unified balance

You can find a full wallet compatibility list on ZecHub → Wallets

Once all fields are filled out, click Save.

✅ Test Your ZEC Payment Flow

Congratulations — your Zcash wallet is now connected to BTCPay Server.

Let’s run a test:

1. Go to:

Invoices → Create New

2. Generate a test invoice for a small amount in ZEC.
3. Send funds from a different wallet (not the one connected to BTCPay).
4. Once the transaction is detected, the invoice page will display a visual celebration 🎉.
5. Confirm that the invoice status changes to Paid.

If everything works — you're ready to integrate ZEC payments into your website using the API or CMS plugins.

Integrating BTCPay Server with Your Website

Once your Zcash wallet is connected to BTCPay Server, you can integrate the payment system into your website.
There are several ways to do this — from direct API access to ready-to-use plugins for popular CMS platforms.

Integration Options

• API Integration
  Ideal for custom-built websites or systems without a CMS.
  Gives you full control over invoice creation, payment tracking, and notifications — all within your own interface and logic.
  Requires basic programming knowledge, so this task is best handled by your developer.

• CMS Plugins
  Available for platforms like WooCommerce, PrestaShop, and others.
  These plugins allow you to accept payments in just a few minutes — no coding required.

• Payment Button or Iframe
  The simplest method.
  Perfect for landing pages, personal websites, or any site where you just want to embed a donation link or checkout widget.

API Integration

If you're using a custom platform (or no CMS at all), the API is the best option.
It gives you complete flexibility: you can create invoices, track their status, receive notifications, and fully control the user experience.

📌 Note: Even some CMS plugins use the API under the hood, so creating an API key is often the first required step, regardless of your integration method.

Next step: generate an API key for your store and start using the Greenfield API to build your integration.

Generating an API Key

To integrate BTCPay Server with your website or app, you'll need to generate an API key.

1. Log in to BTCPay Server and open the user menu (top-right corner)

2. Go to API Keys

3. Click Create a new API key

4. Enter a name for your key

5. In the Permissions section, enable:

   • Can create invoice
   • Can view invoice
   • (Optional) Can modify store settings — only if you need store-level management

6. Click Generate. Your personal API key will be displayed — copy and store it securely.

⚠️ This key grants access to your store’s invoices.
Do not share it publicly or expose it in client-side code.

Example: Creating an Invoice via API

Endpoint:

POST /api/v1/stores/{storeId}/invoices
Authorization: token {apiKey}
Content-Type: application/json

Request body:

{
  "amount": 5,
  "currency": "ZEC",
  "checkout": {
    "speedPolicy": "HighSpeed",
    "paymentMethods": ["Zcash"]
  }
}

Response:

You’ll receive a JSON object with:

• invoiceId
• A payment URL that you can embed on your website or send to the customer

See full documentation: Greenfield API – Create Invoice

Setting Up a Webhook (Optional)

To receive real-time notifications when invoice statuses change (e.g. when a payment is received):

1. Go to your store settings → Webhooks
2. Add the URL of your backend endpoint that will handle POST requests from BTCPay Server
3. BTCPay will automatically send notifications when an invoice is paid or expires

Webhook payloads and retry logic are described in the official webhook documentation .

🧩 Example integrations are available for various programming languages in the BTCPay docs and GitHub repositories.

CMS Integration

BTCPay Server supports plugins for popular content management systems (CMS).
The most mature and widely used integration is with WordPress + WooCommerce, making it easy to accept ZEC payments without writing code.

WooCommerce (WordPress)

BTCPay Server officially supports a plugin for WooCommerce.

Steps to integrate:

1. Install the BTCPay for WooCommerce plugin from the WordPress plugin directory or from GitHub.
2. In your WordPress admin panel, go to:

WooCommerce → Settings → Payments

3. Find BTCPay in the list and click Set up
4. Enter your BTCPay Server URL and follow the authorization instructions
   (automatic API key generation is recommended)
5. Enable the payment method and save your settings

💡 Detailed instructions, video tutorials, and troubleshooting guides are available in the plugin documentation.

You’ll also find other CMS integration options in that same section of the BTCPay docs.

Payment Button or Iframe (No CMS or API Needed)

If you don’t use a CMS and don’t want to work with APIs, the easiest way to accept ZEC payments is to embed a payment link or widget directly on your website.

This method is ideal for:

• Landing pages
• Portfolio sites
• Blogs or static pages
• Projects without a backend server

Option 1: Payment Button (Link)

1. In BTCPay Server, manually create an invoice in the Invoices section
2. Copy the payment link, e.g.:

[https://btcpay.example.com/i/abc123](https://btcpay.example.com/i/abc123)

3. Add the link to your HTML:

<a href="https://btcpay.example.com/i/abc123" target="_blank">
  Pay with ZEC
</a>

Option 2: Embedded Invoice (Iframe)

To display the invoice directly on your site, use an iframe:

<iframe src="https://btcpay.example.com/i/abc123" width="600" height="350" frameborder="0"></iframe>

💡 You can style the button or iframe container to match your site’s design — BTCPay Server allows flexible theming of the invoice page.

Conclusion

This guide was long — but it only covers the foundational aspects of integrating Zcash payments with BTCPay Server.

The BTCPay Server interface offers far more functionality than we've shown here. Luckily, the UI is available in multiple languages (including Russian), making it easy to explore and experiment further.

BTCPay is a highly flexible tool. You can:

• Host multiple independent stores on a single instance
• Define custom roles and permissions for team members — from order view-only to full admin
• Use your own domains and branding
• Set up webhooks, fallback wallets, and even Tor access
• Configure advanced settings such as tax rules, discount codes, checkout page customization, payment method restrictions, and more

BTCPay was built as an open-source alternative to centralized payment providers. If you're looking to accept private ZEC payments with no intermediaries, this platform is absolutely worth your attention.

We wish you success exploring the BTCPay ecosystem and making your payments truly yours.

Resources

• BTCPay Server Official Website
• BTCPay FAQ
• BTCPay Server GitHub Repository
• BTCPay Server Mainnet Demo
• Zcash Plugin for BTCPay (GitHub)
• Zcash Plugin Installation Guide
• Custom zcash-lightwalletd.custom.yml Example
• Lightwalletd Docker Compose File (Zebra)
• BTCPay API Key Docs (Greenfield API)
• Create a Cloudflare Tunnel
• Zcash Wallet Compatibility List (ZecHub)
• Zebra + Lightwalletd on Raspberry Pi 5 (ZecHub)