Acepte pagos USDT en TRON a través de API: Guía de integración de comerciantes

Aceptar USDT en TRON ofrece liquidación casi instantánea y tarifas bajas, lo que resulta atractivo para comerciantes, plataformas SaaS y mostradores OTC. A diferencia de los pagos con tarjeta, el USDT en cadena no tiene devoluciones de cargo ni webhook nativo: usted crea una lógica de confirmación contra TronGrid o su propio nodo completo.

Esta guía describe la arquitectura de producción para la aceptación de pagos TRC-20 USDT.

Descripción general de la arquitectura

Customer → sends USDT to deposit address
                ↓
         TronGrid / event indexer
                ↓
         Your payment service (match txid)
                ↓
         Webhook to app → order fulfilled
                ↓
         Sweep to treasury (optional cron)

Contrato oficial USDT (solo red principal):

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

Verificar: USDT TRC-20 explicado.

Estrategia de dirección

Dirección única por factura

Recomendado. Genere una nueva dirección TRON por pedido desde la billetera HD (ruta BIP44 m/44'/195'/0'/0/n - tipo de moneda 195 para TRON).

Beneficios:

• Coincidencia automática de pedidos por dirección to
• Contabilidad más fácil
• Limita el radio de explosión si la clave está comprometida

Dirección única + monto coincidente

Una dirección, coincidencia por cantidad exacta + ventana de tiempo.

Riesgos:

• Pagos en colisión del mismo monto
• El cliente envía una cantidad incorrecta
• Requiere conciliación manual

Úselo solo para volúmenes bajos con supervisión humana.

Detectando depósitos

Opción A: TRC-20 API de transacciones

const USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';
const url = `https://api.trongrid.io/v1/accounts/${depositAddress}/transactions/trc20?only_confirmed=true&limit=50&contract_address=${USDT}`;

const res = await fetch(url, {
  headers: { 'TRON-PRO-API-KEY': process.env.TRONGRID_KEY }
});
const { data } = await res.json();

for (const tx of data) {
  if (processed.has(tx.transaction_id)) continue;
  const amount = Number(tx.value) / 1e6; // USDT 6 decimals
  await creditOrder(tx.to, amount, tx.transaction_id);
  processed.add(tx.transaction_id);
}

Detalles: consulta TRC-20 API de equilibrio.

Opción B: detectores de eventos

Filtre Transfer(address,address,uint256) donde to = direcciones de depósito. Más escalable en volumen.

Oyentes de eventos TronWeb.

Opción C: hash de transacción del cliente

El cliente envía txid manualmente; usted verifica una vez:

Verificar API de transacción.

Menos automatizado; útil como alternativa.

Reglas de validación {#validación}

Antes de marcar pagado:

1. Contrato = TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
2. Resultado = SUCCESS (vía gettransactioninfobyid)
3. a = dirección de depósito esperada
4. Cantidad ≥ total del pedido (manejar la política de pago excesivo)
5. txid no procesado previamente (idempotencia)
6. Bloquear marca de tiempo dentro de la ventana de vencimiento del pedido

Rechace tokens falsos USDT con el mismo símbolo.

Confirmaciones

const info = await tronWeb.trx.getTransactionInfo(txid);
const confirmed = info.blockNumber > 0 && info.receipt?.result === 'SUCCESS';

Ejemplos de políticas:

TRON el riesgo de reorganización es bajo pero distinto de cero: sintonícese con el riesgo empresarial.

Webhooks a tu aplicación

Flujo interno después de la detección:

await fetch('https://yourapp.com/internal/payment-confirmed', {
  method: 'POST',
  headers: { 'X-Signature': hmac },
  body: JSON.stringify({ orderId, txid, amount, asset: 'USDT-TRC20' })
});

Firme webhooks con HMAC. Vuelva a intentarlo con retroceso exponencial.

Barridos y tesorería

Claves de depósito en caliente en línea para automatización: pase periódicamente a la tesorería fría:

// After confirmation
await usdtContract.transfer(treasuryAddress, balance).send();

Cuenta de energía en los txs de barrido: congelar TRX en la billetera activa o mantener el búfer TRX.

Seguridad

• Nunca almacene la semilla maestra en el servidor de aplicaciones sin cifrar; use HSM o KMS
• Validar direcciones con TronWeb.isAddress() — validación de direcciones
• Puntos finales de facturación pública con límite de tarifa
• Monitorear salidas inesperadas (alerta de compromiso)
• Seguridad de contrato inteligente si se utilizan contratos de depósito en garantía

Recomendaciones de UX

• Mostrar código QR con dirección + etiqueta de red "TRC-20 USDT"
• Mostrar la cantidad exacta esperada (6 decimales)
• Cuenta regresiva de vencimiento de la factura.
• Enlace a TronScan después del pago
• Advertencia: la red incorrecta pierde fondos — guía de red incorrecta

Error al manejar

Pruebas

1. Implementar en Shasta testnet con la prueba USDT
2. Simule los txs SUCCESS y REVERT
3. Límites de velocidad de prueba de carga TronGrid
4. Prueba de caos: webhooks duplicados, tiempo de espera de API

Guía de prueba de Nile.

Lista de verificación para solucionar problemas

Si algo sale mal en TRON, trátelo como un problema de depuración estructurado: confirme el txid exacto en la cadena, verifique la dirección del contrato de destino y solo entonces decida si la falla es recuperable. En TRON, muchos problemas "misteriosos" son simplemente uno de: red incorrecta (mainnet vs testnet), contrato de token incorrecto (falso USDT/tokens con nombres similares), recursos insuficientes (OUT_OF_ENERGY/ancho de banda) o retraso en la interfaz de usuario/indexador entre la billetera y el explorador.

Comience con estas comprobaciones en cadena:- Copie siempre el txid/hash completo de su billetera o explorador.

• Confirme el estado del resultado del tx en TronScan (SUCCESS, REVERT, OUT_OF_ENERGY o aún pendiente).
• Compruebe si la dirección del destinatario/contrato coincide con la que desea enviar.
• Si se trata de una llamada de contrato, confirme que el selector de función y los parámetros coincidan con el estándar de token que cree que está utilizando (TRC-20 vs TRC-10 vs BEP-20 en BSC).

Luego aplique la ruta de corrección para su categoría:

• Confirmar el estado y los parámetros de la transacción.
• Verificar direcciones (contrato de token, destinatario, enrutador/gastador).
• Agregar o delegar recursos (Energía/Ancho de banda) cuando el fallo esté basado en recursos.

Errores comunes

Estos patrones causan la mayoría de los errores a nivel de usuario:

• Usar direcciones de mainnet en testnet (o al revés).
• Copiar un símbolo de token en lugar de la dirección real del contrato TRC-20.
• Firmar la dirección de aprobación/gastador incorrecta porque el enlace de la interfaz de usuario es malicioso o está desactualizado.
• Reintentar sin cambiar la entrada fallida (por ejemplo, REVERT sigue revirtiéndose hasta que corrija el parámetro).

Si no está seguro, no “simplemente envíe de nuevo”. Realice un cambio controlado, verifique en TronScan y luego continúe.

Preguntas frecuentes

¿Cómo sé si una transacción está realmente confirmada?

Utilice TronScan y verifique el estado del resultado del tx. Las etiquetas "pendientes" de la billetera pueden retrasarse; El estado de la cadena es la fuente de la verdad. Copie txid y verifique SUCCESS/REVERT/OUT_OF_ENERGY, no solo el texto de la interfaz de usuario.

¿Por qué la interfaz de usuario difiere de TronScan?

Algunas billeteras y dApps utilizan diferentes indexadores o capas de caché. Es normal que haya un breve retraso entre la transmisión y la indexación; compare txid y espere a que la cadena se estabilice antes de concluir que hay una falla.

¿Qué debo hacer después de un REVERT?

Detenga y decodifique la llamada fallida. La mayoría de los REVERT se deben a parámetros no válidos, dirección de contrato incorrecta, aprobaciones faltantes o una falta de coincidencia entre el estándar del token y el método. Solucione la causa y luego vuelva a firmar.

¿Es seguro firmar una aprobación ilimitada?

Las aprobaciones ilimitadas son seguras solo para direcciones de gastadores confiables que usted haya verificado (fuente verificada, enrutador correcto y contrato de token esperado). Para las pruebas, prefiera aprobaciones limitadas y revoque una vez que haya terminado.

¿Qué recursos requiere TRON para las llamadas de contrato?

La ejecución de contratos inteligentes consume principalmente energía, mientras que los bytes de transacciones consumen ancho de banda. Si recibe OUT_OF_ENERGY, agregue/congela/delegue energía. Si se agota el ancho de banda, concéntrese en mantener suficiente líquido TRX para bytes y asignación de recursos.

¿Cómo puedo reducir los tickets de soporte?

Muestre a los usuarios un mensaje claro de "qué sucedió" basado en el estado de la cadena y vincule directamente a la guía relevante (pendiente, fallida, sin energía o verificación). Guarda txid para que puedas conciliar rápidamente.

Guías relacionadas

• Enviar USDT programáticamente
• TronGrid Guía API
• Guía de seguimiento de transacciones
• TRON Referencia de API HTTP

Preguntas frecuentes

¿Cuál es el contrato oficial USDT sobre TRON para pagos?

TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: filtra todas las detecciones en este contrato.

¿Cuántas confirmaciones debe esperar un comerciante?

Mayor crédito después de un bloque (~3 segundos). Los de alto valor pueden esperar más.

¿Puedo usar TronLink en lugar de la integración personalizada?

Para negocios manuales sí. El pago automatizado requiere integración API.

¿Los clientes necesitan TRX para pagarme USDT?

El remitente paga las tarifas de Energía/TRX, no el comerciante. El comerciante paga tarifas de barrido.

¿Es reversible USDT en TRON?

Sin devoluciones de cargo. Los reembolsos requieren enviar USDT manualmente.