BTCPay Server Integration

BTCPay Server Integration

BTCPay Server — self-hosted Bitcoin payment processor. No third party, no KYC for seller, no fees except on-chain. For a business that wants to accept BTC/LTC/Monero without dependence on Coinbase Commerce or BitPay — this is the standard choice. Integration takes from several hours to several days depending on customization depth.

What BTCPay Server is Internally

BTCPay is a .NET application that runs its own or connects to external full nodes (Bitcoin Core, LND for Lightning, Electrum server). Scheme:

Your website → BTCPay API → Bitcoin Full Node
                      → Lightning Network (LND / CLN)
                      → Electrum Server (for Altcoins)

For production deployment you need a VPS with minimum 2 CPU / 4 GB RAM / 500 GB SSD (Bitcoin blockchain ~600 GB). BTCPay Docker Compose deploys everything automatically.

BTCPay Server Deployment

# On Ubuntu 22.04
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

export BTCPAY_HOST="pay.yourdomain.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_LIGHTNING="lnd"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"

. ./btcpay-setup.sh -i

opt-save-storage enables Bitcoin pruned mode (stores only last ~1 GB of blocks). For Electrum indexing, you need a full node, but for basic payment acceptance, pruned is sufficient.

API: Creating Invoices

BTCPay Greenfield API v1 — RESTful, documentation at /docs:

const BTCPAY_BASE = 'https://pay.yourdomain.com';
const STORE_ID = process.env.BTCPAY_STORE_ID!;
const API_KEY = process.env.BTCPAY_API_KEY!;  // Generated in BTCPay → Account → API Keys

async function createInvoice(params: {
  amount: number;
  currency: string;
  orderId: string;
  buyerEmail?: string;
}): Promise<BTCPayInvoice> {
  const response = await fetch(
    `${BTCPAY_BASE}/api/v1/stores/${STORE_ID}/invoices`,
    {
      method: 'POST',
      headers: {
        'Authorization': `token ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        amount: params.amount.toString(),
        currency: params.currency,  // 'USD', 'EUR' — BTCPay converts to BTC
        metadata: {
          orderId: params.orderId,
          buyerEmail: params.buyerEmail,
        },
        checkout: {
          speedPolicy: 'MediumSpeed',  // 2 confirmations
          expirationMinutes: 30,
          redirectURL: `https://yourshop.com/orders/${params.orderId}`,
          defaultPaymentMethod: 'BTC',
        },
      }),
    }
  );

  return response.json();
}

speedPolicy:

• HighSpeed — 0 confirmations (mempool), only for trusted customers or Lightning
• MediumSpeed — 1 confirmation (~10 min)
• LowMediumSpeed — 2 confirmations
• LowSpeed — 6 confirmations (~1 hour)

Webhook: Processing Payment Events

In BTCPay Store Settings → Webhooks add URL and secret:

import { createHmac } from 'crypto';

app.post('/webhooks/btcpay', express.raw({ type: 'application/json' }), async (req, res) => {
  // Verify signature
  const signature = req.headers['btcpay-sig1'] as string;
  const expectedSig = 'sha256=' + createHmac('sha256', process.env.BTCPAY_WEBHOOK_SECRET!)
    .update(req.body)
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());

  switch (event.type) {
    case 'InvoiceSettled':
      // Paid and confirmed according to speedPolicy
      await fulfillOrder(event.metadata.orderId);
      break;

    case 'InvoiceExpired':
      await cancelOrder(event.metadata.orderId);
      break;

    case 'InvoicePaymentSettled':
      // Specific payment confirmed (relevant for partial payments)
      break;
  }

  res.sendStatus(200);
});

Important: always verify HMAC signature. BTCPay retries webhook delivery if response is unsuccessful.

Lightning Network: Payments in Seconds

If you enabled LND during deployment — Lightning works out of the box:

// Invoice specifically for Lightning
const lightningInvoice = await fetch(
  `${BTCPAY_BASE}/api/v1/stores/${STORE_ID}/lightning/BTC/invoices`,
  {
    method: 'POST',
    headers: { 'Authorization': `token ${API_KEY}` },
    body: JSON.stringify({
      amount: '1000',  // in millisatoshis
      description: `Order ${orderId}`,
      expiry: 900,  // 15 minutes
    }),
  }
).then(r => r.json());

// Returns BOLT11 payment request for QR code
console.log(lightningInvoice.BOLT11);

For Lightning: channels need to be opened and inbound liquidity maintained. For small shops — 1–2 channels with major hub nodes (ACINQ, WalletOfSatoshi) are enough.

Custom Checkout

BTCPay allows checkout customization via Templates or using Payment Request UI. For complete UX control — embedded checkout via iframe:

<iframe
  src="https://pay.yourdomain.com/i/{invoiceId}"
  style="width: 100%; height: 600px; border: none;"
  allow="payment"
>
</iframe>

Or listen for events via postMessage:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://pay.yourdomain.com') return;
  if (event.data === 'invoiceSettled') {
    // Payment succeeded, update UI
    redirectToThankYouPage();
  }
});

Multi-Currency

BTCPay supports LTC, XMR, ETH (via NBXplorer) and others. During deployment add:

export BTCPAYGEN_CRYPTO2="ltc"
export BTCPAYGEN_CRYPTO3="xmr"

For ETH and ERC-20 — separate plugin BTCPayServer.Plugins.Ethereum in settings.

Backup

Critical data for backup:

• LND wallet seed phrase (~/.lnd/data/chain/bitcoin/mainnet/wallet.db)
• BTCPay database (PostgreSQL: btcpayserver)
• Store settings and API keys (export from UI)

Loss of LND wallet seed = loss of funds in open channels. Backup is mandatory before opening any channels.