Что будет, если покупатель заплатил не той монетой или не в той сети?

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

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

Что делает Paymos, если покупатель заплатил из другой сети?

Засчитывает платёж в счёт один к одному — почти в любой сети, где Paymos принимает эту монету.

Заплатить не из той сети вообще получается из-за адреса. Адрес вида 0x… — одна и та же строка во всех сетях на виртуальной машине Ethereum, EVM: в справке MetaMask сказано прямо, что секретная фраза восстановления даёт один и тот же адрес во всех EVM-совместимых сетях. Поэтому если клиент отправил не в ту сеть — страница оплаты показала адрес в Polygon, а он выбрал в форме вывода на бирже BNB Smart Chain, — перевод пришёл на тот же адрес, только в другой сети.

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

Бывает, что Paymos принимает монету в этой сети, а платёж в счёт всё равно не засчитывается. Тогда деньги ложатся на баланс мимо счёта, если сумма не ниже минимума сети, а счёт истекает в свой срок. Когда этот перевод сам или вместе с прежними покрывает сумму счёта, на эндпоинт приходит invoice.paid_late. Статус счёта не меняется, в paid_late_at записано, когда деньги добрали сумму, а выдавать ли заказ, решаете вы.

У Tron, TON и Solana свой формат адреса, и кошелёк другой сети не примет такой адрес получателем, так что ошибки с сетью, которые доходят до счёта, случаются между EVM-сетями.

Прислали USDC вместо USDT — что Paymos делает с деньгами?

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

USDC по счёту в USDT ложатся на баланс как USDC — присланная сумма минус эта комиссия. Ничего не конвертируется, и курс к ним не применяется, чтобы подогнать их под сумму счёта. Счёт этот перевод не оплачивает, и позже другая монета в его сумму тоже не засчитается, так что invoice.paid_late за ней не придёт. Зачисление помечено как оплата не той монетой, а заказ за ним ждёт вашего решения.

Считается пара — эта монета в этой сети. У монеты в каждой сети свой контракт, и каждый эмитент ведёт собственный список сетей: Circle — для USDC, Tether — для USDT. Какие пары принимает Paymos, видно на /tokens/usdt и /tokens/usdc, а чем эти монеты отличаются для бизнеса — в сравнении USDT, USDC и DAI.

Почему деньги на балансе, а заказ отменился?

Потому что счёт истёк, а ваш сервер отреагировал на истечение. Это единственное место, которое стоит поправить в интеграции.

У такого зачисления нет своего вебхука: ни одно из девяти событий счёта в каталоге событий зачисление не описывает. Но счёт, мимо которого прошли деньги, доживает окно оплаты, и Paymos отправляет по нему invoice.expired — в документации это «инвойс истёк без подходящей оплаты». Так и есть. Только о деньгах, которые уже лежат у вас на балансе, там ни слова.

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

// invoice.expired значит: счёт не оплачен.
// Это не значит, что на его адрес ничего не присылали.
if ($type === 'invoice.expired') {
    $this->holdForReview($invoiceId);   // не отменять и не возвращать на склад
}

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

У отложенного заказа может появиться второй сигнал. Если деньги в монете счёта, пришедшие после срока или из другой сети, всё-таки доберут сумму, по тому же счёту придёт invoice.paid_late. Статус останется expired, так что само событие ничего не меняет: это пометка к отложенному заказу и повод для того, кто его разбирает, посмотреть ещё раз. Другая монета такого события не даёт.

Как Paymos сообщает мерчанту о зачислении?

Уведомление уходит вместе с зачислением — письмом и колокольчиком в дашборде, а при привязанном контакте ещё и в Telegram; приходит оно тем же путём, что и сообщение о выводе. В уведомлении сумма, которая легла на баланс, комиссия отдельной строкой, монета, сеть, причина и ссылка в дашборд.

На странице «Баланс» такие поступления стоят на вкладке «Операции», в одной таблице с выводами; фильтр по типу отделит одни от других. По строке видно, пришли деньги по счёту или без счёта и что это было: не та монета, не та сеть, оплата после срока, уже закрытый счёт или адрес, за которым нет счёта. Сумма со знаком «+» — то, что легло на баланс. По щелчку строка раскрывается: «Пришло», «Комиссия», «На баланс», «Инвойс» — тот, которому принадлежал адрес, либо «Без инвойса», — «Отправитель», «Транзакция» и короткое пояснение. Если исходного перевода никто не видел, там стоит «Отправитель неизвестен» и «Транзакция неизвестна», а сведения, найденные позже, подтягиваются к той же строке.

У самих зачислений нет ни вебхука, ни метода API: интеграция узнаёт о них из дашборда и почты. Единственное событие, к которому могут привести эти деньги, — invoice.paid_late, о нём выше.

Что делать с заказом и деньгами?

Решать вам, а всё, что для этого нужно, Paymos уже показал. Счёт останется expired, что бы вы ни выбрали, даже если по нему пришёл invoice.paid_late. Выбирать приходится другое — отгрузить заказ или вернуть деньги.

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

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

До того как что-то обещать покупателю, решите две вещи. На балансе лежит пришедшая сумма за вычетом комиссии, так что вернуть ровно отправленное — значит доплатить разницу из своих. А если отправитель неизвестен, возвращать некуда.

Когда деньги сами не придут?

В трёх случаях, и ни в одном из них перевод не зачисляется автоматически.

Монета, которую Paymos в этой сети не принимает: USDC в Tron или TON, USDT в Base. Такой перевод не зачисляется. Полный список пар — на /tokens/usdt, /tokens/usdc и /chains.

Сеть, которую счёт не принимает. Для адреса вида 0x… это и есть реальная ошибка. Один и тот же адрес существует в любой EVM-сети, а в предложенном стандарте ERC-7828 прямо сказано, что сетей второго уровня с тем же форматом адреса, что у основной сети Ethereum, будут сотни, а со временем тысячи. Это намного больше, чем принимает Paymos. Перевод, отправленный в такой сети, остаётся на этом адресе в этой сети.

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

Что делать покупателю, который уже отправил?

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

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

Главная из них — хеш. С ним платёж находят за один шаг, без сверки сумм и времени.

Чем это отличается от переплаты и недоплаты?

Тем, стоит ли за деньгами счёт.

Переплату и недоплату Paymos ведёт как состояния счёта. У каждого есть статус, который читает интеграция, и событие, на которое она подписана: invoice.paid_over, invoice.underpaid, invoice.underpaid_waiting. За каждым стоит заказ, который чего-то ждёт. Про них — разбор суммы, а как выставлять сам счёт — руководство по криптоинвойсам.

Зачисление мимо счёта — деньги, за которыми счёта нет. Ни статуса, ни собственного события, а заказ, к которому они на вид относятся, мог истечь, мог закрыться месяц назад, а мог и не существовать вовсе.

Различить их проще всего по тому, где их видно. Недоплату видно по самому счёту: у него свой статус, и понятно, сколько не хватило. Зачисление мимо счёта видно только на странице «Баланс» — строкой на вкладке «Операции». Если приход есть на балансе, а счёта за ним нет, это не частичная оплата: счёт по нему не закроется, и решение по заказу принимаете вы.