Недоплата, переплата, поздние и повторные переводы при оплате криптовалютой

Обрабатывайте недоплату, переплату, истёкшие заказы и дубли с точным учётом сумм, комиссий каждого поступления и проверенных callback Suawave.

Опубликовано , обновлено

Недоплата и переплата криптовалютой показаны чашами с разным количеством синих и красных стеклянных шаров

Для обработки недоплаты криптовалютой сначала нужны правила учёта сумм, а уже потом ответ поддержки. Храните сумму заказа, выбранный тикер и минимальный платёж. Учитывайте каждое допустимое подтверждённое поступление один раз с точными суммами. Рассматривайте переплату, адрес с истёкшим сроком и повторный webhook отдельно: они требуют разных решений и не всегда вызывают callback.

Публичный API Suawave для создания адреса не принимает сумму заказа магазина. Он назначает адрес приёма тикеру и callback URL. Магазин определяет, оплачивают ли проверенные поступления покупку на 25 USDT. Шлюз определяет, допустим ли каждый перевод для дальнейшей отправки.

Как странице оплаты обрабатывать недоплату криптовалютой?

Сначала различайте недоплату относительно суммы заказа и перевод ниже минимума шлюза. Поступление 20 USDT для заказа на 25 USDT может быть допустимым для перевода, но оставлять заказ неоплаченным. Перевод ниже минимума тикера не отправляется дальше, не вызывает callback и не отображается в публичных журналах. Это разные состояния ожидания.

Прочитайте minimum_transaction_coin из GET /{ticker}/info/ или ответа create. Покажите его до отправки средств покупателем и проверьте ещё раз, прежде чем предлагать доплату. К переводу применяется минимум, действующий при его первом обнаружении.

Ситуация при оплате Поведение шлюза Ответственность магазина
Допустимое поступление ниже суммы заказа Отдельный перевод со своими комиссиями и confirmed callback Записать поступление и оставить остаток неоплаченным
Поступление ниже минимума тикера Нет перевода и публичного callback Объяснить минимум и обратиться в поддержку для проверки
Допустимое поступление выше суммы заказа Всё допустимое поступление переводится за вычетом комиссий Записать переплату и применить правила магазина
Повторная доставка того же webhook Тот же UUID события Подтвердить получение без повторения действий

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

Может ли покупатель доплатить позже?

Покупатель может отправить ещё одно поступление, пока заказ допускает оплату, но каждое поступление должно независимо соответствовать минимуму тикера. Suawave переводит каждое подходящее поступление отдельно. Части ниже минимума не объединяются в один допустимый перевод.

Рассмотрим заказ на 25 USDT, по которому покупатель сначала отправляет 20 USDT. Недостающие 5 USDT меньше минимума USDT в TRON из исходной конфигурации: 10.00 USDT. Просьба «отправьте оставшиеся 5» создаёт вторую проблему: этот перевод ниже минимума. Минимум USDT BEP20 в исходной конфигурации составляет 1.00 USDT, но перед выдачей инструкций прочитайте фактическое значение API.

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

Нужно ли вычитать комиссии из суммы, засчитываемой в заказ?

Явно выберите основу правил магазина: поступившую сумму до комиссий или чистую выплату. value_coin содержит входящее поступление. value_forwarded_coin содержит сумму, дошедшую до адреса выплат после общей комиссии из fee_coin.

Если магазин засчитывает сумму до комиссий, допустимое поступление 25 USDT может оплатить заказ на 25 USDT, хотя чистая выплата меньше. Если требуется чистая сумма, этого поступления может не хватить. Не вычитайте fee_coin из value_forwarded_coin повторно: комиссия уже удержана из последнего значения.

Храните суммы десятичными строками до преобразования в целое число минимальных единиц или точный десятичный тип. В реестре USDT в TRON имеет шесть знаков после запятой, а USDT в BSC восемнадцать. Предположение, что у каждого тикера USDT шесть знаков, приводит к ошибкам разбора сумм между сетями.

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

Публичный процесс переводит всё допустимое поступление за вычетом комиссий. Он не ограничивает поступление ожидаемой суммой заказа и не возвращает разницу отправителю автоматически. Поступление 30 USDT для заказа на 25 USDT требует решения магазина о лишних 5 USDT.

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

Не считайте txid_in доказательством безопасного адреса возврата. Плательщик мог отправить средства с биржи или другого сервиса, чей адрес отправки не является его личным адресом получения. До отдельного возврата запросите и проверьте нужный адрес через собственный процесс работы с клиентом. Публичный API create в Suawave не является API возвратов.

Два реальных поступления также считаются двумя платежами, даже если покупатель называет второе случайным. У каждого могут быть свои confirmed callback и комиссии. Второй платёж после оплаты заказа должен создавать запись о переплате, а не повторную отправку товара.

Пример учёта: заказ стоит 25 USDT, подтверждённое поступление составляет 20 USDT, неоплаченный остаток равен 5 USDT. Этот остаток ниже указанного выше минимума TRC20, поэтому автоматически просить отправить ровно 5 USDT нельзя.

Что происходит с криптоплатежом после истечения срока заказа?

Create возвращает expires_at, и повторный create для той же пары тикер и callback возвращает исходный срок. Он не продлевает окно оплаты. После истечения срока перестаньте показывать старый адрес приёма и создайте новый заказ с отдельным callback URL, если покупатель хочет повторить попытку.

Срок по умолчанию в публичном API составляет 24 часа, но используйте возвращённую временную метку, не предполагая, что развёрнута именно эта настройка. У шлюза также есть настраиваемый льготный период, по умолчанию две минуты. Это допуск при проверке допустимости, а не дополнительное окно оплаты, которое следует обещать покупателю.

Suawave определяет фактическое время перевода как более раннее из времени наблюдения и временной метки блока с добавлением настроенного допуска рассинхронизации часов. Финализация после срока сама по себе не делает перевод поздним. Допустимость определяют время перевода и настроенный льготный период, а не момент получения callback магазином.

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

Что делать, если оператор позже переводит удержанные средства продавцу?

Ручной перевод оператором на адрес выплат не вызывает публичного callback. Поэтому магазину нужна ручная сверка, если поддержка разрешает удержание позднего платежа таким способом. Не обещайте автоматически, что каждый удержанный платёж со временем переключит заказ в оплаченный.

Разделяйте старый заказ и заменяющий его новый. Повторно использовать callback URL с истёкшим сроком для получения другого адреса не получится, поскольку пара тикер и callback постоянна. Это правило идентификации описано в справочнике создания адресов.

Как отличить повторные платежи от повторных webhook?

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

У pending и confirmed callback разные UUID. Если считать каждый новый UUID дополнительными деньгами, одно поступление будет учтено дважды. В принятую подтверждённую сумму должны входить только confirmed-события, а запись поступления должна сохранять связь между его pending- и confirmed-состояниями.

Callback также могут приходить не по порядку. Если подтверждение уже записано, позднее pending-событие не должно возвращать поступление в ожидание. Статья о финальности криптоплатежей объясняет различие между обнаружением и подтверждённым переводом.

Что должна включать транзакция базы данных?

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

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

Проверка Решение
UUID события уже сохранён Подтвердить получение без повторного учёта
Поступление ниже минимума или позже допустимого срока Разобрать с поддержкой; не ожидать публичного callback
Подтверждённой суммы недостаточно для заказа Записать поступление и неоплаченный остаток
Заказ оплачен с избытком Выполнить заказ один раз и отдельно учесть переплату

Что проверять поддержке, если суммы не сходятся?

Получите журналы исходного заказа по сохранённому callback URL и не раскрывайте полный URL. Он даёт доступ к журналам. Сопоставьте допустимые записи с сохранёнными confirmed-событиями. sent означает подтверждённый перевод без подтверждения получения confirmed callback; done означает, что получение этого callback подтверждено.

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

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