Como integrar recebimentos USDT: pedidos, assinaturas e callbacks
Uma integração USDT precisa relacionar cada pedido a um pagamento verificável. A UUGate suporta TRC20-USDT e BEP20-USDT. Criação, instruções e consultas devem usar o mesmo pedido e rede. O exemplo abaixo usa TRC20 com valor fixo.
Preparar credenciais e callback
Obtenha Merchant UID, API Key e uma URL HTTPS pública própria. Mantenha a chave no servidor, nunca no navegador ou em diretório público. Verifique o comerciante, a conta de tarifas e os limites do plano. Consulte a assinatura de requisições.
Criar e salvar o pedido
Envie este corpo para POST /openapi/payin/orders pelo servidor. Ele não é uma requisição autenticada completa: use o SDK ou acrescente os cinco cabeçalhos documentados.
{
"chainCode": "TRON",
"tokenSymbol": "USDT",
"merchantOrderNo": "EXAMPLE-20260928-001",
"amount": "10.00",
"notifyUrl": "https://merchant.example.com/payments/uugate"
}Valores monetários são strings. Salve orderNo, merchantOrderNo, cashierUrl e expireAt antes de mostrar o checkout. waiting_payment confirma a criação, não a entrada de fundos. Veja os campos e respostas.
Verificar antes de entregar
Valide timestamp, nonce e corpo original usando a API Key empregada no pedido. Não serialize novamente o JSON para conferir a assinatura. Confira comerciante, pedido, rede, ativo e valor recebido. Use uma restrição única para o pedido da plataforma e uma transação para salvar pagamento e estado comercial antes de responder 2xx. Notificações repetidas não podem gerar novo crédito ou envio. Veja os callbacks.
Recuperar resultados incertos
O retorno do navegador não comprova pagamento. Com o número da plataforma, consulte o pedido e use status=completed como sucesso final. Se a criação sofrer timeout sem retornar número, confira o resultado no painel antes de repetir. O número comercial não garante repetição idempotente da criação.
Validar antes de publicar
- Teste pagamento normal, assinatura inválida, callback duplicado e receptor temporariamente indisponível.
- Pagamentos vencidos, insuficientes ou na rede errada não devem liberar produtos automaticamente.
- Guarde pedidos, hashes e resultados sem registrar API Keys.
- Use o SDK Node.js ou PHP / Laravel; confira redes USDT e preços.