Documentação

Perguntas frequentes

Tire suas dúvidas sobre pagamentos em cripto com a Suawave, da criação do endereço de depósito ao processamento do callback confirmado.

Primeiros passos

Como receber pagamentos em USDT TRC20 sem criar uma conta?

A Suawave permite receber pagamentos em USDT TRC20 sem cadastro, conta ou chave de API. Chame GET /trc20/usdt/create/ com o endereço da sua carteira e uma URL pública de callback HTTPS. Mostre ao pagador o address_in e o minimum_transaction_coin retornados, junto com o ativo e a rede do ticker escolhido.

Leia a documentação
Como criar um endereço de pagamento diferente para cada pedido?

Use uma URL de callback exclusiva para cada pedido na Suawave, com a referência do pedido e um nonce imprevisível. Repetir create com o mesmo ticker e callback retorna o mesmo endereço de depósito e mantém as opções originais; guarde a URL exata de callback no servidor.

Leia a documentação

Moedas e redes

Quais moedas e redes a Suawave aceita?

A Suawave aceita estas rotas de pagamento habilitadas: USDC na rede BNB Smart Chain BEP20 (bep20/usdc); USDT na rede BNB Smart Chain BEP20 (bep20/usdt); USDT na rede TRON TRC20 (trc20/usdt). Use o ticker exato em letras minúsculas para o token e a rede escolhidos; o endereço da carteira, sozinho, não identifica o padrão do token.

Leia a documentação
O que acontece se o cliente enviar o token errado ou usar outra rede?

A Suawave processa apenas o token e a rede selecionados para o pedido. Transferências de outro token não são encaminhadas e não geram callback nem registro público; não presuma que um pagamento em outra rede possa ser recuperado ou aceito.

Leia a documentação

Taxas e valores mínimos

Quanto a Suawave cobra por pagamento?

A Suawave cobra cada depósito separadamente: uma taxa de serviço, sujeita a um mínimo, mais uma taxa de rede no token do pagamento. Faixas de serviço pelo volume em USD nos últimos 30 dias: Abaixo de $250,000: 0.50%; De $250,000 a $999,999: 0.45%; De $1,000,000 a $2,499,999: 0.40%; De $2,500,000 a $4,999,999: 0.35%; De $5,000,000 a $9,999,999: 0.30%; De $10,000,000 a $19,999,999: 0.20%; $20,000,000 ou mais: 0.13%. Taxas publicadas por token: BNB Smart Chain BEP20 USDC: taxa mínima de serviço de 0.05 USDC, taxa de rede de 0.05 USDC; BNB Smart Chain BEP20 USDT: taxa mínima de serviço de 0.05 USDT, taxa de rede de 0.05 USDT; TRON TRC20 USDT: taxa mínima de serviço de 0.05 USDT, taxa de rede de 1.00 USDT. As taxas são definidas por depósito; fee_coin e value_forwarded_coin informam a cobrança e o repasse efetivos.

Leia a documentação
Qual é o pagamento mínimo em cripto aceito pela Suawave?

A Suawave tem um depósito mínimo para cada token e rede: BNB Smart Chain BEP20 USDC: 1.00 USDC; BNB Smart Chain BEP20 USDT: 1.00 USDT; TRON TRC20 USDT: 10.00 USDT. Consulte minimum_transaction_coin em create ou info antes de mostrar uma solicitação de pagamento; o mínimo aplicável é registrado quando cada depósito é detectado pela primeira vez.

Leia a documentação
Vários depósitos abaixo do mínimo podem se somar em um pagamento válido?

Não. A Suawave avalia o mínimo de cada depósito separadamente, portanto vários depósitos abaixo do mínimo não formam um pagamento elegível. Um depósito abaixo do mínimo não é encaminhado nem repassado, não envia callback e não aparece nos registros públicos.

Leia a documentação

Confirmações e finalidade

Quando posso marcar um pagamento da Suawave como pago?

Marque o pedido como pago somente após verificar um callback confirmado da Suawave com pending igual a 0 e conferir o pedido, token, endereço e valor. Esse evento indica que o depósito elegível foi encaminhado e a transação de repasse foi confirmada; um callback pendente, sozinho, não autoriza a entrega do pedido.

Leia a documentação
Quantas confirmações a Suawave exige e posso alterar esse número?

A Suawave segue a política de finalidade da rede escolhida, em vez de um número de confirmações definido por quem chama a API. A TRON aguarda evidências solidificadas e a BNB Smart Chain usa cabeçalhos finalizados; o endpoint público create não aceita um número personalizado de confirmações nem prioridade. A indexação e o repasse levam tempo, então o intervalo entre blocos não é um prazo para concluir o pagamento.

Leia a documentação
Um webhook pendente significa que o cliente pagou?

Um callback da Suawave com pending igual a 1 indica que o indexador detectou um depósito elegível, não que o repasse foi confirmado. Solicite esse evento opcional com pending=1 na primeira chamada create; os eventos pendente e confirmado podem chegar fora de ordem e têm UUIDs diferentes.

Leia a documentação

Callbacks e verificação de assinaturas

A Suawave pode enviar webhooks por POST em JSON ou formulário?

Sim. A Suawave envia callbacks por GET por padrão, por POST de formulário com post=1 ou por POST JSON com json=1; JSON tem precedência quando ambos estão definidos. A primeira chamada create fixa essas opções para o par ticker e callback, e seus parâmetros de consulta permanecem na URL de callback.

Leia a documentação
Como verificar a assinatura de um webhook da Suawave?

Verifique o cabeçalho x-ca-signature como uma assinatura RSA-SHA256 PKCS#1 v1.5 em base64, usando a chave pública da Suawave obtida em GET /pubkey/. Callbacks GET assinam a URL original completa; callbacks POST assinam o corpo bruto exato. Verifique antes de interpretar ou confiar nos campos, armazene a chave em cache e atualize-a uma vez se a verificação falhar, antes de rejeitar a requisição.

Leia a documentação
Como confirmar o recebimento de um webhook? A Suawave tenta novamente?

Retorne HTTP 200 com *ok* em até 30 segundos para confirmar o recebimento de um callback da Suawave; ok sem asteriscos também é aceito, sem distinção entre maiúsculas e minúsculas. São 8 tentativas no total: o envio inicial, seguido de intervalos de 30 s, 2 min, 10 min, 30 min, 2 h, 6 h, 24 h, com até 10% de variação adicional. As novas tentativas mantêm o mesmo uuid, então salve-o para evitar processamento duplicado.

Leia a documentação
Como consultar um pagamento se o webhook não chegar?

Use GET /trc20/usdt/logs/ da Suawave com a URL original de callback para conciliar depósitos elegíveis. O resultado pending indica repasse ainda não confirmado; sent indica repasse confirmado sem confirmação de recebimento do callback; done indica que o callback foi reconhecido. Registros vazios não provam que nenhuma transferência foi enviada: pagamentos abaixo do mínimo, não suportados ou atrasados podem não aparecer.

Leia a documentação

Pagamentos a menos, a mais e atrasados

E se o cliente pagar menos que o total do pedido?

Sua loja decide se o valor confirmado atende ao total do pedido; o endpoint público create da Suawave não recebe um valor de fatura. Some os depósitos confirmados elegíveis usando value_coin para uma política de valor bruto ou value_forwarded_coin para valor líquido e elimine duplicatas pelos UUIDs dos callbacks. Cada depósito adicional deve atingir seu próprio mínimo e tem cobrança separada.

Leia a documentação
O que acontece se o cliente enviar cripto a mais?

A Suawave encaminha o depósito elegível, descontadas as taxas, incluindo qualquer valor acima do total do pedido. A API pública não reembolsa o excedente automaticamente; sua loja deve definir como conciliá-lo e providenciar eventuais reembolsos pela própria carteira.

Leia a documentação
O que acontece se o cliente pagar após o vencimento do endereço?

Um depósito na Suawave fora da janela de vencimento aceita fica retido para análise, não é encaminhado e não gera callback nem registro público. A elegibilidade usa o horário efetivo da transferência e o vencimento armazenado, mais a tolerância configurada; assim, uma transferência dentro do prazo pode finalizar depois. Pare de exibir endereços vencidos e concilie pagamentos atrasados manualmente; não há promessa de reembolso automático ao pagador.

Leia a documentação

Repasses e encaminhamento

Como a Suawave encaminha pagamentos para minha carteira?

A Suawave encaminha cada depósito elegível separadamente para o único endereço de repasse informado em create, após descontar as taxas e verificar a rede. O callback confirmado inclui txid_out e value_forwarded_coin para seu servidor identificar a transação de repasse e o valor líquido recebido.

Leia a documentação
Posso mudar o endereço de repasse ou dividir o pagamento entre carteiras?

A Suawave vincula um único endereço de repasse a cada par ticker e callback, sem permitir alteração desse endereço no par existente. Crie um novo pedido com outra URL de callback para usar outro endereço; a API pública não aceita divisão de valores nem múltiplos destinos de repasse.

Leia a documentação

Segurança e custódia

A Suawave mantém cripto antes de encaminhá-la?

A Suawave recebe pagamentos em um endereço de depósito controlado pelo gateway antes de encaminhar os valores elegíveis à sua carteira. O repasse não é instantâneo nem incondicional: aplicam-se verificações da rede, taxas, mínimos e regras de vencimento, e depósitos não elegíveis podem permanecer retidos.

Leia a documentação
Por que devo manter a URL completa de callback em segredo?

A URL completa de callback da Suawave dá acesso aos registros do pedido na API pública, então mantenha-a no servidor e inclua um nonce imprevisível. A verificação de assinatura continua obrigatória para callbacks recebidos; mesmo uma assinatura válida deve corresponder ao pedido armazenado e ao token, endereço e valor esperados.

Leia a documentação

Plugins, SDKs e MCP

Posso receber pagamentos em cripto com WooCommerce, Magento, OpenCart ou PrestaShop?

A Suawave oferece integrações para WooCommerce, Magento 2, OpenCart e PrestaShop. Use o guia correspondente para instalar e configurar o plugin, mostrar o endereço e o QR code e processar callbacks de pagamento assinados.

Leia a documentação
Quais SDKs posso usar para integrar a Suawave?

A Suawave tem SDKs Go e JavaScript/TypeScript para a API pública. Você também pode chamar os endpoints HTTP diretamente e usar os exemplos de verificação de assinatura em Go, JavaScript, PHP ou C# no seu processador de callbacks.

Leia a documentação
Um assistente de IA pode usar a Suawave por MCP?

Sim. O servidor MCP da Suawave disponibiliza ferramentas para sua API pública de pagamentos, incluindo criação de endereços de depósito e consulta de registros. O fluxo público dispensa chave de lojista e não expõe operações administrativas; mantenha URLs de callback e seus nonces secretos fora de prompts compartilhados e saídas públicas.

Leia a documentação

Migração da CryptAPI

Como migrar uma integração CryptAPI para a Suawave?

Altere a origem da API para a Suawave, crie novos pedidos e endereços de depósito e verifique callbacks com a chave da própria Suawave, obtida em /pubkey/. Revise tickers disponíveis, vencimento, novas tentativas de callback e parâmetros não suportados antes da mudança; não reutilize a chave pública nem a lista de IPs permitidos da CryptAPI.

Leia a documentação

Limites, vencimento e reembolsos

A Suawave limita requisições à API ou novos endereços de pagamento?

Sim. A Suawave limita requisições por IP do cliente e host de callback, além de aplicar cotas separadas para novos pares ticker e callback. Ao receber HTTP 429, reduza a frequência e respeite Retry-After quando informado; reutilizar um par evita a cota de novos pares, mas continua contando para os limites de requisições.

Leia a documentação
A Suawave pode reembolsar um pagamento em cripto automaticamente?

A API pública da Suawave não tem endpoint de reembolso ao pagador e não devolve automaticamente pagamentos excedentes ou atrasados. Para um pagamento elegível já encaminhado, sua loja deve providenciar eventuais reembolsos pela própria carteira; uma transferência atrasada retida exige conciliação manual e não gera reembolso automático.

Leia a documentação
Criar novamente o mesmo endereço da Suawave estende seu vencimento?

Não. Repetir create para um par ticker e callback existente retorna o endereço e expires_at originais, sem estender o pedido. Use o vencimento UTC retornado no checkout, pare de exibir o endereço vencido e use outra URL de callback para um novo pedido.

Leia a documentação