Introducción - OnePay Documentación

¿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:

Un cliente registrado
Un plan configurado con monto y frecuencia
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?

Escenario	Solución
Cobro único o esporádico	Usa Payments o Charges
Cobro recurrente con monto fijo	Crea un plan + suscripción
Membresías mensuales/anuales	Crea un plan + suscripción
Cobro recurrente con monto variable	Usa 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

Estado	Descripción
`CREATED`	Suscripción creada, pendiente del primer pago
`ACTIVE`	Pagos al día, cobros automáticos activos
`UNPAID`	Último pago fallido, se reintentará según configuración
`PASS_DUE`	Todos los reintentos fallaron
`FROZEN`	Pausada temporalmente a petición del cliente
`CANCELED`	Cancelada definitivamente
`FINISHED`	Completó su vigencia

Endpoints

Método	Endpoint	Descripción
`POST`	/subscriptions	Crear suscripción
`GET`	/subscriptions	Listar suscripciones
`GET`	/subscriptions/	Detalle de una suscripción
`DELETE`	/subscriptions/	Cancelar suscripción

​¿Qué es una Suscripción?

​Ejemplo Rápido

​Paso 1: Crear un plan

​Paso 2: Crear una suscripción

​¿Cuándo usar Suscripciones?

​Relación Plan - Suscripción

​Estados de una suscripción

​Endpoints