Solução de problemas de pagamentos com contratos inteligentes
Use este guia para resolver problemas comuns ao receber pagamentos não custodiais com contratos inteligentes da Volet.com no Ethereum, na BNB Smart Chain e na TRON.
Encontre o problema abaixo e siga as etapas recomendadas. Os endereços dos contratos, os parâmetros e as definições de erros estão na Referência de contratos inteligentes.
Problemas de carteira e rede
| Problema | Causa possível | Como resolver |
|---|---|---|
| Conexão da carteira rejeitada | O cliente rejeitou a solicitação ou a carteira está bloqueada | Peça ao cliente para desbloquear a carteira e conectar de novo |
| MetaMask não detectada | Nenhuma carteira de navegador compatível está instalada ou disponível | Instale a MetaMask ou conecte uma carteira compatível com WalletConnect |
| Rede EVM incorreta | A carteira está conectada a uma rede diferente da escolhida no pagamento | Solicite a troca de rede e verifique o chain ID |
| Falha na conexão via WalletConnect | Project ID inválido, configuração incorreta ou carteira ou rede sem suporte | Verifique a configuração do projeto na Reown e as redes suportadas |
| TronLink não detectado | A extensão não está instalada, ativada ou desbloqueada | Instale ou desbloqueie o TronLink e atualize a página |
| Rede TRON incorreta | A carteira está conectada a uma rede de teste ou a uma rede inesperada | Mude para a TRON Mainnet e verifique a rede ativa |
Sempre verifique de novo o endereço da carteira e a rede escolhida antes de iniciar um pagamento, principalmente depois de conectar a carteira ou trocar de rede.
Problemas com a aprovação de USDT
Pagamentos em USDT podem exigir uma transação de aprovação antes que o contrato processador possa transferir os tokens.
| Problema | Causa possível | Como resolver |
|---|---|---|
| Transação de aprovação rejeitada | O cliente rejeitou a solicitação na carteira | Permita que o cliente tente a aprovação de novo |
| Permissão de gasto (allowance) insuficiente | O processador não está autorizado a gastar o valor necessário | Verifique allowance() e solicite a aprovação do valor necessário |
| Falha na aprovação de USDT no Ethereum | Uma permissão diferente de zero não pode ser alterada diretamente para outro valor diferente de zero | Aprove 0, aguarde a confirmação e depois aprove o valor necessário |
| Saldo de USDT insuficiente | O cliente não tem tokens suficientes para o total do pagamento | Compare balanceOf() com previewPayment().totalPay |
| A aprovação foi concluída, mas o pagamento está pendente | A aprovação foi concluída, mas a transação de pagamento não foi enviada ou verificada | Verifique a permissão atual e depois inicie ou verifique a transação de pagamento separada |
Importante: uma transação approve() bem-sucedida não é um pagamento concluído. Somente a transação transfer() do contrato processador serve para verificar o pagamento do pedido.
Erros de transações e contratos
| Erro ou problema | Causa possível | Como resolver |
|---|---|---|
InvalidTotalAmountValidation | O value ou callValue nativo não corresponde ao total esperado do pagamento | Chame previewPayment() de novo e envie o totalPay retornado |
SellerIsBuyer | Os endereços das carteiras do comprador e do lojista são iguais | Verifique se a carteira de recebimento do lojista é diferente da carteira conectada do comprador |
SellerZeroAddress | O endereço de recebimento do lojista é o endereço zero | Configure uma carteira válida do lojista |
AmountIsZero | O valor do pagamento é zero | Valide o valor do pedido antes de enviar a transação |
CommissionExceedsAmount | A taxa de processamento não pode ser descontada do valor solicitado | Revise o valor do pedido e a configuração da taxa |
SellerNotWhitelisted | O processador não autoriza a carteira de recebimento do lojista | Fale com a Volet.com para verificar a autorização da carteira |
EnforcedPause | O processamento de pagamentos está pausado no contrato | Pare de enviar pagamentos por esse processador e fale com a Volet.com |
| Falha na transferência do token | Saldo de tokens ou permissão insuficientes, ou restrições do próprio token | Verifique o contrato do token, o saldo, a permissão e a rede escolhida |
| Gas insuficiente | O cliente não tem ETH ou BNB suficiente para a taxa de rede | Peça ao cliente para manter saldo suficiente da moeda nativa |
| Recursos da TRON insuficientes | O cliente não tem Energy, Bandwidth ou TRX disponível suficiente | Revise os recursos necessários e o TRX disponível |
TRON OUT_OF_ENERGY | A execução do contrato esgotou a Energy disponível ou o limite de taxa configurado | Estime o consumo de recursos e revise o feeLimit da transação |
TronGrid HTTP 429 | O limite de requisições da API foi excedido | Use uma chave de API no servidor e repita as requisições com espera progressiva |
Os erros do contrato dependem do processador implantado. Veja a Referência de contratos inteligentes para as definições dos erros.
O pagamento continua pendente
Um pedido pode continuar pendente mesmo depois que o cliente envia uma transação.
| Situação | O que verificar | Ação recomendada |
|---|---|---|
| O hash da transação foi retornado, mas não há recibo | A transação talvez ainda não tenha sido incluída em um bloco | Continue verificando o mesmo txid |
| A transação foi executada, mas não está finalizada | A finalidade de rede exigida ainda não foi atingida | Aguarde a finalidade antes de concluir o pedido |
| A aprovação de USDT foi confirmada, mas não há pagamento | Somente a transação de aprovação foi enviada | Verifique se existe uma transação de pagamento separada |
| A transação foi bem-sucedida, mas o pedido continua pendente | Os dados do pagamento podem não corresponder ao pedido, ou a verificação no backend pode estar incompleta | Compare com o pedido o processador, o ativo, o destinatário, o valor e a chamada ao contrato |
| A transação da TRON está visível, mas não está solidificada | A transação ainda não apareceu nos dados do SolidityNode | Continue verificando o recibo solidificado da transação |
| A requisição RPC falha ou expira | O provedor está temporariamente indisponível | Repita a verificação sem marcar a transação como falha |
| O cliente fechou ou atualizou a página de pagamento | A sessão do navegador terminou antes da confirmação do pagamento | Continue a verificação pelo processo de conciliação do backend |
| O pagamento expirou antes da confirmação | A transação pode ser confirmada depois que a janela de pagamento se fecha | Continue acompanhando as tentativas de pagamento enviadas e concilie os pagamentos atrasados |
A transação foi bem-sucedida, mas o pedido não está marcado como pago
Uma transação bem-sucedida na blockchain não significa necessariamente que o pedido certo foi pago.
Seu backend deve confirmar que:
- A transação usou o contrato processador esperado.
- O ativo e a carteira de recebimento do lojista correspondem ao pedido.
- O valor do pagamento e a configuração da taxa estão corretos.
- O lojista recebeu os fundos esperados.
- A transação atingiu a finalidade exigida na blockchain.
- O hash da transação ainda não foi usado para outro pedido.
Se algum dado obrigatório não corresponder, não marque o pedido como pago automaticamente. Mantenha o pagamento em análise para investigação.
O processo completo de verificação está descrito em Verificação de pagamentos e acompanhamento de pedidos.
Fale com o suporte
Se o problema continuar, fale com a Volet.com e informe:
- A rede blockchain e o ativo.
- O hash da transação de pagamento (
txid), se houver. - A data e a hora aproximadas da transação.
- O ID do pedido do lojista.
- O endereço do contrato processador.
- A mensagem de erro ou uma descrição do problema.
Você pode falar com a nossa equipe pelo suporte da Volet.com.
Segurança: nunca compartilhe frases-semente de carteiras, chaves privadas nem credenciais secretas de API.
Relacionados
- Integração com contratos inteligentes — visão geral dos 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.
- Referência de contratos inteligentes — endereços dos contratos, parâmetros e erros.
- Verificação de pagamentos e acompanhamento de pedidos — verifique transações e concilie pedidos.