Una notificación de pago válida no debería provocar dos entregas del mismo pedido. Los webhooks de pagos con criptomonedas necesitan dos protecciones distintas: verificar quién envió el evento y hacer que repetir su efecto comercial sea seguro. La firma responde a la primera cuestión. La idempotencia, a la segunda.
Esta guía está dirigida a desarrolladores que conectan compras digitales únicas, licencias o abonos en cuentas con Yolfi. Explica el formato nativo de los webhooks y un diseño de aplicación recomendado, no un servicio de entrega listo para usar. En las suscripciones, el acceso también depende del ciclo de vida de la suscripción; no reutilices la regla de un pedido único para todas las renovaciones.
Por qué un webhook auténtico también puede generar un duplicado
Un receptor puede guardar un evento correctamente y perderse su respuesta HTTP. El emisor vuelve a intentarlo. El proceso de trabajo también puede fallar después de conceder acceso, pero antes de registrar que terminó. Ninguna de estas situaciones implica un segundo pago del cliente.
La referencia de eventos webhook de Yolfi documenta la entrega al menos una vez y los reintentos independientes para varios puntos de conexión. Diseña el sistema para recibir de nuevo el mismo evento, incluso mientras la primera entrega sigue procesándose. No dependas de un calendario concreto de reintentos ni supongas que las notificaciones siempre llegan a tu aplicación en el orden en que se crearon.
Mantén separadas estas tres identidades:
| Identidad | Qué identifica | Control recomendado |
|---|---|---|
id del evento firmado |
Un evento del proveedor, incluidas sus entregas repetidas | Registro único del evento dentro del ámbito del proveedor, la organización y el entorno |
| Referencia de factura o pago | Un intento de pago | Relación guardada con el pedido comercial correspondiente |
| Referencia del pedido comercial | Lo que debe recibir el cliente | Acción de entrega única para ese pedido |
Eliminar eventos duplicados no basta: dos intentos satisfactorios de pago para un mismo pedido pueden tener distintos identificadores de evento. La protección a nivel de pedido evita conceder una segunda licencia o un segundo abono mientras el cobro adicional se revisa por separado.
Verifica la solicitud original antes de confiar en sus campos
Sigue las instrucciones actuales de Yolfi sobre firmas. Las solicitudes nativas utilizan X-Yolfi-Signature, un HMAC-SHA256 del cuerpo original de la solicitud, codificado en Base64 y calculado con el secreto de firma de ese punto de conexión. La clave API de la organización no es el secreto del webhook.
Captura el cuerpo original antes de que los componentes intermedios de JSON lo modifiquen. Calcula y compara la firma con una función de comparación en tiempo constante; rechaza las firmas ausentes o mal formadas sin ejecutar acciones comerciales. Guarda los secretos de firma en un gestor de secretos o en una configuración de entorno protegida, nunca en archivos de código fuente ni en registros de asistencia.
Solo después de verificar la firma debes analizar y validar el contenido. Utiliza el id del contenido firmado para eliminar duplicados. X-Yolfi-Event-ID es una copia de conveniencia, no un valor firmado por separado; si lo utilizas, exige que coincida con el identificador del contenido. Vincula el punto de conexión receptor a la organización esperada y valida orgId cuando esté presente. Los metadatos aportados por el usuario no deben determinar la autorización entre organizaciones cliente.
Una firma válida no convierte una entrega antigua en nueva. Sigue siendo necesario conservar los identificadores de los eventos procesados. La firma documentada de Yolfi no comprueba la vigencia mediante una marca de tiempo, por lo que no debes afirmar que la verificación HMAC por sí sola impide la repetición de solicitudes.
Guarda primero, confirma la recepción después y procesa de forma asíncrona
Utiliza una bandeja de entrada persistente: una tabla de la aplicación que registre un evento autenticado y su estado de procesamiento. Inserta el evento bajo una restricción de unicidad de la base de datos, no mediante una comprobación independiente de si ya existe seguida de una inserción sin protección. Dos solicitudes simultáneas pueden superar esa comprobación.
Devuelve 200 OK con rapidez tras aceptar el evento de forma persistente, también cuando un duplicado autenticado ya esté guardado. Si falla la persistencia, no confirmes que el evento se ha aceptado. Una respuesta rápida seguida de una tarea en memoria no es persistente: un reinicio puede hacer que se pierda la única copia que conservó tu aplicación.
Después, un proceso de trabajo puede cargar el evento guardado, validar su relación con el pedido y aplicar la transición comercial. Mantén visibles las tareas fallidas con un contador de reintentos, la siguiente acción y una persona responsable de las alertas. Conserva solo los datos necesarios del contenido en un almacenamiento de acceso restringido; los cuerpos de los eventos pueden contener información del cliente.
Condiciona la entrega a la confirmación y al pedido correcto
La guía de webhooks de Yolfi identifica payment.confirmed como el principal desencadenante de la entrega. invoice.created significa que se creó una factura, no que el cliente haya pagado. Una redirección del navegador o una captura de pantalla no sustituye una confirmación verificada en el servidor.
Relaciona el evento con un pedido guardado en el servidor. En el flujo nativo, los eventos independientes de API Checkout pueden incluir checkoutSessionId y merchantOrderId sin paylinkId. No rechaces una compra independiente válida solo porque falte un identificador de Paylink. Del mismo modo, un identificador de Paylink reutilizable no identifica por sí solo de forma única el pedido de un comprador.
Comprueba la organización, el entorno, el intento de pago y el contexto del importe comercial esperados antes de entregar. El campo amount documentado es el importe neto final que recibe el comercio en el token de pago; no equivale automáticamente al total de tu factura original en moneda local. No compares ambos números como si tuvieran las mismas unidades. Conserva el pedido original aprobado por el servidor y su contexto de precios.
Para compras dinámicas, utiliza el flujo de API Checkout para conservar la relación entre el pedido y la sesión. Para productos fijos, los enlaces de pago ofrecen un punto de entrada de pago reutilizable; tu aplicación sigue siendo responsable de decidir la entrega.
Protege el efecto, no solo la tabla de eventos
Para un pedido cuya entrega se resuelve íntegramente dentro de tu base de datos, registra el resultado del evento y la transición del pedido en una sola transacción. Impón una acción comercial única, como una sola concesión de derechos de acceso por pedido único. Un evento duplicado debe devolver el resultado existente, no conceder otro derecho.
Si la entrega requiere llamar a otro servicio, utiliza una bandeja de salida persistente: guarda la acción prevista junto con la transición del pedido y deja que un proceso de trabajo la envíe después. Asigna a la acción enviada al servicio de destino una clave de idempotencia estable basada en el pedido cuando el receptor la admita. La bandeja de salida por sí sola no impide un duplicado remoto si el proceso de trabajo falla después de que la acción remota se complete correctamente.
Cuando el destino no admita idempotencia ni consulta del resultado, deja el resultado incierto pendiente de conciliación en lugar de reintentar a ciegas una acción irreversible. «Exactamente una vez» no es una garantía que un webhook HTTP pueda ofrecer a través de cualquier combinación de bases de datos, colas y servicios externos.
Evita que los eventos antiguos hagan retroceder un pedido completado. Un evento invoice.overdue corresponde a un intento y no debe anular un pedido ya entregado. Para el acceso recurrente, el proveedor distingue los eventos de factura de subscription.overdue y subscription.cancelled; implementa por separado la política de suscripciones documentada.
Prueba los fallos antes de aceptar pedidos reales
Utiliza estos casos de aceptación para el receptor y el proceso de trabajo:
- Entrega el mismo evento firmado dos veces y de forma simultánea: un evento guardado, un efecto comercial.
- Interrumpe el proceso de trabajo antes y después de la transición del pedido: la recuperación no debe conceder acceso dos veces.
- Entrega dos intentos confirmados para un mismo pedido: entrega una sola vez y marca el cobro adicional para su revisión.
- Envía una firma no válida, una organización que no coincida y un pedido desconocido: ninguna entrega.
- Entrega un evento de factura anterior después de la confirmación: la entrega completada no debe revertirse.
- Envía un evento de modo de prueba al receptor de producción: ninguna licencia, envío ni abono en cuenta reales.
Los eventos de prueba del panel de Yolfi utilizan livemode: false y un identificador evt_test_. Permiten probar la entrega y el tratamiento del contenido, pero no crean registros de pago reales. Separa explícitamente los efectos de prueba de los reales; una notificación de prueba satisfactoria no demuestra que una compra se haya liquidado.
Supervisa los eventos autenticados pendientes de procesamiento, los fallos del proceso de trabajo y los pagos confirmados sin resultado de entrega. Relaciona estas excepciones con la lista de comprobación de conciliación de pagos. Si el segundo cobro es un pago adicional real y no un reintento, sigue el procedimiento de revisión de reembolsos en lugar de borrar las pruebas.
Preguntas frecuentes
¿Verificar la firma evita los abonos duplicados?
No. Verifica la autenticidad y la integridad. Un evento auténtico puede llegar más de una vez y una solicitud que antes era válida puede volver a enviarse. Guarda los identificadores de evento de forma persistente e impón una restricción comercial a nivel de pedido.
¿Debo responder con éxito antes de guardar el evento?
No. Confirma la recepción tras aceptar el evento de forma persistente y realiza después las tareas más lentas de forma asíncrona. De lo contrario, un fallo posterior a la respuesta puede hacer que el evento se pierda sin aviso.
¿Basta el hash de la transacción como clave para eliminar duplicados?
No para procesar webhooks. Utiliza el identificador de evento firmado documentado para las entregas de eventos y tu propia clave de pedido para la entrega de la compra. Las transferencias y los pedidos tienen identidades distintas; una transacción puede contener varias transferencias.
¿Puedo usar el mismo manejador para los contenidos de los adaptadores?
No sin comprobar su contrato. Este artículo describe el formato nativo con el adaptador NONE. Los adaptadores compatibles con proveedores pueden tener una estructura de contenido distinta; valida los campos documentados antes de reutilizar las reglas nativas de análisis y correlación.
Conclusión: confirma, guarda y entrega una sola vez
Una automatización fiable de pagos con criptomonedas separa la entrega autenticada del evento del efecto comercial sobre el pedido. Verifica la firma original, guarda el evento de forma persistente, relaciónalo con el pedido y haz que la entrega sea segura ante reintentos. Empieza con los enlaces de pago de Yolfi para productos fijos o con la sesión documentada creada en el servidor para pedidos dinámicos, y mantén en la aplicación la responsabilidad de conceder cada compra una sola vez.
