Términos de relevancia
La funcionalidad de Planes y suscripciones permite a un comercio configurar cobros recurrentes, vincular clientes a un plan mediante un medio de pago tokenizado y ejecutar cobros automáticos según las condiciones definidas.
Antes de integrar estos endpoints, es importante entender los conceptos principales, cómo se relacionan entre sí y qué reglas influyen en el comportamiento de la solución.
¿Qué son los planes y las suscripciones?
Esta solución se compone de tres entidades principales: Plan, Suscripción y Cobro.
Un Plan define las condiciones generales de un cobro recurrente, como el monto, la moneda, la frecuencia, el número total de cobros y las políticas aplicables en caso de fallo. Un mismo plan puede ser utilizado por múltiples clientes.
Una Suscripción representa la relación entre un cliente y un plan. Se crea cuando el cliente vincula su medio de pago y acepta las condiciones del cobro recurrente. Desde ese momento, la suscripción conserva la información necesaria para operar y los términos aceptados en el momento de la vinculación.
Un Cobro corresponde a la ejecución individual de un cargo dentro de una suscripción. Cada cobro tiene su propio estado, referencia y número de intento.
Conceptos clave
Plan Es la configuración base de un cobro recurrente. Define las condiciones comunes para todos los clientes que se suscriban.
Suscripción Es el vínculo entre un cliente y un plan. Contiene la información del cliente, el medio de pago tokenizado, los términos aceptados y el estado del ciclo de cobro.
Cobro recurrente Es la ejecución periódica de un cargo sobre una suscripción activa, de acuerdo con las condiciones previamente definidas.
Vinculación de medio de pago Es el proceso mediante el cual un cliente registra un medio de pago para ser utilizado en cobros futuros.
Tokenización Es el mecanismo que reemplaza la información sensible del medio de pago por un token seguro provisto por el proveedor de pagos.
Flujo general
De forma general, el flujo funciona así:
Reglas del modelo
Un plan no representa a un cliente
Los planes definen condiciones generales. La relación con un cliente específico existe únicamente a través de una suscripción.
La suscripción conserva los términos aceptados
Cuando un cliente se suscribe, la suscripción almacena una copia de las condiciones vigentes en ese momento. Si el plan cambia más adelante, esos cambios no modifican automáticamente las condiciones ya aceptadas por suscripciones existentes.
Cada cobro es una ejecución independiente
Una suscripción puede generar múltiples cobros a lo largo del tiempo. Cada uno conserva su propio estado, referencia e historial de intentos.
La operación real ocurre sobre la suscripción
Aunque el plan define las reglas generales, la ejecución de cobros depende de la información operativa de cada suscripción, como su estado, sus términos y su próxima fecha de cobro.
Variables dinámicas de descripción
La descripción de un cobro puede construirse usando variables dinámicas que se resuelven en el momento real de la ejecución.
Esto permite mostrar información más clara al cliente y mantener consistencia entre la ejecución del cobro y su descripción.
Variables disponibles:
{{charge_number}}: número del cobro dentro del ciclo{{month}}: nombre del mes de ejecución{{week}}: rango semanal asociado a la fecha de ejecución{{biweek}}: rango quincenal asociado a la fecha de ejecución{{day}}: fecha legible de ejecución
Estas variables deben resolverse con base en la fecha efectiva del cobro, no solo en la fecha programada, ya que un cobro puede ejecutarse posteriormente debido a reintentos u otras condiciones operativas.
Ejemplo:
Si un plan define la descripción:
Cobro {{charge_number}} - {{month}}
y el sistema ejecuta el tercer cobro en agosto, la descripción generada sería:
Cobro 3 - Agosto
También es posible usar formatos como:
Suscripción {{charge_number}} - {{day}}Cobro correspondiente a {{week}}Pago recurrente {{charge_number}} - {{biweek}}
Estados
Plan y Suscripción manejan estados separados. El estado del Plan define si sigue abierto a nuevos suscriptores; el de la Suscripción, en qué punto del ciclo de cobro está cada cliente. Los cambios en el Plan no alteran las suscripciones activas.
Planes
ACTIVE
Disponible para nuevas suscripciones.
PAUSED
No acepta nuevas suscripciones temporalmente. Las suscripciones existentes siguen cobrando normal.
CANCELED
Retirado permanentemente. No acepta nuevas suscripciones. Las suscripciones existentes no se ven afectadas, siguen cobrando con sus terms congelados hasta que se cancelen individualmente.
Suscripción
PENDING
Creada por API o diligenciada en la web, esperando que el cliente vincule su medio de pago.
ACTIVE
Medio de pago vinculado y operando. Puede tener cobros individuales fallidos en curso sin dejar de estar activa.
OVERDUE
Se agotaron los reintentos (max_retries) y status_after_retry = OVERDUE.
CANCELED
Reintentos agotados con status_after_retry = CANCELED, o cancelación manual (API o vista del cliente).
FULFILLED
Se alcanzó el número de cobros permitidos (charges_executed alcanzó total_charges).
Consideraciones importantes
Antes de implementar esta funcionalidad, es importante tener en cuenta algunos comportamientos y límites del modelo.
Límite de cobros por plan
Cada plan puede definir un máximo de cobros dentro del ciclo recurrente. Este valor se establece al crear el plan y determina cuántas ejecuciones puede generar cada suscripción asociada. El máximo permitido es de 12 cobros. Al alcanzar este límite, se debe crear una nueva suscripción o solicitar la actualización del medio de pago.
Uso de trial_days
El campo trial_days permite definir un período de gracia antes del primer cobro. Durante ese tiempo, la suscripción puede quedar activa sin generar un cargo inmediato, según la configuración del plan.
Reintentos de cobro
Cuando un cobro falla, el sistema puede aplicar una política de reintentos definida en el plan. Esta configuración permite establecer cuántos intentos adicionales se realizarán y cada cuánto tiempo. Si se alcanza el número máximo de reintentos sin éxito, la suscripción puede pasar al estado configurado para ese caso. Esto permite definir de antemano el comportamiento esperado del ciclo de cobro.
Vinculación mediante enlace seguro
La captura y tokenización del medio de pago no ocurre directamente en la integración del comercio. En su lugar, la plataforma genera un enlace de vinculación que el cliente debe completar para registrar su medio de pago de forma segura.
Creación de suscripciones por API
Cuando una suscripción se crea por API, la respuesta incluye un enlace de vinculación para completar el registro del medio de pago. La suscripción solo podrá operar normalmente una vez este paso haya sido completado.
Cambios en un plan y suscripciones existentes
Las actualizaciones realizadas sobre un plan no modifican automáticamente las condiciones ya aceptadas por suscripciones existentes. Cada suscripción conserva los términos vigentes al momento de su creación.
Última actualización