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

Интеграция платежей Polygon — набор компонентов, который позволяет приложению принимать и отправлять токены в сети Polygon PoS: кошельки, переводы, проверку и уведомления. Каждый компонент можно реализовать поверх нод напрямую или вызвать REST API, который предоставляет кошельки, переводы и вебхуки. Это руководство описывает оба пути.

TL;DR

• Polygon PoS имеет chain ID 137 и использует POL для газа. Тестовая сеть Amoy имеет chain ID 80002.
• Платёж считается завершённым, только когда вы проверили статус транзакции, получателя, сумму и контракт токена. Один хеш — не доказательство.
• Для отслеживания платежей используйте вебхуки, а не опрос. Проверяйте подпись и делайте обработчик идемпотентным.
• Вебхуки Chaingateway не повторяются автоматически, поэтому сверяйте данные со списком уведомлений.
• Перед запуском продумайте правовые рамки, хранение ключей, конфликты nonce и скачки газа, а не после.

Содержание

• Что входит в интеграцию платежей Polygon?
• Какую сеть и токен выбрать?
• Как настроить кошельки и защитить ключи?
• Как отправить платёж в токенах в Polygon?
• Как проверить, что платёж пришёл?
• Как получать уведомления через вебхуки?
• Как спроектировать бэкенд?
• Что проверить перед запуском?
• FAQ
• Источники

Что входит в интеграцию платежей Polygon?

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

На практике вы строите пять компонентов:

1. Слой кошельков: адреса для получения средств и ключи для их отправки.
2. Слой переводов: код, который формирует, подписывает и рассылает переводы токенов.
3. Слой проверки: проверки, что перевод действительно произошёл так, как ожидалось.
4. Слой уведомлений: вебхуки, которые сообщают вашему приложению об изменении статуса.
5. Учёт: ваша собственная запись в базе данных о том, что должны, что оплачено и что закрыто.

Первые четыре — техническая обвязка блокчейна. Пятый — ваш продукт. Чем меньше времени уходит на обвязку, тем раньше вы выпустите ту часть, которую видят клиенты.

Нужна ли лицензия?

Определите, где вы работаете и какие правила применяются, до того как писать код. В ЕС регулирование крипто-активов (MiCA) касается поставщиков услуг с криптоактивами, как описано на странице ESMA о MiCA. В США руководство FinCEN по виртуальным валютам описывает, когда администрирование или обмен виртуальной валюты делает вас money transmitter.

Сработает ли какое-либо правило, зависит от того, держите ли вы средства других людей или переводите их. Этот вопрос для юриста, который знает платежи, а не для проверки кода. Задайте его до запуска. Ответ может определить, держите ли вы средства вообще.

Какую сеть и токен выбрать?

Для большинства платёжных продуктов выбирайте Polygon PoS со стейблкоином, например USDC или USDT. Документация Polygon указывает chain ID 137 и POL как газовый токен для mainnet, а chain ID 80002 — для тестовой сети Amoy. Жёстко задайте chain ID в коде подписи, чтобы транзакция никогда не ушла в неверную сеть.

Комиссии — причина, по которой команды выбирают Polygon. Но они меняются вместе с загрузкой сети и ценой POL. Строите обработку комиссий на диапазонах и читайте текущую цену газа в момент отправки. В Chaingateway её возвращает GET /api/v2/polygon/gasprice.

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

Кошелькам для отправки нужен POL на газ, даже когда отправляемый актив — стейблкоин. Если вы пополняете кошелёк с торговой площадки, выберите Polygon как сеть вывода и проверьте метку сети перед подтверждением. Вывод в неверной сети — частая причина потери средств при настройке.

Как настроить кошельки и защитить ключи?

Есть два распространённых шаблона:

• Один адрес на клиента или счёт. Каждый платёж получает собственный адрес для депозита. Тогда сопоставить входящий перевод с заказом тривиально, потому что адрес получателя его идентифицирует. Цена — больше адресов для управления и позже вывод средств на казначейский кошелёк.
• Один общий адрес с референсами. Это проще в эксплуатации, но обычный перевод токена не несёт поля с референсом. Вы сопоставляете по сумме и времени. Это ломается, когда два клиента платят одну и ту же сумму.

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

• Никогда не храните приватные ключи в системе контроля версий, логах или клиентском коде.
• Отделяйте кошельки для получения от казначейского кошелька, на котором лежит ваш баланс. Так компрометация одного не открывает другой.
• Ограничивайте, кто и что может инициировать исходящий перевод, и логируйте каждый запрос.
• Сохраняйте резервные копии ключевого материала так, чтобы они переживали потерю одного человека или одного сервера.

Chaingateway работает по модели non-custodial. POST /api/v2/polygon/addresses создаёт кошелёк. Если вы передаёте password, приватный ключ хранится зашифрованным этим паролем. При отправке транзакции вы используете пароль вместо ключа. Chaingateway не хранит пароль и не может восстановить кошелёк, если вы его потеряете. Последовательность вызовов описана в статье создание криптокошелька через API.

Как отправить платёж в токенах в Polygon?

Polygon PoS совместим с EVM, поэтому переводы токенов следуют стандарту ERC-20. Спецификация ERC-20 определяет два шаблона платежа:

• Прямой платёж: плательщик вызывает transfer(recipient, amount), и это испускает событие Transfer.
• Платёж через контракт (pull): плательщик сначала вызывает approve(spender, amount), затем авторизованный контракт вызывает transferFrom(sender, recipient, amount).

Для простого чекаута достаточно прямого перевода. Approve важен, когда деньги собирает смарт-контракт, например при подписках или эскроу. Держите approve узким: одобряйте нужную сумму, а не неограниченный allowance.

Как отправлять через код ноды?

Прямая отправка означает, что вы формируете транзакцию, оцениваете газ, задаёте nonce, подписываете, рассылаете и отслеживаете включение в блок. Для прототипа это управляемо. В продакшене вам также нужны надёжный RPC-провайдер, логика повторов и способ заменять застрявшие транзакции. Наше руководство по отправке токенов ERC-20 сравнивает способы через кошелёк, код и API.

Как отправить одним REST-вызовом?

С Chaingateway перевод токена — это один аутентифицированный запрос. В нём указаны отправитель, контракт токена, получатель и сумма. Поля газа необязательны. В определении OpenAPI from, contractaddress, to и amount помечены как обязательные.

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xSenderAddress",
    "contractaddress": "0xTokenContract",
    "to": "0xRecipientAddress",
    "amount": 25.5,
    "password": "wallet-password"
  }'

X-Network: testnet выполняет запрос в Amoy. Для mainnet заголовок не передавайте. Тот же шаблон работает и в других EVM-сетях, поэтому добавление второй сети позже меняет путь, но не процесс. Полный список эндпоинтов — на странице API Polygon и в файле OpenAPI.

Как проверить, что платёж пришёл?

Хеш транзакции лишь доказывает, что транзакция была отправлена. Прежде чем пометить заказ оплаченным, проверьте статус транзакции, получателя, сумму перевода токена и контракт токена. Переводы ERC-20 записываются в логи событий Transfer, как определено в спецификации ERC-20. Поэтому именно в логе вы читаете реальный перевод.

Проверку контракта команды часто забывают. Любой может задеплоить токен с названием «USDC», который ничего не стоит. Сравните адрес контракта в логе с адресом, который вы внесли в белый список. Ваша процедура проверки должна подтверждать всё это:

1. Транзакция успешна, а не просто включена в блок.
2. Событие Transfer пришло от ожидаемого контракта токена.
3. Получатель совпадает с адресом, который вы выдали под этот заказ.
4. Сумма не меньше выставленной, в наименьших единицах токена.
5. Прошло достаточно блоков в соответствии с вашим допуском риска, прежде чем отдавать товар.

Чтение сырых логов означает ручное декодирование topics и data. Структуру показывает наш разбор события Transfer ERC-20. Chaingateway также возвращает декодированные транзакции запросом GET /api/v2/polygon/transactions/{txid}/decoded.

Как получать уведомления через вебхуки?

Опрос адреса каждые несколько секунд тратит запросы и всё равно отстаёт. С вебхуком сервис вызывает ваш эндпоинт, когда найдена подходящая транзакция. Создайте вебхук запросом POST /api/v2/polygon/webhooks. Поле url обязательно, фильтровать можно по to, from или contractaddress. Механику см. в статье вебхуки Polygon.

Как безопасно построить приёмник?

Эти правила действуют для любого провайдера:

• Проверяйте подпись. Chaingateway добавляет заголовок X-Signature, как только вы задали личный секрет. Это HMAC-SHA256 от ID транзакции в кодировке Base64, ключом служит ваш секрет. См. проверка подписи вебхуков.
• Сравнивайте за постоянное время. Используйте безопасную функцию сравнения вашего языка, а не ==.
• Отвечайте быстро. Сразу возвращайте статус 2xx, а тяжёлую работу выполняйте в очереди.
• Ожидайте дубликаты. Одно и то же событие может прийти дважды, например после повторной отправки уведомления. Сохраняйте ID транзакции и игнорируйте повторы.
• Ожидайте пропущенные события. Chaingateway не повторяет неудачные уведомления автоматически. Получите их списком запросом GET /api/v2/polygon/webhooks/notifications/failed и отправьте каждое повторно через POST /api/v2/polygon/webhooks/notifications/{id}/retry.

Какие состояния платежа хранить?

Держите состояния платежа маленькими и явными: awaiting_payment, pending, confirmed, failed, expired. Каждый вебхук соответствует не более чем одному переходу. Если пришло событие failed для уже подтверждённого платежа, запишите его в лог и оповестите человека, а не перезаписывайте состояние.

Как спроектировать бэкенд?

Держите код, специфичный для сети, на границах. Поставьте внутренний интерфейс перед блокчейном с методами вроде createDepositAddress, sendPayment и getPaymentStatus, а логику заказов оставьте по другую его сторону. Тогда добавление сети означает реализацию этого интерфейса, а не переписывание ядра.

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

Что проверить перед запуском?

Проверьте три вещи особенно тщательно: неудачные транзакции, конфликты nonce и изменения цены газа.

Перед запуском

• Прогоните весь процесс в тестовой сети Amoy: создайте адрес, оплатите его, получите вебхук, пометьте заказ оплаченным.
• Проиграйте каждый вебхук дважды и убедитесь, что второе доставление ничего не меняет.
• Отправьте платёж неверным токеном, с неверной суммой (меньше и больше) и на истёкший заказ. Решите и проверьте, что происходит в каждом случае.
• Сломайте свой эндпоинт намеренно: ошибкой 500 и таймаутом. Затем получите список неудачных уведомлений и отправьте их повторно.
• Отправьте два перевода из одного кошелька одновременно, чтобы выявить конфликты nonce.

При запуске

• Начинайте с низких лимитов и одного токена.
• Настройте оповещение о любом переводе, который остаётся в pending дольше вашего порога.
• Следите за балансом газового кошелька, потому что пустой баланс POL останавливает все исходящие платежи.
• Меняйте личный секрет по расписанию и одновременно обновляйте приёмник.

Частые ошибки

• Доверие хешу вместо лога событий.
• Доверие вебхуку до проверки подписи.
• Жёстко заданная цена газа.
• Пропуск проверки контракта токена.
• Хранение ключей горячего кошелька и казначейства вместе.

Тарифы начинаются с 49 € в месяц (490 € в год) с 7-дневным бесплатным пробным периодом без карты. См. страницу тарифов.

Источники

• Документация Polygon: RPC-эндпоинты и chain ID
• ERC-20: Token Standard
• ESMA: регулирование крипто-активов в ЕС (MiCA)
• FinCEN: руководство о лицах, которые администрируют, обменивают или используют виртуальные валюты

Рекомендуем

• Polygon Blockchain API: платежи USDC и USDT через REST
• Blockchain API: один REST API для Bitcoin, Ethereum и ещё пяти сетей