Устранение неполадок с платежами через смарт-контракты
Это руководство поможет разобраться с частыми проблемами при приёме некастодиальных платежей через смарт-контракты Volet.com в Ethereum, BNB Smart Chain и TRON.
Найдите свою проблему ниже и выполните рекомендуемые шаги. Адреса контрактов, параметры и описания ошибок приведены в справочнике по смарт-контрактам.
Проблемы с кошельком и сетью
| Проблема | Возможная причина | Что делать |
|---|---|---|
| Подключение кошелька отклонено | Клиент отклонил запрос или кошелёк заблокирован | Попросите клиента разблокировать кошелёк и подключиться заново |
| MetaMask не обнаружен | Совместимый браузерный кошелёк не установлен или недоступен | Установите MetaMask или подключитесь через кошелёк с поддержкой WalletConnect |
| Неверная EVM-сеть | Кошелёк подключён не к той сети, что выбрана на странице оплаты | Запросите переключение сети и проверьте chain ID |
| Не удаётся подключиться через WalletConnect | Неверный Project ID, ошибка в настройках или неподдерживаемый кошелёк или сеть | Проверьте настройки проекта Reown и список поддерживаемых сетей |
| TronLink не обнаружен | Расширение не установлено, не включено или заблокировано | Установите или разблокируйте TronLink и обновите страницу |
| Неверная сеть TRON | Кошелёк подключён к тестовой или неожиданной сети | Переключитесь на TRON Mainnet и проверьте активную сеть |
Всегда заново проверяйте адрес кошелька и выбранную сеть перед отправкой платежа, особенно после подключения кошелька или переключения сети.
Проблемы с одобрением USDT
Для платежей в USDT может понадобиться транзакция одобрения, прежде чем контракт-процессор сможет списать токены.
| Проблема | Возможная причина | Что делать |
|---|---|---|
| Транзакция одобрения отклонена | Клиент отклонил запрос в кошельке | Дайте клиенту повторить одобрение |
| Недостаточное разрешение (allowance) | Процессору не разрешено списывать нужную сумму | Проверьте allowance() и запросите одобрение на нужную сумму |
| Одобрение USDT в Ethereum не проходит | Ненулевое разрешение нельзя напрямую изменить на другое ненулевое значение | Одобрите 0, дождитесь подтверждения, затем одобрите нужную сумму |
| Недостаточно USDT на балансе | У клиента не хватает токенов на полную сумму платежа | Сравните balanceOf() с previewPayment().totalPay |
| Одобрение прошло, а платёж в ожидании | Одобрение выполнено, но платёжная транзакция не отправлена или не проверена | Проверьте текущее разрешение, затем отправьте или проверьте отдельную платёжную транзакцию |
Важно: успешная транзакция approve() — это ещё не оплата. Для проверки оплаты заказа подходит только транзакция transfer() контракта-процессора.
Ошибки транзакций и контрактов
| Ошибка или проблема | Возможная причина | Что делать |
|---|---|---|
InvalidTotalAmountValidation | Нативный value или callValue не совпадает с ожидаемой суммой платежа | Повторно вызовите previewPayment() и отправьте полученный totalPay |
SellerIsBuyer | Адреса кошельков покупателя и мерчанта совпадают | Убедитесь, что кошелёк мерчанта для приёма средств отличается от подключённого кошелька покупателя |
SellerZeroAddress | Адрес мерчанта для приёма средств — нулевой адрес | Укажите корректный кошелёк мерчанта |
AmountIsZero | Сумма платежа равна нулю | Проверяйте сумму заказа перед отправкой транзакции |
CommissionExceedsAmount | Комиссию за обработку невозможно вычесть из запрошенной суммы | Проверьте сумму заказа и настройку комиссии |
SellerNotWhitelisted | Процессор не разрешает приём на этот кошелёк мерчанта | Свяжитесь с Volet.com, чтобы проверить статус кошелька |
EnforcedPause | Обработка платежей в контракте приостановлена | Прекратите отправлять платежи через этот процессор и свяжитесь с Volet.com |
| Не проходит перевод токенов | Недостаточный баланс токенов, разрешение или ограничения самого токена | Проверьте контракт токена, баланс, разрешение и выбранную сеть |
| Недостаточно газа | У клиента не хватает ETH или BNB на комиссию сети | Попросите клиента держать на балансе достаточно нативной монеты |
| Недостаточно ресурсов TRON | У клиента не хватает Energy, Bandwidth или доступных TRX | Проверьте требования к ресурсам и доступный баланс TRX |
TRON OUT_OF_ENERGY | Выполнение контракта исчерпало доступную Energy или заданный лимит комиссии | Оцените расход ресурсов и проверьте feeLimit транзакции |
TronGrid HTTP 429 | Превышен лимит запросов к API | Используйте серверный API-ключ и повторяйте запросы с увеличивающейся задержкой |
Ошибки контрактов зависят от развёрнутого процессора. Описания ошибок приведены в справочнике по смарт-контрактам.
Платёж остаётся в ожидании
Заказ может оставаться в ожидании даже после того, как клиент отправил транзакцию.
| Ситуация | Что проверить | Что делать |
|---|---|---|
| Хеш транзакции получен, а квитанции нет | Транзакция, возможно, ещё не попала в блок | Продолжайте проверять тот же txid |
| Транзакция выполнена, но не финализирована | Требуемая финальность сети ещё не достигнута | Дождитесь финальности, прежде чем завершать заказ |
| Одобрение USDT подтверждено, а платежа нет | Отправлена только транзакция одобрения | Проверьте, есть ли отдельная платёжная транзакция |
| Транзакция успешна, а заказ всё ещё в ожидании | Данные платежа могут не совпадать с заказом, или проверка на бэкенде не завершена | Сверьте с заказом процессор, актив, получателя, сумму и вызов контракта |
| Транзакция TRON видна, но не solidified | Транзакция ещё не появилась в данных SolidityNode | Продолжайте проверять solidified-квитанцию транзакции |
| RPC-запрос завершается ошибкой или по тайм-ауту | Провайдер временно недоступен | Повторите проверку, не помечая транзакцию как неуспешную |
| Клиент закрыл или обновил страницу оплаты | Сессия браузера завершилась до подтверждения платежа | Продолжайте проверку через фоновый обработчик сверки на бэкенде |
| Срок оплаты истёк до подтверждения платежа | Транзакция может подтвердиться уже после закрытия окна оплаты | Продолжайте отслеживать отправленные попытки оплаты и сверяйте поздние платежи |
Транзакция успешна, но заказ не помечен как оплаченный
Успешная транзакция в блокчейне ещё не значит, что оплачен именно нужный заказ.
Ваш бэкенд должен убедиться, что:
- Транзакция использовала ожидаемый конт ракт-процессор.
- Актив и кошелёк мерчанта для приёма средств совпадают с заказом.
- Сумма платежа и настройки комиссии верны.
- Мерчант получил ожидаемые средства.
- Транзакция достигла требуемой финальности в блокчейне.
- Хеш транзакции ещё не использован для другого заказа.
Если хоть одна обязательная деталь не совпадает, не помечайте заказ как оплаченный автоматически. Оставьте платёж на ручной проверке.
Полный процесс проверки описан в статье Проверка платежей и отслеживание заказов.
Обращение в поддержку
Если проблема не решилась, обратитесь в Volet.com и укажите:
- Блокчейн-сеть и актив.
- Хеш платёжной транзакции (
txid), если он есть. - Примерную дату и время транзакции.
- Идентификатор заказа мерчанта.
- Адрес контракта-процессора.
- Текст ошибки или описание проблемы.
Связаться с нами можно через поддержку Volet.com.
Безопасность: никогда никому не сообщайте сид-фразы кошельков, приватные ключи и секретные учётные данные API.
См. также
- Интеграция со смарт-контрактами — обзор некастодиальных платежей.
- Интеграция с Ethereum и BNB Smart Chain — приём ETH, BNB и USDT.
- Интеграция с TRON — приём TRX и USDT TRC-20.
- Справочник по смарт-контрактам — адреса контрактов, параметры и ошибки.
- Проверка платежей и отслеживание заказов — проверка транзакций и сверка заказов.