Por qué «detectado» no es «pagado»: la reorganización de la cadena de bloques

Una reorganización de la cadena de bloques ocurre cuando la red reemplaza sus bloques más recientes por otra rama. Una transferencia que ya se veía en un bloque puede entonces desaparecer o quedar en otro bloque. Por eso CryptoLike marca el pago como pending en cuanto detecta la transferencia y como paid solo después de las confirmaciones del activo. Este artículo explica cómo funciona una reorganización, qué hace CryptoLike si se descarta el bloque de tu pago antes o después de ese punto y cómo escribir una integración que siga siendo correcta cuando pasa.

#¿Qué es una reorganización de bloques?

Una reorganización es el cambio de la red de la rama que seguía a una rama competidora, descartando uno o varios de los bloques más recientes. Una transferencia de un bloque descartado puede volver a entrar en la nueva rama, por lo general a otra altura, o no volver nunca; por ejemplo, si la nueva rama tiene una transacción en conflicto que gasta las mismas monedas.

Las ramas competidoras existen porque los bloques los producen muchos participantes independientes. En Bitcoin y Litecoin dos mineros pueden encontrar un bloque casi al mismo tiempo, y los nodos siguen el que vieron primero hasta que una rama se vuelve más larga. Ethereum y TRON producen bloques con un calendario fijo, pero sus bloques más recientes también pueden reemplazarse mientras la red no los considere definitivos. En todas las redes, cuanto más profundo está un bloque, menos probable es que se reemplace.

#¿Por qué «detectado» no es «pagado»?

«Detectado» significa que CryptoLike vio la transferencia en un bloque. «Pagado» significa que la transferencia alcanzó el umbral de confirmaciones del activo y el dinero está en tu saldo. Entre los dos momentos, una reorganización todavía puede quitar la transferencia, así que CryptoLike separa las etapas en todos los lugares donde las ves.

CryptoLike no lee las transferencias que aún no entraron en un bloque, así que pending ya significa «en un bloque». La página de pago también muestra detected_amount, la suma de transferencias vistas pero no confirmadas, y la documentación de la API lo dice claro: no está acreditada y una reorganización puede eliminarla. Cuántas confirmaciones necesita cada activo y por qué los números cambian entre redes se explica en cuántas confirmaciones necesita un pago cripto y en la entrada del glosario sobre confirmaciones; los valores actuales están en GET /v1/currencies y en las páginas de monedas, por ejemplo Bitcoin.

#¿Cómo detecta CryptoLike una reorganización?

CryptoLike lee cada red bloque por bloque y comprueba que cada bloque nuevo apunte al hash del bloque que leyó antes. Si el hash del bloque padre no coincide, la cadena que seguía fue reemplazada, y CryptoLike retrocede hasta el último bloque que ambas ramas comparten.

A partir de ahí los pasos son siempre los mismos:

1. Cada transferencia a tus direcciones en los bloques por encima del bloque común se marca como huérfana (orphaned), y se publica un evento para el libro contable.
2. CryptoLike lee la nueva rama desde el bloque común, un bloque a la vez.
3. Una transferencia que vuelve a aparecer en la nueva rama se detecta de nuevo y cuenta sus confirmaciones desde su nuevo bloque; el destinatario y el monto se toman del nuevo bloque.
4. Los registros que parecen confirmados se cotejan con la cadena guardada de encabezados de bloque antes de contarse, así que una confirmación de un bloque reemplazado no se acepta.

El manejo automático tiene un límite. CryptoLike guarda una ventana de bloques recientes de cada red: el doble del umbral de confirmaciones más estricto entre sus activos, y al menos 8 bloques. Una reorganización más profunda que esa ventana detiene el procesamiento de esa red hasta que el equipo de CryptoLike la revise: no se acredita ni se revierte nada desde una rama que no se puede verificar. Mientras tanto, los pagos de esa red esperan; los que llegan al final de su plazo de pago se cierran como expired, como siempre.

#¿Qué le pasa a un pago si se descarta su bloque?

Lo que hace CryptoLike depende de hasta dónde llegó el pago antes de que se descartara el bloque. La regla es la misma en las cuatro redes —Bitcoin, Litecoin, Ethereum y TRON—; solo cambia el umbral de confirmaciones de cada activo.

Dos detalles más. Si solo se descarta un excedente y la factura sigue en paid, no llega invoice.reverted: no cambió nada en lo que te basaste. Y en una factura cerrada —vencida o cancelada—, si se descarta un pago tardío que ya estaba confirmado, igual llega invoice.reverted, aunque el estado no cambia.

#¿Qué registra el libro contable?

El libro contable nunca edita ni borra un asiento: una reorganización se registra con asientos nuevos de reversión, que reflejan los originales. CryptoLike revierte en el orden inverso al del abono: primero la confirmación (available vuelve a pending y se devuelve la comisión de la plataforma) y después el abono en sí (pending sale de la plataforma).

Así las cuentas se pueden comprobar. Cada asiento cuadra, el abono y su reversión quedan uno junto al otro con referencia a la misma transferencia, y la cuenta sigue cumpliendo «acreditado − revertido − retiros − saldo = 0». Si la transferencia vuelve a entrar en un bloque, se acredita con la siguiente generación de la misma clave, así que un evento antiguo repetido no puede acreditarla dos veces.

El único caso que el libro contable no resuelve solo es revertir dinero que ya no está porque se retiró. CryptoLike no crea un saldo negativo ni una deuda oculta: la transferencia se marca como descartada y el equipo de CryptoLike resuelve el caso a mano.

#¿Cómo debe manejar tu integración una reorganización?

Trata cada webhook como una descripción del estado actual, no como un paso en un solo sentido. Si una transferencia descartada vuelve a entrar en un bloque, una factura todavía abierta pasa por paid → reverted → paid. Pero a menudo su plazo ya terminó: las confirmaciones empiezan de nuevo desde el nuevo bloque y una factura dura 30 minutos por defecto. Entonces la factura se cierra como expired, y el dinero que vuelve se acredita y se anuncia con invoice.late_payment. Tu código debe seguir los dos caminos sin ayuda manual.

• Entrega con paid, no con pending. invoice.pending es una señal de avance. Si la transferencia se descarta antes del umbral, ningún webhook de la factura lo avisa: el pago puede volver a new y vencer más tarde.
• Procesa invoice.reverted. Si el pedido no se envió, mantenlo en espera; si ya se envió, márcalo para revisión. Los plugins para CMS hacen exactamente esto: un pedido pagado que se revirtió pasa a un estado de revisión. Si después llega invoice.late_payment, el dinero vuelve a estar en tu saldo y el estado sigue en expired: envía el pedido o reembolsa al cliente.
• Aplica cada evento una sola vez por event_id. Las entregas llegan al menos una vez y sin orden fijo: guarda el event_id, omite las repeticiones y compara created_at en lugar del orden de llegada. El artículo sobre idempotencia en las API de pagos muestra el patrón con código.
• Verifica primero la firma. Un invoice.paid falso es peor que una reorganización; consulta cómo verificar los webhooks de pagos cripto.
• Confía en los montos del evento, no en tus propias sumas. Cada evento de la factura trae el pago completo con paid_amount y remaining_amount actuales. En Ethereum la posición de una transferencia de token dentro del bloque puede cambiar cuando se mina de nuevo, así que una clave propia hecha con txid y output_index puede no coincidir con la nueva aparición.
• Si tienes dudas, consulta la API. GET /v1/invoices/{id} devuelve el estado y los montos actuales.

Si todavía comparas proveedores, preguntar cómo manejan las reorganizaciones es razonable: es uno de los puntos de cómo elegir una pasarela de pagos cripto.

#Cómo incluir las reorganizaciones en tu integración

En CryptoLike no hay una configuración aparte para las reorganizaciones: los estados y webhooks de arriba vienen con cada pago y cada dirección estática. Lo que te toca es el manejador de webhooks.

1. En tu panel, abre Webhooks, agrega un endpoint y suscríbelo a invoice.paid, invoice.reverted, invoice.late_payment, deposit.confirmed y deposit.reverted, o a todos los eventos (*).
2. Haz que el manejador verifique la firma, guarde el event_id y pase el pedido a «listo para enviar» con invoice.paid y a «en espera» con invoice.reverted.
3. Prueba el flujo en redes de prueba con una clave de prueba —los pasos están en la guía para probar pagos cripto— y ten a mano la lista de eventos de la referencia de webhooks.

#Preguntas frecuentes

#¿Qué es una reorganización en una blockchain?

Es el reemplazo de los bloques más recientes por una rama competidora. Las transferencias de los bloques descartados pueden desaparecer o volver a entrar en un bloque posterior. Cuanto más profundo está un bloque, menos probable es que se reemplace; por eso un pago espera un número de confirmaciones antes de contar.

#¿Se puede revertir un pago cripto ya pagado?

Por parte de la red, solo si una reorganización descarta el bloque de una transferencia confirmada. En ese caso CryptoLike revierte el abono en el libro contable, recalcula el pago y envía invoice.reverted (o deposit.reverted para una dirección estática). Si la transferencia vuelve a entrar en un bloque mientras la factura está abierta, llega un nuevo invoice.paid; si la factura venció entretanto, su estado se queda en expired y en su lugar recibes invoice.late_payment. Detén la entrega con reverted y vuelve a decidir con el evento que llegue.

#¿Recibo un webhook si desaparece un pago pendiente?

Para una factura, no. Una transferencia descartada antes del umbral nunca se acreditó, así que el pago vuelve sin aviso a new (o sigue en pending si otra transferencia está esperando) y el cambio queda en su historial. Para una dirección estática recibes deposit.reverted en cualquier etapa.

#¿Qué pasa si ya retiré el dinero de un pago revertido?

El libro contable no deja tu saldo en negativo ni crea una deuda por su cuenta. La transferencia se marca como descartada y el caso pasa al equipo de CryptoLike, que lo resuelve contigo. Para llegar a esto hace falta una reorganización más profunda que el umbral del activo, y el umbral se fija para que eso no sea un riesgo práctico.

#¿CryptoLike maneja las reorganizaciones igual en todas las redes?

Sí. Bitcoin, Litecoin, Ethereum y TRON usan la misma comprobación bloque por bloque y los mismos estados, reversiones en el libro contable y webhooks. Lo que cambia es el umbral de confirmaciones de cada activo, publicado en GET /v1/currencies, porque las redes difieren en el intervalo de bloques y en cómo los vuelven definitivos.