Pocos escenarios son tan peligrosos en pagos como un timeout.
Cuando una API devuelve un rechazo explícito, el sistema tiene una respuesta. Cuando devuelve éxito, también. En un timeout, sin embargo, la aplicación puede no saber si la operación falló antes de llegar al procesador, si se procesó y se perdió la respuesta o si sigue en curso en algún punto de la cadena.
Esta incertidumbre cambia por completo la estrategia de reintentos.
Tratar un timeout como «ha fallado» puede provocar un segundo cobro cuando el primero ya tuvo efecto. Tratarlo como «ha salido bien» puede liberar un producto sin pruebas suficientes. La vía segura es representar la incertidumbre como un estado propio y buscar pruebas antes de tomar una acción irreversible.
Guion operativo: ¿qué hacer cuando el PSP no responde?
Utiliza este guion como propuesta operativa, adaptada a los métodos y garantías documentados del proveedor. El objetivo es elegir la siguiente acción a partir de pruebas, sin convertir la ausencia de respuesta en un rechazo o una aprobación. Que termine la espera del checkout no pone fin a la investigación financiera.
Primero, clasifica la operación y la fase del fallo. ¿Era una creación de cobro, autorización, captura, consulta o reembolso? ¿El plazo terminó en el navegador, en tu servicio o en la comunicación con el PSP? Registra el endpoint y la operación lógica sin copiar credenciales ni datos sensibles al incidente. Una consulta sin respuesta y una captura sin respuesta exigen acciones diferentes.
Segundo, verifica las pruebas de transmisión y ejecución. Un fallo demostrado antes de cualquier envío, sin otra ejecución en cola o en curso, es distinto de perder la conexión después de transmitir el cuerpo. El registro local de timeout, un HTTP500 genérico o la interrupción del socket no demuestran ausencia de efectos. Si hay dudas sobre un proxy, una cola o un intento anterior, mantenlas explícitas.
Tercero, conserva el identificador de la intención comercial, el del intento, la ruta, la referencia externa disponible y la clave de idempotencia utilizada. No sustituyas el intento por un registro nuevo para limpiar el error de la pantalla. Esta relación permite reconocer una confirmación tardía y comprobar si otro proceso ya intentó la misma operación.
Cuarto, marca el intento como pendiente o indeterminado cuando no haya conclusión. Bloquea las acciones incompatibles con ese estado, incluido un segundo cobro o una entrega basada en un éxito no demostrado. Informa al soporte y al cliente de que la confirmación sigue en curso, con una vía para seguir la resolución.
Quinto, consulta el estado cuando la integración permita consultar o buscar por la referencia adecuada. Confirma que la respuesta pertenece al mismo intento, destinatario, importe, moneda y tipo de operación. Una búsqueda vacía aislada puede reflejar un retraso de visibilidad o una referencia incorrecta; trata la ausencia como conclusión solo cuando la semántica documentada y las demás pruebas lo respalden.
Sexto, correlaciona los webhooks autenticados con el intento y procesa la confirmación de forma idempotente. Conserva el evento y su efecto, distinguiendo la reentrega de una nueva operación. La documentación de tratamiento de webhooks de Adyen (se abre en una pestaña nueva ↗), consultada el 22/10/2026, ilustra la verificación y el tratamiento de duplicados. La guía de webhooks en pagos explica cómo integrar esta vía en la aplicación.
Séptimo, elige la rama de decisión. Resultado favorable confirmado: aplica el estado correspondiente e impide repetir esa operación; una autorización confirmada no significa captura ni liquidación. Resultado desfavorable confirmado: registra el motivo y evalúa si la política permite otro intento, porque un rechazo no es automáticamente recuperable. Fallo demostrado antes de la ejecución: puede programarse un intento si no hay otro en curso y se cumplen las demás condiciones. Resultado indeterminado: continúa la investigación y prohíbe otra ejecución financiera independiente mientras no se resuelva el riesgo de la anterior.
Repetir la misma operación bajo una garantía documentada de idempotencia es distinto de iniciar otro cobro. Comprueba alcance, validez, carga de datos y reglas de concurrencia antes de utilizar esta recuperación. La documentación de idempotencia de Adyen (se abre en una pestaña nueva ↗) muestra que la garantía tiene límites propios. Profundiza en idempotencia para evitar cobros duplicados; cambiar de PSP no traslada automáticamente esa garantía.
Octavo, escala los resultados contradictorios o inconclusos con un responsable, las pruebas disponibles, la siguiente comprobación y un plazo operativo definido para ese flujo. Contacta con el proveedor por el canal contratado cuando sea necesario. La antigüedad del incidente, por sí sola, no autoriza a marcar el intento como fallido. Si no se puede recuperar la referencia, registra esa limitación y la vía de conciliación disponible.
Noveno, concilia la conclusión con los movimientos posteriores y corrige solo lo que demuestren las pruebas. Si dos intentos tuvieron efecto, identifica ambos antes de cancelar una autorización o reembolsar conforme al ciclo aplicable. Cada acción correctiva también necesita identidad y confirmación; no conviertas la corrección en otra duplicidad.
Décimo, cierra el incidente con el rastro del resultado, la decisión tomada y la condición que permitió o bloqueó el reintento. Registra la causa de la pérdida de respuesta y prueba la recuperación en un entorno de pruebas. Al preparar picos, incorpora este escenario a las pruebas de pagos para Black Friday, sin depender de incidentes reales para descubrir el comportamiento.
Caso completamente ficticio: se aprueba una autorización de R$ 120, pero se pierde la respuesta. El pedido sigue esperando confirmación. Un webhook posterior, autenticado y correlacionado, confirma la autorización del mismo intento. La aplicación registra el resultado una vez y sigue la política de captura de ese flujo; no crea otra autorización. Si hubiera realizado failover a otro PSP durante la incertidumbre, podría terminar con dos autorizaciones para la misma compra, cada una con su propio seguimiento.
¿Qué es un timeout en una API de pagos?
Un timeout ocurre cuando un participante espera una respuesta durante un periodo determinado y ese plazo termina antes de recibir una conclusión utilizable.
Puede ocurrir entre tu backend y el PSP, entre el PSP y el adquirente, entre el adquirente y otro participante o incluso dentro de una capa intermedia de tu propia arquitectura.
Desde la aplicación, todos pueden parecer iguales: «no he recibido una respuesta a tiempo».
Desde el punto de vista financiero, los resultados pueden ser distintos.
¿Un timeout significa que se ha rechazado la transacción?
No.
Un rechazo es una decisión conocida. Un timeout es la ausencia de una respuesta suficiente dentro de la ventana esperada.
Una transacción puede haberse aprobado y aun así la aplicación sufrir un timeout si la respuesta se pierde a la vuelta.
Por eso, convertir automáticamente un timeout en declined es semánticamente incorrecto.
¿Un timeout significa que se ha aprobado la transacción?
Tampoco.
La ausencia de respuesta no demuestra el éxito.
El sistema debe conservar la incertidumbre hasta poder consultar el estado, recibir un webhook, encontrar la transacción mediante idempotencia o conciliar después el efecto.
¿Dónde puede producirse el timeout?
Puede ocurrir antes de que la solicitud salga del sistema, durante DNS, la conexión TCP, TLS, el envío del cuerpo, el procesamiento del proveedor o la espera de la respuesta.
También puede ocurrir después de que el proveedor haya ejecutado la operación, pero antes de que llegue la respuesta.
Cuanto más detalle de observabilidad tenga la aplicación, mejor podrá estimar dónde falló.
Aun así, los logs de red no siempre demuestran si hubo un efecto financiero.
¿Por qué es peligroso el reintento automático?
Porque una operación de pago puede no ser idempotente por naturaleza.
Si la primera autorización se procesó y envías una segunda solicitud como nueva intención, el emisor puede aprobar ambas.
El resultado es un cobro duplicado causado precisamente por el intento de recuperación.
Reintentar es seguro cuando el sistema sabe que repite la misma intención bajo una garantía de idempotencia o cuando ha confirmado que la primera no tuvo efecto.
¿Qué es un resultado desconocido?
Es un estado operativo que representa exactamente lo que sabe el sistema: la operación se inició, pero todavía no hay pruebas suficientes para clasificarla como éxito o fallo.
Puede resultar incómodo para producto, pero es mejor que una certeza falsa.
Permite bloquear acciones incompatibles, iniciar la conciliación y actualizar el pago después.
¿Debería todo sistema de pagos tener un estado unknown?
No tiene que utilizar esa palabra, pero sí representar la idea.
Puede ser «processing», «pending_confirmation», «uncertain» u otro nombre coherente con el dominio.
Lo importante es no reducirlo todo a succeeded y failed cuando la realidad distribuida tiene una tercera posibilidad.
¿Cómo ayuda la idempotencia?
Una clave de idempotencia identifica la intención de una operación repetible.
Si el cliente no recibió respuesta y vuelve a enviar la misma solicitud con la misma clave, un proveedor que implemente bien la idempotencia puede devolver el resultado de la primera ejecución en lugar de crear otro efecto.
Esto convierte el reintento de una nueva operación en una repetición de la misma intención.
¿Resuelve la idempotencia todos los timeouts?
No.
Reduce el riesgo de duplicidad, pero el sistema sigue necesitando entender el estado.
La clave puede tener un alcance, una ventana de retención y reglas específicas según el proveedor. Algunas API pueden ser idempotentes en ciertos endpoints y no en otros.
Además, una aplicación multi-PSP puede no conseguir reutilizar la misma garantía entre proveedores diferentes.
¿Puedo hacer failover a otro PSP después de un timeout?
Solo después de resolver o controlar la incertidumbre del intento anterior.
Enviar inmediatamente el mismo cobro a otro PSP puede producir dos autorizaciones.
Un failover seguro debe saber que el primer intento no tuvo efecto o disponer de un mecanismo para neutralizar el riesgo.
En algunos escenarios, es mejor esperar unos segundos a una consulta o un webhook que aumentar la probabilidad de duplicidad.
¿Cuánto debo esperar?
No existe una cifra universal.
La ventana depende del método, el proveedor, el SLA, el comportamiento observado y el impacto comercial.
La arquitectura puede tener un timeout corto para la experiencia del usuario y una ventana mayor para conciliar el resultado.
Por ejemplo, la API puede dejar de bloquear el checkout tras unos segundos, mientras el backend sigue investigando el intento.
¿El timeout del frontend es un timeout financiero?
No.
El navegador puede desistir antes que el backend. El balanceador puede tener una ventana distinta del servicio. El servicio puede tener un timeout menor o mayor que el cliente HTTP utilizado para hablar con el PSP.
Es habitual que existan varias capas de timeout.
Si no están coordinadas, el frontend puede mostrar un error mientras el backend sigue esperando y acaba confirmando el éxito.
¿Cómo diseñar timeouts por capas?
La capa externa debe conocer el comportamiento de las internas.
Si el frontend espera 10 segundos, pero el backend puede tardar 20, la experiencia debe saber gestionar el procesamiento asíncrono.
Si el backend espera 30 segundos y el gateway corta la conexión a los 15, la mitad de las respuestas nunca llegará al cliente.
Los timeouts deben diseñarse como un presupuesto de latencia, no elegirse por separado.
¿Qué es deadline propagation?
Consiste en propagar el tiempo restante de una operación a los servicios internos.
Si una solicitud solo dispone de tres segundos útiles antes de caducar, no tiene sentido que un servicio posterior inicie un trabajo de quince segundos cuyo resultado nadie recibirá directamente.
Sin embargo, en pagos, cancelar el trabajo no siempre cancela el efecto externo.
La aplicación debe diferenciar el plazo de su solicitud del ciclo de vida de la transacción financiera.
¿Cancelar la conexión cancela el cobro?
No necesariamente.
Cerrar una conexión HTTP no equivale a cancelar una autorización en el procesador.
El proveedor puede seguir procesando la solicitud después de que el cliente local haya desistido.
Este es uno de los motivos para tratar un timeout como incertidumbre.
¿Cómo consultar el estado después de un timeout?
Lo ideal es que la operación tenga un identificador estable creado antes de la llamada o una clave de idempotencia que permita localizar la intención.
La aplicación utiliza entonces un endpoint de consulta o una búsqueda por referencia para verificar el resultado.
Si el proveedor solo entrega el ID después de crear el objeto y la respuesta se perdió, la idempotencia cobra aún más valor.
¿Y si el PSP no ofrece una consulta adecuada?
El riesgo operativo aumenta.
La plataforma puede depender de un webhook, un informe posterior o la conciliación para descubrir el resultado.
En ese caso, la política de reintentos debe ser más conservadora.
La falta de observabilidad externa es una característica importante al elegir proveedor.
¿Resuelve el webhook el timeout?
Puede resolver la incertidumbre cuando llega el evento correspondiente.
Pero no hay garantía de que llegue inmediatamente.
El sistema debe correlacionar el webhook con el intento en estado desconocido y completar la transición de forma idempotente.
¿Qué ocurre si el webhook llega después de un segundo intento?
Ese es precisamente el escenario que puede crear una arquitectura sin control.
Quizá el segundo intento se aprobó por otra ruta. Después, el webhook del primero confirma el éxito.
Ahora hay dos efectos para una única intención comercial.
Por eso, cada intento necesita su propia entidad y el pago debe controlar cuántos efectos financieros son aceptables.
¿Hay que separar pago e intento?
Separarlos ayuda mucho.
El pago representa la intención comercial. El intento representa una ejecución concreta por una ruta determinada.
Un intento puede tener un resultado desconocido mientras el pago sigue esperando resolución.
Si se autoriza un nuevo intento, el sistema debe seguir vigilando el anterior hasta demostrar que no tuvo efecto o tomar medidas correctivas.
¿Qué es una retry storm?
Es una cascada de reintentos causada por un fallo temporal.
Si miles de transacciones sufren un timeout y todas se repiten inmediatamente, aumenta la carga sobre un proveedor ya degradado.
Esto puede prolongar el incidente y crear más timeouts.
Las esperas progresivas, el jitter, los límites de concurrencia y los circuit breakers ayudan a controlar ese comportamiento.
¿Funciona la espera exponencial en pagos?
Es útil para fallos técnicos recuperables, pero no debe aplicarse a ciegas a operaciones financieras.
Antes de repetir, hay que saber si la operación puede reintentarse con seguridad.
La espera progresiva controla la frecuencia. La idempotencia controla la duplicidad. El estado controla la validez de la operación.
Son problemas diferentes.
¿Qué es un circuit breaker?
Un circuit breaker interrumpe temporalmente las llamadas a una dependencia cuyos fallos superan un umbral determinado.
En pagos, puede impedir que el sistema siga enviando tráfico a un PSP degradado.
Pero abrir el circuito no resuelve los intentos ya en curso.
Estos siguen necesitando conciliación.
¿Debe el circuit breaker redirigirlo todo automáticamente?
No necesariamente.
Para nuevas intenciones, quizá convenga otra ruta.
Para intentos ya enviados cuyo resultado es incierto, cambiar de PSP puede duplicar los efectos.
El enrutamiento debe distinguir «nueva transacción» de «reintento de una operación potencialmente procesada».
¿Qué es una hedged request y por qué resulta peligrosa aquí?
Una hedged request envía solicitudes paralelas o casi paralelas para reducir la latencia de cola.
Esta técnica puede ser útil en operaciones de lectura idempotentes.
En pagos, enviar dos autorizaciones simultáneas a procesadores distintos es extremadamente arriesgado.
Una latencia baja no compensa un efecto financiero duplicado.
¿Cómo clasificar los tipos de timeout?
El equipo puede distinguir timeouts de conexión, lectura, upstream, cola, aplicación y dependencia externa.
Esta taxonomía ayuda a la observabilidad.
Pero, para decidir financieramente, la clasificación más importante es si hay pruebas de que la solicitud pudo llegar al procesador.
¿Cómo ayudan los logs?
Los logs con correlation ID, attempt ID, clave de idempotencia, marcas de tiempo, ruta y fases de la llamada permiten reconstruir el evento.
También conviene registrar si se estableció el socket, cuándo se envió el cuerpo y cuánto tardó cada etapa, cuando la pila técnica ofrece ese detalle.
Pero los logs no deben utilizarse para afirmar un resultado financiero que solo conoce el proveedor.
¿Qué medir?
La tasa de timeout por PSP, endpoint, método, país, versión de integración y ventana temporal.
También conviene medir cuántos timeouts terminan después como éxito, fallo o siguen sin conclusión.
Esa distribución muestra el riesgo real de clasificar incorrectamente un timeout.
¿Por qué importan los percentiles de latencia?
La media oculta la cola.
Un PSP puede responder en 400 ms la mayoría de las veces y tardar 12 segundos en una pequeña proporción crítica.
P95, p99 y la distribución ayudan a elegir timeouts que no corten un número excesivo de transacciones legítimas.
¿Puede mi aplicación causar el timeout?
Sí.
Un pool de conexiones agotado, un hilo bloqueado, un bucle de eventos congestionado, DNS lento, CPU alta, una cola interna o la base de datos pueden consumir el presupuesto antes de la llamada externa.
Culpar al PSP sin descomponer la latencia es un error habitual.
¿Cómo separar un problema interno de uno externo?
Utiliza trazas y métricas por etapa.
¿Cuánto tiempo estuvo la solicitud en cola? ¿Cuánto tardó en obtener una conexión? ¿Cuánto tiempo pasó en el PSP? ¿El servicio respondió y la capa superior perdió la respuesta?
La observabilidad distribuida reduce el espacio de suposición.
¿Qué hacer en el checkout mientras el resultado es desconocido?
Evita decir «pago rechazado» si no se sabe.
La interfaz puede informar de que se está confirmando el pago e impedir que el usuario pulse repetidamente.
También puede ofrecer una actualización automática o una página de seguimiento.
El mensaje debe reflejar la verdad operativa.
¿Debo mostrar un botón «volver a intentar»?
Solo cuando la política sepa que un nuevo intento es seguro.
En estado desconocido, el botón puede ser precisamente el mecanismo que cree la duplicidad.
Es mejor esperar la resolución o indicar al usuario que no lo repita todavía.
¿Cómo debe ver el soporte un timeout?
El panel debería mostrar que el intento está en investigación, con identificadores y las pruebas más recientes.
Si el agente solo ve «error», puede indicar al cliente que vuelva a pagar.
La herramienta de soporte debe reflejar la misma máquina de estados que el backend.
¿Cómo gestionar un timeout en captura?
La captura es una operación financiera sobre una autorización existente.
Si se pierde la respuesta, repetir sin idempotencia puede producir un comportamiento inesperado según el proveedor.
El sistema debe consultar el estado del cobro o de la captura antes de decidir.
¿Y en un reembolso?
Es aún más crítico.
Una devolución repetida puede devolver dos veces un importe cuando el modelo admite varias operaciones.
Cada intención de refund debe tener identidad propia y conciliarse antes de crear otra.
¿Un timeout en Pix es igual que en tarjeta?
El principio de incertidumbre es el mismo, pero el ciclo de vida es diferente.
Crear una solicitud Pix, consultar un Pix e iniciar una devolución tienen semánticas distintas.
La aplicación debe utilizar los identificadores propios del método y no forzar el modelo de autorización de tarjeta.
¿Cómo funciona la idempotencia en multi-PSP?
Cada PSP puede tener su propia clave y su propio alcance.
La plataforma debe mantener una clave interna de intención y derivar o mapear las claves externas por intento.
Si un intento cambia de PSP, normalmente es un nuevo intento, no una repetición idempotente del anterior.
Esta distinción es esencial.
¿Cuándo puedo crear un nuevo intento?
Cuando la política de estados concluya que está permitido.
Puede ocurrir después de un rechazo explícito recuperable, un fallo conocido antes del envío o la resolución de un intento incierto sin efectos.
También puede haber una decisión de negocio que acepte riesgo residual en casos concretos, pero debe ser consciente y medible.
¿Cómo conciliar los timeouts al final del día?
Mantén una cola de intentos que terminaron sin un resultado concluyente.
Consulta a los proveedores, compara informes y revisa los webhooks tardíos.
Cada elemento debe terminar en un estado conocido o seguir escalado como discrepancia.
Dejar que los resultados desconocidos se acumulen indefinidamente es ocultar riesgo financiero.
¿Qué hacer cuando el timeout se convierte en un cobro duplicado?
Primero, identifica qué intentos produjeron efecto.
Después, aplica la política de corrección adecuada, normalmente cancelando la autorización todavía abierta o reembolsando cuando sea necesario.
El caso también debe alimentar mejoras en la regla de reintentos que permitió la duplicidad.
Un incidente financiero debe generar aprendizaje para la plataforma.
¿Cómo probar este escenario?
Hay que simular una respuesta lenta, la pérdida de conexión después del envío, un webhook tardío y una consulta cuyo estado cambia.
Probar solo HTTP 500 no cubre el problema.
Las pruebas de caos controladas en entornos de pruebas ayudan a validar que la aplicación conserva la idempotencia y el estado.
¿Cuál es la diferencia entre timeout, rechazo y error técnico conocido?
El rechazo es una decisión negativa explícita.
Un error técnico conocido indica un fallo identificado en un punto que puede ser seguro o no para reintentar.
El timeout indica que la ventana de espera terminó sin una conclusión suficiente.
Estas categorías pueden solaparse técnicamente, pero no deberían producir automáticamente la misma acción.
El timeout es un problema de estado, no solo de red
El error más peligroso es pensar que un timeout se resuelve aumentando los segundos del cliente HTTP.
La causa puede ser la red, pero el reto financiero es saber qué ocurrió cuando la respuesta dejó de ser fiable.
Una arquitectura robusta conserva la identidad del intento, utiliza idempotencia, consulta al proveedor, procesa webhooks, concilia resultados y solo permite una nueva operación cuando el estado la hace segura.
En pagos, admitir «todavía no lo sé» durante unos segundos es mejor que crear dos cobros intentando parecer disponible.