El cliente elige qué pagar

Permitir que el cliente elija qué pagar no requiere un tercer tipo de precio. En ONVO, el precio sigue usando type: "one_time" o type: "recurring"; esta experiencia se activa con customUnitAmount en el precio. Para Checkout, usá type: "one_time" cuando querés que el comprador elija un monto para un pago único.

Este flujo usa el mismo modelo de catálogo que un cobro normal: creás un producto, creás un precio con customUnitAmount para ese producto y creás una sesión de Checkout que referencia ese precio.

Cuándo usarlo

• Donaciones o aportes voluntarios.
• Propinas.
• Reservas o pagos donde el comprador define el monto dentro de un rango.
• Formularios donde querés sugerir un monto inicial, pero permitir cambiarlo.

1. Crear el producto

Creá el producto que se va a mostrar en Checkout. La descripción y las imágenes ayudan a que el comprador entienda qué está pagando.

curl https://api.onvopay.com/v1/products \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Donación Fundación Azul",
    "description": "Aporte voluntario para campaña anual",
    "images": [
      "https://example.com/donacion.png"
    ]
  }'

Guardá el id del producto para crear el precio.

2. Crear el precio

Creá un precio one_time con customUnitAmount. Los valores se envían en la unidad menor de la moneda: centavos para USD y céntimos para CRC.

curl https://api.onvopay.com/v1/prices \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "CRC",
    "type": "one_time",
    "productId": "prod_abc123",
    "customUnitAmount": {
      "preset": 1000000,
      "minimum": 500000,
      "maximum": 5000000
    }
  }'

En este ejemplo, Checkout sugiere CRC 10,000.00, permite bajar hasta CRC 5,000.00 y permite subir hasta CRC 50,000.00.

No enviés unitAmount en este precio. Cuando un precio usa customUnitAmount, ONVO guarda el monto fijo como 0 y usa preset, minimum y maximum para la experiencia de Checkout.

3. Crear la sesión de Checkout

Creá la sesión con el priceId del precio que acabás de crear. Usá un solo line item con quantity: 1.

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": [
      {
        "priceId": "price_abc123",
        "quantity": 1
      }
    ],
    "redirectUrl": "https://example.com/gracias",
    "cancelUrl": "https://example.com/cancelado",
    "metadata": {
      "campaignId": "donaciones-2026"
    }
  }'

La sesión no recibe customUnitAmount directamente. Checkout lee esa configuración desde el precio asociado y muestra el monto sugerido, el mínimo y el máximo al comprador.

ONVO Checkout se encarga de guardar el monto que el comprador elige antes de confirmar el pago. El comercio no tiene que llamar un endpoint adicional para aplicar ese monto en la sesión.

Reglas importantes

• No enviés unitAmount y customUnitAmount en el mismo precio.
• Enviá productId o productData al crear el precio, pero no ambos.
• preset es requerido y debe estar dentro de minimum y maximum cuando enviás esos límites.
• En esta experiencia, usá un solo line item con quantity: 1.
• Usá type: "one_time" cuando el cliente elige qué pagar en Checkout. recurring sigue siendo para cargos recurrentes.