Справочник по смарт-контрактам
В справочнике собраны адреса контрактов, данные токенов и описания функций для некастодиальных платежей Volet.com в Ethereum, BNB Smart Chain и TRON.
Пошаговые инструкции — в руководствах Интеграция с Ethereum и BNB Smart Chain и Интеграция с TRON.
Адреса платёжных процессоров
Для каждого поддерживаемого актива используется свой смарт-контракт — платёжный процессор.
| Сеть | Актив | Контракт-процессор |
|---|---|---|
Ethereum Mainnet (1) | ETH | 0x2fceE245109Cf3c535489a6F52fe11b3BBd644FF |
Ethereum Mainnet (1) | USDT ERC-20 | 0xe4083ED0A1101615b9092E8cD2164e2f42B4571E |
BNB Smart Chain (56) | BNB | 0x2fceE245109Cf3c535489a6F52fe11b3BBd644FF |
BNB Smart Chain (56) | USDT BEP-20 | 0xe4083ED0A1101615b9092E8cD2164e2f42B4571E |
| TRON Mainnet | TRX | TSK9sgBTjvZa6x2yW1bXNWqvQ57WsVUQ3W |
| TRON Mainnet | USDT TRC-20 | TDuE6VueULx5oivQd4MsYr9DEhNMgXNfTm |
Прежде чем принимать платежи, сверьте адреса развёрнутых контрактов и ABI с Volet.com. У контрактов для других сетей, активов или нестандартных платёжных сценариев могут быть другие адреса и интерфейсы.
Адреса и decimals токенов
| Сеть | Актив | Контракт токена | Decimals |
|---|---|---|---|
| Ethereum | ETH (нативный) | — | 18 |
| Ethereum | USDT ERC-20 | 0xdAC17F958D2ee523a2206206994597C13D831ec7 | 6 |
| BNB Smart Chain | BNB (нативный) | — | 18 |
| BNB Smart Chain | USDT BEP-20 | 0x55d398326f99059fF775485246999027B3197955 | 18 |
| TRON | TRX (нативный) | — | 6 (SUN) |
| TRON | USDT TRC-20 | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
Все суммы для смарт-контракта указываются в минимальных единицах актива.
- ETH и BNB: переводите суммы в wei с помощью
ethers.parseEther(). - USDT в EVM-сетях: используйте
ethers.parseUnits(amount, tokenDecimals)с точностью соответствующего токена. - TRX: используйте SUN, 1 TRX = 1 000 000 SUN.
- USDT в TRON: используйте целые базовые единицы токена, 1 USDT = 1 000 000 единиц.
Не рассчитывайте суммы платежей в арифметике с плавающей точкой.
Интерфейс платёжного контракта
У стандартного платёжного процессора две основные функции: previewPayment() и transfer().
interface IVoletPaymentProcessor {
function previewPayment(
uint256 amount,
bool buyerPaysCommission
) external view returns (
uint256 commission,
uint256 totalPay
);
function transfer(
address seller,
uint256 amount,
bool buyerPaysCommission,
address optionalCommissionWallet
) external payable;
}
Этот интерфейс описывает платёжные функции, которые используются в руководствах по интеграции. Для декодирования событий и обработки ошибок конкретного контракта используйте полный верифицированный ABI развёрнутого контракта.
previewPayment()
Рассчитывает комиссию за обработку и полную сумму, которую должен заплатить клиент.
Параметры
| Параметр | Тип | Описание |
|---|---|---|
amount | uint256 | Запрошенная сумма платежа в минимальных единицах актива |
buyerPaysCommission | bool | Определяет, добавляется ли комиссия за обработку к платежу клиента или вычитается из выручки мерчанта |
Возвращаемые значения
| Параметр | Тип | Описание |
|---|---|---|
commission | uint256 | Комиссия за обработку в минимальных единицах актива |
totalPay | uint256 | Полная сумма к оплате клиентом в минимальных единицах актива |
Для платежей в нативном активе передайте totalPay как value транзакции в EVM или как callValue в TRON.
Для платежей в USDT баланс токенов клиента и разрешение (allowance) для процессора должны быть не меньше totalPay.
Всегда используйте значения, которые возвращает previewPayment(). Не рассчитывайте комиссию за обработку вручную.
transfer()
Выполняет платёж и распределяет средства по настройкам комиссии контракта.
Параметры
| Параметр | Тип | Описание |
|---|---|---|
seller | address | Кошелёк мерчанта для приёма средств |
amount | uint256 | Запрошенная сумма платежа в минимальных единицах актива |
buyerPaysCommission | bool | Определяет, кто платит комиссию за обработку |
optionalCommissionWallet | address | Кошелёк партнёра для получения комиссии или нулевой адрес сети, если партнёра нет |
Нулевые адреса
| Сеть | Нулевой адрес |
|---|---|
| Ethereum / BNB Smart Chain | 0x0000000000000000000000000000000000000000 |
| TRON (Base58) | T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb |
Функция transfer() не принимает параметр orderId. Ваш бэкенд должен сам связывать хеш каждой платёжной транзакции (txid) с соответствующим заказом.
О сопоставлении транзакций и защите от повторных платежей — в статье Проверка платежей и отслеживание заказов.
Событие платежа
После распределения платежа на кошелёк мерчанта платёжные процессоры генерируют событие PaymentProcessed.
event PaymentProcessed(
address indexed buyer,
address indexed seller,
uint256 commission,
uint256 totalPay
);
| Параметр | Тип | Описание |
|---|---|---|
buyer | address | Кошелёк, с которого инициирован платёж |
seller | address | Кошелёк мерчанта для приёма средств |
commission | uint256 | К омиссия за обработку в минимальных единицах актива |
totalPay | uint256 | Полная сумма, уплаченная покупателем, в минимальных единицах актива |
Сумма, которую получает мерчант:
receivedAmount = totalPay - commission
Формула верна при любом значении buyerPaysCommission.
Для платежей в нативных ETH, BNB и TRX успешная финализированная транзакция с подлинным совпадающим событием PaymentProcessed подтверждает платёж мерчанту в рамках задокументированной реализации процессора.
Для платежей в USDT дополнительно проверьте событие Transfer токена с переводом от платёжного процессора мерчанту на ожидаемую сумму.
Всегда сверяйте адрес контракта, сгенерировавшего событие, с утверждённым адресом процессора.
Примеры реализации — в статье Проверка платежей и отслеживание заказов.
Комиссия за обработку
Параметр buyerPaysCommission определяет, как применяется комиссия за обработку.
| Значение | Клиент платит | Мерчант получает |
|---|---|---|
true | Запрошенная сумма + комиссия за обработку | Запрошенная сумма |
false | Запрошенная сумма | Запрошенная сумма − комиссия за обработку |
Фактическую комиссию за обработку и полную сумму платежа рассчитывает previewPayment() по правилам развёрнутого контракта.
Комиссии блокчейн-сети оплачиваются отдельно от комиссии за обработку:
- Ethereum / BNB Smart Chain: газ, оплачивается в ETH или BNB.
- TRON: расход Energy и Bandwidth, который может оплачиваться в TRX.
Расчёты
При некастодиальных платежах смарт-контракт переводит средства напрямую на кошелёк мерчанта для приёма средств.
Средства не зачисляются на аккаунт Volet.com, и автоматическая конвертация в фиат в этот платёжный сценарий не входит.
Ошибки контракта
Платёжный процессор может вернуть следующие ошибки:
| Ошибка | Описание |
|---|---|
SellerZeroAddress | Адрес мерчанта для приёма средств — нулевой |
SellerIsBuyer | Адреса кошельков покупателя и мерчанта совпадают |
AmountIsZero | Сумма платежа равна нулю |
InvalidTotalAmountValidation | value или callValue нативного актива не совпадает с ожидаемой суммой |
CommissionExceedsAmount | Комиссия за обработку больше суммы, из которой её можно вычесть |
SellerNotWhitelisted | Развёрнутый контракт, возможно, не разрешает приём на этот кошелёк мерчанта |
EnforcedPause | Обработка платежей приостановлена |
Набор ошибок и их точное поведение зависят от развёрнутого контракта. Для декодирования пользовательских ошибок используйте его верифицированный ABI.
Причины и рекомендуемые действия — в статье Устранение неполадок с платежами через смарт-контракты.
См. также
- Интеграция со смарт-контрактами — обзор некастодиальной платёжной интеграции
- Интеграция с Ethereum и BNB Smart Chain — приём ETH, BNB и USDT
- Интеграция с TRON — приём TRX и USDT TRC-20
- Проверка платежей и отслеживание заказов — проверка транзакций и сопоставление платежей с заказами
- Устранение неполадок — решение частых ошибок кошельков и платежей