Криптоплатежи в e-commerce: кастомный платёжный шлюз

Криптоплатежи в e-commerce: кастомный платёжный шлюз

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

Кастомная интеграция окупается при объёмах от 100 платежей в день в 3 раза быстрее, чем hosted-решения. Мы занимаемся интеграцией криптоплатежей с начала развития этого направления и видели, как магазины теряли до 12% выручки из-за неправильной обработки нюансов.

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

Сравним три варианта:

Готовый сервис — для объёмов до нескольких сотен платежей в месяц. Кастомная интеграция оправдана при:

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

Ниже — кастомная интеграция, так как она требует больше технических решений. Наш опыт: 30+ проектов, гарантия на код 12 месяцев.

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 });
}

Как курс и таймер влияют на 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. Это критично для налогового учёта.

Что делать при частичной оплате (partial payment)?

Edge case: пользователь отправил 0.02 ETH вместо 0.0271 ETH. Без специальной логики заказ зависнет. Решение: на уровне воркера проверяем, что полученная сумма >= expected, иначе помечаем как partially_paid и генерируем второй invoice на остаток. Включаем поддержку мульти-транзакций в одном заказе.

Почему стоит выбрать кастомную интеграцию?

Кастомная интеграция даёт полный контроль над стэком: от выбора блокчейна до логики обработки ошибок. Вы не зависите от комиссий и ограничений провайдера. При объёмах от 100 платежей в день экономия на комиссиях превышает стоимость разработки уже за 3 месяца. Мы также реализуем защиту от reentrancy-атак и оптимизируем gas consumption для массовых операций.

Что входит в работу

1. Технический аудит текущего магазина (CMS, хостинг, платёжные модули)
2. Выбор архитектуры: hosted или кастомный, on-chain или L2
3. Разработка платёжного шлюза (WooCommerce, Shopify, кастом)
4. Интеграция с кошельком (MetaMask, WalletConnect, Ledger)
5. Настройка webhook-ов и статусов заказов
6. Разработка страницы оплаты с QR-кодом и таймером
7. Подключение оракула курса (Chainlink) или биржевого API
8. Тестирование на testnet "под ключ"
9. Аудит смарт-контрактов (Slither, Mythril) — при необходимости
10. Документация и обучение персонала
11. Пост-релизная поддержка 1 месяц

Получите консультацию — мы свяжемся в течение 3 часов и покажем пример аналогичной интеграции для вашей ниши. Закажите пилотную интеграцию на тестовом домене — 3 дня, чтобы убедиться в совместимости.