Skip to main content
POST
/
subscriptions
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",
    "name": "Plan Premium Mensual",
    "description": "<p>Acceso completo a todas las funcionalidades</p>",
    "currency": "COP",
    "amount_in_cents": 44900000,
    "reference_price_in_cents": "44900000",
    "cicle_frequency": "monthly",
    "cicles": null,
    "start_date": "2025-03-01T00:00:00Z",
    "payment_mode": "request",
    "suggest_auto_debit": true,
    "remember_to_pay_before": 3,
    "cancel_after_no_payment_before": 2,
    "trial": {
      "has_trial": true,
      "trial_days": 14,
      "start_trial_date": "2025-02-15T00:00:00Z"
    },
    "metadata": {
      "salesforce_id": "OP-554",
      "plan_type": "premium"
    }
  }'

{
  "id": "9f01f541-7d9c-4f62-88c1-0b0f2c2d4c31",
  "name": "OnePay Pro",
  "status": "created",
  "description": "<p>Plan mensual con onboarding asistido</p>",
  "internal_id": "SaaSSpectre",
  "plan_id": null,
  "coupon_id": null,
  "reference_price_in_cents": "44900000",
  "currency": "COP",
  "amount_in_cents": 44900000,
  "cicle_frequency": "monthly",
  "cicles": null,
  "current_cicle": 0,
  "allows": {
    "cards": true,
    "accounts": true,
    "card_extra": false,
    "realtime": false,
    "pse": true,
    "transfiya": true
  },
  "suggest_auto_debit": true,
  "start_date": "2025-01-05T00:00:00.000000Z",
  "end_date": null,
  "payment_mode": "request",
  "trial": {
    "has_trial": false,
    "start_trial_date": null,
    "trial_days": 0
  },
  "remember_to_pay_before": 3,
  "cancel_after_no_payment_before": 2,
  "complex_payments": [],
  "features": [],
  "metadata": {
    "salesforce_id": "OP-554"
  },
  "created_at": "2025-01-02T19:24:48.000000Z",
  "updated_at": "2025-01-02T19:24:48.000000Z",
  "customer": {
    "id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "first_name": "Empresa",
    "last_name": "SAS",
    "email": "empresa@empresa.com",
    "phone": "+573221234567",
    "document": "1234567890",
    "document_type": "RUT"
  }
}

​
Headers

​
x-idempotency
string
required
Token único para garantizar la idempotencia de la petición

​
Body

​
customer_id
string
required
ID del cliente que asumirá los cobros. Crea primero el cliente.
​
name
string
required
Nombre público de la suscripción.
​
description
string
Descripción rica que se mostrará en correos y facturas.
​
currency
string
default:"COP"
required
Moneda en formato ISO-4217. Actualmente soportamos COP.
​
amount_in_cents
number
required
Valor a cobrar en cada ciclo expresado en centavos.
​
reference_price_in_cents
string
Precio de referencia que se mostrará en UI. Puede diferir del amount_in_cents cuando usas pagos complejos.
​
cicle_frequency
string
required
Frecuencia: daily, weekly, monthly, annual.
​
cicles
number
Número máximo de ciclos. Usa null para renovaciones indefinidas.
​
start_date
date
Fecha en la que deseas iniciar los cobros. Si se omite se usa la fecha actual.
​
internal_id
string
Identificador que usas en tus sistemas.
​
plan_id
string
ID del plan preconfigurado que deseas usar. Ver cómo crear planes.
​
payment_mode
string
default:"request"
Define si se cobrará automáticamente (auto_debit) o vía solicitudes (request).
​
suggest_auto_debit
boolean
default:false
Si es true, el checkout sugerirá activar débito automático.
​
remember_to_pay_before
number
Días de anticipación para recordatorios de pago.
​
cancel_after_no_payment_before
number
Número de ciclos consecutivos fallidos antes de cancelar la suscripción.
​
metadata
object
Pares clave/valor para enriquecer la suscripción.
​
trial
object
Configuración del periodo de prueba.
​
complex_payments
array
Pagos con valores especiales por ciclo (ej. matrículas o cargos iniciales).
​
allows
object
Configuración de métodos de pago permitidos.
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",
    "name": "Plan Premium Mensual",
    "description": "<p>Acceso completo a todas las funcionalidades</p>",
    "currency": "COP",
    "amount_in_cents": 44900000,
    "reference_price_in_cents": "44900000",
    "cicle_frequency": "monthly",
    "cicles": null,
    "start_date": "2025-03-01T00:00:00Z",
    "payment_mode": "request",
    "suggest_auto_debit": true,
    "remember_to_pay_before": 3,
    "cancel_after_no_payment_before": 2,
    "trial": {
      "has_trial": true,
      "trial_days": 14,
      "start_trial_date": "2025-02-15T00:00:00Z"
    },
    "metadata": {
      "salesforce_id": "OP-554",
      "plan_type": "premium"
    }
  }'

​
Response

​
id
string
Identificador único de la suscripción (UUID).
​
name
string
Nombre comercial de la suscripción.
​
status
string
Estado actual (active, unpaid, pass_due, canceled, finished, frozen).
​
description
string
Descripción enriquecida (puede contener HTML).
​
internal_id
string
Identificador interno que usas en tu sistema.
​
plan_id
string
ID del plan asociado, si aplica.
​
coupon_id
string
ID del cupón aplicado.
​
reference_price_in_cents
string
Precio de referencia en centavos como string.
​
currency
string
Moneda en formato ISO-4217 (ej. COP).
​
amount_in_cents
number
Valor base cobrado en cada ciclo.
​
cicle_frequency
string
Frecuencia de cobro: weekly, monthly, annual, etc.
​
cicles
number
Cantidad máxima de ciclos; null para indefinido.
​
current_cicle
number
Ciclo actual procesado.
​
allows
object
Configuración de métodos de pago permitidos para la suscripción.
​
suggest_auto_debit
boolean
Indica si se sugiere activar débito automático durante el onboarding del cliente.
​
start_date
date
Fecha programada de inicio.
​
end_date
date
Fecha de finalización si aplica.
​
trial
object
Información de periodo de prueba (has_trial, trial_days, start_trial_date).
​
payment_mode
string
Modo de cobro (request, auto_debit, etc.).
​
remember_to_pay_before
number
Días de anticipación para recordatorios de pago.
​
cancel_after_no_payment_before
number
Número de ciclos fallidos antes de cancelar automáticamente.
​
complex_payments
array
Pagos con valores diferenciados por ciclo.
​
metadata
object
Atributos personalizados que acompañan la suscripción.
​
customer
object
Resumen del cliente asociado.
​
plan
object
Información del plan enlazado, cuando existe.
​
created_at
date
Fecha de creación de la suscripción.
​
updated_at
date
Fecha de última actualización.
{
  "id": "9f01f541-7d9c-4f62-88c1-0b0f2c2d4c31",
  "name": "OnePay Pro",
  "status": "created",
  "description": "<p>Plan mensual con onboarding asistido</p>",
  "internal_id": "SaaSSpectre",
  "plan_id": null,
  "coupon_id": null,
  "reference_price_in_cents": "44900000",
  "currency": "COP",
  "amount_in_cents": 44900000,
  "cicle_frequency": "monthly",
  "cicles": null,
  "current_cicle": 0,
  "allows": {
    "cards": true,
    "accounts": true,
    "card_extra": false,
    "realtime": false,
    "pse": true,
    "transfiya": true
  },
  "suggest_auto_debit": true,
  "start_date": "2025-01-05T00:00:00.000000Z",
  "end_date": null,
  "payment_mode": "request",
  "trial": {
    "has_trial": false,
    "start_trial_date": null,
    "trial_days": 0
  },
  "remember_to_pay_before": 3,
  "cancel_after_no_payment_before": 2,
  "complex_payments": [],
  "features": [],
  "metadata": {
    "salesforce_id": "OP-554"
  },
  "created_at": "2025-01-02T19:24:48.000000Z",
  "updated_at": "2025-01-02T19:24:48.000000Z",
  "customer": {
    "id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "first_name": "Empresa",
    "last_name": "SAS",
    "email": "empresa@empresa.com",
    "phone": "+573221234567",
    "document": "1234567890",
    "document_type": "RUT"
  }
}