El cliente paga una vez, pero tu tienda recibe dos avisos. La primera notificación confirma la compra; la segunda vuelve a descontar inventario y manda otro mensaje de preparación. Para el comprador hubo un solo pago. Para la operación, una repetición técnica se convirtió en trabajo duplicado.
Un aviso de pago repetido debe poder reconocerse sin volver a ejecutar la misma acción comercial. Para lograrlo, separá el identificador del evento, el del pago y el del pedido; validá el origen y los datos, registrá el resultado de forma duradera y controlá la concurrencia. Dos pagos reales, en cambio, necesitan conciliación: no se descartan como si fueran el mismo aviso.
Esta guía incluye una secuencia simulada y una lista de comprobaciones para conversar con tu equipo técnico. Los nombres de campos y eventos del ejemplo son didácticos: deben adaptarse al contrato y los estados de tu proveedor de pagos.
Un webhook es un aviso, no una nueva compra
Un webhook permite que un sistema le avise a otro que ocurrió algo. En pagos, puede informar un cambio de estado y disparar una revisión de la compra relacionada. Que el aviso llegue por segunda vez no significa que el cliente haya comprado otra unidad.
La documentación de recepción de eventos de Stripe contempla entregas repetidas y eventos fuera de orden, además de la verificación del origen. Es una referencia técnica pública: el contrato que debés implementar es el de tu pasarela concreta, con sus identificadores, firma o mecanismo de autenticación y reglas de reintento.
Para el negocio, la pregunta útil es esta: «Si recibimos este aviso otra vez, ¿qué puede volver a pasar?». Revisá inventario, mensajes, preparación, comprobantes y cualquier conexión que opere después del pago. Un pedido puede conservarse una sola vez y, aun así, producir dos solicitudes de despacho.
Revisá qué puede repetirse después del pago. Descargá la secuencia Excel de ocho avisos simulados y pruebas propuestas o el registro de la secuencia en CSV. No realiza cobros ni instala una integración. Incluye dos pagos distintos y una sola tarea local de preparación.
Los tres identificadores que conviene distinguir
El identificador del evento reconoce un aviso emitido por el proveedor. El del pago identifica la transacción financiera. El del pedido identifica la compra dentro del negocio. Puede haber varios eventos para un pago y varios intentos de pago para un mismo pedido.
| Referencia del ejemplo | Qué identifica | Para qué sirve la revisión |
|---|---|---|
| EVT-02 | Un evento del proveedor | Reconocer la entrega repetida del mismo aviso |
| PAY-A | Un pago | Reconocer eventos diferentes sobre una misma transacción |
| PED-901 | Un pedido ya existente | Evitar repetir la misma transición o preparación de esa compra |
En una operación con varias cuentas o proveedores, el identificador debe guardarse junto a su contexto. No supongás que una cadena es única en todos los servicios. El diseño puede utilizar proveedor, cuenta e identificador para definir cada referencia inequívoca.
El pedido del ejemplo ya existe antes de recibir el pago. La confirmación lo relaciona con una transacción y cambia su estado según la regla definida. Crear un pedido nuevo cada vez que llega un aviso pierde esa relación desde el inicio.
Una secuencia ficticia de ocho avisos
El ejercicio parte de PED-901, por ₡12.900, todavía pendiente. Los importes y referencias son ficticios; no se realizan cobros. La columna de autenticación es una condición de la simulación, no un mecanismo de firma listo para producción.
| Paso | Aviso simulado | Resultado que esperamos |
|---|---|---|
| 1 | EVT-01: PAY-A pendiente | Registrar el estado conocido sin preparar el pedido |
| 2 | EVT-02: PAY-A confirmado por ₡12.900 | Registrar el pago y crear una sola solicitud local de preparación |
| 3 | EVT-02 vuelve a llegar | Reconocer el evento ya tratado; no repetir la acción |
| 4 | EVT-03 confirma el mismo PAY-A | Conservar un solo pago y una sola preparación del pedido |
| 5 | Llega tarde otro estado pendiente de PAY-A | No regresar automáticamente el pedido a pendiente |
| 6 | EVT-05 carece de autenticación válida | Rechazarlo sin modificar el pedido ni registrar un pago válido |
| 7 | EVT-06 informa un importe distinto del esperado | Retener el caso para revisión, sin otra preparación |
| 8 | EVT-07 confirma otro pago, PAY-B, por ₡12.900 | Registrar la segunda transacción y señalar conciliación; no preparar dos veces |
Después del último paso hay dos pagos confirmados distintos en el ejercicio y una sola solicitud local de preparación. Ese resultado es intencional: ocultar PAY-B como un duplicado técnico borraría evidencia de un posible pago adicional.
No se propone devolver dinero automáticamente. El responsable debe comprobar las transacciones reales, el pedido y las reglas de su proveedor antes de decidir cómo resolverlas. La simulación únicamente muestra que dos hechos financieros diferentes no deben confundirse.
Cada acción necesita una referencia estable. KMSOFT puede evaluar el recorrido entre aviso, comprobación y operación comercial. Revisar mi integración de pagos.
Validá antes de cambiar el estado comercial
El equipo técnico debe comprobar el origen mediante el mecanismo documentado por la pasarela. Un dato que diga «pagado» dentro de una petición recibida no autentica por sí mismo a quien la envió. Tampoco una captura que comparte el cliente equivale a un evento verificado del proveedor.
Después comprobá a qué cuenta, pedido, transacción, importe y moneda corresponde. Si el aviso no contiene toda la información necesaria, definí cómo consultar la fuente autorizada antes de continuar. No rellenés los campos que falten con valores tomados de la conversación.
En el ejemplo, un importe inesperado termina en revisión. En una integración real puede haber pagos parciales u otras reglas comerciales; deben estar diseñadas expresamente. Comparar todo aviso con el total completo sin conocer ese contrato también puede dar una respuesta equivocada.
La validación y el registro necesitan un orden claro. Un evento que todavía no fue aceptado no debe quedar marcado como una operación comercial completada. Si se produce un error temporal, el sistema debe poder retomarlo de forma controlada.
Por qué «buscar y después insertar» puede fallar
Dos trabajadores pueden recibir avisos al mismo tiempo. Ambos consultan «¿ya procesamos este pago?» y obtienen que no. Si después insertan sin una restricción que lo impida, los dos pueden ejecutar la acción.
El control necesita una regla duradera de unicidad y una transacción que agrupe los cambios locales que deben ocurrir juntos. Guardar identificadores únicamente en la memoria del proceso deja de servir cuando el servicio reinicia o hay más de una instancia.
Además, conviene distinguir «recibido», «en proceso», «aplicado» y «requiere revisión». Marcar «procesado» antes de terminar puede hacer que un reintento legítimo se salte una operación que falló. No marcar nada puede repetir una operación que sí terminó.
La simulación privada de esta guía usa almacenamiento SQLite y comprueba repeticiones, eventos distintos para el mismo pago y dos transacciones para un pedido. Es una demostración del resultado local esperado; no valida tu infraestructura, el contrato de una pasarela ni la ejecución de servicios externos.
La segunda protección está en la acción comercial
Bloquear el mismo identificador de evento es necesario, pero puede resultar insuficiente. El proveedor puede emitir dos eventos diferentes sobre el mismo pago. Por eso, la acción «preparar PED-901» también necesita una referencia que evite crear el mismo trabajo local dos veces.
En la guía de cumplimiento de pedidos de Stripe se contempla que la función de cumplimiento pueda invocarse repetida o simultáneamente y que deba comprobar el estado existente. Es una distinción útil entre recibir eventos y ejecutar la consecuencia comercial.
Si un mensaje, una factura o una solicitud de transporte se envía a otro servicio, ya no basta con una transacción en tu base local. Definí una cola de tareas duradera y una referencia estable, y comprobá si el destino permite operaciones idempotentes o consultar el resultado de una solicitud anterior.
La plantilla pide revisar esos destinos por separado. Una única tarea en la cola no demuestra, por sí sola, una única entrega externa: un corte de red después de que el destino recibe la solicitud puede dejar el resultado incierto. Ese caso necesita recuperación y conciliación según el servicio.
Avisos atrasados y estados que no deben retroceder
La hora de llegada no siempre coincide con el orden de los hechos. Un aviso pendiente recibido después de una confirmación no debería hacer que el negocio ignore un pago que ya comprobó.
Escribí cuáles transiciones admitís y cuál es la fuente del estado actual. El ejemplo no revierte un confirmado por un pendiente tardío. Reembolsos, contracargos o anulaciones son hechos diferentes: requieren sus propias reglas, no una instrucción general de ignorar todo lo que llegue después.
Cuando haya dudas, conservá evidencia y llevá el caso a una revisión identificable. El operador debe poder explicar qué se conoce, qué dato falta y quién lo va a resolver. Un estado «revisar» sin responsable termina convirtiéndose en otra bandeja abandonada.
Qué pedir en una prueba de aceptación
La hoja descargable incluye la secuencia y una lista de pruebas propuestas. Pedí al equipo que repita el mismo evento, cambie el identificador manteniendo el mismo pago, simule dos entregas simultáneas y reinicie el proceso antes de volver a recibir un aviso.
También comprobá el caso de dos pagos reales para el mismo pedido. El criterio es conservar las dos transacciones financieras y evitar la duplicación de la acción comercial. Agregá la prueba de importe o moneda inesperados y la de una notificación sin autenticación válida.
La evidencia debe mostrar estados y referencias sin exponer claves, firmas secretas o datos completos de tarjetas. Usá el entorno de pruebas de tu proveedor y medios de prueba autorizados; no generes cobros reales para demostrar un reintento.
Si necesitás revisar el recorrido previo, consultá nuestra guía de cobros en línea en Costa Rica y la de WhatsApp, tienda y mostrador. Un pago tiene que continuar la compra que ya existe, con sus mismas referencias.
Revisemos qué ocurre después de un pago
KMSOFT es Tech Provider de Meta y desarrolla automatizaciones oficiales de atención y ventas. Podemos evaluar cómo se relacionan la conversación, el pedido, la comprobación de pago y las tareas posteriores, según los servicios que realmente utiliza tu negocio.
Para revisar la integración, escribinos por WhatsApp. Empezamos con un mapa de eventos, referencias y acciones. El alcance técnico se valida con la documentación y los controles de cada proveedor.
Preguntas frecuentes
¿Dos avisos significan que el cliente pagó dos veces?
No necesariamente. Compará el evento y la transacción: puede ser una entrega repetida del mismo aviso, otro evento del mismo pago o dos pagos realmente distintos.
¿Guardar el identificador del evento evita cualquier duplicación?
No por sí solo. También deben revisarse la identidad del pago, la concurrencia y la unicidad de la acción comercial, además de las tareas enviadas a servicios externos.
¿Un segundo pago real debe ignorarse como duplicado?
No. Conservá la transacción y enviá el caso a conciliación. Evitá preparar el mismo pedido dos veces y comprobá los pagos antes de decidir cómo resolverlos.
¿La hoja instala protección en mi tienda?
No. Documenta una secuencia ficticia y pruebas de aceptación. La implementación requiere validar el contrato de la pasarela, el almacenamiento y los servicios conectados.
