Skip to main content
Esta guía explica cómo implementar y gestionar suscripciones utilizando la API de Confío.

​
Descripción general

La API de Suscripciones te permite crear planes de facturación recurrente y asignarlos a tus clientes. El sistema maneja:
  • Gestión de planes (creación, actualización, archivado)
  • Suscripciones a clientes
  • Procesamiento de cobros recurrentes
  • Reintentos de pago
  • Gestión de estados

​
Conceptos Clave

​
Planes de Suscripción

Un plan define los términos de facturación:
  • Monto: Cuánto cobrar
  • Frecuencia: Con qué frecuencia cobrar (Semanal/Mensual/Anual)
  • Intervalo: Número de períodos entre cobros (ej. cada 2 meses)
  • Período de Prueba: Días gratuitos opcionales antes del primer cobro

​
Suscripciones

Una suscripción vincula a un cliente con un plan. Rastrea:
  • Estado actual (Activo, Atrasado, etc.)
  • Próxima fecha de cobro
  • Método de pago
  • Historial de cobros

​
Estados de una Suscripción

EstadoDescripción
PENDING_ACCEPTANCERecién creada. Esperando que el cliente acepte los términos y registre su método de pago.
ACTIVEEl cliente aceptó y los cobros se procesan normalmente.
TRIALINGEn período de prueba gratuito. Los cobros inician al vencer el trial.
PROCESSINGUn cobro está en curso. Estado transitorio durante la ejecución del pago.
PAST_DUEEl cobro más reciente falló. El sistema reintenta automáticamente hasta 4 veces.
SUSPENDEDLos 4 reintentos del ciclo se agotaron, o se eliminó el método de pago. Requiere intervención del cliente para reactivar.
CANCELEDCancelada manualmente por el comercio, o de forma automática tras 3 ciclos de suspensión consecutivos.
Lógica de reintentos y suspensiones: El sistema distingue dos niveles de fallo:
  1. Reintentos dentro de un ciclo (PAST_DUE): cuando un cobro falla, el sistema reintenta hasta 4 veces en días específicos (día 0, 2, 5 y 7). Si los 4 reintentos fallan, la suscripción pasa a SUSPENDED.
  2. Ciclos de suspensión consecutivos (CANCELED): si la suscripción se suspende 3 veces seguidas sin que el cliente actualice su método de pago, se cancela automáticamente.
Diagrama de transiciones: 
PENDING_ACCEPTANCE
    │
    ├─► ACTIVE         (cliente acepta, sin período de prueba)
    └─► TRIALING       (cliente acepta, con período de prueba)
            │
            └─► ACTIVE (fin del período de prueba, cobro exitoso)

ACTIVE / TRIALING
    │
    └─► PROCESSING     (cobro iniciado)
            │
            ├─► ACTIVE     (cobro exitoso)
            └─► PAST_DUE   (cobro fallido → inician reintentos automáticos)

PAST_DUE
    │
    └─► PROCESSING     (reintento en curso, hasta 4 intentos: días 0, 2, 5, 7)
            │
            ├─► ACTIVE      (reintento exitoso)
            └─► PAST_DUE    (reintento fallido, aún quedan intentos)
                    │
                    └─► SUSPENDED   (4 reintentos agotados, o método de pago eliminado)
                                │
                                ├─► ACTIVE    (cliente actualiza método de pago y reactiva)
                                └─► CANCELED  (3 ciclos de suspensión consecutivos sin reactivación)

Cualquier estado ──► CANCELED   (cancelación manual por el comercio)

​
Pasos de Integración

​
1. Crear un Plan de Suscripción

Primero, define tu oferta creando un plan. 
curl -X POST "https://api.confiopagos.com/v1/stores/{storeId}/subscription-plans" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Premium Mensual",
    "description": "Acceso a funciones premium",
    "amountCents": 5000000,
    "currencyCode": "COP",
    "billingCycleFrequency": "MONTHLY",
    "billingCycleInterval": 1,
    "trialPeriodDays": 7
  }'

​
2. Asignar Plan a un Cliente

Crea una suscripción para un cliente. Esto genera un enlace de aceptación. 
curl -X POST "https://api.confiopagos.com/v1/stores/{storeId}/subscription-plans/{planId}/subscriptions" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionPlan": "organizations/{org}/stores/{store}/subscription-plans/{planId}",
    "buyer": {
      "email": "cliente@ejemplo.com",
      "phoneNumber": "+573001234567",
      "firstName": "Juan",
      "lastName": "Perez"
    }
  }'

​
3. Aceptación del Cliente

El cliente recibe un enlace para:
  1. Validar su identidad (OTP)
  2. Registrar su método de pago (Tarjeta)
  3. Aceptar los términos de la suscripción
Una vez aceptado, la suscripción pasa a estado ACTIVE.

​
4. Gestionar Suscripciones

Puedes listar y filtrar suscripciones para rastrear a tus suscriptores. 
curl -X GET "https://api.confiopagos.com/v1/stores/{storeId}/subscriptions?status=ACTIVE" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN"