Криптоинвойсы: как выставлять счета и принимать оплату

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

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

Какие данные входят в криптоинвойс?

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

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

Как создать счёт без дублей?

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

Это правило важно для любой интеграции. Сетевой сбой не говорит, выполнил ли сервер первый запрос. Без постоянного номера заказа магазин рискует показать клиенту две разные страницы оплаты и два адреса. С external_order_id повтор становится безопасной штатной операцией.

Создавать счёт можно через REST API, готовую страницу оплаты, платёжную ссылку, встраиваемый блок или официальный плагин CMS. Механика подтверждения остаётся одинаковой; меняется только способ, которым клиент попадает к оплате.

Что происходит после отправки перевода?

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

Заказ безопасно исполнять только по конечному состоянию счёта. Проверка одного хеша в обозревателе не заменяет эту политику: свежий блок может измениться, а перевод может не совпасть по активу, сети или сумме. Готовая страница Paymos обновляет состояние без перезагрузки, а сервер бизнеса получает то же изменение через вебхук. Почему первое обнаружение ещё не означает оплату, подробно объясняет руководство по подтверждениям.

Как обрабатывается недоплата?

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

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

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

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

Доставка выполняется по принципу «хотя бы один раз», поэтому одно событие может прийти повторно. Полный цикл включает 11 попыток — начальную и десять повторов — примерно за 16 часов. Обработчик должен сначала проверить подпись, затем проверить, не применялось ли событие раньше, и только после этого менять заказ.

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

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

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

Какой способ выставления счёта выбрать?

Платёжная ссылка подходит для разовой продажи без разработки. Готовая страница оплаты закрывает обычный интернет-магазин: она показывает сети, QR-код и состояние платежа. Плагин CMS связывает эти действия с заказом WooCommerce, WHMCS, OpenCart и других поддерживаемых систем.

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