Crear link de suscripción

Esta sección detalla el uso del endpoint para generar un link de pago de suscripción, una forma de pago que permite realizar un cobro inicial único al cliente, configurando automáticamente los pagos mensuales por el número de meses definidos. Esto garantiza que el cliente no tenga que preocuparse por realizar los pagos manualmente en cada ciclo.

Detalles del endpoint

Método: POST
URL: /api/v1/links/subscription

El endpoint permite generar un link de pago para suscripciones mediante el envío de datos específicos del plan y la API Key.

Configuración de la solicitud

Headers

Header	Descripción
`X-API-KEY`	API Key generada en Cubo Admin.

Si aún no has generado tu API Key, revisa nuestra sección de autenticación.

Cuerpo de la solicitud

Parámetro	Tipo	Descripción
`description`	`string`	Descripción de la suscripción.
`amount`	`number`	Cantidad de dinero a pagar.
`installments`	`number`	Cantidad de cuotas mensuales en las que se dividirá el pago.
`redirectUri`	`string`	URL a la que se redirigirá al usuario tras completar el pago.

💡

El campo amount siempre debe enviarse como un número entero en centavos.

A continuación se muestra un ejemplo de la solicitud en formato JSON:


{
  "description": "Test Subscription",
  "amount": 10000, // Monto en centavos (10000 = $100)
  "installments": 12,
  "redirectUri": "https://example.com"
}

Suscripción sin vencimiento

Es posible generar un link de pago de suscripción sin fecha de vencimiento, lo que permite que los cobros mensuales al cliente se realicen de manera indefinida hasta que se cancele manualmente la suscripción.

Para lograr esto, simplemente debes enviar el campo installments con el valor null en el cuerpo de la solicitud. Esto le indica al sistema que la suscripción no tiene una duración definida y continuará generando cargos mensuales de forma automática.


{
  "description": "Suscripción sin vencimiento",
  "amount": 10000,
  "installments": null,
  "redirectUri": "https://example.com"
}

Este tipo de suscripción es ideal para servicios que se ofrecen de manera continua, como membresías o plataformas de contenido.

Ejemplos de uso

JavaScript


fetch('https://api.cubo.com/api/v1/links/subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'TU_API_KEY_AQUI',
  },
  body: JSON.stringify({
    description: 'Test Subscription',
    amount: 1000,
    installments: 12,
    redirectUri: 'https://example.com'
  }),
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Respuestas del servidor

✅ Respuesta exitosa

Indica que el link de suscripción fue generado exitosamente.


{
  "paymentIntentToken": "INTENT_TOKEN",
  "description": "Test Subscription",
  "amount": "100.00",
  "currency": {
    "iso": "USD",
    "symbol": "$",
    "decimalSeparator": ".",
    "thousandsSeparator": ","
  },
  "installments": 12,
  "startingDate": "2025-03-12T18:16:25.480Z",
  "endingDate": "2025-03-12T18:16:25.480Z",
  "cuboRedirectUri": "https://cubo-payment-link.com/INTENT_TOKEN"
}

❌ Respuesta de error

Indica que no fue posible generar el link de suscripción.


{
  "statusCode": 400,
  "message": ["Error en la solicitud"],
  "error": "Bad Request"
}

Webhook de notificación

Cuando se procesa un pago a través de un link de suscripción en nuestra API, enviaremos una notificación al webhook que hayas configurado en la sección Developers de Cubo Admin. Esta notificación contendrá información clave sobre el estado del pago y otros datos relevantes, permitiendo a tu sistema realizar las acciones necesarias de acuerdo al resultado del proceso.

Para más detalles, te recomendamos visitar la sección:

Aprende a configurar tu Webhook