Skip to main content
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.

​
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

EstadoDescripción
PENDING_ACCEPTANCELa suscripción fue creada y espera que el comprador acepte los términos y registre su tarjeta.
ACTIVELa suscripción está activa y los cobros se procesan normalmente.
TRIALINGLa suscripción está en período de prueba. El primer cobro recurrente se realizará al finalizar el trial.
PAST_DUEUn cobro falló. Confío reintentará automáticamente según la política de reintentos.
SUSPENDEDSe agotaron los intentos de cobro del ciclo o el método de pago requiere intervención.
CANCELEDLa 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:
  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 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.

​
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.
IntentoMomento aproximado
1Día 0, cobro inicial del ciclo
2Día 2
3Día 5
4Dí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