Crear link de pago único

Esta sección detalla el uso del endpoint para generar un link de pago de una sola vez, una solución rápida para cobrar un monto específico al cliente.

Detalles del endpoint

• Método: POST
• URL: /api/v1/links/one-use

Este endpoint genera un link de pago único que puede compartirse con el cliente para completar un pago puntual.

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

Meses sin intereses

Puedes ofrecer pagos a meses sin intereses agregando el campo monthlyInstallmentId en tu solicitud. Este campo recibe el id del plan de cuotas que deseas aplicar.

Para consultar los planes disponibles y sus montos mínimos, utiliza el endpoint de meses sin intereses.

Información del cliente

Puedes precargar los datos del cliente en el link de pago para agilizar el checkout. Todos estos campos son opcionales.

Sección de checkout

Para ofrecer una experiencia de pago más clara y confiable, ahora puedes mostrar a tus clientes el detalle de los productos que van a pagar directamente en el link de pago. Solo necesitas agregar un array llamado items en tu request, con el nombre, precio y cantidad de cada producto. De esta forma, tus clientes verán exactamente qué está comprando.

Cada elemento del array items representa un producto con los siguientes campos:

• name (string): Nombre del producto que se está vendiendo.
• price (string): Precio unitario en formato "15.00".
• quantity (number): Cantidad de unidades.
• url (string opcional): URL de la imagen del producto.

A continuación se muestra un ejemplo completo del cuerpo de la solicitud:

{
  "description": "Test Link",
  "amount": 8000,
  "redirectUri": "https://example.com",
  "clientName": "John Doe", // opcional
  "clientEmail": "[email protected]", // opcional
  "clientPhone": "+50322577777", // opcional
  "items": [
    {
      "name": "Camiseta básica unisex",
      "price": "15.00",
      "quantity": 1,
      "url": "https://example.com"
    },
    {
      "name": "Pantalón jogger deportivo",
      "price": "32.50",
      "quantity": 2,
      "url": "https://example.com"
    }
  ],
  "metadata": {
    "orderId": "12345"
    // otros datos de referencia
  },
  "monthlyInstallmentId": 3 // opcional: ID del plan de meses sin intereses
}

Esta es la forma en que se mostrarán los productos en los links de pago que envíes a tus clientes:

Ejemplos de uso

fetch('https://<CUBO_API_URL>/api/v1/links/one-use', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'TU_API_KEY_AQUI',
  },
  body: JSON.stringify({
    description: 'Test Link',
    amount: 8000,
    redirectUri: 'https://example.com',
    clientName: 'John Doe', // opcional
    clientEmail: '[email protected]', // opcional
    clientPhone: '+50322577777', // opcional
    items: [
      {
        name: 'Camiseta básica unisex',
        price: '15.00',
        quantity: 1,
        url: 'https://example.com'
      },
      {
        name: 'Pantalón jogger deportivo',
        price: '32.50',
        quantity: 2,
        url: 'https://example.com'
      }
    ],
    metadata: {
      orderId: '12345'
      // otros datos de referencia
    },
    monthlyInstallmentId: 3, // opcional
  }),
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

curl --location '/api/v1/links/one-use' \
--header 'X-API-KEY: TU_API_KEY_AQUI' \
--data-raw '{
    "description": "Test Link",
    "amount": 8000,
    "redirectUri": "https://example.com",
    "clientName": "John Doe",
    "clientEmail": "[email protected]",
    "clientPhone": "+50322577777",
    "items": [
      {
        "name": "Camiseta básica unisex",
        "price": "15.00",
        "quantity": 1,
        "url": "https://example.com"
      },
      {
        "name": "Pantalón jogger deportivo",
        "price": "32.50",
        "quantity": 2,
        "url": "https://example.com"
      }
    ],
    "metadata": {
      "orderId": "12345"
    },
    "monthlyInstallmentId": 3
  }'

Respuestas del servidor

✅ Respuesta exitosa

Indica que el link fue generado exitosamente:

{
  "paymentIntentToken": "881KOEOTD",
  "description": "Test Link",
  "amount": "80.00",
  "currency": {
    "iso": "USD",
    "symbol": "$",
    "decimalSeparator": ".",
    "thousandsSeparator": ","
  },
  "items": [
    {
      "name": "Camiseta básica unisex",
      "price": "15.00",
      "quantity": 1,
      "url": "https://example.com"
    },
    {
      "name": "Pantalón jogger deportivo",
      "price": "32.50",
      "quantity": 2,
      "url": "https://example.com"
    }
  ],
  "startingDate": "2026-03-18T00:00:00.000Z",
  "endingDate": "2026-03-18T00:00:00.000Z",
  "cuboRedirectUri": "https://link.cubopago.com/881KOEOTD"
}

❌ Respuesta de error

{
  "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 único 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: