Интеграция криптоплатежей с интернет-магазином

Интеграция криптоплатежей в интернет-магазины

Типичная ошибка при интеграции крипты в e-commerce: относятся к ней как к ещё одному payment method в существующем checkout. На деле это другой flow — у криптоплатежей нет instant finality (кроме L2), нет chargebacks, курс меняется пока пользователь идёт к кошельку, а partial payment — реальный edge case, а не теоретический.

Выбор подхода: hosted vs кастомный

Для интернет-магазина с объёмом до нескольких сотен платежей в месяц разумнее использовать готовые решения — NOWPayments, CoinGate, BitPay. Они берут 0.5–1% комиссию, но избавляют от инфраструктурных задач.

Кастомная интеграция оправдана при:

• Нужен конкретный set монет/сетей, которые не поддерживает провайдер
• Требования к приватности (клиент не хочет, чтобы третья сторона видела транзакции)
• Высокие объёмы где комиссии провайдера значительны
• Специфическая логика (например, автоматическая конвертация через DEX)

Ниже — кастомная интеграция, так как она требует больше технических решений.

WooCommerce: кастомный payment gateway plugin

WooCommerce предоставляет абстрактный класс WC_Payment_Gateway — достаточно его расширить:

class WC_Crypto_Gateway extends WC_Payment_Gateway {
  
  public function __construct() {
    $this->id = 'crypto_payment';
    $this->title = 'Оплата криптовалютой';
    $this->method_description = 'Bitcoin, Ethereum, USDT и другие';
    $this->supports = ['products'];
    $this->init_form_fields();
    $this->init_settings();
    
    add_action('woocommerce_update_options_payment_gateways_' . $this->id,
      [$this, 'process_admin_options']);
    add_action('woocommerce_api_crypto_payment', [$this, 'handle_webhook']);
  }
  
  public function process_payment($order_id): array {
    $order = wc_get_order($order_id);
    
    // Создаём платёж во внешнем сервисе или генерируем адрес
    $payment = $this->create_crypto_payment($order);
    
    // Сохраняем данные для отображения инструкций
    $order->update_meta_data('_crypto_payment_id', $payment['id']);
    $order->update_meta_data('_crypto_pay_address', $payment['address']);
    $order->update_meta_data('_crypto_pay_amount', $payment['amount']);
    $order->update_meta_data('_crypto_expires_at', $payment['expires_at']);
    $order->set_status('pending', 'Ожидание криптоплатежа');
    $order->save();
    
    return [
      'result' => 'success',
      'redirect' => $this->get_return_url($order),
    ];
  }
  
  public function handle_webhook(): void {
    $payload = file_get_contents('php://input');
    $signature = $_SERVER['HTTP_X_PAYMENT_SIGNATURE'] ?? '';
    
    if (!$this->verify_signature($payload, $signature)) {
      wp_die('Invalid signature', 401);
    }
    
    $data = json_decode($payload, true);
    $order = wc_get_order($data['order_id']);
    
    if (!$order) wp_die('Order not found', 404);
    
    if ($data['status'] === 'confirmed') {
      $order->payment_complete($data['transaction_hash']);
      $order->add_order_note(
        sprintf('Криптоплатёж подтверждён. TX: %s', $data['transaction_hash'])
      );
    }
    
    wp_die('OK', 200);
  }
}

Страница thank you (после редиректа) должна показывать адрес, QR-код и сумму с таймером. WooCommerce вызывает get_return_url() который ведёт на стандартную thank you страницу — её можно кастомизировать через woocommerce_thankyou_{gateway_id} action.

Shopify: использование Payment Apps API

Shopify не позволяет произвольный кастомный PHP. Для интеграции крипты нужно создать Shopify App через Partner Dashboard, использовать Payments Apps API.

Принцип: ваше приложение регистрируется как payment provider. При оформлении заказа Shopify делает HTTP запрос к вашему endpoint с данными заказа, вы возвращаете URL для редиректа на вашу payment page, и после подтверждения отправляете resolved/rejected через GraphQL mutation.

// Shopify вызывает этот endpoint
app.post('/shopify/payment', async (req, res) => {
  const { gid, amount, currency, cancelUrl, kind } = req.body;
  
  // Создаём внутренний платёж
  const payment = await createCryptoInvoice({
    shopifyOrderGid: gid,
    fiatAmount: parseFloat(amount),
    fiatCurrency: currency,
  });
  
  // Редиректим на нашу payment страницу
  res.json({
    redirect_url: `${process.env.APP_URL}/pay/${payment.id}`,
  });
});

// После подтверждения платежа
async function notifyShopifyPaymentComplete(paymentGid: string, txHash: string) {
  const mutation = `
    mutation PaymentSessionResolve($id: ID!) {
      paymentSessionResolve(id: $id) {
        paymentSession {
          id
          state { ... on PaymentSessionStateResolved { code } }
        }
        userErrors { field message }
      }
    }
  `;
  
  await shopifyGraphQL(mutation, { id: paymentGid });
}

Курс и expiration: критичные детали UX

Пользователь видит цену 99$, нажимает "оплатить криптой", и попадает на страницу с суммой 0.0271 ETH. Эта сумма действительна 15–30 минут. Если пользователь медлит или курс сильно меняется — нужен refresh механизм.

Таймер на странице оплаты должен быть не декоративным — при истечении автоматически обновляем invoice:

// Клиентский код
let expiresAt = new Date(invoice.expiresAt);

const timer = setInterval(async () => {
  const remaining = expiresAt.getTime() - Date.now();
  
  if (remaining <= 0) {
    clearInterval(timer);
    // Запрашиваем новый invoice с актуальным курсом
    const refreshed = await fetch(`/api/payment/${invoiceId}/refresh`, {
      method: 'POST'
    });
    const newInvoice = await refreshed.json();
    expiresAt = new Date(newInvoice.expiresAt);
    updateUI(newInvoice); // Обновляем QR и сумму
  }
}, 1000);

На бэкенде при refresh — пересчитываем сумму в крипте по актуальному курсу, обновляем запись в БД, тот же адрес (если используем unique address per payment).

Статусы заказа и коммуникация с клиентом

Reconciliation и отчётность

Для бухгалтерии нужна конвертация крипто-суммы в фиат на момент получения. Фиксируем в базе: crypto_amount, crypto_currency, fiat_amount, fiat_currency, exchange_rate, confirmed_at. Источник курса — Chainlink (on-chain) или CoinGecko API (off-chain) с timestamp. Это критично для налогового учёта.