Integración de pagos con Ethereum para desarrolladores
Cómo integrar pagos con Ethereum: elegir ETH o tokens, crear solicitudes de pago, detectar y confirmar transacciones, gestionar gas, proteger claves y probar.
Revisado por Maurice Sobiera
La integración de pagos con Ethereum consiste en aceptar ETH o tokens dentro de su propia aplicación. Implica asignar a cada cliente una dirección única, detectar la transacción cuando llega, decidir cuándo se considera definitiva y conciliarla con el pedido. Puede construirla sobre nodos y JSON-RPC, o llamar a una API que se encargue de las wallets y las notificaciones.
Esta guía cubre ambas vías, para que pueda elegir con las ventajas e inconvenientes a la vista.
TL;DR
- Un pago con Ethereum es una transacción firmada que mueve ETH o tokens. Enviarla no es lo mismo que confirmarla: debe comprobar el recibo.
- Decida primero: solo ETH, stablecoins y tokens ERC-20, o un token propio. Esa elección determina el manejo de eventos y la estrategia de gas.
- Use una dirección de depósito por pedido o por usuario, y escuche los eventos mediante webhooks en lugar de sondear.
- Trate las claves privadas, las firmas de webhooks y el código de los contratos como las tres superficies de seguridad principales.
- Una API como Chaingateway sustituye al nodo y al escáner de bloques, con planes desde 49 € al mes. La configuración del gas y la política de confirmación siguen siendo decisiones suyas.
¿Qué es un pago con Ethereum?
Un pago con Ethereum es una instrucción firmada criptográficamente, emitida por una cuenta, que actualiza el estado de la red, por ejemplo transfiriendo ETH o tokens. Según la documentación de transacciones de ethereum.org, un validador comprueba entonces la transacción y la incluye en un bloque. Solo después existe el dinero en la dirección del destinatario.
Para su aplicación, esto tiene una consecuencia práctica. El cliente no le paga a usted. Difunde una transacción a la red, y su sistema tiene que darse cuenta. Toda integración es una variación de ese problema de observación.
Hay dos tipos de pago con los que se encontrará:
- Transferencias de ETH nativo. La propia transacción lleva un destinatario y un importe. Es sencillo y se ve directamente en la transacción y en su recibo.
- Transferencias de tokens (ERC-20 y similares). La transacción va al contrato del token, que actualiza los saldos internamente. El estándar define para ello un evento
Transfer, tal como recoge la especificación ERC-20 en ethereum.org. Su sistema se entera del pago por ese registro de evento, no por el campo de valor de la transacción.
La mayoría de los pagos con stablecoins son del segundo tipo. Si solo vigila la llegada de ETH a una dirección, se le escaparán.
¿Qué debe decidir antes de escribir código?
¿Qué activos aceptará?
Empiece por el conjunto más reducido que sirva a sus clientes. Solo ETH es lo más fácil de implementar. Añadir una stablecoin elimina la volatilidad de precio de la ecuación, lo que importa en facturas y suscripciones. Si emite su propio token, también necesita conocer sus decimales, su dirección de contrato y si se comporta como un ERC-20 estándar.
Cada activo adicional añade una dirección de contrato que vigilar, un valor de decimales que aplicar y una regla de precios. Mantenga una lista corta de permitidos y rechace lo demás de forma deliberada.
¿Checkout alojado, enlaces de pago o una API?
Hay tres formas de integración, y cada una cambia control por rapidez:
| Enfoque | Ideal para | Usted controla | Renuncia a |
|---|---|---|---|
| Checkout alojado o enlace de pago | Lanzamiento rápido, bajo volumen | Casi nada del flujo | Marca propia, custodia, lógica a medida |
| Conexión de wallet en su propio front end | Dapps donde los usuarios ya tienen ETH | La experiencia de usuario | La detección y la conciliación siguen siendo suyas |
| API de backend con wallets y webhooks | Aplicaciones, marketplaces, facturación SaaS | Direcciones, importes, lógica de pedidos | Operar su propia infraestructura |
Si usted es desarrollador y construye pagos dentro de un producto, la tercera fila es normalmente donde acaba. Una lista útil para cualquier proveedor: ¿ofrece un entorno de pruebas, formatos de error claros, límites de peticiones documentados y webhooks que encajan con su stack?
Custodia y cumplimiento normativo
¿Quién posee las claves? Si su plataforma genera wallets de depósito para los clientes, usted está gestionando fondos. Según su jurisdicción y su modelo de negocio, eso puede conllevar obligaciones de licencia o de información. Consulte con un abogado que conozca su mercado antes del lanzamiento, no después. Esta guía trata de ingeniería, no de asesoramiento jurídico.
¿Cómo funciona el flujo de pago, paso a paso?
Esta es la secuencia que se sostiene en producción, tanto si la construye como si la compra.
1. Cree una solicitud de pago
Cuando el cliente llega al checkout, cree un registro de pedido con un importe, un activo y una fecha de caducidad. Después asigne a ese pedido una dirección receptora única. Una dirección única por pedido permite asociar una transferencia entrante con el cliente correcto sin pedirle que pegue un memo o una referencia.
Fije el precio del pedido en una unidad estable. Si acepta activos volátiles, bloquee un importe en ETH durante una ventana corta y guarde ambos valores.
2. El cliente firma y envía
Si el cliente paga desde una wallet de navegador, su front end pide permiso para usar su cuenta, construye un objeto de transacción y lo envía. La referencia de eth_sendTransaction de MetaMask describe este orden: obtener el permiso de la cuenta, enviar la transacción y conservar el hash devuelto. Si el cliente envía desde un exchange o una wallet móvil a la dirección que usted muestra, usted nunca ve este paso. Solo ve el resultado en la cadena.
En cualquier caso, el hash de la transacción es el número de recibo del pago. Guárdelo.
3. Detecte la transacción
Tiene tres opciones para darse cuenta de un pago:
- Sondeo. Pida a un nodo el recibo o el saldo de la dirección cada pocos segundos. Es sencillo, pero derrochador y frágil a escala.
- Suscripciones. Abra un WebSocket a un nodo y suscríbase a nuevos bloques o a logs de contratos. La documentación de go-ethereum sobre eventos en tiempo real describe
eth_subscribejusto para esto. Usted debe gestionar las conexiones caídas y reproducir los bloques perdidos. - Webhooks. Un servicio vigila la cadena y llama a su servidor cuando ocurre algo relevante. Es la opción de menor mantenimiento y la que elige la mayoría de los equipos.
Para los tokens, lo que vigila son los logs de eventos. La documentación de Ethereum señala que las aplicaciones pueden escuchar eventos de contratos a través de la API JSON-RPC y actuar sobre los logs que emiten.
4. Confirme el resultado
Enviar no es confirmar. La guía de envío de transacciones de MetaMask muestra el patrón: consulte el recibo por hash. Si no hay recibo, la transacción sigue pendiente. Un estado 0x1 significa éxito, y 0x0 significa fallo. La referencia de eth_getTransactionReceipt añade que el recibo contiene el número de bloque, el gas usado y los logs.
La máquina de estados de su pedido debe reflejar esto de forma explícita:
awaiting_payment: dirección emitida, nada visto todavía.pending: hay una transacción coincidente visible, pero aún no está en un bloque.confirmed: recibo encontrado, estado exitoso, importe y activo coinciden.final: han pasado suficientes bloques adicionales según su tolerancia al riesgo.failed,underpaid,overpaidoexpired: los casos que necesitan una regla, no un encogimiento de hombros.
Cuántos bloques esperar antes de liberar la mercancía es una decisión de negocio. Los bienes digitales de pocos dólares pueden enviarse con la primera confirmación. Los pedidos de alto valor merecen una espera más larga, porque un bloque puede reorganizarse en raras ocasiones antes de que la red lo asiente.
5. Concilie
Compare cada día la suma de los pagos confirmados en su base de datos con lo que dice la cadena que llegó a sus direcciones. Cualquier diferencia es un error, un webhook perdido o un cliente que pagó con el activo equivocado. La sección de datos y análisis de ethereum.org enumera indexadores que sirven logs de eventos históricos, lo que puede reducir cuánto de esto mantiene usted mismo.
¿Cómo funcionan el gas, las transacciones fallidas y los reembolsos?
El gas es donde muchas primeras integraciones se llevan una sorpresa. Cada transacción paga una comisión formada por una comisión base y una comisión prioritaria, y la paga el remitente, como explica la documentación de transacciones. De ahí se derivan tres consecuencias para usted.
- Los clientes pueden pagar de menos o quedarse bloqueados. Si fijan una comisión demasiado baja, la transacción queda pendiente. Su pedido no debe caducar mientras una transacción válida esté en curso.
- Las transacciones fallidas también cuestan gas. Una transferencia de token revertida produce un recibo con estado fallido, y los fondos del cliente no se mueven. No marque el pedido como pagado porque vio un hash.
- Enviar desde su lado tiene coste. Los reembolsos, los barridos desde direcciones de depósito a una wallet de tesorería y los pagos salientes requieren gas, y las direcciones de tokens necesitan ETH para mover tokens. Estime la comisión antes de enviar y presupuéstela.
En la API de Chaingateway, gas, gasprice, maxFeePerGas y maxPriorityFeePerGas son campos opcionales de los endpoints de transacciones ETH y ERC-20, y GET /api/v2/ethereum/gasprice devuelve el precio actual del gas. Nuestra guía sobre cómo estimar las comisiones de gas en Ethereum y otras cadenas recorre los métodos de estimación.
Si quiere que los clientes paguen sin tener ETH en absoluto, la abstracción de cuentas permite a los desarrolladores patrocinar transacciones, como se describe en el tutorial de ethereum.org sobre patrocinio de comisiones de gas. Añade complejidad al contrato, así que reserve esta opción para productos en los que la fricción del gas le cuesta conversiones de verdad.
Para los reembolsos, decida la política desde el principio. Reembolse a la dirección remitente solo después de comprobar que no es una dirección de depósito de un exchange que usted no controla, o pida al cliente una dirección de reembolso. Descuente la comisión de red de forma explícita, o asúmala, pero escriba la regla.
¿Cómo se protegen las claves, las firmas y los contratos?
Claves privadas
Quien tiene la clave controla los fondos. Genere las claves en un entorno endurecido, nunca las registre en logs, nunca las suba al repositorio, y separe las wallets calientes (saldos pequeños, usadas para los pagos salientes) del almacenamiento en frío (la mayor parte de los fondos). Barra las direcciones de depósito hacia el lado frío según un calendario.
Autenticidad de los webhooks
Un endpoint de webhook es una URL pública que puede marcar pedidos como pagados, así que cualquiera que la encuentre puede enviar un evento falso. Protéjalo de cuatro maneras:
- Verifique una firma en cada petición. La firma HMAC es el enfoque habitual. Si el esquema incluye una marca de tiempo, rechace las peticiones antiguas.
- Haga que el manejador sea idempotente, para que una entrega duplicada no abone dos veces un pedido.
- Confirme el importe y el destinatario con una consulta directa antes de liberar la mercancía.
- La cabecera
X-Signaturede Chaingateway cubre solo el ID de la transacción, como explica el artículo sobre verificación de firmas, así que la consulta directa importa.
Código de los contratos inteligentes
Si escribe sus propios contratos de pago, el riesgo se traslada al código. El propio informe de seguridad de Ethereum señala que las auditorías, las bibliotecas probadas, la verificación formal y el análisis estático mejoran la seguridad de los contratos, y que el código a medida para controles avanzados puede aumentar el riesgo de vulnerabilidad. La regla práctica: no despliegue un contrato a medida cuando una dirección sencilla y los eventos estándar de token bastan para su caso de uso.
¿Debe construirlo usted mismo o usar una API?
La vía de hacerlo uno mismo implica ejecutar o alquilar nodos y escribir un generador de direcciones. También debe construir el decodificador de logs para cada token que acepte, estimar el gas, gestionar las reorganizaciones y mantener todo en marcha. Es un camino razonable para un equipo cuyo producto es la infraestructura de pagos.
Para todos los demás, el coste es tiempo y mantenimiento continuo. La cuestión de arquitectura es si recibir los eventos según ocurren o conciliar por lotes más tarde. En pagos, los eventos según ocurren son el valor por defecto mejor.
Nuestra comparativa de tipos de API blockchain y cuándo usar cada uno expone las categorías. La visión general de Ethereum explica ETH, el gas y los tokens ERC-20 para equipos que se inician en la cadena.
¿Cómo encaja Chaingateway en una integración con Ethereum?
La API de Ethereum permite enviar tokens ERC-20 mediante REST, sin web3.js. Tres endpoints cubren la mayor parte de un flujo de pago:
| Paso | Endpoint |
|---|---|
| Crear una dirección de depósito | POST /api/v2/ethereum/addresses |
| Vigilarla por si llegan ETH o tokens | POST /api/v2/ethereum/webhooks con to, url y type (ETH, ERC20 o ERC721) |
| Enviar ETH o un token ERC-20 después | POST /api/v2/ethereum/transactions o .../transactions/erc20 |
Un pago de salida en ERC-20 necesita el remitente, el destinatario, contractaddress y amount, además de la password de la wallet para las wallets que la API creó con contraseña. El error 422 por saldo de comisiones vacío es insufficient funds for gas * price + value. Pruébelo primero en Sepolia añadiendo la cabecera X-Network: testnet. La página de webhooks de Chaingateway y la de la API Blockchain cubren las demás redes compatibles con las mismas llamadas.
Las notificaciones de webhook fallidas no se reintentan automáticamente. Enumérelas con GET /api/v2/ethereum/webhooks/notifications/failed y reenvíe cada una.
Los planes se facturan según uso y funciones: Plus cuesta 49 € al mes, Pro 99 €, Premium 249 € y Enterprise 499 €, o 490 €, 990 €, 2.490 € y 4.990 € al año con facturación anual. Todos los planes empiezan con una prueba gratuita de 7 días sin tarjeta ni KYC. Consulte la página de precios para ver lo que incluye cada plan.
¿Cómo se prueba y se monitoriza una integración de pagos con Ethereum?
Una integración de pagos no está terminada cuando funciona la demostración. Recorra esta lista en una red de pruebas primero, y después otra vez con importes reales pequeños:
- Pago exacto, pago insuficiente y pago excesivo, tanto de ETH como de cada token aceptado.
- Pago tardío tras caducar el pedido, y pago duplicado a la misma dirección.
- Una transacción fallida con un límite de gas bajo, para ver un recibo fallido y confirmar que el pedido no se completa.
- Webhooks duplicados y fuera de orden, reproducidos a propósito.
- Su propia caída: detenga su servidor durante diez minutos, envíe un pago, reinicie y compruebe que no se pierde nada.
- Flujos de wallet en el front end. Los equipos de QA pueden hacer pruebas de regresión sin tener claves privadas, usando herramientas como la que aparece en la página de Impersonator.xyz de ethereum.org.
Tras el lanzamiento, configure alertas para tres señales: pedidos atascados en pending más tiempo que un umbral, una diferencia entre los totales de su base de datos y los totales en la cadena, y fallos en la entrega de webhooks. La primera detecta problemas de comisiones, la segunda detecta eventos perdidos, y la tercera detecta sus propias caídas.
Fuentes
- Transactions, ethereum.org
- ERC-20 Token Standard, ethereum.org
- eth_sendTransaction, documentación de MetaMask
- eth_getTransactionReceipt, documentación de MetaMask
- Send transactions, documentación de MetaMask
- Real-time Events, go-ethereum
- Logging data from smart contracts with events, ethereum.org
- Sponsoring gas fees, ethereum.org
- Security Challenges Overview, ethereum.org
- Data and analytics, ethereum.org
- Impersonator.xyz, ethereum.org
Recomendado
Preguntas frecuentes
No. Un nodo le da acceso directo a la cadena, pero también hereda su mantenimiento, sincronización y monitorización. La mayoría de los equipos usa una API de proveedor o un servicio que vigila la cadena por ellos y llama a un webhook cuando llega un pago.
Vigile el evento Transfer del contrato del token para su dirección receptora. El estándar ERC-20 define ese evento, y una transferencia de token no aparece como un valor en ETH de la transacción. Una notificación de webhook de Chaingateway incluye directamente el remitente, el destinatario, la dirección del contrato y el importe.
No hay un número único correcto. Depende del valor del pedido y de su tolerancia a la rara reorganización de la cadena. Los bienes digitales de bajo valor pueden liberarse pronto, mientras que los pedidos de alto valor deben esperar más. Escriba los umbrales en la lógica de pedidos para que el soporte no decida caso por caso.
La paga el remitente. Así que los clientes cubren la comisión de sus propios pagos, y usted la cubre cuando envía reembolsos, barridos o pagos salientes. El gas patrocinado mediante abstracción de cuentas puede trasladar ese coste a usted en flujos concretos.
Sí, si elige una interfaz que no esté ligada a una sola cadena. Con Chaingateway, añadir Polygon o Arbitrum más adelante reutiliza las mismas llamadas de wallet, transferencia y webhook, con otro nombre de cadena en la ruta. TRON usa un patrón parecido con su propio modelo de comisiones.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API de Ethereum para la referencia completa de los endpoints.