Недоплата, переплата и просроченный крипто-счёт

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

09.11.20269 мин чтения
Underpaid invoice for 96.50 of 100 USDT, with overpaid and expired invoice cards on either side

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

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

Ниже — откуда берётся каждый случай, как устроены статусы счёта в 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 минут после истечения, всё ещё может быть сопоставлен со счётом.

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

Откуда берётся

  • Клиент открыл счёт, пошёл покупать крипту на бирже, а верификация затянулась.

  • Биржа задержала вывод на проверку безопасности.

  • Клиент отправил из сети, где в этот момент подтверждения шли медленно.

  • Он просто вернулся к старой вкладке на следующий день.

Что делать

  1. Оплата пришла в пределах 30 минут после истечения: ничего, она сопоставится автоматически.

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

  3. Оплаты не было: закройте заказ и у себя, а клиенту дайте кнопку «Оплатить снова», которая создаёт новый счёт. Не пересылайте ссылку на истёкший.

Что отвечать клиенту

Здравствуйте! Счёт истёк до того, как пришёл платёж, но мы нашли вашу транзакцию и выполнили заказ вручную. В следующий раз, пожалуйста, оплачивайте, пока идёт таймер на странице оплаты, или нажмите «Оплатить снова», чтобы получить новый счёт.

Не та сеть или не та монета — это не недоплата

Если клиент отправил 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.

Как вернуть переплату?

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

Недоплата криптовалютой, переплата и истёкший счёт | Zypher