Skip to main content

​
¿Qué es una Suscripción?

Una suscripción automatiza cobros recurrentes a un cliente. Se crea asociando un cliente a un plan con un método de pago autorizado (tarjeta o cuenta bancaria).
Antes de crear una suscripción, necesitas:
  1. Un cliente registrado
  2. Un plan configurado con monto y frecuencia
  3. Una tarjeta o cuenta bancaria autorizada

​
Ejemplo Rápido

​
Paso 1: Crear un plan

curl https://api.onepay.la/v1/plans \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Premium Mensual",
    "amount": 50000,
    "currency": "COP",
    "cycle_frequency": 1,
    "cycle_type": "monthly"
  }'
Respuesta: 
{
  "id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "name": "Plan Premium Mensual",
  "amount": 50000,
  "currency": "COP",
  "cycle_frequency": 1,
  "cycle_type": "monthly"
}

​
Paso 2: Crear una suscripción

curl https://api.onepay.la/v1/subscriptions \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: subscription-001" \
  -d '{
    "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "plan_id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "card_id": "9e01eeae-2868-4564-9d04-84d1d1d027d2"
  }'
Respuesta: 
{
  "id": "9e5a2b3c-1234-5678-9abc-def012345678",
  "status": "ACTIVE",
  "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
  "plan_id": "9e5a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "card_id": "9e01eeae-2868-4564-9d04-84d1d1d027d2",
  "next_billing_date": "2025-03-08T00:00:00.000000Z",
  "created_at": "2025-02-08T15:45:00.000000Z"
}
OnePay cobrará automáticamente $50.000 cada mes al método de pago autorizado.

​
¿Cuándo usar Suscripciones?

EscenarioSolución
Cobro único o esporádicoUsa Payments o Charges
Cobro recurrente con monto fijoCrea un plan + suscripción
Membresías mensuales/anualesCrea un plan + suscripción
Cobro recurrente con monto variableUsa Charges con tu propia lógica de recurrencia

​
Relación Plan - Suscripción

Un plan es la plantilla (monto, frecuencia) y una suscripción es la instancia asociada a un cliente específico. 
Plan "Premium $50.000/mes"
  ├── Suscripción de Cliente A (activa)
  ├── Suscripción de Cliente B (activa)
  └── Suscripción de Cliente C (cancelada)

​
Estados de una suscripción

EstadoDescripción
CREATEDSuscripción creada, pendiente del primer pago
ACTIVEPagos al día, cobros automáticos activos
UNPAIDÚltimo pago fallido, se reintentará según configuración
PASS_DUETodos los reintentos fallaron
FROZENPausada temporalmente a petición del cliente
CANCELEDCancelada definitivamente
FINISHEDCompletó su vigencia

​
Endpoints

MétodoEndpointDescripción
POST/subscriptionsCrear suscripción
GET/subscriptionsListar suscripciones
GET/subscriptions/Detalle de una suscripción
DELETE/subscriptions/Cancelar suscripción