Enlaces de un solo uso

Los enlaces de un solo uso crean una sesión de Checkout directa para un cobro fijo. Usalos cuando ya conocés el monto final y querés enviar una URL de pago al comprador.

Para donaciones, propinas o cobros donde el comprador escoge el monto, usá El cliente elige qué pagar.

Referencia API relacionada

• Crear una sesión de Checkout
• Listar sesiones de Checkout
• Expirar una sesión de Checkout
• Crear un cupón
• Listar cupones

Crear una sesión con monto fijo

El endpoint recibe lineItems. Cada item puede usar un priceId existente o crear un producto inline con unitAmount, currency y description. Los montos se envían en la unidad menor de la moneda.

curl https://api.onvopay.com/v1/checkout/sessions/one-time-link \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      {
        "quantity": 1,
        "unitAmount": 250000,
        "currency": "CRC",
        "description": "Orden #1001"
      }
    ],
    "customerEmail": "comprador@example.com",
    "redirectUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "discounts": [
      {
        "coupon": "cpn_abc123"
      }
    ],
    "metadata": {
      "orderId": "1001"
    }
  }'

La respuesta incluye url. Redirigí al comprador a esa URL o enviala por el canal que use tu flujo de venta.

Cupones para enlaces de un solo uso

Podés crear cupones desde el dashboard o desde la API:

• En el dashboard, entrá a Descuentos y creá el cupón con el formulario visual. Es útil para campañas operadas por equipos comerciales o de soporte.
• En la API, creá el cupón con POST /v1/coupons. Es útil para campañas generadas desde tu backend, integraciones internas o cargas masivas.

Ambos caminos crean el mismo objeto Coupon. Para usarlo en un enlace de un solo uso, guardá el id del cupón y envialo en discounts cuando creás la sesión de Checkout.

Flujo recomendado

1. Creá el cupón en el dashboard o con la API.
2. Configurá sus reglas: tipo de descuento, límite de usos, fecha de vencimiento y BINs elegibles.
3. Creá el enlace de un solo uso con discounts: [{ "coupon": "cpn_..." }].
4. Checkout aplica el descuento durante el pago cuando la tarjeta del comprador coincide con una regla de BIN activa.

Crear un cupón con la API

Este ejemplo crea un cupón de 10% para tarjetas cuyo BIN empieza con 411111.

curl https://api.onvopay.com/v1/coupons \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Banco Sponsor 10%",
    "type": "percentage",
    "percentOff": 10,
    "scope": "checkout_session",
    "appliesTo": ["one_time_links"],
    "maxRedemptions": 100,
    "redeemBy": "2026-06-30",
    "binRules": [
      {
        "bin": "411111"
      }
    ]
  }'

La respuesta incluye el id del cupón. Usá ese valor en el payload del enlace:

{
  "discounts": [
    {
      "coupon": "cpn_abc123"
    }
  ]
}

Atributos principales

Atributo	Para qué sirve
name	Nombre interno para identificar el cupón en el dashboard, reportes y respuestas de Checkout.
type	Define si el descuento es percentage o fixed_amount.
percentOff	Porcentaje a descontar cuando type es percentage. Debe ser mayor que 0 y como máximo 100.
amountOff	Monto fijo a descontar cuando type es fixed_amount. Se envía en la unidad menor de la moneda.
currency	Moneda requerida para cupones fixed_amount. Debe coincidir con la moneda del enlace.
scope	Alcance del cupón. Para enlaces de un solo uso usá checkout_session. Si lo omitís, ONVO usa ese valor por defecto.
appliesTo	Lista de superficies donde aplica. Para estos enlaces incluí one_time_links. Si lo omitís, ONVO usa ese valor por defecto.
binRules	Lista de BINs de tarjeta que hacen elegible el descuento.
maxRedemptions	Límite total de pagos exitosos que pueden consumir el cupón. Omitilo si no querés límite.
redeemBy	Fecha límite de uso. Podés enviar una fecha ISO completa o YYYY-MM-DD; las fechas sin hora se normalizan a medianoche de Costa Rica.
isActive	Activa o desactiva el cupón sin borrarlo. Por defecto es true.
promotionCodes	Códigos promocionales asociados al cupón. En one-time links se usan desde el backend, no como un campo visible para que el comprador escriba un código.

Tipos de descuento

Usá percentage cuando querés descontar un porcentaje del monto final:

{
  "type": "percentage",
  "percentOff": 15
}

Usá fixed_amount cuando querés descontar un monto específico:

{
  "type": "fixed_amount",
  "amountOff": 250000,
  "currency": "CRC"
}

Los montos se envían en la unidad menor de la moneda. Por ejemplo, 250000 en CRC representa CRC 2,500.00.

Reglas de BIN

Los descuentos de one-time links se aplican por BIN. Un BIN son los primeros dígitos de una tarjeta; ONVO acepta reglas de 6 a 8 dígitos. En el dashboard, el campo de BINs es una lista simple: pegás o escribís los BINs elegibles y ONVO los guarda como reglas. En la API, esa misma lista se envía como binRules, donde cada item tiene al menos bin.

Enviá solo números, sin espacios ni guiones. Cuando el comprador ingresa o selecciona una tarjeta, Checkout revisa si el BIN coincide con alguna regla activa del cupón.

{
  "binRules": [
    {
      "bin": "411111"
    },
    {
      "bin": "41111112"
    }
  ]
}

Si varios cupones elegibles coinciden con el BIN, ONVO aplica el descuento más alto. Si el monto descontado empata, usa la regla de BIN más específica, es decir, la que tiene más dígitos.

La elegibilidad real depende de bin y de que la regla esté activa.

Cada regla puede incluir isActive. Esto permite pausar un BIN específico sin apagar todo el cupón. Si actualizás un cupón por API y enviás binRules, ONVO reemplaza la lista anterior por la lista enviada, así que incluí todas las reglas que querés conservar.

Códigos promocionales

Un cupón puede tener códigos promocionales asociados:

{
  "promotionCodes": [
    {
      "code": "SUMMER25"
    }
  ]
}

ONVO guarda el código en mayúsculas. En el payload de creación del one-time link, promotionCode espera el id del objeto de código promocional, no el texto del código:

{
  "discounts": [
    {
      "promotionCode": "promo_abc123"
    }
  ]
}

Para integraciones nuevas, lo más simple es enviar el coupon directamente. Usá promotionCode cuando ya gestionás códigos promocionales como objetos separados en tu sistema.

Si actualizás un cupón por API y enviás promotionCodes, ONVO también reemplaza la lista anterior por la lista enviada.

Aplicar el cupón al enlace

Para crear un enlace con descuento, agregá discounts al payload de la sesión. ONVO acepta un solo descuento por sesión. Ese descuento puede apuntar a un cupón directo o a un código promocional:

{
  "discounts": [
    {
      "coupon": "cpn_abc123"
    }
  ]
}

Enviá coupon o promotionCode, pero no ambos en el mismo objeto. El valor debe ser el id del cupón o del código promocional.

El cupón debe estar activo, pertenecer al mismo modo de la sesión (test o live), tener alcance checkout_session y aplicar a one_time_links. Si usás un cupón de monto fijo, la moneda del cupón debe coincidir con la moneda del enlace.

Para enlaces de un solo uso, no usés allowPromotionCodes: Checkout recibe el descuento específico desde discounts y lo aplica durante el pago.

Checklist

• El cupón y la sesión deben estar en el mismo modo: test o live.
• El cupón debe estar activo.
• Para one-time links, usá scope: "checkout_session" y appliesTo: ["one_time_links"].
• Para descuentos de monto fijo, currency debe coincidir con la moneda del enlace.
• Agregá al menos una regla de BIN activa para que Checkout pueda aplicar el descuento con tarjetas elegibles.
• Copiá el id del cupón desde el dashboard o desde la respuesta de POST /v1/coupons.