Криптоплатежі в 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 дні, щоб переконатися в сумісності.