Недоплата, переплата и просроченный крипто-счёт
Откуда берутся недоплаты, переплаты и просроченные счета при оплате криптой, как обрабатывать каждый случай в коде и в поддержке и как предотвратить большинство из них.

Недоплата криптовалютой — это когда клиент прислал меньше суммы счёта, чаще всего потому, что биржа вычла из перевода свою комиссию за вывод. Переплата — когда пришло больше, а просроченный счёт — когда таймер закончился раньше, чем пришли деньги. Всё это нормальные ситуации для криптоплатежей, и у каждой есть стандартное решение: попросить доплатить остаток, выдать заказ и разобраться с разницей или сопоставить поздний платёж и выставить новый счёт.
Криптоплатёж — это перевод, который клиент отправляет сам: вводит или вставляет сумму и жмёт «Отправить» в своём кошельке или на бирже. Ничто не мешает ему отправить другую сумму или сделать это позже. Процессинг не может это запретить, зато может распознать ситуацию, понятно показать её клиенту и дать способ всё исправить.
Ниже — откуда берётся каждый случай, как устроены статусы счёта в Zypher, что должен делать ваш код и что отвечать в поддержке.
Статусы счёта
Счёт в Zypher проходит через такие статусы:
| Статус | Что значит | Что делать |
|---|---|---|
| PENDING | Счёт создан, денег пока нет | Ждать |
| CONFIRMING | Платёж виден в сети и ждёт подтверждений | Ждать, товар пока не выдавать |
| PAID | Пришло и подтвердилось не меньше 98% суммы | Выдавать заказ |
| OVERPAID | Пришло больше 102% суммы | Выдавать заказ и решить, что делать с излишком |
| UNDERPAID | Пришло меньше 98% суммы | Не выдавать, клиент может доплатить |
| EXPIRED | Время вышло до полной оплаты | Не выдавать, при необходимости выставить новый счёт |
| FAILED | Счёт не завершён | Не выдавать, проверить детали счёта |
Нижняя граница в 98% поглощает мелкие расхождения из-за округления и комиссий: если клиент прислал $99,10 по счёту на $100, счёт просто оплачен. Всё от 98% до 102% считается точной оплатой.
Число подтверждений, после которого платёж засчитывается: BTC 2, LTC 3, DOGE 3, XMR 5, BSC 5, Ethereum, Base и Arbitrum 6, Solana 8, TRON 10, TON 1. Поэтому в статусе CONFIRMING счёт может провисеть от нескольких секунд до нескольких минут.
Недоплата криптовалютой
Откуда берётся
Биржа вычла свою комиссию из суммы. Самая частая причина. Клиент выводит с биржи «10 USDT», а биржа отправляет 10 минус комиссия за вывод. Binance, например, берёт около $1 за вывод USDT в TRC20 — и вместо 10 приходит примерно 9 USDT, то есть 90%.
Клиент округлил. Ввёл 49,5 вместо 49,87.
Клиент заплатил по старой сумме. Скопировал её из истёкшего счёта.
Кошелёк вычел комиссию сети. В некоторых кошельках есть «отправить всё» или «комиссия включена», и уходит чуть меньше.
Как это обрабатывает Zypher
Если пришло меньше 98%, счёт переходит в статус UNDERPAID. На странице оплаты видно, сколько осталось, и клиент может доплатить остаток на тот же уникальный адрес. Частичные платежи суммируются: как только набирается 98% и больше, счёт становится PAID и приходит вебхук.
Что делать в коде
Событие вебхука одно — invoice.paid, и приходит оно только при data.status PAID или OVERPAID. Отдельного вебхука о недоплате нет. Поэтому:
Пока счёт недоплачен, с вашей стороны ничего делать не нужно. Когда клиент доплатит, придёт обычный вебхук об оплате.
Если хотите показывать «недоплачено» на странице заказа у себя, запрашивайте счёт через
GET /api/v1/invoice/:id, когда клиент её открывает. Опрашивать API каждые несколько секунд не нужно.Никогда не выдавайте заказ при UNDERPAID, даже если не хватает совсем чуть-чуть: допуск и так щедрый.
Что отвечать клиенту
Здравствуйте! По счёту на 10,00 USDT пришло 9,00 USDT — скорее всего, биржа удержала из суммы свою комиссию за вывод. Откройте ту же страницу оплаты и отправьте оставшийся 1,00 USDT на тот же адрес в той же сети. Как только деньги придут, заказ выполнится автоматически.
Если клиент не может или не хочет доплачивать, договоритесь: вернуть частичную сумму на адрес, который он укажет письменно, или зачислить её на баланс в магазине.
Переплата
Откуда берётся
Клиент добавил сверху «на всякий случай».
Оплатил дважды — с телефона и с компьютера.
Отправил сумму от другого, большего счёта.
Что делать в коде
При поступлении больше 102% счёт получает статус OVERPAID, и вебхук invoice.paid всё равно приходит, с data.status: "OVERPAID". Считайте такой счёт оплаченным и выдавайте заказ. Обработчик должен принимать оба статуса:
import hashlib, hmac, json, os
SECRET = os.environ["ZYPHER_API_SECRET"].encode()
def zypher_webhook(raw_body: bytes, signature: str) -> int:
expected = hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature or ""):
return 401
p = json.loads(raw_body)
if p["event"] == "invoice.paid" and p["data"]["status"] in ("PAID", "OVERPAID"):
fulfill_order_once(p["data"]) # идемпотентно
if p["data"]["status"] == "OVERPAID":
flag_for_review(p["data"]) # решить, что делать с излишком
return 200Частая ошибка — проверять только PAID. Тогда клиент, который заплатил больше, чем нужно, остаётся без заказа. Хуже обращения в поддержку не придумаешь.
Что делать с излишком
Заведите правило и запишите его:
Небольшая переплата (скажем, до $5): зачислите на баланс в магазине или, если баланса нет, оставьте как есть и сообщите клиенту.
Крупная переплата или двойная оплата: верните разницу. Попросите у клиента письменно адрес и сеть, затем отправьте обычный вывод — он оплачивает комиссию сети. Можно вычитать эту комиссию из суммы возврата, но тогда напишите об этом в правилах.
Просроченный счёт
Сколько живёт счёт
Счёт в монете истекает через 30 минут.
Счёт в долларах даёт 60 минут на выбор монеты и сети и ещё 30 минут на оплату после выбора.
Платёж, пришедший в течение 30 минут после истечения, всё ещё может быть сопоставлен со счётом.
Таймер нужен потому, что курс монет меняется. Счёт в долларах фиксирует сумму в монете на ограниченное время, и ценовой риск ни у вас, ни у клиента не висит долго.
Откуда берётся
Клиент открыл счёт, пошёл покупать крипту на бирже, а верификация затянулась.
Биржа задержала вывод на проверку безопасности.
Клиент отправил из сети, где в этот момент подтверждения шли медленно.
Он просто вернулся к старой вкладке на следующий день.
Что делать
Оплата пришла в пределах 30 минут после истечения: ничего, она сопоставится автоматически.
Оплата пришла позже: найдите транзакцию по адресу депозита и сумме, убедитесь, что деньги дошли, и выполните заказ вручную или зачислите сумму на баланс клиента.
Оплаты не было: закройте заказ и у себя, а клиенту дайте кнопку «Оплатить снова», которая создаёт новый счёт. Не пересылайте ссылку на истёкший.
Что отвечать клиенту
Здравствуйте! Счёт истёк до того, как пришёл платёж, но мы нашли вашу транзакцию и выполнили заказ вручную. В следующий раз, пожалуйста, оплачивайте, пока идёт таймер на странице оплаты, или нажмите «Оплатить снова», чтобы получить новый счёт.
Не та сеть или не та монета — это не недоплата
Если клиент отправил USDT в BEP20 на счёт, где была указана TRC20, счёт не увидит частичную оплату — он не увидит ничего, потому что деньги ушли в другой блокчейн. Это отдельная проблема со своими правилами возврата; она разобрана в статье клиент отправил USDT не в той сети. У каждого счёта свой уникальный адрес депозита, поэтому найти транзакцию проще.
Чек-лист профилактики
Большинство таких обращений исчезают после нескольких изменений:
Цена в долларах, сеть выбирает клиент. Тогда страница оплаты показывает точную сумму в монете для выбранной сети.
Предупреждение о комиссии биржи рядом с кнопкой оплаты.
Дешёвые сети для небольших сумм. В TRC20 комиссия зависит от энергии TRON, а BEP20, TON и Solana для клиента обычно дешевле. Подробнее — в статье TRC20, BEP20 или ERC20: какую сеть USDT принимать.
В коде вебхука обрабатываются и PAID, и OVERPAID.
Выдача идемпотентна. Неудачная доставка вебхука повторяется до пяти раз.
Кнопка «Оплатить снова» вместо пересылки старых ссылок.
Короткие правила возврата и переплаты со ссылкой со страницы оплаты.
Шаблоны ответов поддержки на три случая выше.
Что видит клиент на странице оплаты
Если страница оплаты понятная, большинство проблем клиент решает сам. Страница оплаты Zypher показывает QR-код, таймер и отдельные состояния для недоплаты, переплаты и истечения срока, причём на 11 языках. Для каждого магазина можно задать адреса редиректа при успехе и неудаче, чтобы клиент попадал на страницу, где объяснено, что будет дальше.
Форматы запросов и ответов — в документации API, комиссии — на странице тарифов, а если выбираете провайдера, посмотрите сравнение комиссий криптоэквайринга. Чтобы проверить эти сценарии на реальном магазине, зарегистрируйтесь — это минута и без документов.
Частые вопросы
- Что значит недоплата при оплате криптовалютой?
Это значит, что клиент прислал меньше суммы счёта; в Zypher — меньше 98% от неё. Обычно причина в том, что биржа вычла из перевода свою комиссию за вывод. Клиент может доплатить остаток на тот же адрес, и частичные платежи суммируются.
- Выдавать ли заказ, если не хватает совсем немного?
Нет, пока счёт в статусе недоплаты — не выдавать. Zypher и так считает оплату от 98% полной, так что мелкие расхождения уже учтены. Если пришло меньше, попросите клиента доплатить остаток.
- Что будет, если клиент оплатил после истечения счёта?
Платёж, пришедший в течение 30 минут после истечения, всё ещё может быть сопоставлен со счётом. Более поздние платежи обрабатываются вручную: найдите транзакцию, сверьте сумму и выполните заказ или верните деньги. Для новой попытки создавайте новый счёт.
- Есть ли вебхук о недоплате или истечении счёта?
Нет. Zypher отправляет одно событие —
invoice.paid, когда статус PAID или OVERPAID. Чтобы показывать другие состояния в своём интерфейсе, запрашивайте счёт черезGET /api/v1/invoice/:id.- Как вернуть переплату?
Попросите у клиента письменно адрес и сеть для возврата. Отправьте разницу обычным выводом, он оплачивает комиссию сети. В правилах возврата укажите, вычитается ли эта комиссия из суммы.