Приём криптоплатежей через REST API: полное руководство

REST API для криптоплатежей соединяет собственную систему заказов с Paymos. Сервер создаёт счёт, сохраняет его связь с заказом и направляет покупателя на оплату. После подтверждения обработчик получает подписанное уведомление и меняет состояние заказа.

Качество интеграции проверяется сбоями. Повтор запроса не должен создавать новый счёт, задержка вебхука — терять оплату, а повтор события — выдавать товар второй раз. Поэтому проектирование начинается с границы учёта, а не с копирования первого примера HTTP-запроса.

Когда бизнесу нужен REST API?

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

Если менеджеру нужно отправить разовый счёт, проще использовать платёжную ссылку. Магазину на поддерживаемой CMS стоит сначала проверить официальный плагин. Host-to-Host API оправдан, когда бизнесу действительно нужна программная связь между счётом, внутренним заказом и дальнейшим исполнением.

Ключевое условие — сервер остаётся единственным местом, где хранится связь заказа и счёта.

Иначе платёжный контур не сможет восстановить контекст после сбоя или повторного запроса.

Как спроектировать границу между заказом и Paymos?

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

Рядом с заказом сохраните идентификатор счёта Paymos и запись о выполненном результате. Не используйте номер отдельной HTTP-попытки в качестве внешнего номера заказа. Тогда повтор запроса восстанавливает связь, а не создаёт новый объект без понятного владельца.

Такая граница позволяет повторять сетевые операции, не меняя бизнес-смысл заказа и не теряя его владельца.

Изменения товара и клиента остаются внутри системы бизнеса; Paymos не подменяет этот учёт.

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

Передайте external_order_id при создании счёта. Если ответ не дошёл из-за сетевого сбоя, повторите запрос с тем же значением. Paymos вернёт существующий счёт; заголовок Idempotency-Key для создания счёта не нужен.

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

Значение должно сохраняться и после перезапуска сервиса: его нельзя вычислять заново для каждой попытки создания счёта.

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

Как разделить ключи и среды?

Merchant API использует HMAC-SHA256, а не Bearer-токен. Подпись формирует доверенный сервер с общим секретом. Секрет нельзя помещать в браузерный JavaScript, мобильное приложение, открытый репозиторий или журналы аналитики.

Для Payment и Payout действуют разные учётные данные. Тестовый и рабочий режимы также используют отдельные ключи при одинаковом наборе методов API. Назовите секреты по назначению и среде, а сервису создания счетов выдайте только доступ Payment.

Создание счетов не требует ключей Payout, а тестовый режим не должен использовать рабочие ключи.

Это обязательная граница доступа.

Так каждый сервис получает только те полномочия, которые нужны его конкретной операции.

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

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

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

Связывайте изменение заказа только с подтверждённым состоянием счёта, а не со временем после его создания.

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

Как построить обработчик вебхука?

Paymos передаёт X-Webhook-Signature в формате t={timestamp},v1={hmac_hex}. Обработчик пересчитывает HMAC-SHA256 на секрете вебхука и сравнивает подписи способом, устойчивым к атакам по времени, до любого изменения данных.

Смена секрета предусматривает переходный период, когда могут приниматься текущий и предыдущий секреты. После завершения периода предыдущий секрет удаляют. Не заменяйте криптографическую проверку списком IP-адресов или Bearer-токеном.

В переходный период проверяйте подпись по разрешённым секретам. Только после успешной проверки разбирайте событие, извлекайте данные и обращайтесь к заказу.

Проверка завершается до изменения заказа, баланса или статуса. Ошибка подписи останавливает обработку события.

Что произойдёт при недоступности обработчика?

Один цикл доставки включает 11 попыток: первую отправку и десять повторов. Задержки увеличиваются от одной минуты до восьми часов, а полный цикл занимает примерно 16 часов. После восстановления событие можно повторить вручную.

Ручной и автоматический повторы должны использовать один обработчик. Paymos блокирует адреса обратной петли, частные и локальные адреса канала, CGNAT и IPv6 ULA и не следует автоматическим HTTP-перенаправлениям. Поэтому адрес должен быть доступен из интернета напрямую.

Восстановление не должно требовать отдельной ветки кода или специальных данных для ручного повтора.

Обработчик должен одинаково принимать задержанное событие, автоматический повтор и ручную повторную доставку.

Что проверять в тестовом режиме?

Тестовый режим использует тот же набор методов API с отдельными учётными данными. Проверьте предусмотренные сценарии платежей и выводов без реального движения активов. Повторите создание счёта с одним external_order_id, затем дважды передайте одно уведомление.

Добавьте проверку недоплаты. По умолчанию допуск проекта равен 0 %, а платёж в настроенном пределе закрывает счёт по фактически полученной сумме. Убедитесь, что частичная оплата ниже порога не исполняет заказ раньше установленного правила.

Отдельно проверьте отмену и вывод, если эти операции входят в ваш конкретный сценарий.

Цель теста — доказать, что повтор и частичная оплата не создают второй результат.

Какой интерфейс оплаты показать покупателю?

Создание счёта через API не требует собственной платёжной страницы. Paymos предоставляет готовую страницу оплаты с QR-кодом и переходами в Trust Wallet, MetaMask, Coinbase Wallet и OKX Wallet. Её можно открыть отдельно или встроить через iframe.

Для оплаты внутри сайта доступен Widget SDK. Он поддерживает встроенный режим и переход на отдельную страницу. Покупателю не нужны учётная запись Paymos, электронная почта или проверка KYC на странице оплаты.

Выбор между отдельной страницей и iframe не меняет серверную связь созданного счёта с заказом.

Сервер всё равно создаёт счёт и сохраняет его идентификатор рядом с заказом.

Как сверять платежи после запуска?

Сопоставляйте каждый счёт Paymos с одним заказом по сохранённым идентификаторам. Контролируйте неудачные доставки, повторяйте их после восстановления обработчика и проверяйте, что повторное уведомление не меняет уже исполненный заказ.

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

Сверяйте фактически полученную сумму, особенно если проект допускает недоплату.

Регулярная сверка показывает, где доставка остановилась и какой заказ требует внимания.