Suscripciones

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

Tu servidor crea un plan de suscripción para una tienda.
Tu servidor crea una suscripción para un comprador y recibe un acceptanceUrl.
Compartes el acceptanceUrl con el comprador.
El comprador abre el enlace, valida su identidad y registra su tarjeta en Confío.
Confío activa la suscripción y procesa los cobros recurrentes automáticamente.
Tu plataforma se sincroniza mediante webhooks y usa consultas GET/List para conciliación.

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.

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

curl -X GET "https://api.confiopagos.com/v1/stores" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN"

Ejemplo de respuesta:

{
  "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

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:

{
  "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

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:

{
  "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:

Valida su identidad.
Revisa los términos de la suscripción.
Registra su tarjeta en Confío.
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 para ver payloads y validación de Authorization, X-Confio-Event y X-Confio-Checksum.

Consultar suscripciones

Consultar una suscripción

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

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.

Consultar varias suscripciones

Si ya conoces las suscripciones, puedes consultar hasta 100 en una sola llamada. Repite el parámetro names por cada suscripción. Cada valor puede ser el name de la suscripción (stores/{store}/subscription-plans/{plan}/subscriptions/{subscription}), tal como lo devuelve la API, o solo su identificador globalmente único. Para consultar suscripciones de diferentes planes de la misma tienda, usa - como identificador del plan en la ruta. Los name completos conservan el plan real de cada suscripción:

curl -X GET "https://api.confiopagos.com/v1/stores/{store}/subscription-plans/-/subscriptions:batchGet?names=stores/{store}/subscription-plans/{plan1}/subscriptions/{subscription1}&names=stores/{store}/subscription-plans/{plan2}/subscriptions/{subscription2}" \
  -H "Authorization: Bearer CONFIO_ACCESS_TOKEN"

También puedes reemplazar - por un {plan} concreto para limitar toda la solicitud a ese plan. Ejemplo de respuesta:

{
  "subscriptions": [
    {
      "name": "stores/01JNRRDZDPH40DB2YRW329BFXM/subscription-plans/01JNRVWWHH68E76V3TMFFT6GHJ/subscriptions/01K0ABCDEF1234567890XYZ",
      "status": "ACTIVE"
    },
    {
      "name": "stores/01JNRRDZDPH40DB2YRW329BFXM/subscription-plans/01JNRWXYZH68E76V3TMFFT6AAA/subscriptions/01K0GHIJKL1234567890XYZ",
      "status": "PAST_DUE"
    }
  ]
}

Las suscripciones se devuelven en el mismo orden de los names de la solicitud y con la misma representación que la consulta individual (el ejemplo omite campos por brevedad).
La respuesta no es paginada.
Debes enviar entre 1 y 100 names, sin repetir suscripciones (un identificador y el name de la misma suscripción cuentan como repetidos). De lo contrario, la API responde 400.
Todas las suscripciones deben pertenecer a la tienda de la ruta. Si indicas un plan concreto, también deben pertenecer a ese plan; de lo contrario, la API responde 400.
La operación es atómica: si alguna suscripción no existe o no pertenece al alcance indicado, la solicitud completa falla con 404 y no se devuelve ninguna suscripción.

Cancelar una suscripción

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 1, cobro inicial del ciclo
2	Día 2
3	Día 3
4	Día 4

Los cobros se procesan en ventanas programadas, por lo que la hora exacta puede variar. 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

Guarda el name del plan y de la suscripción en tu sistema.
Envía el acceptanceUrl al comprador tan pronto crees la suscripción.
Usa webhooks como fuente principal de sincronización.
Usa GET, List y la consulta por lotes como mecanismos de conciliación.
Diseña tu procesamiento de webhooks para ser idempotente.
No recolectes datos de tarjeta ni intentes aceptar suscripciones desde tu backend.

Getting Started

Developer Guides

Partners Guide

Descripción general del proceso

Requisitos previos

Conceptos clave

Plan de suscripción

Suscripción

Estados de una suscripción

Paso 1: obtener la tienda

Paso 2: crear un plan de suscripción

Paso 3: crear una suscripción para el comprador

Sobre `firstChargeAmountCents`

Paso 4: enviar el enlace de aceptación

Paso 5: sincronizar estados con webhooks

Consultar suscripciones

Consultar una suscripción

Listar suscripciones de una tienda

Consultar varias suscripciones

Cancelar una suscripción

Reintentos de cobro

Errores comunes

Mejores prácticas

Recursos adicionales

​Descripción general del proceso

​Requisitos previos

​Conceptos clave

​Plan de suscripción

​Suscripción

​Estados de una suscripción

​Paso 1: obtener la tienda

​Paso 2: crear un plan de suscripción

​Paso 3: crear una suscripción para el comprador

​Sobre firstChargeAmountCents

​Paso 4: enviar el enlace de aceptación

​Paso 5: sincronizar estados con webhooks

​Consultar suscripciones

​Consultar una suscripción

​Listar suscripciones de una tienda

​Consultar varias suscripciones

​Cancelar una suscripción

​Reintentos de cobro

​Errores comunes

​Mejores prácticas

​Recursos adicionales

Descripción general del proceso

Requisitos previos

Conceptos clave

Plan de suscripción

Suscripción

Estados de una suscripción

Paso 1: obtener la tienda

Paso 2: crear un plan de suscripción

Paso 3: crear una suscripción para el comprador

Sobre `firstChargeAmountCents`

Paso 4: enviar el enlace de aceptación

Paso 5: sincronizar estados con webhooks

Consultar suscripciones

Consultar una suscripción

Listar suscripciones de una tienda

Consultar varias suscripciones

Cancelar una suscripción

Reintentos de cobro

Errores comunes

Mejores prácticas

Recursos adicionales