Generar Plan

Crea un nuevo plan de cobro recurrente. A través de este endpoint defines las condiciones económicas (monto, moneda, frecuencia, número de cobros) y de comportamiento (reintentos, campos personalizados del formulario de vinculación) que aplicarán a todos los clientes que se suscriban a este plan.

Endpoint

POST {{base_url}}/plan

Headers

Name	Value
Content-Type*	application/json
x-auth-token*	{token}
child-id	{business_id}

El child-id es opcional y se usa para las cuentas administradas para conocer más puedes ingresa a este enlace.

Body

Información general

Campos base para la identificación del plan y del comercio que lo crea.

Campo	Tipo	Obligatorio	Descripción
merchant_id_number	String	Sí	Número de documento del cobrador o responsable del plan. Ejemplo: 12345678
name	String	Sí	Nombre visible del plan. Ejemplo: Servicio mensual
plan_details.currency	String	Sí	Código de la divisa del cobro bajo el estándar ISO 4217. COP | USD
plan_details.amount	Number	Sí	Monto fijo de cada cobro. El cliente no puede modificarlo. Ejemplo: 54000.85
plan_details.description	String	No	Texto visible durante la vinculación y en el comprobante. Admite variables dinámicas, como {{charge_number}} y {{month}}. Consulte Términos de relevancia. Ejemplo: Cuota {{charge_number}} - Servicio
plan_details.frequency	String	Sí	Frecuencia en la que se ejecutará el cobro. monthly | biweekly | weekly
plan_details.trial_days	Integer	No	Número de días de gracia antes del primer cobro. Si trial_days > 0, no se realiza un cobro inmediato. El primer cobro se programa para la fecha actual más el número de días indicado. ℹ️ Predeterminado: 0. ⚠️ trial_days tiene prioridad sobre billing_day.
plan_details.billing_day	Integer	No	Día del mes en que debe realizarse el primer cobro. Si billing_day = 0 o no se envía, el cobro se realiza inmediatamente. Si billing_day tiene un valor entre 1 y 30, el primer cobro se programa para ese día del mes. ℹ️ Predeterminado: 0. Ejemplo: 4
plan_details.total_charges	Integer	No	Número máximo de cobros del plan. Admite valores entre 1 y 12. ℹ️ Predeterminado: 12.
plan_details.expires_at	Date	No	Fecha límite para aceptar nuevas suscripciones a este plan. ℹ️ Si se omite, el plan acepta nuevas suscripciones sin límite de tiempo.
plan_details.retry.max_attempts	Integer	No	Número de reintentos antes de aplicar status_after_retry. El máximo es 3. ℹ️ Predeterminado: 1.
plan_details.retry.interval_days	Integer	No	Número de días entre cada reintento. ℹ️ Predeterminado: 1.
plan_details.retry.final_status	String	No	Estado de la suscripción después de agotar los reintentos. ℹ️ Predeterminado: OVERDUE. ACTIVE | OVERDUE | CANCELED

Configuración adicional

Define la redirección posterior a la vinculación y los campos que se muestran en el formulario.

Campo	Tipo	Obligatorio	Descripción
return_url	String	No	Enlace al que se redirige automáticamente al cliente después de vincular su medio de pago. Ejemplo: https://comercio.com/exito
custom_webhook	String	No	Si necesitas que los eventos de esta transacción en específico (como el éxito o fallo del pago) se notifiquen a una URL distinta a la que configuraste globalmente, envía aquí tu enlace personalizado. Ejemplo: https://miwebhook.com/status
form_fields.image_url	String	No	URL de la imagen visible para el plan, cuando aplique. Ejemplo: https://comercio.com/plan.png
form_fields.field_one a form_fields.field_six	Object	No	Campos adicionales del formulario. Puede definir hasta seis campos con la misma estructura que se guardaran en la referencia del cobro respectivamente. field_one | field_two | field_three | field_four | field_five | field_six
form_fields.field_*.type	String	Sí	Tipo de campo que se muestra en el formulario. text | number | list
form_fields.field_*.label	String	Sí	Nombre que identifica el campo para el cliente. Ejemplo: Tipo de servicio
form_fields.field_*.is_visible	Boolean	Sí	Define si el campo se muestra en el formulario. true | false
form_fields.field_*.is_required	Boolean	Sí	Define si el campo es obligatorio para el cliente. true | false
form_fields.field_*.options	Array	Condicional	Opciones disponibles para el cliente. ⚠️ Requerido cuando type es list. Ejemplo: ["Básico", "Premium"]
form_fields.field_*.default_value	String	No	Valor inicial del campo. Ejemplo: ""

---

Response

200

{
  "plan_id": "A1A2A3A4",
  "name": "Plan de Suscripción de Ejemplo",
  "status": "active",
  "expires_at": "2027-12-31",
  "plan_url": "https://{host}/p/abc123",
  "created_at": "2026-06-28T15:30:00Z"
}

400

{
  "error": {
    "type": "bad_request",
    "message": "The request contains invalid or incomplete data.",
    "details": [
      {
        "field": "payment_policy.total_charges",
        "message": "total_charges must be between 1 and 12."
      }
    ]
  }
}

401

{
  "error": {
    "type": "unauthorized",
    "message": "Authentication failed."
  }
}

---

Ejemplo

cURL

curl -X POST "{{base_url}}/plan" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: YOUR_SECRET_TOKEN" \
  -d '{
    "merchant_id_number": "12345678",
    "name": "Plan Premium",
    "plan_details": {
      "currency": "COP",
      "amount": 150000,
      "description": "Cobro {{charge_number}} - {{month}}",
      "frequency": "monthly",
      "billing_day": 5,
      "total_charges": 6,
      "initial_charge": true,
      "trial_days": 7,
      "expires_at": "2026-09-12",
      "retry": {
        "max_attempts": 3,
        "interval_days": 2,
        "final_status": "OVERDUE"
      }
    },
    "form_fields": {
      "field_one": {
        "type": "list",
        "label": "Tipo de servicio",
        "is_visible": true,
        "is_required": true,
        "options": ["Básico", "Premium"],
        "default_value": "Premium"
      },
      "field_two": {
        "type": "text",
        "label": "Documento de identidad",
        "is_visible": true,
        "is_required": true,
        "default_value": ""
      }
    },
    "return_url": "https://comercio.com/pagos/resultado",
    "custom_webhook": "https://comercio.com/pagos/webhook"
  }'