Guia de integração de pagamentos USDT

Identidades de tokens da rede principal

Contratos e Mint são valores predefinidos, não o estado atual do serviço. Criar pedidos exige rede e ativo habilitados e carteira válida. Pague sempre a payment.address da API, nunca ao contrato ou Mint.

Identidades de tokens da rede principal

Rede	Moeda	Contrato / Mint	Decimais do token
TRC20	USDT	TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6tCopiar	6
ERC20	USDT	0xdAC17F958D2ee523a2206206994597C13D831ec7Copiar	6
BEP20	USDT	0x55d398326f99059fF775485246999027B3197955Copiar	18
POLYGON	USDT	0xc2132D05D31c914a87C6611C10748AEb04B58e8FCopiar	6
SOLANA	USDT	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYBCopiar	6
BASE	USDT	0xfde4c96c8593536e31f229ea8f37b2ada2699bb2Copiar	6

Configuração do comerciante

1. Configure uma carteira receptora da rede e um Webhook habilitado com URL e chave. Guarde API Key e chave HMAC apenas no servidor.
2. Confira a disponibilidade de network / currency. Administradores mantêm RPC, redes e ativos; comerciantes não precisam implantar scanners.
3. Mostre payment.amount, payment.address, currency, network e validade da resposta. Os dados QR não são uma imagem.
4. Verifique a assinatura, elimine duplicatas e salve o evento de forma durável antes de responder HTTP 2xx. Faça a entrega de forma idempotente.

Notas sobre redes e ativos

USDT é aceito em seis redes. O token configurado na BNB Smart Chain usa 18 decimais; as outras cinco usam 6. Isso difere da precisão do valor do pedido. Base usa o USDT em ponte configurado; BoltUtil não transfere fundos entre redes. Escolha a rede do pedido e a versão exata listada: símbolos ou endereços iguais não tornam redes ou tokens intercambiáveis.

• TRC20 é o código API de TRON e aceita apenas USDT, não currency=USDC. USDT tem 6 decimais de token; preserve o valor retornado pela API. A confirmação segue configuração e varredura, sem garantia de segundos.

Exemplos de solicitação assinada e resposta

25.00 é um valor de exemplo. Use o valor real do pedido e respeite o mínimo do ativo. Endereços, pedidos e hashes são fictícios. O cURL ou programa Java copiado envia uma solicitação: configure suas próprias chaves antes de executar.

# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"TRC20","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Confirmação e notificações

Detectar não é confirmar. Use o status e callbacks verificados: PAID aguarda confirmação. CONFIRMED / COMPLETED também podem vir de aceitação manual; confira paidAmount, shortfallAmount e settlementType. COMPLETED não comprova a entrega.

Perguntas sobre integração