Интеграция с BTCPay Server

Интеграция с BTCPay Server

BTCPay Server — self-hosted процессор биткоин-платежей. Никакой третьей стороны, никакой KYC для продавца, никаких комиссий кроме on-chain. Для бизнеса, который хочет принимать BTC/LTC/Monero без зависимости от Coinbase Commerce или BitPay — это стандартный выбор. Интеграция занимает от нескольких часов до нескольких дней в зависимости от глубины кастомизации.

Что такое BTCPay Server изнутри

BTCPay — это .NET приложение, которое запускает собственные или подключается к внешним полным нодам (Bitcoin Core, LND для Lightning, Electrum server). Схема:

Ваш сайт → BTCPay API → Bitcoin Full Node
                      → Lightning Network (LND / CLN)
                      → Electrum Server (для Altcoins)

Для production развёртывания нужен VPS с минимум 2 CPU / 4 GB RAM / 500 GB SSD (Bitcoin blockchain ~600 GB). BTCPay Docker Compose разворачивает всё автоматически.

Деплой BTCPay Server

# На 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 включает Bitcoin pruned mode (хранит только последние ~1 GB блоков). Для Electrum-индексирования нужен full node, но для базового приёма платежей pruned достаточен.

API: создание инвойса

BTCPay Greenfield API v1 — RESTful, документация на /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 сам конвертирует в BTC
        metadata: {
          orderId: params.orderId,
          buyerEmail: params.buyerEmail,
        },
        checkout: {
          speedPolicy: 'MediumSpeed',  // 2 подтверждения
          expirationMinutes: 30,
          redirectURL: `https://yourshop.com/orders/${params.orderId}`,
          defaultPaymentMethod: 'BTC',
        },
      }),
    }
  );

  return response.json();
}

speedPolicy:

• HighSpeed — 0 подтверждений (mempool), только для доверенных покупателей или Lightning
• MediumSpeed — 1 подтверждение (~10 мин)
• LowMediumSpeed — 2 подтверждения
• LowSpeed — 6 подтверждений (~1 час)

Webhook: обработка событий оплаты

В BTCPay Store Settings → Webhooks добавляете URL и секрет:

import { createHmac } from 'crypto';

app.post('/webhooks/btcpay', express.raw({ type: 'application/json' }), async (req, res) => {
  // Верификация подписи
  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':
      // Оплачено и подтверждено согласно speedPolicy
      await fulfillOrder(event.metadata.orderId);
      break;

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

    case 'InvoicePaymentSettled':
      // Конкретный платёж подтверждён (актуально при partial payments)
      break;
  }

  res.sendStatus(200);
});

Важно: всегда верифицируйте HMAC подпись. BTCPay повторяет доставку webhook при неуспешном ответе.

Lightning Network: платежи за секунды

Если включили LND при деплое — Lightning работает из коробки:

// Инвойс специально для 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',  // в millisatoshis
      description: `Order ${orderId}`,
      expiry: 900,  // 15 минут
    }),
  }
).then(r => r.json());

// Возвращает BOLT11 payment request для QR-кода
console.log(lightningInvoice.BOLT11);

Для Lightning: каналы нужно открыть и поддерживать ликвидность входящую. Для небольших магазинов — достаточно 1–2 каналов с крупными hub-нодами (ACINQ, WalletOfSatoshi).

Кастомный checkout

BTCPay позволяет кастомизировать checkout страницу через Templates или использовать Payment Request UI. Для полного контроля над UX — embedded checkout через iframe:

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

Или слушайте события через postMessage:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://pay.yourdomain.com') return;
  if (event.data === 'invoiceSettled') {
    // Платёж прошёл, обновите UI
    redirectToThankYouPage();
  }
});

Мультивалютность

BTCPay поддерживает LTC, XMR, ETH (через NBXplorer) и другие. При деплое добавляйте:

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

Для ETH и ERC-20 — отдельный плагин BTCPayServer.Plugins.Ethereum в настройках.

Резервное копирование

Критичные данные для бэкапа:

• Seed фраза LND wallet (~/.lnd/data/chain/bitcoin/mainnet/wallet.db)
• BTCPay database (PostgreSQL: btcpayserver)
• Настройки store и API ключи (экспорт из UI)

Потеря LND wallet seed = потеря средств в открытых каналах. Бэкап обязателен до открытия любых каналов.