Интеграция платежей в Ethereum для разработчиков

Абстрактная изометрическая заставка: платежи в Ethereum

Интеграция платежей в Ethereum — это приём ETH или токенов в вашем приложении: выдача каждому клиенту уникального адреса, обнаружение транзакции в момент её появления, решение о том, когда она считается окончательной, и сверка с заказом. Её можно построить на собственных нодах и JSON-RPC или вызывать API, который берёт на себя кошельки и уведомления.

Это руководство описывает оба пути, чтобы вы выбирали с учётом компромиссов.

Коротко

Платёж в Ethereum — это подписанная транзакция, которая перемещает ETH или токены. Отправить её — не то же самое, что подтвердить: нужно проверить квитанцию.
Сначала решите: только ETH, стейблкоины и токены ERC-20 или собственный токен. Этот выбор определяет обработку событий и стратегию газа.
Используйте один адрес для депозита на заказ или пользователя и получайте события через вебхуки, а не опросом.
Ключи, подписи вебхуков и код контрактов — три основные поверхности атаки.
API вроде Chaingateway заменяет ноду и сканер блоков, тарифы от 49 € в месяц. Настройки газа и политику подтверждения вы определяете сами.

Что такое платёж в Ethereum?

Платёж в Ethereum — это криптографически подписанная инструкция от аккаунта, которая меняет состояние сети, например переводит ETH или токены. По документации ethereum.org о транзакциях валидатор затем проверяет транзакцию и включает её в блок. Только после этого деньги появляются на адресе получателя.

Для вашего приложения это имеет практическое следствие. Клиент платит не вам. Он рассылает транзакцию в сеть, а ваша система должна её заметить. Всё в интеграции — вариация этой задачи наблюдения.

Встретятся два вида платежей:

Переводы нативного ETH. Сама транзакция несёт получателя и сумму. Это просто, и это видно прямо в транзакции и её квитанции.
Переводы токенов (ERC-20 и подобные). Транзакция адресуется контракту токена, который внутри обновляет балансы. Стандарт определяет для этого событие Transfer, как описано в спецификации ERC-20 на ethereum.org. Ваша система узнаёт о платеже из этого лога события, а не из поля суммы транзакции.

Большинство оплат стейблкоинами относятся ко второму виду. Если отслеживать только поступление ETH на адрес, такие платежи будут пропущены.

Что нужно решить до написания кода?

Какие активы вы будете принимать?

Начните с самого узкого набора, который обслуживает ваших клиентов. Только ETH реализовать проще всего. Добавление стейблкоина убирает ценовую волатильность, что важно для счетов и подписок. Если вы выпускаете собственный токен, нужно знать его decimals, адрес контракта и то, ведёт ли он себя как стандартный ERC-20.

Каждый дополнительный актив добавляет адрес контракта для мониторинга, значение decimals для применения и правило ценообразования. Держите небольшой список разрешённых активов и намеренно отклоняйте всё остальное.

Размещённая оплата, платёжные ссылки или API?

Есть три варианта интеграции, и они меняют контроль на скорость:

Подход	Лучше всего подходит для	Что вы контролируете	Чем жертвуете
Размещённая оплата или платёжная ссылка	Быстрый запуск, небольшой объём	Почти ничего в потоке	Брендинг, хранение средств, собственная логика
Подключение кошелька в вашем фронтенде	dApp, где пользователи уже держат ETH	Пользовательский опыт	Обнаружение и сверка по-прежнему на вас
Бэкенд API с кошельками и вебхуками	Приложения, маркетплейсы, биллинг SaaS	Адреса, суммы, логику заказов	Эксплуатацию собственной инфраструктуры

Если вы разработчик, встраивающий платежи в продукт, обычно вы приходите к третьему варианту. Полезный чек-лист для любого провайдера: есть ли песочница, понятные форматы ошибок, задокументированные лимиты запросов и вебхуки, которые подходят вашему стеку?

Хранение средств и комплаенс

Кто держит ключи? Если ваша платформа создаёт депозитные кошельки для клиентов, вы работаете со средствами, и в зависимости от юрисдикции и бизнес-модели это может влечь лицензирование или отчётность. Спросите юриста, который знает ваш рынок, до запуска, а не после. Это руководство о разработке, а не юридическая консультация.

Как работает поток платежа, шаг за шагом?

Вот последовательность, которая выдерживает эксплуатацию, независимо от того, строите вы её сами или покупаете.

1. Создайте запрос на оплату

Когда клиент доходит до оформления, создайте запись заказа с суммой, активом и сроком действия. Затем назначьте этому заказу уникальный адрес для получения. Уникальный адрес на заказ позволяет сопоставить входящий перевод с нужным клиентом, не прося его вставлять memo или номер.

Выставьте цену заказа в стабильной единице, зафиксируйте сумму в ETH на короткое окно, если вы принимаете волатильные активы, и сохраните оба числа.

2. Клиент подписывает и отправляет

Если клиент платит из браузерного кошелька, ваш фронтенд запрашивает разрешение на использование его аккаунта, формирует объект транзакции и отправляет её. Справочник MetaMask по eth_sendTransaction описывает этот порядок: получить разрешение аккаунта, отправить транзакцию, сохранить возвращённый хеш. Если клиент отправляет со счёта биржи или мобильного кошелька на показанный адрес, вы этот шаг не видите. Вы видите только результат в блокчейне.

В любом случае хеш транзакции — это номер квитанции платежа. Сохраните его.

3. Обнаружьте транзакцию

Есть три варианта, как заметить платёж:

Опрос. Каждые несколько секунд запрашивайте у ноды квитанцию или баланс адреса. Просто, но расточительно и хрупко при масштабировании.
Подписки. Откройте WebSocket к ноде и подпишитесь на новые блоки или логи контрактов. Документация go-ethereum о событиях в реальном времени описывает для этого eth_subscribe. Обрывы соединения и повторную обработку пропущенных блоков вы обрабатываете сами.
Вебхуки. Сервис следит за цепочкой и вызывает ваш сервер, когда происходит что-то значимое. Это вариант с наименьшими затратами на обслуживание, и его выбирают большинство команд.

Для токенов вы следите за логами событий. Документация Ethereum отмечает, что приложения могут слушать события контрактов через JSON-RPC API и действовать по логам, которые они создают.

4. Подтвердите результат

Отправка — это не подтверждение. Руководство MetaMask по отправке транзакций показывает шаблон: опрашивайте квитанцию по хешу; если квитанции нет, транзакция ещё в ожидании; статус 0x1 означает успех, а 0x0 — ошибку. Справочник eth_getTransactionReceipt добавляет, что квитанция содержит номер блока, использованный газ и логи.

Машина состояний заказа должна явно отражать это:

awaiting_payment: адрес выдан, ничего не замечено.
pending: подходящая транзакция видна, но ещё не в блоке.
confirmed: квитанция найдена, статус успешный, сумма и актив совпадают.
final: прошло достаточно дополнительных блоков по вашему порогу риска.
failed, underpaid, overpaid или expired: случаи, которым нужно правило, а не пожатие плечами.

Сколько блоков ждать перед отправкой товара, — деловое решение. Цифровые товары на несколько долларов можно отправлять после первого подтверждения. Заказы с высокой суммой заслуживают более долгого ожидания, потому что блок может иногда быть реорганизован до того, как сеть на нём сойдётся.

5. Сверяйте

Каждый день сравнивайте сумму подтверждённых платежей в вашей базе с тем, что цепочка показывает поступившим на ваши адреса. Любое расхождение — это ошибка, пропущенный вебхук или клиент, который заплатил не тем активом. Раздел данных и аналитики на ethereum.org перечисляет индексаторы, которые отдают исторические логи событий, что может уменьшить объём этой работы, который вы ведёте сами.

Как работают газ, неудачные транзакции и возвраты?

Газ — это то, чем удивляются многие первые интеграции. Каждая транзакция платит комиссию из базовой комиссии и комиссии за приоритет, и её оплачивает отправитель, как объясняет документация по транзакциям. Для вас из этого следуют три последствия.

Клиенты могут недоплатить или застрять. Если они поставили слишком низкую комиссию, транзакция висит в ожидании. Заказ не должен истекать, пока действительная транзакция в пути.
Неудачные транзакции всё равно стоят газ. Откаченный перевод токена даёт квитанцию с неудачным статусом, а средства клиента не двигаются. Не отмечайте заказ оплаченным только потому, что вы увидели хеш.
Отправка с вашей стороны стоит денег. Возвраты, сбор средств с депозитных адресов на казначейский кошелёк и выплаты требуют газ, а для перевода токенов адресу нужен ETH. Оценивайте комиссию до отправки и закладывайте её в бюджет.

В API Chaingateway поля gas, gasprice, maxFeePerGas и maxPriorityFeePerGas необязательны в эндпоинтах транзакций ERC-20 и ETH, а GET /api/v2/ethereum/gasprice возвращает текущую цену газа. Наше руководство как оценивать комиссии за газ в Ethereum и других сетях описывает методы оценки.

Если вы хотите, чтобы клиенты платили вообще без ETH, абстракция аккаунтов позволяет разработчикам спонсировать транзакции, как описано в руководстве ethereum.org по спонсированию комиссий за газ. Это добавляет сложность контрактов, поэтому оставляйте этот вариант для продуктов, где трение из-за газа действительно снижает конверсию.

Для возвратов заранее решите политику. Возвращайте на адрес отправителя, только проверив, что это не адрес депозита биржи, которым вы не управляете, или попросите клиента указать адрес для возврата. Открыто вычитайте сетевую комиссию или берите её на себя, но запишите правило.

Иллюстрация газа, неудачных транзакций и возвратов в потоке платежа Ethereum

Как защитить ключи, подписи и контракты?

Приватные ключи

Тот, кто держит ключ, контролирует средства. Генерируйте ключи в защищённом окружении, никогда не логируйте их, не коммитьте и разделяйте горячие кошельки (небольшие суммы для выплат) и холодное хранение (основная часть средств). По расписанию переводите средства с депозитных адресов на холодную сторону.

Подлинность вебхуков

Конечная точка вебхука — это публичный URL, который может отмечать заказы оплаченными, поэтому любой, кто её найдёт, может отправить поддельное событие. Защитите её четырьмя способами:

Проверяйте подпись каждого запроса. Общий подход — подпись HMAC. Если схема включает временную метку, отклоняйте устаревшие.
Делайте обработчик идемпотентным, чтобы повторная доставка не зачисляла заказ дважды.
Подтверждайте сумму и получателя прямым запросом до отправки товара.
Заголовок X-Signature в Chaingateway покрывает только ID транзакции, как объясняет статья о проверке подписи, поэтому запрос напрямую важен.

Код смарт-контрактов

Если вы пишете собственные платёжные контракты, риск переходит в код. В собственном отчёте Ethereum о безопасности сказано, что аудиты, проверенные библиотеки, формальная верификация и статический анализ повышают безопасность контрактов, а самописный код для сложных механизмов контроля может увеличить уязвимость. Практическое правило: не развёртывайте собственный контракт, если для вашего случая достаточно обычного адреса и стандартных событий токена.

Строить самостоятельно или использовать API?

Путь «сделай сам» означает запуск или аренду нод и написание генератора адресов. Вам также придётся написать декодер логов для каждого принимаемого токена, оценивать газ, обрабатывать реорганизации и поддерживать всё это в работе. Это разумный путь для команды, чей продукт и есть платёжная инфраструктура.

Для остальных цена — это время и постоянное обслуживание. Архитектурный вопрос в том, получать ли события по мере их появления или сверять пакетами позже. Для платежей лучший выбор по умолчанию — события по мере появления.

Наше сравнение типов блокчейн-API и когда какой применять описывает категории. Обзор Ethereum объясняет ETH, газ и токены ERC-20 для команд, которые впервые работают с этой сетью.

Как Chaingateway вписывается в интеграцию с Ethereum?

API Ethereum позволяет отправлять токены ERC-20 через REST без web3.js. Три эндпоинта покрывают большую часть потока платежа:

Шаг	Эндпоинт
Создать адрес для депозита	`POST /api/v2/ethereum/addresses`
Следить за ним на поступление ETH или токенов	`POST /api/v2/ethereum/webhooks` с `to`, `url` и `type` (`ETH`, `ERC20` или `ERC721`)
Отправить ETH или токен ERC-20 дальше	`POST /api/v2/ethereum/transactions` или `.../transactions/erc20`

Выплата ERC-20 требует отправителя, получателя, contractaddress и amount, а также пароль кошелька password для кошельков, которые API создал с паролем. Ошибка 422 при пустом балансе на комиссию — это insufficient funds for gas * price + value. Сначала протестируйте в Sepolia, добавив заголовок X-Network: testnet. Страница вебхуков Chaingateway и блокчейн-API описывают другие поддерживаемые сети с теми же вызовами.

Неудачные уведомления вебхуков автоматически не повторяются. Выведите их списком через GET /api/v2/ethereum/webhooks/notifications/failed и отправьте каждое заново.

Тарифы зависят от объёма и функций: Plus стоит 49 € в месяц, Pro — 99 €, Premium — 249 € и Enterprise — 499 €, либо 490 €, 990 €, 2 490 € и 4 990 € в год при годовой оплате. Каждый тариф начинается с бесплатного пробного периода на 7 дней без карты и KYC. Что входит в каждый тариф, см. на странице цен.

Скриншот главной страницы Chaingateway: единый блокчейн-API для криптоплатежей и вебхуков в 7 сетях

Как протестировать и мониторить интеграцию платежей в Ethereum?

Интеграция платежей не готова, когда работает демонстрация. Сначала пройдите этот список в тестовой сети, а затем повторите его с небольшими реальными суммами:

Точная оплата, недоплата и переплата как в ETH, так и в каждом принимаемом токене.
Поздняя оплата после истечения заказа и повторная оплата на тот же адрес.
Неудачная транзакция с низким лимитом газа: проверьте, что вы видите неудачную квитанцию и что заказ не завершается.
Повторные и не по порядку пришедшие вебхуки, воспроизведённые намеренно.
Ваш собственный простой: остановите сервер на десять минут, отправьте платёж, запустите сервер и убедитесь, что ничего не потеряно.
Сценарии кошельков во фронтенде. QA-команды могут проводить регрессионные тесты без приватных ключей, используя инструменты из списка на странице Impersonator.xyz на ethereum.org.

После запуска настройте оповещения по трём сигналам: заказы, которые висят в pending дольше порога, расхождение между итогами в базе и итогами в цепочке и сбои доставки вебхуков. Первый сигнал ловит проблемы с комиссиями, второй — пропущенные события, третий — ваши собственные сбои.

Часто задаваемые вопросы

Нужно ли запускать собственную ноду Ethereum, чтобы принимать платежи?

Нет. Нода даёт прямой доступ к цепочке, но вместе с ней вы получаете её обслуживание, синхронизацию и мониторинг. Большинство команд используют API провайдера или сервис, который следит за цепочкой и вызывает вебхук, когда приходит платёж.

Как понять, что пришёл именно платёж токеном, а не ETH?

Следите за событием Transfer контракта токена для вашего принимающего адреса. Стандарт ERC-20 определяет это событие, а перевод токена не отображается как значение ETH в транзакции. Уведомление вебхука Chaingateway сразу содержит отправителя, получателя, адрес контракта и сумму.

Сколько подтверждений ждать?

Единого правильного числа нет. Оно зависит от суммы заказа и вашей готовности терпеть редкую реорганизацию цепочки. Цифровые товары низкой стоимости можно выдавать раньше, а заказы с высокой суммой должны ждать дольше. Запишите пороги в логику заказов, чтобы поддержка не решала каждый случай отдельно.

Кто платит за газ?

Его платит отправитель, поэтому клиенты покрывают комиссию за свои платежи, а вы покрываете её при возвратах, сборах средств и выплатах. Спонсируемый газ через абстракцию аккаунтов может переложить эту стоимость на вас для отдельных потоков.

Может ли та же интеграция работать с другими блокчейнами?

Может, если выбрать интерфейс, не привязанный к одной сети. В Chaingateway поддержка Polygon или Arbitrum позже использует те же вызовы кошельков, переводов и вебхуков с другим названием сети в пути. Tron использует похожий шаблон со своей моделью комиссий.