Considere un checkout en el que el pago se realiza con éxito, pero la actualización del pedido falla. El cliente ve un error e intenta de nuevo. Mientras tanto, soporte tiene un registro de la transacción, el almacén no tiene un pedido confirmado y finanzas necesita saber si el cliente adeuda algo.

¿Qué sistema debería resolver la situación? Incidentes como este son donde las decisiones de arquitectura se hacen visibles: cuando la propiedad no está definida, cada ocurrencia recibe una solución hecha a mano, y esas soluciones tienden a acumularse donde sea más fácil escribirlas.

Una arquitectura debería responder esa pregunta antes de que la primera transacción llegue a producción. De lo contrario, el código de pagos absorbe gradualmente la recuperación de pedidos, las reglas de suscripciones, los ajustes de facturas y las decisiones de fulfillment.

El modelo de propiedad que se describe a continuación ofrece un punto de partida práctico: mantener la pasarela enfocada en la comunicación con el proveedor, dar a las operaciones de pago un hogar propio y dejar las decisiones comerciales en la facturación y los pedidos.

Empezar con Cuatro Responsabilidades, No Tres

Para este diseño, hay que distinguir la pasarela de pagos del servicio de pagos más amplio. El modelo utiliza cuatro límites lógicos que cubren la pasarela, el servicio de pagos, la facturación y los pedidos.

Trátelos como límites de propiedad, no como una instrucción para desplegar cuatro microservicios. Comenzar con módulos dentro de una sola aplicación está bien si eso se adapta al equipo. En cualquier caso, las responsabilidades deben hacerse explícitas.

Al revisar la arquitectura de pasarelas de pago, combine el diagrama de componentes con un mapa de decisiones: ¿quién decide el monto, quién solicita el cobro, quién registra el resultado y quién autoriza la siguiente acción de negocio?

Mantener la Pasarela Cerca del Proveedor

Dale a la pasarela un contrato reducido. Debe aceptar una operación de soportada, traducirla al formato del proveedor y devolver un resultado que el servicio de pagos pueda interpretar.

El aislamiento tiene una motivación práctica: los proveedores de pagos difieren en APIs, esquemas de autenticación, formatos de campos y mecanismos de notificación, y consolidar esa variación en una sola capa mantiene al resto del sistema aislado de las particularidades del proveedor.

Asígnele responsabilidades como:

• Validar la solicitud orientada al proveedor
• Autenticar la comunicación con el proveedor
• Traducir campos internos a campos específicos del proveedor
• Verificar las notificaciones entrantes del proveedor
• Mapear las respuestas conservando detalles útiles del proveedor

El conocimiento del producto queda fuera de ese contrato. La pasarela no debería necesitar entender niveles de lealtad, elegibilidad de envío, períodos de gracia de suscripciones ni paquetes promocionales. Pásele el monto aprobado, la moneda, la referencia de pago y la información requerida del método de pago, no las reglas que los produjeron.

Una pregunta de revisión útil: ¿cambiar la política de devoluciones requeriría cambiar el código de la pasarela? Si es así, replantee el límite.

Dar a las Operaciones de Pago un Responsable Separado

Los intentos de pago y sus resultados pertenecen al servicio de pagos. Para cada intento, registre un identificador interno, las referencias relevantes del proveedor, el monto solicitado, la moneda, el tipo de operación y el estado. Conserve suficiente historial para investigar qué se solicitó y qué se confirmó realmente.

Evite reducir el modelo a una única bandera de "pagado". Defina en cambio las distinciones que los flujos de trabajo necesitan, incluidos los resultados no resueltos. La comunicación con el proveedor es genuinamente incierta en ocasiones: los timeouts, las notificaciones tardías y las actualizaciones fuera de orden son rutinarios, por lo que el modelo de estados necesita espacio para la ambigüedad en lugar de colapsar cada resultado en éxito o fracaso.

Diseñe explícitamente para esta secuencia hipotética: el servicio de pagos solicita una autorización, la solicitud llega al proveedor y la respuesta se pierde. La aplicación debe entonces decidir qué hacer a continuación. Un timeout nunca debería activar automáticamente un nuevo cobro. Exija que el servicio de pagos resuelva o gestione de forma segura el intento original antes de permitir otra operación.

También deben separarse dos tipos de reintento:

• Reintento técnico: repetir la comunicación para la misma operación prevista bajo reglas de seguridad definidas.
• Reintento de cobro: hacer un nuevo intento para cobrar un pendiente.

Asigne la gestión del reintento técnico al diseño de la integración de pagos. La facturación determina el momento y la elegibilidad del cobro, y el servicio de pagos ejecuta el intento aprobado.

Dejar que la Facturación Decida Qué se Adeuda

La facturación es propietaria de la obligación financiera: el cálculo del cargo, la factura, los créditos y el saldo restante. Para un producto de suscripción, las reglas de cambios de plan, prorrateos, períodos de facturación y calendarios de cobro pertenecen aquí.

Exija que la facturación emita cada solicitud de cobro con un monto explícito, una moneda y una referencia a la obligación que se está cobrando. El servicio de pagos informa el resultado, y la facturación determina luego cómo ese resultado afecta el saldo.

Considere una factura hipotética de $100 con un crédito de $30. La facturación debería solicitar los $70 restantes. Nunca se le debería pedir a la pasarela que reconstruya ese cálculo a partir de los metadatos de la suscripción.

La importancia crece con la complejidad de los precios: cada cálculo que aterriza en el componente equivocado se convierte en lógica que luego deberá encontrarse, migrarse y conciliarse entre sistemas.

La misma disciplina aplica después de un reembolso. Los registros de pagos establecen qué se devolvió a través del proveedor; la facturación determina qué factura o ajuste de saldo corresponde a esa devolución.

Dejar que los Pedidos Decidan Qué Pasa con la Compra

Las decisiones de fulfillment y del ciclo de vida de la compra se quedan en el dominio de pedidos. El servicio de pagos debería publicar un resultado de pago, no emitir una instrucción al almacén, y el flujo de pedidos debería interpretar ese resultado junto con sus demás requisitos. Interpretar el resultado es un juicio de negocio tanto como técnico, ya que el mismo pago confirmado puede tener un peso distinto para diferentes modelos de fulfillment.

Un ejemplo de regla de fulfillment explícita: liberar el pedido solo cuando la condición de pago requerida se cumpla, el inventario esté asignado y cualquier revisión requerida esté completa. La condición de pago debe elegirse según el modelo de negocio y nunca enterrarse dentro de un manejador de respuestas del proveedor.

Las cancelaciones merecen la misma separación. Los pedidos deciden si la cancelación está permitida y qué debe pasar con la compra, y luego solicitan la operación de pago correspondiente a través del servicio de pagos. Evite un comando de "cancelar" sobrecargado que podría significar cancelar el pedido, liberar una autorización, reembolsar un pago o terminar una suscripción. Nombre cada acción con precisión.

Coordinar Reembolsos sin Darle a un Solo Sistema Todos los Trabajos

Un flujo de reembolso es una buena prueba de si los límites se sostienen. Suponga que un cliente devuelve un artículo de un pedido de tres artículos. Estructure el flujo de modo que:

• El componente de devoluciones oidos apruebe la devolución.
• El responsable designado del cálculo comercial determine el monto reembolsable.
• El servicio de pagos verifique el historial de pagos y los límites de operación aplicables.
• La pasarela envíe la solicitud al proveedor.
• El servicio de pagos registre el resultado confirmado o no resuelto.
• La facturación y los pedidos actualicen sus propios registros en consecuencia.

Asigne un responsable a cada cálculo. La facturación y los pedidos no deberían calcular de forma independiente montos de reembolso diferentes y dejar que pagos elija entre ellos.

Mantenga "reembolso solicitado" separado de "reembolso confirmado". Si el resultado del proveedor no está resuelto, conserve esa incertidumbre y proporcione una vía de investigación en lugar de marcar todo el flujo como completo.

Hacer de la Recuperación Parte del Contrato

Cada operación que cruza límites debería especificar más que la respuesta exitosa. Documente:

• Cómo se identifican las solicitudes repetidas
• Qué componente posee el estado autoritativo
• Cómo se manejan las notificaciones tardías o duplicadas
• Qué sucede cuando el siguiente componente no está disponible
• Cómo el personal investiga los resultados no resueltos
• Qué acciones se pueden reintentar de forma segura

Para las solicitudes repetidas en particular, los proveedores suelen ofrecer mecanismos de idempotencia diseñados exactamente para este propósito, permitiendo que la misma operación se reenvíe sin ejecutarse dos veces.

Dé a cada dominio sus propios identificadores y conéctelos explícitamente: ID de pedido, ID de factura, ID de pago, ID de intento y referencia del proveedor. No fuerce un solo identificador a representar todas las relaciones.

El personal de soporte puede recibir una línea de tiempo combinada, pero las correcciones deben permanecer bajo el control del componente propietario. Un panel conveniente no debería convertirse en permiso para sobrescribir el historial de pagos ni alterar silenciosamente los saldos de las facturas.

Probar los Límites con Cambios de Negocio

Antes de aprobar el diseño, recorra varios cambios:

• Agregar un proveedor de pagos sin cambiar las reglas de precios.
• Cambiar el momento de cobro de suscripciones sin editar los adaptadores de la pasarela.
• Introducir devoluciones parciales sin reescribir el manejo de notificaciones del proveedor.
• Cambiar la política de fulfillment sin alterar las definiciones de estados de pago.

Trate los cambios inesperados entre componentes como señales de revisión. Alguna coordinación es legítima; el acoplamiento inexplicado merece atención.

La deriva de responsabilidades rara vez se anuncia; se acumula un cambio conveniente a la vez. Volver a ejecutar estos recorridos cada vez que se introduce un nuevo proveedor, método de pago o modelo de precios mantiene los límites explícitos mucho después de la revisión inicial del diseño.

La pasarela terminar en la comunicación de pago orientada al proveedor. El servicio de pagos debe ser propietario de la ejecución y la evidencia de los pagos. La facturación debe ser propietaria de las obligaciones y los saldos. Los pedidos deben ser propietarios de la compra y su fulfillment.

Escriba esas responsabilidades en las interfaces, los procedimientos de recuperación y la propiedad por equipos. Un diagrama por sí solo no los mantendrá separados.