Como receber pagamentos em USDT no seu site com uma chamada de API

Receba USDT com a Suawave: crie um endereço, mostre a rede e o QR code, verifique callbacks e atualize o pedido após o repasse.

Publicado em , atualizado em

Para receber USDT com a Suawave, crie um endereço de depósito informando sua carteira de recebimento e uma URL de callback HTTPS. Mostre ao cliente o endereço, a rede e o depósito mínimo. Verifique a assinatura de cada callback, associe o evento ao pedido e entregue somente após um callback confirmado indicar que o valor recebido é suficiente.

A chamada mencionada no título cria o endereço. Seu site ainda precisa de uma tela de checkout e de um processador de callbacks. O guia de início rápido apresenta esse fluxo completo.

1. Escolha a rede e consulte o mínimo

O ticker identifica rede e ativo. Os exemplos usam trc20/usdt, ou seja, USDT na TRON. Mantenha essa rede visível durante o checkout: mostrar apenas “USDT” omite uma informação necessária para o envio.

Antes de criar o pedido, consulte GET /trc20/usdt/info/:

curl "https://api.suawave.com/trc20/usdt/info/"

Leia minimum_transaction_coin na resposta. Trate valores como strings decimais e use aritmética decimal exata ou unidades inteiras do ativo.

Informação no checkout Fonte
Depósito mínimo do ticker minimum_transaction_coin em info ou create
Taxas do endereço criado Resposta de create
Valor efetivamente repassado value_forwarded_coin no callback confirmado

O guia de taxas explica os descontos. O endpoint de estimativa retorna um limite configurado na moeda nativa da rede; não é uma cotação da taxa descontada de um depósito USDT.

2. Crie o endereço de depósito

Guarde a referência do pedido e um nonce novo e imprevisível no servidor. Inclua ambos no callback para conferi-los depois. Chame GET /trc20/usdt/create/ com sua carteira de recebimento e esse callback. Substitua os valores ilustrativos abaixo pelos seus:

curl -G "https://api.suawave.com/trc20/usdt/create/" \
  --data-urlencode "address=TXyzPayoutAddressExample0000000000000" \
  --data-urlencode "callback=https://shop.example/hook?order=1001&nonce=7f3a9c" \
  --data-urlencode "pending=1"

O nonce curto é apenas um exemplo. Gere o seu com o gerador criptográfico da plataforma.

Salve address_in junto ao pedido: é o destino do depósito do cliente. address_out é a sua carteira de recebimento. Confundi-los compromete o checkout.

O par canônico ticker e callback identifica o pedido. Repetir esse par retorna o endereço existente; a primeira chamada fixa as opções. Outra carteira de repasse para o mesmo par é recusada. Use uma URL de callback distinta por pedido que precise acompanhar separadamente.

A referência da API explica a canonicalização do callback e os parâmetros completos. Use HTTPS e codifique cada valor de consulta. Destinos privados e de loopback são recusados.

3. Mostre o endereço e o QR code

Exiba endereço, ativo, rede, valor do pedido e mínimo. Mantenha o valor também em texto. Consulte GET /trc20/usdt/qrcode/ com o address_in real; este exemplo usa endereço e valor ilustrativos:

curl -G "https://api.suawave.com/trc20/usdt/qrcode/" \
  --data-urlencode "address=TDepositAddressExample0000000000" \
  --data-urlencode "value=25.5"

A resposta contém qr_code, uma data URI PNG, e payment_uri, o texto exato codificado no QR.

Na TRON, o QR contém apenas o endereço. A API valida value, mas não o inclui no QR; o cliente digita o valor na carteira. Para tokens EVM, informar value gera uma requisição EIP-681. O suporte varia por carteira e o pagador pode alterar o valor. Escanear um QR não comprova pagamento: o processador de callbacks decide isso pelos dados verificados.

4. Verifique cada callback antes de alterar o pedido

O padrão é GET. Na criação, post=1 seleciona POST de formulário e json=1 seleciona POST JSON, com precedência sobre post=1. Seus parâmetros personalizados permanecem na URL.

Verifique x-ca-signature com a chave de GET /pubkey/. GET usa a URL completa exata, incluindo a ordem original da consulta. POST usa o corpo bruto antes de interpretá-lo. Consulte os exemplos de assinatura.

Depois, confira referência, nonce, address_in e coin. Para trc20/usdt, o valor de coin no callback é trc20_usdt.

Campo Significado Ação
pending igual a "1" Depósito detectado Aguarde; não entregue
pending igual a "0" Transação de repasse confirmada Compare o valor confirmado ao pedido

Esses eventos opcionais de detecção são solicitados com pending=1. Pendente e confirmado têm UUIDs diferentes; novas tentativas do mesmo evento mantêm o UUID. Registre-os de forma durável para impedir entregas duplicadas.

5. Registre o pagamento e confirme o recebimento

O callback confirmado informa value_coin como valor depositado, fee_coin como total cobrado e value_forwarded_coin como valor líquido repassado. Defina qual valor sua política exige e compare com aritmética exata.

Salve evento e alteração do pedido juntos antes de responder. Retorne HTTP 200 com *ok* em até 30 segundos. Para um evento já processado, não repita o trabalho e envie a mesma confirmação.

Callbacks podem chegar fora de ordem. Um evento pendente atrasado não pode desfazer uma confirmação. O guia de callbacks explica entregas, novas tentativas e ordenação.

Se faltar um callback, consulte GET /trc20/usdt/logs/ com a URL original para conciliar. sent significa repasse confirmado sem confirmação de recebimento do callback, inclusive após esgotar as tentativas.

Pagamentos menores ou repetidos

Qual é o depósito mínimo em USDT?

Leia minimum_transaction_coin do ticker escolhido. Vale o mínimo vigente quando o depósito foi detectado pela primeira vez.

E se o cliente pagar menos que o pedido?

O total do pedido e o mínimo do ticker são limites diferentes. Um depósito elegível pode não quitar a compra. Mantenha o pedido não pago até os depósitos confirmados atenderem à sua política. Cada depósito tem seu repasse e callback; elimine eventos duplicados antes de somar.

Um depósito abaixo do mínimo não é encaminhado, não gera callback e não aparece nos registros públicos. Mostre o mínimo antes do envio.

Quando o pagamento está confirmado?

Entregue com pending igual a "0", após verificar assinatura e dados do pedido. Esse evento vem depois da confirmação do repasse. Detecção, leitura do QR ou resposta de create não comprovam que o pedido foi pago.