Describa primero todo el ciclo del pago
La palabra «pagado» puede significar cosas distintas según el producto y proveedor. Una solicitud puede estar creada, autorizada, confirmada, en proceso, liquidada, reembolsada o en disputa. No son simples colores de interfaz: afectan a la entrega, contabilidad, soporte y comunicación con el cliente. Antes de diseñar se define qué estado permite cada acción comercial y qué sistema lo confirma.
El mapa incluye al cliente, aplicación interna, proveedor de pagos, quizá un banco y el proceso de disputas. Recoge identificadores, tiempos, monedas, importes, razones de cambio y responsable de la reparación. En cada límite se pregunta qué ocurre si la otra parte no responde. Un sistema que funciona solo con éxito inmediato no ha resuelto el flujo de pagos aunque todas las pantallas parezcan acabadas.
Resultado desconocido no significa rechazo
Después de un timeout la aplicación quizá ignore si el proveedor completó la operación. Reintentar sin contexto puede crear un pago duplicado; marcar fracaso puede pedir al cliente que pague otra vez sin necesidad. Se utiliza un identificador comercial estable, un estado pendiente de verificación y una forma de conocer el resultado real. El mensaje al cliente debe reflejar el grado de certeza disponible.
Una solicitud idempotente facilita repetir llamadas técnicas con seguridad. Su comportamiento preciso depende de la API, del periodo de conservación de la clave y de los parámetros. La documentación de Stripe, por ejemplo, describe idempotency keys y diferencias entre versiones de su API. No se puede asumir el mismo comportamiento con todos los proveedores. Antes de implementar se verifica cómo reconocen repeticiones, qué devuelven tras errores y cómo manejan solicitudes simultáneas.
Eventos y webhooks como cambios de estado
Un evento asíncrono puede confirmar el resultado cuando el cliente ya volvió de la página del proveedor. El webhook se convierte así en una entrada importante del proceso. Hay que verificar su origen, procesarlo con seguridad más de una vez y separar la recepción del trabajo posterior. Un proveedor puede no entregar eventos en el orden esperado. El estado no debería basarse solo en el último mensaje recibido sin valorar su significado.
La documentación oficial de Stripe describe webhooks firmados y la necesidad de conservar el cuerpo original para verificar la firma. Otro proveedor puede usar otro mecanismo. Un buen diseño guarda el identificador del evento, el motivo de rechazo de mensajes inválidos y una ruta segura para repetir el procesamiento. El trabajo pesado puede ejecutarse después de confirmar rápido la recepción si su finalización duradera es observable. Una respuesta HTTP 200 no demuestra por sí sola que la contabilidad coincida.
Conciliación y reparación
Los registros internos y del proveedor pueden discrepar temporalmente. La causa puede ser un evento retrasado, intervención manual, mensaje perdido, reembolso o cambio en otro sistema. Se necesita conciliación regular por identificador, importe, moneda y estado previsto. Su resultado no debe ser solo una cifra en un panel: debe crear un caso resoluble con responsable y pruebas. Una corrección manual conserva la historia original.
No es seguro sobrescribir un sistema desde otro sin reglas de autoridad para cada dato. Una fuente puede ser decisiva para autorización, otra para liquidación y otra para la factura. Estas reglas se fijan durante el diseño y se prueban con ejemplos que incluyan reembolsos parciales. La primera versión operativa debe poder detectar y resolver discrepancias, no confiar en que jamás existirán.
Protección de datos y alcance de responsabilidades
Los datos de pago son sensibles y conviene reducir su circulación. No es lo mismo una aplicación que almacena datos de tarjeta que otra que envía al cliente a una página de pago alojada. Sin embargo, el alcance real de responsabilidad sigue toda la arquitectura y los contratos, no una pantalla. El PCI Security Standards Council describe PCI DSS como base de protección para entidades que almacenan, procesan o transmiten datos pertinentes o pueden afectar a ese entorno.
Partes cualificadas deben evaluar obligaciones concretas del producto y proveedor. Una decisión técnica puede reducir datos sensibles tratados, pero no demuestra por sí sola conformidad. Secretos de API y webhooks quedan fuera del código, con acceso limitado y plan de rotación. Registros, analítica y errores no deberían recoger datos personales o de pago sin necesidad. Permisos para reembolsos o cambios de configuración se separan de la lectura ordinaria de estados.
Pruebas que protegen el flujo real
Un pago exitoso en pruebas es solo el comienzo. Los escenarios incluyen timeout después de enviar, clic repetido, webhook duplicado, eventos desordenados, rechazo, cancelación, reembolso, resultado desconocido y caída de la base de datos propia. Para cada uno se comprueba el mensaje al cliente, estado interno, vínculo contable y procedimiento de reparación. Las pruebas usan datos simulados; secretos de producción y datos reales de pago no pertenecen a ejemplos de desarrollo.
Además de pruebas automáticas, realice un ejercicio operativo: detenga el procesamiento de eventos, deje mensajes en espera y observe si se recuperan con seguridad. Mida pagos sin resolver, antigüedad del evento más viejo, diferencias de conciliación y tiempo para resolver excepciones. Una alarma necesita responsable y procedimiento. Si el sistema informa del problema pero nadie sabe repararlo, el riesgo operativo permanece.
Primera entrega y límite de la integración
Un primer recorrido completo recibe la intención de pagar, crea una operación con identificador propio, la envía al proveedor, recibe confirmación, procesa sin daño un evento repetido y muestra al cliente un estado verdadero. Incluye una forma de investigar manualmente un resultado desconocido. Así se valida el contrato principal y el modelo de estados. Más proveedores, métodos o reembolsos complejos se añaden por necesidad real, no automáticamente en la primera versión.
Antes de estimar se necesitan proveedor, disponibilidad del entorno de pruebas, mercados, monedas, tipo de producto, métodos requeridos y responsable del registro contable. Defina quién aprueba reembolsos y quién habla con el cliente ante un resultado incierto. Si faltan respuestas, empiece por el análisis técnico y del proceso. Sus resultados serán mapa de estados, contratos de datos, escenarios de prueba, diseño de conciliación y plan operativo antes de delimitar la implementación con precisión.
Preguntas antes del lanzamiento
El flujo de pago debe ser comprensible para personas ajenas al desarrollo. Si un cliente informa de un problema, soporte debe encontrar la operación y decir qué se sabe, qué se está verificando y qué sigue. Operaciones debe localizar un evento perdido o discrepancia y repararlos con seguridad. Producto necesita entender el riesgo y aprobar los límites de automatización. Sin estas tres vistas, un endpoint técnicamente funcional no es suficiente.
- ¿Qué estado permite entregar un producto o servicio?
- ¿Tiene cada operación identificadores internos y del proveedor estables?
- ¿Se distingue rechazo de resultado todavía desconocido?
- ¿Qué ocurre al repetir una solicitud o recibir un evento duplicado?
- ¿Cómo se verifica el origen de webhooks y se protege el secreto?
- ¿Cuándo y cómo se concilian registros internos y externos?
- ¿Quién puede reembolsar y quién aprueba una excepción?
- ¿Se ha ensayado recuperar el sistema con eventos en espera?