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

> Qué es una reorganización de la cadena de bloques, por qué un pago detectado aún no está pagado y qué hace CryptoLike si se descarta su bloque: estados y webhooks.

Source: https://cryptolike.net/es/blog/blockchain-reorg-explained
Published: 2026-10-04 · Updated: 2026-10-04 · Author: CryptoLike team

Puntos clave:

- Una reorganización reemplaza los bloques más recientes de la cadena; una transferencia que ya viste puede desaparecer o pasar a otro bloque.
- CryptoLike deja la transferencia detectada en tu saldo pendiente y la acredita solo al alcanzar el umbral de confirmaciones del activo; una reorganización antes del umbral no toca tu saldo disponible.
- Si la transferencia se descarta antes del umbral, el pago vuelve a su estado anterior sin webhook de la factura; si se descarta una transferencia confirmada, el libro contable la revierte y recibes invoice.reverted o deposit.reverted.
- Entrega con paid, detente con reverted y aplica cada webhook una sola vez por event_id. Si la transferencia vuelve a un bloque, llega invoice.paid mientras la factura está abierta, o invoice.late_payment si ya venció.

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.

| Etapa | Estado del pago | Qué ve el cliente | Webhook | Tu saldo |
|---|---|---|---|---|
| Transferencia vista en un bloque | `pending` | «Pago detectado. Esperando confirmación.» | `invoice.pending` o `deposit.pending` | Monto completo en `pending`; no se puede retirar |
| Umbral alcanzado | `paid` (o `underpaid` si falta monto) | «Pago confirmado.» | `invoice.paid` o `deposit.confirmed` | Monto menos la comisión de la plataforma en `available` |
| Se descartó una transferencia confirmada | Se recalcula: `paid`, `underpaid`, `pending` o `new` | La página se actualiza sola | `invoice.reverted` o `deposit.reverted` | Abono y comisión revertidos |

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](https://cryptolike.net/blog/crypto-payment-confirmations) y en la entrada del glosario sobre [confirmaciones](https://cryptolike.net/es/glossary/confirmations); los valores actuales están en `GET /v1/currencies` y en las [páginas de monedas](https://cryptolike.net/es/coins), por ejemplo [Bitcoin](https://cryptolike.net/es/coins/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.

| Situación | Estado | Libro contable | Webhook |
|---|---|---|---|
| Factura, transferencia aún por debajo del umbral | Vuelve a `new`, o sigue en `pending` si otra transferencia a la dirección sigue esperando | El monto sale de `pending` | Ninguno; el historial del pago en tu panel lo registra |
| Factura en `paid` o `underpaid`, se descartó una transferencia confirmada | Se recalcula con lo que sigue confirmado: `paid`, `underpaid`, `pending` o `new` | Se revierten la confirmación, la comisión y el abono | `invoice.reverted` con los nuevos `paid_amount` y `remaining_amount` |
| Dirección estática, cualquier etapa | En Transacciones, la transferencia aparece como «Revertida» | Se revierte todo lo que se había registrado | `deposit.reverted`; `confirmed_reversed: true` si el monto ya estaba disponible |
| La transferencia vuelve a entrar en la nueva rama | Factura abierta: `pending` y luego `paid` al alcanzar el umbral. Si el plazo de la factura termina antes, se cierra como `expired` y se queda así | Se acredita de nuevo | Factura abierta: `invoice.paid`; factura vencida: `invoice.late_payment`; dirección estática: `deposit.confirmed`. Cada uno con un `event_id` nuevo |
| El monto confirmado ya se retiró | El estado de la factura no cambia hasta la revisión | Sin reversión automática; tu saldo nunca queda en negativo | Ninguno; el equipo de CryptoLike revisa el caso |

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](https://cryptolike.net/blog/idempotency-in-payment-apis) 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](https://cryptolike.net/guides/verify-crypto-payment-webhooks).
- **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](https://cryptolike.net/es/blog/choose-crypto-payment-gateway).

## 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](https://cryptolike.net/es/guides/test-crypto-payments)— y ten a mano la lista de eventos de la [referencia de webhooks](https://cryptolike.net/docs/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.