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

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

Cuerpo de la solicitud

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"
}

Ejemplos de uso

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));

curl --location '/api/v1/links/subscription' \
--header 'X-API-KEY: TU_API_KEY_AQUI' \
--data-raw '{
"description": "Test Subscription",
"amount": 1000,
"installments": 12,
"redirectUri": "https://example.com"
}'

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

¿Qué es un Webhook?

Un webhook es una URL configurada en tu aplicación que recibe notificaciones automáticas cuando ocurre un evento específico.

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.

Configuración del Webhook

Ingresa a Cubo Admin

Dirígete a la sección Developers

Da clic sobre el recuadro donde se muestra la información de tu API Key.
(Si aún no tienes tu API Key, revisa nuestra sección de autenticación.)

Se mostrará una ventana emergente, donde debes seleccionar la opción “Agregar Webhook”.

Agrega tu Webhook

Ingresa la URL donde deseas recibir la información del pago y da clic en “Confirmar”.

Payload

A continuación se detalla el payload que recibirás en el webhook. Este incluye los campos y datos relevantes que tu aplicación deberá procesar. Cada campo se describe con su nombre, tipo de dato y una breve explicación de su función para facilitar la integración.

Este es un ejemplo de cómo se vería la información en formato JSON, reflejando los datos clave de la transacción:

{
  "identifier": "RHBKY73PZ",
  "status": "SUCCEEDED",
  "referenceId": "355069574072669",
  "authorizationCode": "007194",
  "processedAt": "2025-03-10T09:56:47.228Z",
  "paymentType": "LINK-SUBSCRIPTION",
  "amount": 1000,
  "metadata": null
}