--- title: Módulo de suscripciones y recurrencia slug: modulo-de-suscripciones-y-recurrencia docTags: createdAt: 2026-03-29T23:27:49.269Z --- # 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 ::Image[]{src="https://api.archbee.com/api/optimize/wYlzYU9oe8HZjh9BkqeFY/h-790sGLEs89tiNnFrcF__image.png" size="62" width="1278" height="902" position="center" showCaption="false"} 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 | ::Image[]{src="https://api.archbee.com/api/optimize/wYlzYU9oe8HZjh9BkqeFY/m8wQcljK0r3oHshvfHAcs_image.png" size="62" width="1278" height="1052" position="center" showCaption="false"} 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* # 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** |