Crear suscripción

Crea una suscripción recurrente asociada a un cliente.

POST https://api.onepay.la/v1/subscriptions

Crear suscripción

cURL

curl --request POST \
  --url https://api.onepay.la/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency: <x-idempotency>' \
  --data '
{
  "customer_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "currency": "<string>",
  "amount_in_cents": 123,
  "reference_price_in_cents": "<string>",
  "cicle_frequency": "<string>",
  "cicles": 123,
  "start_date": "<string>",
  "internal_id": "<string>",
  "plan_id": "<string>",
  "payment_mode": "<string>",
  "suggest_auto_debit": true,
  "remember_to_pay_before": 123,
  "cancel_after_no_payment_before": 123,
  "metadata": {},
  "trial": {
    "trial.has_trial": true,
    "trial.trial_days": 123,
    "trial.start_trial_date": "<string>"
  },
  "complex_payments": [
    {
      "complex_payments[].amount_in_cents": 123,
      "complex_payments[].apply_on_cicle": 123,
      "complex_payments[].for_cicles": 123,
      "complex_payments[].label": "<string>",
      "complex_payments[].target_price": "<string>"
    }
  ],
  "allows": {
    "cards": true,
    "accounts": true,
    "wallets": true,
    "card_extra": true,
    "realtime": true,
    "pse": true,
    "full_extra": true,
    "pse_debit": true,
    "breb": true
  }
}
'

201

{
  "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": "[e-mail]",
    "phone": "[phone]",
    "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.

Show Propiedades

trial.has_trial · boolean · default: false

Activa o desactiva el trial.

trial.trial_days · number

Número de días del periodo de prueba.

trial.start_trial_date · date

Fecha desde la que se debe contar el trial.

complex_payments · array

Pagos con valores especiales por ciclo (ej. matrículas o cargos iniciales).

Show items

complex_payments[].amount_in_cents · number

Valor que se cobrará en el ciclo indicado.

complex_payments[].apply_on_cicle · number

Ciclo en el que aplica este pago.

complex_payments[].for_cicles · number

Cantidad de ciclos que usarán este monto.

complex_payments[].label · string

Texto descriptivo.

complex_payments[].target_price · string

Precio base esperado para el ciclo posterior.

allows · object

Configuración de métodos de pago permitidos.

Show properties

cards · boolean · default: true

Permite pagos con tarjetas.

accounts · boolean · default: true

Permite pagos con cuentas bancarias.

wallets · boolean · default: true

Permite pagos con billeteras digitales.

card_extra · boolean · default: false

El usuario pagador debe de asumir un costo extra en la transacción aprox. 2.65%

realtime · boolean · default: false

Permite pagos en tiempo real.

pse · boolean · default: true

Permite pagos a través de PSE.

full_extra · boolean · default: false

El usuario pagador asume el costo completo de la transacción.

pse_debit · boolean · default: false

Permite débitos automáticos a través de PSE.

breb · boolean · default: true

Permite pagos a través de BREB (transferencias bancarias).

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.

201

{
  "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": "[e-mail]",
    "phone": "[phone]",
    "document": "1234567890",
    "document_type": "RUT"
  }
}