Módulo de suscripciones y recurrencia

definición el módulo de suscripciones y recurrencia de la plataforma suga permite a los comercios del adquirente implementar modelos de cobro recurrente y automático sobre medios de pago tokenizados, sin necesidad de intervención del tarjetahabiente en cada ciclo resuelve uno de los problemas más complejos del ecosistema de pagos sostener una relación de débito recurrente entre un comercio y un cliente a lo largo del tiempo, gestionando el ciclo de vida completo de esa relación desde la inscripción del medio de pago, pasando por la ejecución periódica de cobros, hasta la gestión de rechazos, reintentos, suspensiones y bajas el módulo abstrae la complejidad operativa asociada a • tokenización y reutilización de medios de pago • programación y ejecución de agendas de cobro • gestión de reintentos ante rechazos • estados del suscriptor a lo largo del tiempo • notificaciones en tiempo real mediante webhooks existen dos modelos de operación soportados por el módulo tipos de suscripción dynamic → el motor de la plataforma ejecuta los cobros automáticamente según el intervalo configurado (7d, 15d, 1m, 2m, 3m, 6m, 1y) manual → el adquirente o comercio controla la ejecución de cada cobro vía api, permitiendo lógicas de negocio propias rol dentro de la plataforma el módulo de suscripciones y recurrencia ocupa un rol transversal dentro de la arquitectura suga no es simplemente un canal de pago adicional es una capa de orquestación de cobros que opera sobre las capacidades de procesamiento del smart acquiring core, consume datos de medios de pago tokenizados, y alimenta los flujos de liquidación y conciliación con las ejecuciones aprobadas este módulo interactúa con los siguientes componentes de la plataforma módulo relación smart acquiring core ejecuta las autorizaciones de cada cobro recurrente contra el procesador gestión de medios de pago provee los tokens de los medios de pago asociados a cada suscriptor (ssv) tokenización (security vault) almacena y gestiona de forma segura los datos de tarjeta bajo token pci/token de marca gestión de transacciones registra y expone cada ejecución como una transacción trazable dentro del sistema módulo de liquidaciones recibe las transacciones aprobadas de las ejecuciones para su inclusión en la liquidación al comercio webhooks / notificaciones publica eventos de ciclo de vida del suscriptor y resultados de ejecuciones en tiempo real abstracción lograda por el módulo el módulo de suscripciones y recurrencia abstrae la complejidad de operar un modelo de cobro recurrente dentro del ecosistema de pagos sin este módulo, cada adquirente o comercio debería implementar de forma propia • almacenamiento seguro de tokens de medios de pago (cumplimiento pci) • lógica de scheduling y agenda de cobros • reintentos automáticos y gestión de rechazos • cuenta corriente de deuda acumulada • notificaciones a comercios y suscriptores • trazabilidad de ejecuciones y estados la plataforma suga encapsula todo este circuito en una capa reutilizable flujo abstraído por el módulo medio de pago tokenizado → suscriptor creado → agenda generada agenda → ejecución automática (dynamic) o manual (manual) → autorización en core rechazo → reintento automático / cuenta corriente / notificación aprobación → evento webhook → impacto en liquidación al comercio funcionamiento del módulo el módulo opera sobre dos entidades principales la suscripción y el suscriptor estas entidades tienen ciclos de vida independientes pero vinculados, y sobre ellas se ejecutan todas las operaciones del módulo entidades principales suscripción es la plantilla de cobro recurrente define el monto, la frecuencia, los medios de pago aceptados, el tipo de operación (dynamic o manual), y las reglas de comportamiento (reintentos, cuenta corriente, validación de identidad, etc ) una suscripción puede tener múltiples suscriptores suscriptor es la instancia de un cliente dentro de una suscripción tiene su propio estado, su medio de pago activo, su agenda de cobros y su historial de ejecuciones cada suscriptor puede tener un monto personalizado distinto al definido en la suscripción ciclo de vida de la suscripción una suscripción transita entre los siguientes estados • active → el cobro está habilitado para todos sus suscriptores activos • inactive → el cobro está suspendido para todos los suscriptores • eliminada (lógicamente) → los suscriptores no se modifican de estado pero no se ejecutan cobros el gráfico muestra el ciclo completo algunos detalles del diseño que reflejan la lógica del módulo la transición active ↔ inactive es bidireccional (suspender y reactivar son operaciones reversibles) la transición hacia eliminada es en línea punteada y parte de ambos estados, indicando que es irreversible el estado eliminada deja en claro las dos consecuencias suscriptores sin cambios de estado, pero cobros detenidos ciclo de vida del suscriptor un suscriptor transita los siguientes estados a lo largo de su relación con la suscripción estado descripción pendiente suscriptor creado pero sin medio de pago cargado aún active suscriptor con medio de pago activo, con cobros habilitados según agenda suspended cobros suspendidos de forma individual, sin afectar a otros suscriptores finished el suscriptor completó todos los períodos configurados en la suscripción eliminado baja lógica del suscriptor, sin ejecución de nuevos cobros el ciclo del suscriptor tiene más riqueza que el de la suscripción porque opera a nivel individual algunos puntos clave que el diagrama deja en evidencia pendiente → active solo ocurre cuando el suscriptor carga su medio de pago hasta ese momento, existe en el sistema pero no genera cobros active ↔ suspended es la única transición bidireccional, y es siempre individual suspender un suscriptor no afecta al resto finished es terminal por reglas de negocio ocurre cuando se agotan los períodos configurados en la suscripción no hay vuelta desde ese estado la eliminación lógica puede ejecutarse desde active o suspended, y también es irreversible agenda de cobros cuando una suscripción es de tipo dynamic, el módulo genera una agenda de cobros para cada suscriptor basada en la fecha de inicio (startdate) y el intervalo definido la agenda puede ser • estándar cobros cada n días o meses desde la fecha de inicio • agenda fija cobros el mismo día de cada mes (initialday), con posibilidad de cobrar un proporcional en el primer período (startoninitialday) la agenda puede modificarse mediante la acción de reschedule, recalculando todos los períodos futuros desde una nueva fecha de inicio ejecución de cobros cada cobro ejecutado sobre un suscriptor genera una ejecución sobre ella el módulo registra • medio de pago utilizado (primary o secondary) • resultado de la autorización (aprobado / rechazado) • fecha y monto del cobro • referencia de la transacción en el procesador sobre una ejecución fallida es posible • reintentar la ejecución (retry) • marcarla como paga externamente (paid) para cerrar el período sin procesar en suscripciones manuales, la ejecución es siempre iniciada por el operador vía api, ya sea de forma individual o masiva sobre múltiples suscriptores reintentos y cuenta corriente el comportamiento del módulo ante rechazos puede configurarse mediante features de la suscripción • no retry desactiva el reintento automático el operador debe ejecutar el cobro manualmente • no retry with secondary desactiva el reintento con el medio de pago secundario del suscriptor • no cc desactiva la cuenta corriente si el cliente posee deuda acumulada, no se intentará recobrarla automáticamente • charge on first source ejecuta el primer cobro automáticamente al cargar el medio de pago componentes y funcionalidades principales gestión de suscripciones • creación y edición de suscripciones con configuración de tipo, intervalo, monto, períodos de prueba y límite de cobros • configuración de setupfee monto inicial diferente al recurrente, cobrado una única vez al suscribirse • limitación de medios de pago aceptados por suscripción (sources) • activación, suspensión y eliminación lógica de suscripciones • paginación y filtrado de suscripciones por estado, nombre o referencia • soporte para split de cobros en múltiples comercios (modelo marketplace) gestión de suscriptores • alta de suscriptores con datos del cliente y fecha de inicio configurada • monto personalizado por suscriptor, independiente del monto de la suscripción • gestión del medio de pago activo del suscriptor (carga, cambio) • activación, suspensión y eliminación individual del suscriptor • reasignación del suscriptor a otra suscripción de la misma entidad (move) • modificación de la agenda (reschedule) a partir de una nueva fecha de inicio ejecuciones • ejecución manual individual sobre un suscriptor con monto y referencia personalizable • ejecución masiva sobre múltiples suscriptores de una misma suscripción • programación de ejecuciones a futuro (schedule) con fecha específica • reintento de ejecuciones fallidas (retry) • marcado manual como paga (paid) para cerrar períodos sin procesamiento • soporte de impuestos por ejecución (taxes) features configurables el nodo features de una suscripción permite activar o desactivar comportamientos específicos feature efecto validate id controla que el dni del suscriptor coincida con el del tarjetahabiente accept no funds acepta la tokenización aunque la tarjeta no tenga fondos no email desactiva los emails de aviso al suscriptor no cc desactiva la cuenta corriente de deuda acumulada no retry desactiva el reintento automático ante rechazo no retry with secondary desactiva el reintento con el medio de pago secundario charge on first source ejecuta el primer cobro al cargar el medio de pago dimensiones y entidades del módulo el módulo opera sobre las siguientes entidades y dimensiones principales entidad nivel descripción suscripción raíz plantilla de cobro define reglas, intervalo, monto base y features suscriptor hijo de suscripción cliente asociado a una suscripción tiene su propio estado, medio de pago y agenda ejecución hijo de suscriptor instancia de un cobro realizado o intentado sobre un suscriptor medio de pago asociado al suscriptor token del instrumento de pago (tarjeta de crédito, débito o prepaga) agenda asociada al suscriptor lista de fechas programadas de cobro para el suscriptor entidad / comercio contexto organización bajo la cual se crean y operan las suscripciones integración técnica el módulo expone una api rest completa bajo el endpoint base solicitar documentación solicitar documentación flujo operativo el siguiente diagrama representa el flujo operativo completo del módulo, desde la creación de la suscripción hasta la liquidación del cobro al comercio flujo — suscripción dinámica 1 operador crea suscripción (post /subscriptions) → plantilla configurada 2 operador crea suscriptor (post /subscriptions/{id}/subscriber) → datos del cliente + fecha 3 suscriptor carga medio de pago (sourceurl) → token generado en security vault 4 webhook subscription registration → suscriptor activo 5 plataforma ejecuta cobro según agenda → smart acquiring core 6 procesador autoriza o rechaza → respuesta al core 7a aprobado → webhook subscription execution → transacción registrada 7b rechazado → reintento automático / cuenta corriente → notificación al operador 8 ejecución aprobada alimenta liquidación → acreditación al comercio flujo — suscripción manual 1 operador crea suscripción tipo manual (sin intervalo) → plantilla configurada 2 operador crea suscriptores → datos del cliente 3 suscriptores cargan medio de pago (sourceurl) → tokens registrados 4 operador ejecuta cobros (individualmente o masivo) → post /execution 5 smart acquiring core procesa autorización → resultado por webhook 6 ejecuciones aprobadas se incluyen en liquidación → acreditación al comercio beneficios y valor operativo dimensión valor que aporta el módulo automatización de cobros elimina la intervención manual en cada ciclo para suscripciones dinámicas flexibilidad operativa soporte para modelos automáticos y manuales según la lógica de negocio del comercio reducción de fuga de cobros reintentos automáticos y cuenta corriente minimizan el impacto de rechazos transitorios control granular acciones individuales por suscriptor sin afectar al resto de la suscripción trazabilidad completa cada ejecución queda registrada como transacción en el módulo de gestión de transacciones cumplimiento pci los medios de pago se almacenan como tokens, sin exposición de datos sensibles integración nativa las ejecuciones aprobadas se integran directamente con el módulo de liquidaciones configuración sobre customización el comportamiento del módulo se define por features, sin necesidad de desarrollo a medida qué transmite este módulo el módulo de suscripciones y recurrencia demuestra que la plataforma comprende el ciclo completo de un modelo de cobro recurrente no solo la transacción individual, sino la relación continua entre un adquirente, un comercio y sus clientes a lo largo del tiempo ✔ automatización del ciclo de cobro recurrente ✔ arquitectura modular con entidades independientes y versionables ✔ control operativo granular a nivel suscripción y suscriptor ✔ integración nativa con el ecosistema de procesamiento, liquidación y seguridad ✔ configuración sobre customización comportamiento definido por features, no por código ✔ plataforma escalable con soporte para operación masiva vía api