Comienza por una intención de compra: alguien quiere adquirir un producto a un precio. El comercio crea un pedido, luego BTCPay emite una invoice. El cliente ve un checkout y su wallet intenta ejecutar un pago. El sistema de cobros observa su estado y, cuando se cumplen las condiciones, el comercio ejecuta la entrega. Finalmente quedan una conciliación y un justificante.

Una invoice no equivale a un pago. Una TXID publicada no es liquidación de Lightning. Un webhook no es una verificación criptográfica independiente del pago. Y que el pedido figure como entregado no demuestra que el receptor tenga control de sus claves.

El objetivo es poder recorrer esos objetos sin «saltos de fe». A cada uno le asignaremos identificador, fuente de información, estado y decisión. En un sistema real conviene además separar responsabilidades: cliente, cajero, servidor de cobros y responsable del comercio.

Prepara una hoja con tres pedidos ficticios: R-001 (12 EUR, Lightning), R-002 (45 EUR, on-chain) y R-003 (18 EUR, un pago tardío con dos invoices). No calcules sats a partir de la cotización del día: cada factura real tiene sus importes y su ventana de cotización.

Para cada pedido escribe: orderId, invoiceId, importe cotizado, método, estado base, excepción, evidencia consultada, entrega sí/no y seguimiento. Si utilizas una tienda de pruebas, no incluyas nombres, direcciones postales o API keys en el informe.

Si no tienes BTCPay, inventa las respuestas que se indican en el ejercicio. No generes una transacción real para completar una columna: aquí se evalúa la calidad de la decisión, no la capacidad de mover fondos.

1. PASO 1 · Pedido: crea un identificador comercial único y comprueba producto, importe, moneda y responsable. El orderId no es la TXID.
2. PASO 2 · Invoice: relaciona el pedido con una factura concreta (metadato orderId) y registra la fecha de caducidad. Distingue precio de referencia y sats solicitados por la invoice.
3. PASO 3 · Checkout: revisa los métodos ofrecidos y que la dirección o invoice Lightning pertenezca a la tienda. Una captura del QR no confirma cobro.
4. PASO 4 · Pago: identifica qué puede mostrar el emisor y qué debe comprobar el receptor. On-chain requiere revisar transacción y confirmaciones; Lightning requiere revisar liquidación del pago y de la invoice.
5. PASO 5 · Estado: consulta status y additionalStatus en BTCPay. Un webhook firmado es un aviso válido de que algo cambió, pero una captura o un correo no lo son; antes de entregar, comprueba el estado actual de la factura.
6. PASO 6 · Entrega: aplica la política comercial según importe y método. Anota que la entrega ya se ejecutó para impedir duplicados.
7. PASO 7 · Conciliación: comprueba que una invoice se relaciona con el pedido correcto, incluyendo posibles pagos tardíos, parciales o múltiples.
8. PASO 8 · Continuidad: si el checkout se cae, identifica qué componente de acceso, datos, nodo o proveedor debe recuperarse y quién está autorizado a hacerlo.

Cada puerta debe poder responder «qué ocurrió», «cómo lo sé» y «qué puedo hacer ahora». No sustituyas las tres por un único símbolo verde.

El cliente de R-001 abre el checkout y recibe una invoice Lightning por el valor que BTCPay ha cotizado para 12 EUR. La simulación indica que el emisor la pagó y que BTCPay informa Settled, sin excepción. El pedido todavía figura pendiente de entrega.

Pregunta: ¿qué datos debes comprobar? Coincidencia de invoice y orderId, importe, estado de liquidación y ausencia de entrega previa. No necesitas buscar una TXID on-chain para el pago Lightning de canal. Una vez verificadas las condiciones, puedes marcar el pedido como entregado una sola vez.

Variante: llega un segundo webhook para la misma invoice. No entregas un segundo producto: el sistema registra el evento si hace falta, pero la transición del pedido a «entregado» ya estaba realizada. Revisa la autenticación e idempotencia de webhooks BTCPay.

Para R-002, el cliente enseña una TXID y el checkout muestra un pago detectado con estado Processing. El producto es un artículo físico de valor relevante para el comercio. La simulación dice que la tienda exige confirmaciones y todavía no se alcanzaron.

Pregunta: ¿darías por pagado el pedido? Puedes afirmar que existe evidencia de un pago detectado, pero todavía no se cumple la condición acordada para entregar. Apunta TXID, fecha, importe de la salida receptora y estado de la invoice. Evita suponer que una transacción que alguien retransmite por un explorador tiene asegurada su confirmación: mientras no confirme, puede ser sustituida.

Si el tiempo pasa, no emitas una segunda factura independiente como si la primera transacción no existiera. El cliente puede subir la comisión con RBF si su wallet lo permite, y el comercio puede acelerar desde su lado con CPFP si controla la salida recibida. Antes de decidir, sigue el diagnóstico de transacciones pendientes.

El comprador de R-003 abrió una invoice A de 18 EUR y dejó que expirara. Después la web generó una invoice B para el mismo pedido. En la simulación, la primera recibe un pago tardío y la segunda sigue abierta. El cliente solicita completar la compra.

Pregunta: ¿qué haces? Relaciona ambas invoices con el mismo orderId y determina si realmente hay fondos recibidos. Busca la excepción PaidLate en la invoice original. No ignores la primera factura, no cobres automáticamente una segunda vez y no entregues dos productos.

Podría corresponder regularizar el pedido, solicitar una diferencia si faltara importe o acordar una devolución. Si devuelves, hazlo desde la factura con el reembolso de BTCPay: el cliente aporta su dirección en un enlace de reclamación, en lugar de reutilizar la dirección de origen. La elección depende de la política, los importes y la voluntad del cliente, no de que la página anterior muestre «Expirado».

El criterio de éxito es explicar cada decisión con evidencias de un sistema apropiado. Un procedimiento que entrega correctamente en el caso fácil, pero duplica pedidos en el caso tardío, no está terminado.

Si todo el circuito se puede explicar, es el momento de decidir qué partes conviene automatizar. Un flujo de n8n podría recibir una señal de webhook, verificar su firma, obtener el estado real de la invoice con una clave limitada a lectura y registrar una decisión. La entrega o el reembolso exige además un mecanismo de autorización apropiado y una actualización idempotente.

Una automatización no debería almacenar seeds, generar pagos de devolución por error ni ampliar permisos solo para eliminar clics. Puede quedar en revisión humana cuando haya pago parcial, tardío o contradicción entre sistemas.

Para aplicar el aprendizaje a una tienda real, consulta la política de cobros, confirmaciones y devoluciones. No des por completo un proceso hasta haber ensayado también cómo avisa, cómo se detiene y cómo vuelve a funcionar ante un error.

Para repetir este reto por componentes, consulta la preparación del POS, la conciliación de pedidos y la matriz de incidencias. Para la infraestructura, añade la vigilancia del servicio y la recuperación tras una avería.

En una wallet, comprobar puede consistir en verificar una dirección en la pantalla del dispositivo. En un nodo, implica contrastar bloques con las reglas de Bitcoin. En un comercio, también debes comprobar la relación entre factura, pago, pedido y decisión. Son preguntas diferentes, pero todas exigen evidencias.

El objetivo de este reto no es añadir barreras innecesarias al comprador. Es que una operación sencilla pueda seguir siendo sencilla sin esconder sus dependencias. Cuando algo falla, sabrás dónde mirar antes de repetir un pago o entregar un producto.

Si puedes explicar los tres casos ficticios y tu respuesta cambia de forma coherente cuando cambian las evidencias, has superado la parte esencial del ejercicio. La siguiente mejora es repetirlo en tu propia arquitectura con un laboratorio delimitado y un procedimiento de recuperación probado.

1. Pedido: tengo referencias comerciales que no son claves de wallet.
2. Cobro: distingo solicitud, pago y liquidación según el método.
3. Excepciones: puedo tratar un pago pendiente o tardío sin duplicar acciones.
4. Seguridad: mis verificaciones no requieren exponer seeds ni APIs administrativas.
5. Continuidad: sé qué fallaría si se pierde el checkout y cómo documentarlo.

• BTCPay Server — estados de factura y excepciones ↗
• BTCPay Server — integración y conciliación comercial ↗
• BTCPay Server — reembolsos ↗