Referência de contratos inteligentes

Esta referência reúne os endereços dos contratos, os dados dos tokens e as definições das funções dos pagamentos não custodiais da Volet.com no Ethereum, na BNB Smart Chain e na TRON.

Para instruções passo a passo, veja Integração com Ethereum e BNB Smart Chain ou Integração com TRON.

Endereços dos processadores de pagamento

Cada ativo suportado usa um contrato inteligente processador de pagamentos.

Rede	Ativo	Contrato processador
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

Antes de processar pagamentos, confirme com a Volet.com os endereços dos contratos implantados e a ABI. Contratos de outras redes, ativos ou fluxos de pagamento personalizados podem usar endereços e interfaces diferentes.

Endereços e decimais dos tokens

Rede	Ativo	Contrato do token	Decimais
Ethereum	ETH (nativo)	N/A	18
Ethereum	USDT ERC-20	0xdAC17F958D2ee523a2206206994597C13D831ec7	6
BNB Smart Chain	BNB (nativo)	N/A	18
BNB Smart Chain	USDT BEP-20	0x55d398326f99059fF775485246999027B3197955	18
TRON	TRX (nativo)	N/A	6 (SUN)
TRON	USDT TRC-20	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t	6

Todos os valores do contrato inteligente devem ser expressos nas menores unidades do ativo.

• ETH e BNB: use ethers.parseEther() para converter os valores em wei.
• USDT em EVM: use ethers.parseUnits(amount, tokenDecimals) com a precisão do token correspondente.
• TRX: use SUN, sendo 1 TRX = 1.000.000 SUN.
• USDT na TRON: use unidades base inteiras do token, sendo 1 USDT = 1.000.000 unidades.

Não use aritmética de ponto flutuante para calcular os valores dos pagamentos.

Interface do contrato de pagamento

O processador de pagamentos padrão oferece duas funções principais: previewPayment() e 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;
}

Esta interface descreve as funções de pagamento usadas nos guias de integração. Use a ABI verificada completa do contrato implantado para decodificar eventos ou tratar erros específicos do contrato.

previewPayment()

Calcula a taxa de processamento e o valor total que o cliente deve pagar.

Parâmetros

Parâmetro	Tipo	Descrição
amount	uint256	Valor de pagamento solicitado nas menores unidades do ativo
buyerPaysCommission	bool	Define se a taxa de processamento é somada ao pagamento do cliente ou descontada da receita do lojista

Valores retornados

Parâmetro	Tipo	Descrição
commission	uint256	Taxa de processamento nas menores unidades do ativo
totalPay	uint256	Valor total que o cliente deve pagar, nas menores unidades do ativo

Em pagamentos com o ativo nativo, passe totalPay como value da transação em EVM ou como callValue na TRON.

Em pagamentos em USDT, o saldo de tokens do cliente e a permissão de gasto (allowance) do processador devem ser de pelo menos totalPay.

Sempre use os valores retornados por previewPayment(). Não calcule a taxa de processamento manualmente.

transfer()

Executa o pagamento e distribui os fundos de acordo com a configuração de taxas do contrato.

Parâmetros

Parâmetro	Tipo	Descrição
seller	address	Carteira de recebimento do lojista
amount	uint256	Valor de pagamento solicitado nas menores unidades do ativo
buyerPaysCommission	bool	Define quem paga a taxa de processamento
optionalCommissionWallet	address	Carteira de comissão do parceiro, ou o endereço zero da rede se não se aplicar

Endereços zero

Rede	Endereço zero
Ethereum / BNB Smart Chain	0x0000000000000000000000000000000000000000
TRON (Base58)	T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

A função transfer() não aceita o parâmetro orderId. Seu backend deve associar o hash de cada transação de pagamento (txid) ao pedido correspondente.

Veja Verificação de pagamentos e acompanhamento de pedidos para associar transações e evitar pagamentos duplicados.

Evento de pagamento

Os processadores de pagamento emitem o evento PaymentProcessed depois de distribuir o pagamento ao lojista.

event PaymentProcessed(
    address indexed buyer,
    address indexed seller,
    uint256 commission,
    uint256 totalPay
);

Parâmetro	Tipo	Descrição
buyer	address	Carteira que iniciou o pagamento
seller	address	Carteira de recebimento do lojista
commission	uint256	Taxa de processamento nas menores unidades do ativo
totalPay	uint256	Valor total pago pelo comprador nas menores unidades do ativo

O valor recebido pelo lojista é:

receivedAmount = totalPay - commission

Esta fórmula vale para qualquer valor de buyerPaysCommission.

Em pagamentos com ETH, BNB e TRX nativos, uma transação bem-sucedida e finalizada com um evento PaymentProcessed autêntico e correspondente confirma o pagamento ao lojista conforme a implementação documentada do processador.

Em pagamentos em USDT, verifique também o evento Transfer do token do processador de pagamentos para o lojista no valor esperado.

Sempre confira se o endereço do contrato que emitiu o evento corresponde ao endereço aprovado do processador.

Veja Verificação de pagamentos e acompanhamento de pedidos para exemplos de implementação.

Taxas de processamento

O parâmetro buyerPaysCommission define como a taxa de processamento é aplicada.

Valor	O cliente paga	O lojista recebe
true	Valor solicitado + taxa de processamento	Valor solicitado
false	Valor solicitado	Valor solicitado − taxa de processamento

A taxa de processamento real e o valor total do pagamento são calculados por previewPayment() de acordo com o contrato implantado.

As taxas de rede da blockchain são cobradas à parte da taxa de processamento:

• Ethereum / BNB Smart Chain: taxas de gas pagas em ETH ou BNB.
• TRON: custos de Energy e Bandwidth, que podem ser pagos em TRX.

Liquidação

Com pagamentos não custodiais, o contrato inteligente transfere os fundos diretamente para a carteira de recebimento do lojista.

Os fundos não são creditados em uma conta Volet.com, e a conversão automática para fiat não faz parte deste fluxo de pagamento.

Erros do contrato

O processador de pagamentos pode retornar os seguintes erros:

Erro	Descrição
SellerZeroAddress	O endereço de recebimento do lojista é zero
SellerIsBuyer	Os endereços das carteiras do comprador e do lojista são iguais
AmountIsZero	O valor do pagamento é zero
InvalidTotalAmountValidation	O value ou callValue do ativo nativo não corresponde ao total esperado
CommissionExceedsAmount	A taxa de processamento é maior que o valor disponível para desconto
SellerNotWhitelisted	O contrato implantado pode não autorizar a carteira do lojista
EnforcedPause	O processamento de pagamentos está pausado

Os erros disponíveis e o comportamento exato deles dependem do contrato implantado. Use a ABI verificada do contrato para decodificar erros personalizados.

Para causas e ações recomendadas, veja Solução de problemas de pagamentos com contratos inteligentes.

Guias relacionados

• Integração com contratos inteligentes — visão geral da integração de pagamentos não custodiais.
• Integração com Ethereum e BNB Smart Chain — receba ETH, BNB e USDT.
• Integração com TRON — receba TRX e USDT TRC-20.
• Verificação de pagamentos e acompanhamento de pedidos — verifique transações e associe pagamentos a pedidos.
• Solução de problemas — resolva erros comuns de carteiras e pagamentos.