Привязка платежей и несовпадение сумм

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

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

Правило совпадения суммы

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

Сумма платежа должна совпадать с суммой счета один в один. Допуска нет. Сумма к оплате формируется с точностью до 2 знаков после запятой для стейблкоинов USDT и USDC и до 8 знаков для остальных криптовалют, и поступивший платеж сравнивается с ней точно. Любое отклонение — недоплата или переплата, даже на минимальную величину — означает, что автоматической привязки не произойдет.

Пример. Счет на 100.00 USD выставлен с зафиксированной суммой 100.12 USDT.

Сумма поступившего платежа	Результат
100.12 USDT	Счет автоматически переходит в статус «Оплачен»
100.11 USDT	Автоматической привязки нет
100.50 USDT	Автоматической привязки нет

Если на один адрес одновременно выставлено несколько счетов на одинаковую фиатную сумму, сервис назначит каждому немного отличающуюся сумму в криптовалюте. Уникальность проверяется среди всех ваших актуальных счетов на этом кошельке, поэтому один адрес можно безопасно использовать в нескольких ваших проектах — суммы не пересекутся.

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

Что происходит при несовпадении суммы

Сервис фиксирует факт поступления средств, но не выполняет никаких действий со счетом:

• Счет не меняет статус. Он остается актуальным до истечения срока оплаты. Покупатель по-прежнему может закрыть его правильной суммой, пока не истек срок поиска.
• Webhook не отправляется. Уведомление на Webhook URL уходит исключительно в момент перехода счета в статус «Оплачен».
• Частичная оплата не учитывается. Сервис не различает недоплату и не ведет учет остатка по счету.
• Платежи не суммируются. Если покупатель после недоплаты отправит недостающую разницу второй транзакцией, эти два платежа не будут сложены. Оба останутся отдельными непривязанными платежами.
• Переплата не возвращается автоматически. Средства поступают напрямую на ваш кошелек, вопрос возврата разницы покупателю решается вне сервиса.

Промежуточных статусов вида «Частично оплачен» или «Переплата» в сервисе не предусмотрено.

Как продавец узнаёт о проблеме

Если в настройках проекта включены уведомления, продавец получает на email и в Telegram-бот сообщение о каждом входящем платеже — независимо от того, привязался он к счету или нет.

Отсюда простое диагностическое правило: пришло уведомление о входящем платеже, но следом не пришло уведомление об оплаченном счете — значит, платеж не привязался из-за расхождения в сумме и требует ручной обработки.

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

Непривязанные платежи можно находить и программно. Метод payments/list возвращает платежи по всем вашим кошелькам, и у платежа, не привязанного к счету, в ответе отсутствует блок invoice. Это и есть кандидаты на ручную привязку: сопоставьте сумму и время с ожидаемым счетом и вызовите invoices/bindPayment.

Ручная привязка платежа

Если вы уверены, какой платеж соответствует какому счету, привяжите их вручную — в личном кабинете в карточке счета или в списке платежей, либо через API методом invoices/bindPayment.

Условия привязки

Привязка возможна, только если выполнены все условия одновременно:

1. Счет в статусе «Актуален» или «Просрочен». Отмененные и уже оплаченные счета привязать нельзя.
2. Платеж еще не привязан к другому счету. Один платеж может быть связан только с одним счетом.
3. Платеж поступил на кошелек, задействованный в этом счете.
4. Платеж попадает в окно доступных платежей — сутки до и сутки после создания счета.

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

Что происходит после привязки

• Счет переходит в статус «Оплачен» — так же, как при автоматической привязке.
• Webhook отправляется в обязательном порядке. Уведомление уходит при каждом переходе счета в «Оплачен», независимо от способа привязки.
• Сумма счета в USD пересчитывается по факту. Поле amountFiatUSD перезаписывается фактически поступившей суммой по курсу на момент привязки. Исходная сумма в amountFiat не меняется.
• Комиссия пересчитывается от фактической суммы. Считается по ставке тарифа проекта от суммы, которую вы получили.