> ## Documentation Index > Fetch the complete documentation index at: https://developers.confiopagos.com/llms.txt > Use this file to discover all available pages before exploring further. # Suscripciones > Guía para crear planes, asignar suscripciones y sincronizar cobros recurrentes con la API de Confío Esta guía explica cómo implementar suscripciones recurrentes con la API pública de Confío. El flujo está pensado para que tu backend cree planes y suscripciones, y para que el comprador acepte la suscripción en una experiencia hospedada por Confío. ## Descripción general del proceso 1. Tu servidor crea un plan de suscripción para una tienda. 2. Tu servidor crea una suscripción para un comprador y recibe un `acceptanceUrl`. 3. Compartes el `acceptanceUrl` con el comprador. 4. El comprador abre el enlace, valida su identidad y registra su tarjeta en Confío. 5. Confío activa la suscripción y procesa los cobros recurrentes automáticamente. 6. Tu plataforma se sincroniza mediante webhooks y usa consultas `GET`/`List` para conciliación. ```mermaid theme={null} sequenceDiagram participant TuPlataforma as "Tu Plataforma" participant Confio as "Confío" participant Comprador TuPlataforma->>Confio: POST /v1/stores/{store}/subscription-plans Confio-->>TuPlataforma: Plan creado TuPlataforma->>Confio: POST /v1/stores/{store}/subscription-plans/{plan}/subscriptions Confio-->>TuPlataforma: Suscripción PENDING_ACCEPTANCE + acceptanceUrl TuPlataforma->>Comprador: Comparte acceptanceUrl Comprador->>Confio: Acepta y registra tarjeta Confio-->>TuPlataforma: Webhook subscription.subscriptionStatusChanged Confio-->>TuPlataforma: Webhooks subscription.billingStatusChanged en cada cobro ``` ## Requisitos previos * Un token de acceso válido a la API de Confío. Debes contactarnos para generar el token. Una vez generado, te recomendamos almacenarlo en un lugar seguro y no compartirlo. * IID de la tienda (`{store}`). Puedes obtenerlo con `GET /v1/stores`. * La funcionalidad de suscripciones habilitada para tu organización. Si la funcionalidad no está habilitada, los endpoints de creación devuelven `403` con el mensaje `Subscriptions feature is not active`. * Un endpoint de webhooks configurado si necesitas sincronización automática de estados y cobros. ## Conceptos clave ### Plan de suscripción Un plan define los términos recurrentes: * `displayName`: nombre visible del plan. * `amountCents` y `currencyCode`: monto regular de cada ciclo. * `billingCycleFrequency`: `WEEKLY` o `MONTHLY`. * `billingCycleInterval`: número de períodos entre cobros. Por ejemplo, `1` mensual o `3` trimestral si la frecuencia es `MONTHLY`. * `trialPeriodDays`: días de prueba antes del primer cobro recurrente. Usa `0` si no hay prueba. La API pública permite crear, listar y consultar planes. La actualización o el archivado de planes no están expuestos actualmente en la API pública. ### Suscripción Una suscripción vincula a un comprador con un plan. Al crearla, Confío devuelve una URL de aceptación para que el comprador complete el proceso. Campos importantes: * `name`: identificador estable de la suscripción, por ejemplo `stores/{store}/subscription-plans/{plan}/subscriptions/{subscription}`. * `status`: estado actual de la suscripción. * `acceptanceUrl`: enlace hospedado por Confío para aceptar la suscripción. Solo aparece cuando la suscripción está en `PENDING_ACCEPTANCE`. * `firstChargeAmountCents`: monto opcional solo para el primer ciclo de cobro. * `redirectUri`: URL opcional a la que Confío puede redirigir al comprador después de aceptar la suscripción. ## Estados de una suscripción | Estado | Descripción | | -------------------- | -------------------------------------------------------------------------------------------------------- | | `PENDING_ACCEPTANCE` | La suscripción fue creada y espera que el comprador acepte los términos y registre su tarjeta. | | `ACTIVE` | La suscripción está activa y los cobros se procesan normalmente. | | `TRIALING` | La suscripción está en período de prueba. El primer cobro recurrente se realizará al finalizar el trial. | | `PAST_DUE` | Un cobro falló. Confío reintentará automáticamente según la política de reintentos. | | `SUSPENDED` | Se agotaron los intentos de cobro del ciclo o el método de pago requiere intervención. | | `CANCELED` | La suscripción fue cancelada manualmente o por reglas automáticas de cobro fallido. | El flujo principal tiene dos momentos: primero el comprador acepta la suscripción; después Confío procesa cobros y reintentos. ```mermaid theme={null} flowchart TB pending["PENDING_ACCEPTANCE
Esperando aceptación"] active["ACTIVE
Cobros normales"] trialing["TRIALING
Período de prueba"] pastDue["PAST_DUE
Cobro fallido"] suspended["SUSPENDED
Intentos agotados"] canceled["CANCELED
Cobros detenidos"] pending -->|Acepta sin trial| active pending -->|Acepta con trial| trialing trialing -->|Trial termina;
cobro exitoso| active trialing -->|Trial termina;
cobro falla| pastDue active -->|Cobro falla| pastDue pastDue -->|Reintento exitoso| active pastDue -->|Se agotan intentos| suspended suspended -->|Actualiza método de pago| active suspended -->|Fallos consecutivos| canceled pending -.->|Cancelación manual| canceled active -.->|Cancelación manual| canceled trialing -.->|Cancelación manual| canceled pastDue -.->|Cancelación manual| canceled ``` Mientras la suscripción está `ACTIVE`, cada cobro exitoso mantiene la suscripción activa y avanza al siguiente ciclo de facturación. ## Paso 1: obtener la tienda ```bash theme={null} curl -X GET "https://api.confiopagos.com/v1/stores" \ -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" ``` Ejemplo de respuesta: ```json theme={null} { "stores": [ { "name": "stores/01JNRRDZDPH40DB2YRW329BFXM", "displayName": "Mi Tienda" } ] } ``` Usa el identificador de la tienda como `{store}` en las siguientes solicitudes. ## Paso 2: crear un plan de suscripción ```bash theme={null} curl -X POST "https://api.confiopagos.com/v1/stores/{store}/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 }' ``` Ejemplo de respuesta: ```json theme={null} { "name": "stores/01JNRRDZDPH40DB2YRW329BFXM/subscription-plans/01JNRVWWHH68E76V3TMFFT6GHJ", "displayName": "Premium Mensual", "description": "Acceso a funciones premium", "amountCents": 5000000, "currencyCode": "COP", "billingCycleFrequency": "MONTHLY", "billingCycleInterval": 1, "trialPeriodDays": 7, "status": "ACTIVE", "createTime": "2026-01-15T10:30:00Z", "updateTime": "2026-01-15T10:30:00Z" } ``` ## Paso 3: crear una suscripción para el comprador ```bash theme={null} curl -X POST "https://api.confiopagos.com/v1/stores/{store}/subscription-plans/{plan}/subscriptions" \ -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "firstChargeAmountCents": 3000000, "redirectUri": "https://tu-tienda.com/suscripciones/resultado", "buyer": { "email": "cliente@ejemplo.com", "phoneNumber": "+573001234567", "firstName": "Juan", "lastName": "Pérez" } }' ``` Ejemplo de respuesta: ```json theme={null} { "name": "stores/01JNRRDZDPH40DB2YRW329BFXM/subscription-plans/01JNRVWWHH68E76V3TMFFT6GHJ/subscriptions/01K0ABCDEF1234567890XYZ", "firstChargeAmountCents": 3000000, "redirectUri": "https://tu-tienda.com/suscripciones/resultado", "status": "PENDING_ACCEPTANCE", "buyer": { "email": "cliente@ejemplo.com", "phoneNumber": "+573001234567", "firstName": "Juan", "lastName": "Pérez" }, "acceptanceUrl": "https://checkout.confiopagos.com/s/01K0ABCDEF1234567890XYZ", "createTime": "2026-01-15T10:35:00Z" } ``` Guarda el `name` de la suscripción y comparte el `acceptanceUrl` con el comprador. No recolectes ni almacenes datos de tarjeta en tu plataforma para aceptar una suscripción. El comprador debe registrar su método de pago en el flujo hospedado por Confío usando `acceptanceUrl`. ### Sobre `firstChargeAmountCents` `firstChargeAmountCents` es opcional y solo aplica al primer ciclo de cobro: * Si el plan no tiene trial, el primer cobro ocurre durante la aceptación del comprador. * Si el plan tiene trial, el primer cobro recurrente ocurre al finalizar el período de prueba. * Los ciclos posteriores usan el `amountCents` regular del plan. ## Paso 4: enviar el enlace de aceptación Envía el `acceptanceUrl` al comprador por tu canal preferido. En ese enlace, el comprador: 1. Valida su identidad. 2. Revisa los términos de la suscripción. 3. Registra su tarjeta en Confío. 4. Acepta la suscripción. Después de aceptar, la suscripción pasa a `ACTIVE` o `TRIALING`, según el `trialPeriodDays` del plan. ## Paso 5: sincronizar estados con webhooks Para mantener tu sistema actualizado, configura webhooks y escucha estos eventos: * `subscription.subscriptionStatusChanged`: cambios de estado de la suscripción, por ejemplo creación, aceptación, mora, suspensión o cancelación. * `subscription.billingStatusChanged`: resultado de cada cobro recurrente, exitoso o fallido. Consulta la [guía de webhooks](/cookbooks/webhooks) para ver payloads y validación de `Authorization`, `X-Confio-Event` y `X-Confio-Checksum`. ## Consultar suscripciones ### Consultar una suscripción ```bash theme={null} curl -X GET "https://api.confiopagos.com/v1/stores/{store}/subscription-plans/{plan}/subscriptions/{subscription}" \ -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" ``` Usa esta llamada para reconciliar una suscripción específica después de recibir un webhook o ante dudas operativas. ### Listar suscripciones de una tienda ```bash theme={null} curl -X GET "https://api.confiopagos.com/v1/stores/{store}/subscription-plans/subscriptions?pageSize=20" \ -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" ``` Usa el listado para backfills, auditorías o conciliación periódica. Evita usar polling como mecanismo principal si tienes webhooks configurados. ## Cancelar una suscripción ```bash theme={null} curl -X POST "https://api.confiopagos.com/v1/stores/{store}/subscription-plans/{plan}/subscriptions/{subscription}/cancel" \ -H "Authorization: Bearer CONFIO_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "reason": "Solicitado por el cliente" }' ``` La cancelación detiene los cobros futuros y marca la suscripción como `CANCELED`. ## Reintentos de cobro Cuando un cobro falla, Confío mueve la suscripción a `PAST_DUE` y reintenta automáticamente. | Intento | Momento aproximado | | ------- | ------------------------------ | | 1 | Día 0, cobro inicial del ciclo | | 2 | Día 2 | | 3 | Día 5 | | 4 | Día 7 | Si se agotan los intentos del ciclo, la suscripción puede pasar a `SUSPENDED`. Si los fallos continúan durante varios ciclos, Confío puede cancelarla automáticamente. ## Errores comunes * `400`: datos inválidos, por ejemplo teléfono fuera de formato E.164, `redirectUri` sin HTTPS o monto menor al mínimo permitido. * `401`: falta o es inválido el Bearer token. * `403`: la funcionalidad de suscripciones no está habilitada para la organización. * `404`: tienda, plan o suscripción no encontrada o sin permisos. * `5xx`: error interno o dependencia temporal. Reintenta de forma segura desde tu backend. ## Mejores prácticas 1. Guarda el `name` del plan y de la suscripción en tu sistema. 2. Envía el `acceptanceUrl` al comprador tan pronto crees la suscripción. 3. Usa webhooks como fuente principal de sincronización. 4. Usa `GET` y `List` como mecanismos de conciliación. 5. Diseña tu procesamiento de webhooks para ser idempotente. 6. No recolectes datos de tarjeta ni intentes aceptar suscripciones desde tu backend. ## Recursos adicionales * [Crear plan de suscripción](/api-reference/create-subscription-plan) * [Crear suscripción](/api-reference/create-subscription) * [Consultar suscripción](/api-reference/get-subscription) * [Listar suscripciones](/api-reference/list-subscriptions) * [Cancelar suscripción](/api-reference/cancel-subscription) * [Webhooks](/cookbooks/webhooks)