Sistemas de pago con criptomonedas: arquitectura, integración y verificación

Alcance y respuesta directa

Los sistemas de pago con criptomonedas no son un producto único. Son un patrón de integración: un comerciante o plataforma crea una factura, un cliente difunde una transferencia en una blockchain y los servicios backend detectan, confirman y concilian esa transferencia antes de liberar bienes o saldos. La blockchain es el riel de liquidación; todo lo demás —precios, asignación de direcciones, política de confirmaciones, contabilidad— es lógica de aplicación que tú posees o delegas a una pasarela.

Esta guía está dirigida a ingenieros y operadores que construyen o auditan esa lógica. Cubre el mecanismo, un procedimiento de verificación ejecutable, los resultados esperados, los modos de fallo y las ventajas y desventajas entre diseños autocustodiados y mediados por pasarela. No clasifica proveedores. Cuando necesites un endpoint RPC concreto o una recomendación de proveedor, utiliza el Asistente RPC de OnFinality en lugar de tratar esta página como una lista de proveedores.

• Comportamiento documentado: qué prueban realmente una transferencia en blockchain y su recibo.
• Recomendaciones: profundidad de confirmaciones, idempotencia y decisiones de diseño de conciliación.
• Mediciones: latencia, frecuencia de reorganizaciones y tiempos de finalidad que debes observar en tus propias redes.

Supuestos y requisitos previos

Los procedimientos a continuación asumen una cadena compatible con EVM y un endpoint JSON-RPC que controlas o en el que confías, como un nodo dedicado o un endpoint gestionado. Necesitas la capacidad de ejecutar curl o un script corto, una base de datos o tabla de libro mayor para facturas, y un programador de tareas para sondeo o una suscripción websocket para eventos push.

También necesitas una decisión de política clara antes de escribir código: qué activos aceptas, cuántas confirmaciones requieres y si liquidas en el propio activo o conviertes a fiat o stablecoins. Esas decisiones determinan el resto de la arquitectura. Para la selección de endpoints entre redes, consulta el directorio de redes de OnFinality y la guía de endpoints RPC.

• Una URL JSON-RPC para cada cadena que aceptes, almacenada como variable de entorno, por ejemplo RPC_URL.
• Una tabla de facturas con IDs únicos, monto esperado, activo y una dirección de depósito o memo asignado.
• Una política de confirmaciones por cadena, revisada según el comportamiento de finalidad documentado de esa cadena.
• Un trabajo de conciliación que compare el estado on-chain con tu libro mayor interno.

Modelo mental: el ciclo de vida de la factura

Todo pago cripto pasa por una pequeña máquina de estados. Modelarla explícitamente previene la clase de errores más común: liberar valor por una transacción que luego es reorganizada fuera o que pagó el monto incorrecto.

El ciclo de vida es: creada → en espera de pago → detectada (vista en mempool o en un bloque) → confirmada (alcanzó tu política de profundidad) → liquidada (acreditada en tu libro mayor) → conciliada. Una rama separada de expirada o pagada insuficientemente maneja tiempos de espera y pagos parciales. Cada transición debe ser idempotente y estar impulsada por una clave única, como el hash de la transacción más el ID de la factura.

• Creada: factura persistida con una dirección de depósito única y una marca de tiempo de expiración.
• Detectada: aparece una transferencia coincidente en un bloque; aún no acredites.
• Confirmada: la transferencia alcanzó la profundidad de confirmaciones requerida.
• Liquidada: tu libro mayor registra el crédito y cualquier conversión.
• Conciliada: un trabajo periódico vuelve a verificar las transacciones liquidadas contra el estado de la cadena.

Componentes de un sistema de pago con criptomonedas

Un sistema en producción normalmente separa responsabilidades en un servicio de checkout, un observador de cadena, un motor de confirmaciones, un libro mayor y un servicio de liquidación o pagos. El servicio de checkout fija el precio de la factura y asigna una dirección. El observador de cadena se suscribe a bloques o sondea transferencias a tus direcciones. El motor de confirmaciones aplica reglas de profundidad y valor. El libro mayor es la fuente de verdad para la contabilidad, y el servicio de liquidación maneja la conversión o el pago.

Si utilizas una pasarela alojada, varios de estos componentes se externalizan, pero el libro mayor y la conciliación siguen siendo tuyos. Esa frontera importa: el webhook de una pasarela es una notificación, no una prueba. Tu sistema aún debería poder verificar la transferencia subyacente de forma independiente. Para equipos que ejecutan su propia infraestructura, un nodo dedicado reduce la dependencia de límites de tasa de terceros y te da acceso consistente a registros históricos.

Verificación ejecutable: comprobar una transacción de pago mediante JSON-RPC

El primer diagnóstico para cualquier pago disputado o retrasado es leer la transacción y su recibo directamente. Las siguientes llamadas curl usan marcadores de posición; reemplaza RPC_URL con tu endpoint y TX_HASH con el hash de la transacción. La primera llamada devuelve la transacción, incluidos el destinatario y el valor. La segunda devuelve el recibo, incluidos el estado y el número de bloque.

curl -s -X POST "$RPC_URL" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getTransactionByHash","params":["TX_HASH"]}'

curl -s -X POST "$RPC_URL" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_getTransactionReceipt","params":["TX_HASH"]}'

Resultado esperado de la verificación

Una transacción de pago válida devuelve un objeto de transacción no nulo cuyo campo to coincide con tu dirección de depósito asignada y cuyo value coincide con el monto de la factura en la unidad más pequeña del activo. El recibo devuelve status 0x1 para éxito y un blockNumber. Si el recibo es nulo, la transacción está pendiente o es desconocida; si status es 0x0, la transferencia se revirtió y no movió valor.

Registra el número de bloque y compáralo con la cabeza actual de eth_blockNumber. La diferencia es tu conteo de confirmaciones observado. No trates un avistamiento en mempool como pago. La siguiente tabla es una plantilla para registrar lo que observas; complétala con valores de tus propias ejecuciones en lugar de asumir números.

• | Campo | Fuente | Esperado |
• | tx.to | eth_getTransactionByHash | coincide con la dirección asignada |
• | tx.value | eth_getTransactionByHash | igual al monto de la factura |
• | receipt.status | eth_getTransactionReceipt | 0x1 |
• | confirmaciones | cabeza menos receipt.blockNumber | igual o superior a la política |

Implementación: un bucle de confirmación y conciliación

El siguiente esbozo en Python sondea la cabeza, verifica facturas pendientes y solo liquida cuando se cumple la política de confirmaciones. Es intencionalmente pequeño; el código de producción necesita reintentos, retroceso y estado persistente. El punto clave de diseño es que la liquidación está condicionada a confirmaciones derivadas de la cadena, no solo a un webhook.

import os, time, requests

RPC_URL = os.environ["RPC_URL"]
REQUIRED_CONFIRMATIONS = int(os.environ.get("REQUIRED_CONFIRMATIONS", "12"))

def rpc(method, params):
    r = requests.post(RPC_URL, json={"jsonrpc":"2.0","id":1,"method":method,"params":params}, timeout=10)
    r.raise_for_status()
    return r.json()["result"]

def confirmations(tx_hash):
    receipt = rpc("eth_getTransactionReceipt", [tx_hash])
    if not receipt or receipt.get("status") != "0x1":
        return 0
    head = int(rpc("eth_blockNumber", []), 16)
    return head - int(receipt["blockNumber"], 16) + 1

# Example loop over invoice rows from your database
for invoice in load_pending_invoices():
    depth = confirmations(invoice["tx_hash"])
    if depth >= REQUIRED_CONFIRMATIONS:
        mark_settled(invoice["id"], depth)

Solución de problemas comunes de pago

La mayoría de los incidentes de pago caen en unas pocas categorías: la transacción está pendiente porque la comisión era demasiado baja, la transferencia fue a la dirección o memo incorrectos, el monto se pagó insuficientemente debido al movimiento del precio, o el recibo se revirtió. Cada una tiene una ruta de diagnóstico distinta.

Para transacciones pendientes, verifica la tarifa base actual y compárala con los campos de comisión de la transacción. Para transferencias a dirección incorrecta, normalmente no hay recuperación sin la cooperación del destinatario; por eso la asignación de direcciones debe ser única y mostrarse claramente. Para pago insuficiente, compara el valor recibido con el monto de la factura a la tasa cotizada y decide si aceptar, completar o expirar. Para recibos revertidos, el valor no se movió y la factura permanece impaga.

• Pendiente: inspecciona los campos de comisión y el estado del mempool; considera reemplazo solo si tu política lo permite.
• Pago insuficiente: concilia contra la tasa cotizada y define una tolerancia antes del lanzamiento.
• Revertido: status 0x0 significa que no se transfirió valor; no acredites.
• Webhooks duplicados: deduplica por hash de transacción más ID de factura.

Limitaciones y compensaciones

Los sistemas autocustodiados te dan control y reducen el riesgo de contraparte, pero tú asumes la gestión de claves, el manejo de reorganizaciones y el cumplimiento. Los sistemas mediados por pasarela reducen la carga operativa y pueden ofrecer conversión a fiat, pero introducen un intermediario de confianza y dependencias de webhooks. Ninguno elimina la necesidad de conciliación.

La profundidad de confirmaciones es una compensación entre velocidad y seguridad. Las stablecoins y las cadenas de finalidad rápida pueden necesitar menos confirmaciones que las cadenas de finalidad probabilística, pero debes medir el comportamiento de reorganización en tu red elegida en lugar de asumirlo. El rendimiento y la latencia también dependen de tu proveedor RPC; mide bajo tu propia carga. Para implementaciones sensibles al rendimiento, revisa las opciones de nodo dedicado y el modelo de precios antes de comprometerte.

Próximos pasos

Comienza escribiendo tu máquina de estados de factura y tu política de confirmaciones, luego implementa el procedimiento de verificación anterior contra una testnet. Una vez que pase, ejecuta un trabajo de conciliación de forma programada y registra cada transición de estado. Si necesitas ayuda para elegir un endpoint o una red, el Asistente RPC puede darte una recomendación directa, y la biblioteca Learn cubre temas de infraestructura relacionados, como el alojamiento de nodos y los endpoints multicadena.

• Lee la guía de alojamiento de nodos blockchain para la planificación de infraestructura.
• Revisa la guía de endpoints RPC multicadena si aceptas activos en varias redes.
• Compara las opciones de nodo dedicado para un rendimiento constante en el monitoreo de pagos.