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

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

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://api.cubo.com/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',
    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"
      }
    ]
  }),
})
.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",
    "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"
      }
    ]
  }'

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"
    },
  ],
  "cuboRedirectUri": "https://cubo-payment-link.com/INTENT_TOKEN"
}

❌ 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: