Розробка шлюзу прийому криптоплатежів під ключ

Ми часто чуємо від клієнтів: «Хочемо приймати крипту як звичайний Stripe, тільки без посередників». Спочатку здається, що достатньо підключити Blockchain listener і генерувати адреси. Але на практиці спливають проблеми: детекція платежів без постійного polling, волатильність при конвертації, partial payments, confirmations thresholds у різних мережах, ідемпотентність при збоях. Ми вирішуємо волатильність фіксацією курсу через Chainlink Price Feed. Ми розібрали кожне з цих питань у продакшені та пропонуємо готове архітектурне рішення під ключ. Наша команда має понад 5 років досвіду в блокчейн-розробці та реалізувала більше 20 інтеграцій платіжних шлюзів. Економія на комісіях за рахунок відсутності посередників може сягати 2% від обороту — це суттєвий фактор при високих обсягах.

Як влаштований шлюз прийому криптоплатежів

Мінімально життєздатний payment gateway складається з чотирьох компонентів:

[Клієнт] → [API Gateway] → [Payment Service] ↓ [Blockchain Listener] ↓ [Event Queue (Redis/Kafka)] ↓ [Settlement Service] → [ERP/CRM] 

Payment Service — створює замовлення, генерує унікальну адресу (або payment ID), повертає клієнту дані для оплати. Stateful — зберігає mapping address → order. Blockchain Listener — моніторить вхідні транзакції. Це найкритичніший компонент з точки зору надійності. Два підходи:

1. WebSocket підписка (eth_subscribe("logs", filter) або eth_subscribe("newHeads")) — низька латентність, але з'єднання рветься, потрібен reconnect з backoff і replay пропущених блоків.
2. Polling + cursor — менш елегантно, але передбачувано. Зберігаємо останній оброблений блок, опитуємо eth_getLogs з фільтром по адресах. Стійкіше до мережевих збоїв.

Для production: hybrid підхід — WebSocket для низької латентності, polling як fallback з cursor-based recovery.

Event Queue — буфер між listener і settlement. Kafka для високих навантажень, Redis Streams для середніх. Ключовий момент: listener публікує TransactionDetected event, settlement підписується. Це розв'язує компоненти та гарантує обробку при тимчасовому падінні settlement service.

Settlement Service — перевіряє confirmations, конвертує суму, оновлює статус замовлення, нотифікує upstream систему (webhook).

Чому детекція платежів — найскладніший компонент?

EVM-мережі (ETH, BNB, Polygon, Arbitrum...) — розробка шлюзу прийому

Нативні перекази ETH: моніторимо через eth_subscribe("newHeads") + eth_getBlockByNumber і фільтруємо транзакції по to адресі.

ERC-20 токени (USDT, USDC, DAI): моніторимо подію Transfer(address indexed from, address indexed to, uint256 value) через eth_getLogs з фільтром:

const filter = { fromBlock: 'latest', topics: [ ethers.id('Transfer(address,address,uint256)'), null, // from: будь-який ethers.zeroPadValue(paymentAddress, 32), // to: наша адреса ], }; 

Важливо для USDT (Tether): у нього нестандартний ERC-20 — функція transfer не повертає bool. Виклик через стандартний інтерфейс впаде. Використовуємо safeTransfer або низькорівневий call з перевіркою returndata.

Bitcoin та UTXO-модель

Для BTC немає поняття «адреса → транзакція» на рівні ноди. Використовуємо або:

• Electrum Server (Electrs) — індексує UTXO по адресах, дозволяє підписатися на адресу
• BlockCypher / Blockcypher WebHook API — hosted рішення, але залежність від третьої сторони
• Bitcoin Core з importaddress — додаємо адресу в wallet node, отримуємо нотифікації через ZMQ

Мінімальні confirmations для BTC: 1 для small amounts (<$100), 3 для medium, 6 для large. Для Ethereum достатньо 12–20 блоків.

TON

TON транзакції асинхронні: вхідний transfer це bounce-able повідомлення, і ви повинні перевіряти, що це саме transfer, а не bounce. Використовуємо TonAPI або TON Center API з webhook на адресу.

Як забезпечити ідемпотентність webhook?

Нотифікація upstream системи через webhook повинна бути ідемпотентною — можливі повторні доставки при retry. У payload включаємо payment_id (унікальний) + tx_hash + status. Upstream система повинна перевіряти, чи не обробляла вона вже цей payment_id. Retry policy: експоненціальний backoff, 5–10 спроб, після — dead letter queue для ручного розбору.

Confirmation threshold та захист від double-spend

Не можна вважати платіж завершеним після першого виявлення транзакції в mempool — це pending стан, не підтверджений. Мінімальні пороги:

Partial payments та overpayments

Реальні користувачі іноді платять не точну суму — біржі знімають комісії, люди помиляються. Потрібна політика:

• Underpayment: якщо отримано 99–100% суми — вважаємо оплаченим (tolerance 1%). Якщо менше — partially_paid, чекаємо доплати 30 хвилин, потім expired.
• Overpayment: автоматично приймаємо, різницю повертаємо (потрібен refund flow) або зараховуємо як кредит.

Порівняння підходів до детекції

# config.yml listener: networks: - name: ethereum rpc: wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY polling_interval: 12s confirmations: 12 addresses: - 0xYourPaymentAddress - name: bitcoin rpc: http://user:pass@localhost:18332 confirmations: 3 addresses: - bc1q... - name: polygon rpc: wss://polygon-mainnet.infura.io/ws/v3/YOUR_KEY confirmations: 128 addresses: - 0x...