Pagos con TRON: guía para desarrolladores de 2026

Ilustración de un servidor con el logo de Tron que envía una moneda a una wallet, como representación de un pago en TRON

Una integración de pagos en TRON es el conjunto de componentes que permite a su aplicación aceptar y enviar TRX y tokens TRC-20 como USDT: direcciones, transacciones firmadas, detección de depósitos y comprobaciones de confirmación. Puede construirla sobre las APIs de nodo de TRON, o llamar a una API REST que crea wallets, envía transferencias y emite webhooks. Esta guía cubre ambas vías.

Resumen

Los pagos en TRX son transferencias nativas de cuenta a cuenta. Los pagos TRC-20 (como USDT) son llamadas a contratos inteligentes, así que consumen Energy además de Bandwidth.
Toda operación que cambia el estado sigue tres pasos: construir una transacción sin firmar, firmarla con la clave del remitente y difundirla a un nodo.
Acredite los depósitos solo desde bloques solidificados, solo para transacciones exitosas y, en el caso de TRC-20, solo desde contratos de token que haya aprobado.
Las comisiones dependen de los recursos bloqueados o delegados. Planifíquelas antes del lanzamiento, o se quemará TRX en cada transferencia.
Puede prescindir de ejecutar nodos y de analizar bloques usando una API de wallets, transferencias y webhooks como la de Chaingateway. Sus webhooks no se reintentan automáticamente, así que planifique la conciliación.

Tabla de contenidos

¿Cómo funcionan los pagos en TRON?
¿Construyo sobre APIs de nodo o uso una API?
¿Cómo construyo, firmo y difundo una transacción?
¿Cómo detecto los pagos entrantes?
¿Cuándo es final un pago en TRON?
¿Cómo protejo las wallets y las claves privadas?
¿Cuánto cuestan Energy y Bandwidth?
¿Cómo gestiono los pagos fallidos, retrasados y duplicados?
¿Puedo aceptar pagos en mi propio token?
¿Cómo envío pagos en TRON a través de Chaingateway?
Preguntas frecuentes
Fuentes

¿Cómo funcionan los pagos en TRON?

TRX es el token nativo de TRON. Paga las comisiones de red, y el staking de TRX proporciona recursos de red y derechos de voto, según la documentación para desarrolladores de TRON sobre TRX. Sin embargo, la mayor parte del volumen de pagos comerciales en TRON está en tokens como USDT-TRC20, así que necesita entender ambos tipos de transferencia.

Un pago en TRX es una transferencia simple de cuenta a cuenta en la cadena. Un pago TRC-20 es diferente: el remitente llama a la función de transferencia del contrato del token, que actualiza los saldos dentro del contrato y emite un evento Transfer. Ambos quedan registrados en TRON, pero las transferencias TRC-20 requieren ejecución de contrato inteligente, así que consumen Bandwidth y Energy, como se describe en el libro blanco de TRON.

Esta diferencia condiciona toda su integración:

	Transferencia de TRX	Transferencia TRC-20 (p. ej., USDT)
Qué es	Transferencia nativa entre cuentas	Llamada a un contrato de token
Recursos usados	Bandwidth	Bandwidth y Energy
Cómo se detecta	Historial de transacciones, transacciones internas	Logs de eventos Transfer del contrato
Qué debe verificar	Éxito, destinatario, importe	Éxito, contrato aprobado, remitente, destinatario, importe

¿Construyo sobre APIs de nodo o uso una API?

La documentación de integración de TRON enumera lo que suele implicar una integración: conectar las wallets de los usuarios finales, construir y firmar transacciones, vigilar depósitos y retiradas, y usar TronGrid o un nodo completo propio. Los operadores de exchanges y de wallets custodiadas gestionan la vigilancia de depósitos, las retiradas y las consultas de saldo e historial sobre la misma base.

Eso le deja dos caminos realistas.

Vía uno: construir sobre las APIs de nodo. Obtiene control total. También asume la derivación de direcciones, el análisis de bloques, la lógica de reintentos, la gestión de recursos y, si lo aloja usted, el mantenimiento del nodo. Nuestra guía para montar un nodo TRON cubre la vía del Lite FullNode con jar o Docker si elige este camino.

Vía dos: usar una API de wallets y webhooks. Llama a un endpoint REST para crear una wallet, a otro para enviar una transferencia, y recibe un webhook firmado cuando llega un depósito. Nuestra API de TRON está pensada para esto: transferencias USDT-TRC20 y webhooks de depósito sin operar nodos. Los endpoints están en la definición OpenAPI.

Una regla práctica: si los pagos son el diferenciador principal de su producto y tiene un equipo que pueda operar la infraestructura, construya. Si los pagos son una función de otra cosa, una API le lleva a producción más rápido y mantiene a sus ingenieros en su producto real.

APIs de nodo comparadas con APIs de webhooks de wallet

¿Cómo construyo, firmo y difundo una transacción?

Tanto si usa llamadas directas al nodo como un SDK, toda operación de TRON que cambia el estado sigue el mismo flujo de tres pasos: construir una transacción sin firmar a través de una API de nodo, firmarla en el cliente con la clave privada del remitente y difundir la transacción firmada a un nodo.

Hay dos detalles que conviene conocer:

TAPOS. Cada transacción hace referencia a un bloque reciente, lo que limita la reproducción en las ramas de la cadena que no contienen ese bloque, según la documentación del protocolo sobre transacciones. En la práctica, construya y firme cerca del momento de difundir. Una transacción firmada y aparcada durante mucho tiempo puede caducar.
Use los helpers del SDK para firmar. La guía para desarrolladores de wallets recomienda usar helpers de SDK en producción en lugar de primitivas de firma propias, para evitar casos límite en la serialización protobuf y la recuperación de firmas. No escriba la suya.

Para flujos en navegador en los que el usuario paga desde su propia wallet, la guía de integración con DApps describe dos opciones: TronWallet Adapter, para soporte unificado de varias wallets, o la integración directa con TronLink, que inyecta un proveedor en window.tron. Los checkouts de comerciantes que generan una dirección de depósito por pedido normalmente no necesitan nada de esto. El cliente paga desde la wallet que ya usa.

¿Cómo detecto los pagos entrantes?

El modelo habitual del comerciante es una dirección de depósito por pedido o por cliente. Su trabajo es entonces notar el dinero que llega a esas direcciones.

La guía para exchanges y wallets custodiadas describe dos métodos de detección: consultar cada pocos segundos las APIs de historial de cuentas de TronGrid, o analizar los bloques en secuencia. Si analiza bloques, use la altura solidificada más reciente, y obtenga los logs de eventos y las transacciones internas por separado de los resultados de ejecución, tratándolos como registros distintos.

No pase por alto las transacciones internas

Es la brecha más habitual en las integraciones caseras. Los usuarios pueden recibir TRX o tokens TRC-10 mediante una llamada a un contrato inteligente, y esas transferencias no aparecen como transacciones de primer nivel. La misma guía indica que hay que analizar las transacciones internas al acreditar depósitos. Si su listener solo vigila transferencias de primer nivel, algunos clientes pagarán y nunca se les acreditará.

Verifique bien los depósitos TRC-20

En los depósitos de tokens, el hash de una transacción por sí solo no demuestra nada. La guía de integración de wallets de exchanges indica que hay que verificar que la transacción se completó con éxito y analizar los logs Transfer solo de contratos de token aprobados, validando remitente, destinatario e importe. Nunca acredite transacciones fallidas. Tras solidificarse una transacción TRC-20, la guía de interacción con TRC-20 indica confirmar la ejecución con getTransactionInfoById y, para transfer y transferFrom, verificar también el evento Transfer que emitió el contrato del token.

Una lista mínima de verificación para cada depósito TRC-20:

La dirección del contrato está en su lista de permitidos (el contrato real de USDT, no un token parecido con el mismo nombre).
El resultado de la transacción es un éxito.
Existe un evento Transfer con su dirección de depósito como destinatario.
El importe coincide con el pedido, usando correctamente los decimales del token.
No ha acreditado ya este ID de transacción.

El paso de la lista de permitidos importa más de lo que parece. Cualquiera puede desplegar un token llamado «USDT». Su código debe comprobar el contrato, no el símbolo.

¿Cuándo es final un pago en TRON?

Una transacción de TRON pasa por cuatro fases: crear y firmar, difundir y validar, inclusión en un bloque por un Super Representante y solidificación. Según la documentación del protocolo, queda totalmente confirmada cuando al menos 19 Super Representantes activos y distintos han producido bloques en su bloque o posteriores, lo que normalmente tarda alrededor de un minuto.

Para su lógica de pagos, eso significa:

Lea desde la altura de bloque solidificada, no desde la cabeza de la cadena, para que una reversión de bifurcación no pueda deshacer un pago que ya acreditó. La guía de integración para exchanges indica que la solidificación va unos minutos por detrás de la cabeza, en torno a un minuto.
Muestre al cliente un estado de «pago visto» pronto, y un estado de «pago confirmado» solo en la solidificación. Así el checkout parece instantáneo sin arriesgar una reversión.
Haga que la acreditación sea idempotente. Con clave en el ID de la transacción y el índice del log, un webhook reintentado o un bloque analizado de nuevo no pueden acreditar dos veces un pedido.

¿Cómo protejo las wallets y las claves privadas?

La misma guía para exchanges da indicaciones claras sobre las claves. Use una derivación compatible con BIP-44 para las direcciones de depósito, y firme las retiradas sin conexión, en un HSM o en una wallet de hardware, nunca con una clave guardada en texto plano en un servidor de aplicaciones.

En la práctica:

Derive las direcciones de depósito a partir de una única semilla protegida, para no tener miles de claves independientes que respaldar.
Mantenga el entorno de firma separado de la aplicación expuesta a la web.
Registre cada solicitud de retirada con quién la aprobó. Exija límites y aprobación para importes grandes.

Con Chaingateway, POST /api/v2/tron/addresses crea una wallet. Si envía una password, la clave privada se guarda cifrada con ella, y usted pasa la contraseña en lugar de la clave al enviar. Chaingateway no almacena la contraseña y no puede restaurar una wallet si la pierde. Puede leer más en nuestra guía sobre wallets de TRON protegidas con contraseña.

¿Cuánto cuestan Energy y Bandwidth?

Las comisiones son lo que sorprende a los equipos nuevos en TRON. Según la guía de integración para exchanges, las retiradas consumen Bandwidth, mientras que las transferencias TRC-20 y otras llamadas a contratos consumen además Energy. Los recursos proceden del staking o de la delegación, y cuando escasean, se quema TRX en su lugar. El staking se recomienda a los operadores de gran volumen, y fee_limit limita el presupuesto de Energy del lado del llamante en las llamadas a contratos inteligentes.

Las cifras que conviene tener presentes, según la documentación de tokenomía de TRON:

Tasa de quema: 0,001 TRX por byte de Bandwidth y 0,0001 TRX por unidad de Energy. Estas tasas pueden cambiarse mediante propuestas, así que léalas de la cadena en lugar de fijarlas en el código.
Bloquear TRX proporciona Bandwidth o Energy y genera TRON Power para votar. Desbloquear inicia un periodo de espera fijado por el parámetro de cadena getUnfreezeDelayDays.

Cada cuenta activada recibe además una asignación renovable de 600 unidades gratuitas de Bandwidth, que se repone gradualmente en 24 horas tras su uso, y se quema TRX como respaldo cuando el Bandwidth o la Energy no bastan, según la comparación entre TRON y Ethereum.

Planificar su presupuesto de comisiones

Antes del lanzamiento, estime el número de transferencias mensuales y los recursos que necesita cada una, y decida cuánto bloquear o delegar frente a cuánto quemar. Nuestra calculadora de Energy y Bandwidth de TRON y la calculadora de comisiones USDT-TRC20 ayudan con la aritmética. Nuestra guía sobre Energy frente a Bandwidth explica qué recurso usa cada acción, y el artículo sobre cómo reducir las comisiones de transacciones TRC-20 recoge formas de bajar lo que gasta.

Chaingateway tiene endpoints para el staking y la delegación: POST /api/v2/tron/freeze y POST /api/v2/tron/delegate. El antiguo servicio de comisiones Paymaster está obsoleto. Use TronFuel si quiere que sus usuarios tengan las comisiones patrocinadas. GET /api/v2/tron/chainparameters devuelve los precios actuales de Energy y Bandwidth.

Un hábito práctico: fije siempre un fee_limit razonable en las llamadas a contratos, y compruebe los recursos disponibles de una cuenta antes de enviar, para que una retirada no queme en silencio más TRX del presupuesto.

¿Cómo gestiono los pagos fallidos, retrasados y duplicados?

Los sistemas de pago de producción se ganan el sueldo en los casos límite. Así se gestiona cada uno en TRON.

Situación	Qué hacer
La transacción se difundió pero nunca aparece	Compruebe si caducó (la referencia TAPOS es demasiado antigua). Reconstruya, vuelva a firmar y difunda de nuevo con una referencia nueva.
La transacción se incluyó pero falló	No acredite. Registre el resultado del fallo y, en el caso de retiradas, revise Energy y `fee_limit`.
El mismo webhook llegó dos veces	Deduplique por ID de transacción e índice de log antes de acreditar.
El webhook nunca llegó	Chaingateway no reintenta automáticamente. Liste `GET /api/v2/tron/webhooks/notifications/failed` y reenvíe con `POST /api/v2/tron/webhooks/notifications/{id}/retry`.
Se vio un depósito y después se reorganizó el bloque	Acredite solo desde bloques solidificados, para que esto no pueda ocurrir a un pago ya acreditado.
El cliente envía un token equivocado	Ignore los tokens fuera de su lista de permitidos y ofrezca un proceso de recuperación manual.
El cliente paga de menos o de más	Compare el importe recibido con el pedido y aplique su propia política de pagos parciales y excedentes.

Para las pruebas, ejecute primero el flujo completo en una red de pruebas: cree una dirección, fóndela, envíe una transferencia de TRX y otra TRC-20, y observe cada estado por el que pasa su sistema. Después provoque fallos a propósito, como una llamada a un contrato sin Energy suficiente y un webhook reproducido, y confirme que su sistema se comporta como indica la tabla anterior.

¿Puedo aceptar pagos en mi propio token?

Si emite un token en TRON, puede aceptarlo como cualquier otro TRC-20. TRC-20 es el estándar de TRON para tokens fungibles implementados por contratos inteligentes. Su interfaz requerida incluye balanceOf, transfer, transferFrom, approve, allowance, y los eventos Transfer y Approval. Como esas funciones y eventos son comunes, las wallets y los exchanges pueden interactuar con su token sin código especial.

Para aceptar pagos, eso significa tres cosas: añada la dirección de su contrato a su lista de permitidos de depósitos, asegúrese de que los decimales se gestionan correctamente en las comprobaciones de importe, y pruebe con transferencias pequeñas antes de abrirlo a los clientes. Su token se comporta como USDT en lo que respecta a la detección: un evento Transfer en un contrato aprobado.

¿Cómo envío pagos en TRON a través de Chaingateway?

Cree una wallet, envíe una transferencia TRC-20 y suscríbase a los depósitos con tres tipos de petición. El endpoint TRC-20 exige from, to, contractaddress y amount, además de password o privatekey.

curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/trc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{"from": "T...", "to": "T...", "contractaddress": "T...", "amount": 10, "password": "wallet-password"}'

X-Network: testnet usa la testnet Nile. Cree un webhook para una dirección receptora con POST /api/v2/tron/webhooks, y verifique cada entrega con la cabecera X-Signature (guía de firmas). La carga útil del webhook contiene txid, from, to, amount, contractaddress, blocknumber y type. Empiece con la API blockchain y las notificaciones por webhook. Los planes empiezan en 49 € al mes, con una prueba gratuita de 7 días que no requiere tarjeta (precios).

Preguntas frecuentes

¿Qué red es TRON y qué necesito para aceptar pagos en ella?

TRON es su propia blockchain de capa 1, con TRX como token nativo para las comisiones. Para aceptar pagos necesita una dirección de depósito para cada cliente o pedido, una forma de detectar las transferencias entrantes y suficiente Bandwidth y Energy para mover fondos. Puede obtener la detección y las transferencias a través de APIs de nodo o de una API de wallets y webhooks.

¿Cuánto tarda un pago en TRON en ser final?

Una transacción queda totalmente confirmada cuando al menos 19 Super Representantes activos y distintos han producido bloques en su bloque o posteriores, lo que normalmente tarda alrededor de un minuto, según la documentación de TRON. Acredite a los clientes desde bloques solidificados, y muestre un estado provisional mientras espera.

¿Por qué cuesta más una transferencia USDT-TRC20 que una transferencia de TRX?

Una transferencia TRC-20 es una llamada a un contrato inteligente, así que usa Energy además de Bandwidth. Si su cuenta no tiene Energy bloqueada o delegada, se quema TRX para cubrirla. Estimar la Energy antes de enviar, y bloquear o delegar para un volumen constante, mantiene los costes previsibles.

¿Es seguro guardar las claves privadas en mi servidor de aplicaciones?

La orientación de TRON para los operadores es no guardar las claves de retirada en texto plano en un servidor de aplicaciones. Firme sin conexión, en un HSM o con una wallet de hardware. Una API de wallets traslada el almacenamiento de claves al proveedor, que pasa a formar parte de su modelo de confianza.