Distinguir aceptación de finalización
Un flujo de pago puede confirmar hechos distintos: que la aplicación aceptó una intención, el proveedor recibió una instrucción, el pago se autorizó, procesó o liquidó definitivamente. No deben fundirse en un solo estado de éxito. Antes de implementar defina el modelo para proveedor y producto reales. Para cada estado decida qué ve el cliente y qué puede hacer después el sistema operativo. Una respuesta HTTP no prueba por sí sola que el dinero se movió. Si la pantalla anuncia finalización demasiado pronto, un rechazo posterior crea un problema de soporte y confianza. Incluya estados retrasados y desconocidos en vez de disfrazarlos de fallo.
Asigne un identificador interno estable al pago y conserve el del proveedor. Sirven para relacionar mensajes, investigar manualmente y conciliar. Registre importe, moneda, comisiones si corresponden y reglas de redondeo. No permita que otro intento de la misma intención comercial cree en silencio una segunda transacción. Decidir si se trata de otra compra o un reintento corresponde al proceso, no solo al cliente HTTP. La aplicación debe poder decir qué sabe y qué desconoce todavía sin convertir incertidumbre automáticamente en fracaso. Facilite los identificadores a soporte autorizado sin exponer credenciales sensibles.
Un timeout crea un resultado desconocido
Imagine que la aplicación envía la instrucción y se corta la conexión justo antes de la respuesta. El proveedor pudo crear el pago sin que quien llamó lo sepa. Repetir automáticamente con otro ID puede crear una segunda operación. Distinga reintento seguro con la misma clave de idempotencia, consulta de estado e instrucción verdaderamente nueva. Stripe documenta solicitudes idempotentes para repetir ciertas operaciones con seguridad; verifique alcance y duración de la clave en el API concreto. No suponga que todo proveedor ofrece igual garantía. Tras un fallo determine qué hizo realmente la otra parte antes de volver a actuar.
Muestre la incertidumbre de forma comprensible. El cliente no necesita conocer el timeout técnico, pero sí que la confirmación está pendiente y que no debería pagar otra vez sin necesidad. El operador requiere ID interno, último paso confirmado y procedimiento seguro para comprobar. Restringir temporalmente otras acciones sobre el mismo caso puede impedir que el estado se complique. Fije cuándo empieza una investigación humana o consulta automática al proveedor. No deje desaparecer un caso pendiente porque la petición HTTP original no respondió. Explique al cliente cuándo recibirá más información.
La idempotencia debe sobrevivir a concurrencia y reinicio
Vincule la clave de repetición a la operación comercial y no a la marca de tiempo de la petición. El receptor debe conservar pruebas de haber procesado la instrucción en almacenamiento persistente. El patrón de consumidor idempotente de Microsoft trata entregas repetidas y copias concurrentes. Una consulta antes de insertar no basta si dos instancias pasan el control a la vez; se necesita escritura segura con restricción de unicidad. Defina alcance y conservación de claves. Si se reutilizan más tarde, una petición antigua repetida puede parecer nueva. El diseño debe corresponder al proveedor y a la duración de la intención comercial.
La idempotencia también hace falta dentro de su aplicación. Un webhook puede actualizar pedido, enviar correo y crear evento contable. Si cada parte usa un ID distinto y ninguna recuerda haber terminado, un mensaje repetido puede desencadenar efectos múltiples. Para cada consumidor decida qué solo debe ocurrir una vez y qué puede repetirse sin problema. En pruebas entregue el mismo mensaje dos veces a la vez y después de reiniciar. Debe producirse un único efecto comercial correcto y quedar rastro del duplicado reconocido. Compruebe el almacén de datos y no solo la respuesta API. Incluya fallos entre dos efectos secundarios.
Los webhooks obedecen a la realidad de la red
Un webhook no es continuación síncrona de la petición original. Puede llegar tarde, duplicado o desordenado. La documentación de webhooks de Stripe explica verificación y entrega; otros proveedores difieren. Verifique firma u otro mecanismo de origen y limite lo que puede modificar. Reciba el evento con seguridad y guarde su identificador antes de procesarlo. Si su endpoint responde con error después de un efecto, el proveedor puede reenviarlo. El diseño debe soportarlo sin crear otro pago ni otra confirmación al cliente. No confíe en una dirección de remitente visible como prueba de origen.
Una máquina de estados impide que un mensaje tardío sobrescriba un estado final más reciente. Conserve eventos originales y decida qué transición está permitida. Con algunos proveedores resulta más seguro consultar el estado actual del objeto tras la notificación que asumir que cada evento trae la imagen definitiva. Verifíquelo en su documentación. Lleve webhooks imposibles de procesar a una ruta controlada de reparación con motivo y opción de reintento. No los pierda en registros que se borrarán en días. Soporte necesita ver si esperan, fallaron o terminaron. Revise el tratamiento tras cambiar el esquema de eventos.
La conciliación arregla lo que el flujo normal no ve
Ni un webhook bien hecho garantiza que cada estado interno coincida con el proveedor. Compare periódicamente pagos internos con estados externos, identificadores, importes, moneda y periodo. Comparar solo ingresos totales no basta: dos transacciones equivocadas pueden compensarse en la suma. Defina tolerancia para estados pendientes y cuándo una diferencia pasa a excepción. Cada excepción necesita dueño, prioridad, última acción y ruta de reparación segura. Trate el resultado de conciliar como indicador del producto, no como archivo técnico privado. Incluya operaciones sin registro correspondiente en cualquiera de los lados.
Reparar puede significar consultar estado, asociar un evento perdido, devolver dinero o crear asiento contable inverso. Nunca borre historia hasta que no se pueda explicar el desacuerdo original. Antes de una acción importante confirme que el proveedor no la realizó ya. Exija segunda aprobación para correcciones sensibles según riesgo. El informe debe mostrar diferencias abiertas por antigüedad e importe sin revelar todos los datos a cualquier administrador. Mida tiempo de cierre y causas repetidas. Use esos hallazgos para mejorar la integración en vez de arreglar casos a mano indefinidamente.
Probar combinaciones desagradables, no solo cobros correctos
Antes de lanzar pruebe éxito, rechazo, timeout antes y después del envío, doble clic, petición repetida, dos webhooks simultáneos, confirmación perdida y fallo de base al registrar estado. Para cada caso especifique qué ve el cliente, qué dice su registro, qué afirma el proveedor y cómo se resuelve. Pruebe recuperación tras reiniciar. Si el sandbox no produce una condición, simúlela en la capa de integración y documente el límite. Un pago de prueba correcto no demuestra manejo de resultados desconocidos o avisos duplicados. Mantenga pruebas separadas de datos reales de clientes.
Examine límites: la misma clave con parámetros diferentes, caducidad, devolución tardía y webhook de objeto desconocido. Los mensajes de error deben llevar a una decisión segura. Si tras timeout el cliente ve un botón para pagar de nuevo sin explicación, la prueba encontró un problema del producto. Vaya más allá del código y pida a un operador resolver el caso con las instrucciones. Debe encontrar ID, comparar estados y elegir reparación sin adivinar. Añada los huecos a pruebas de regresión y documentación. Repita escenarios al cambiar proveedor, SDK o suscripción de eventos.
Fijar responsabilidades y límites antes de producción
Proveedor de pagos, aplicación y contabilidad pueden tener niveles de servicio y momentos de finalización distintos. Registre contactos, horarios, escalada y reglas para informar al cliente. Distinga fallo técnico de rechazo comercial. Decida de antemano cuándo detener una operación, cuándo retrasar confirmación y quién puede emitir una devolución. Los requisitos normativos cambian según producto y jurisdicción; compruébelos con un especialista. No prometa cero interrupciones ni ausencia absoluta de duplicados. Prometa controles medibles y utilizables. Asigne persona o revisión programada a cada estado pendiente.
EXCOIN puede diseñar e implementar un flujo concreto, pero su comportamiento depende de la documentación y contrato de la otra parte. Una primera fase debe entregar modelo de estados, contrato de datos, reglas de idempotencia, casos de fallo y conciliación. Tras un piloto mida estados desconocidos, entregas duplicadas, correcciones manuales y tiempo necesario para explicar un caso discutido. Un sistema que puede decir con seguridad que aún no sabe el resultado y luego averiguarlo puede valer más que una demostración impecable de un único pago correcto. Use las pruebas para decidir si el riesgo operativo es aceptable.