Skip to main content

Customer chooses what to pay

Letting the customer choose what to pay does not require a third price type. In ONVO, a price still uses type: "one_time" or type: "recurring"; this experience is enabled with customUnitAmount on the price. For Checkout, use type: "one_time" when you want the buyer to choose an amount for a one-time payment.

This flow uses the same catalog model as a standard charge: create a product, create a price with customUnitAmount for that product, and create a Checkout session that references that price.

When to use it​

  • Donations or voluntary contributions.
  • Tips.
  • Reservations or payments where the buyer defines the amount within a range.
  • Forms where you want to suggest an initial amount but allow changes.

1. Create the product​

Create the product that Checkout displays. The description and images help the buyer understand what they are paying for.

curl https://api.onvopay.com/v1/products \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blue Foundation donation",
    "description": "Voluntary contribution for the annual campaign",
    "images": [
      "https://example.com/donation.png"
    ]
  }'

Save the product id so you can create the price.

2. Create the price​

Create a one_time price with customUnitAmount. Values are sent in the currency's minor unit: cents for USD and centimos for 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
    }
  }'

In this example, Checkout suggests CRC 10,000.00, allows the buyer to go down to CRC 5,000.00, and allows the buyer to go up to CRC 50,000.00.

Do not send unitAmount on this price. When a price uses customUnitAmount, ONVO stores the fixed amount as 0 and uses preset, minimum, and maximum for the Checkout experience.

3. Create the Checkout session​

Create the session with the priceId for the price you just created. Use a single line item with 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/thanks",
    "cancelUrl": "https://example.com/canceled",
    "metadata": {
      "campaignId": "donations-2026"
    }
  }'

The session does not receive customUnitAmount directly. Checkout reads that configuration from the associated price and shows the suggested amount, minimum, and maximum to the buyer.

ONVO Checkout saves the amount the buyer chooses before confirming the payment. The merchant does not need to call an additional endpoint to apply that amount to the session.

Important rules​

  • Do not send unitAmount and customUnitAmount on the same price.
  • Send either productId or productData when creating the price, but not both.
  • preset is required and must be within minimum and maximum when you send those limits.
  • For this experience, use a single line item with quantity: 1.
  • Use type: "one_time" when the customer chooses what to pay in Checkout. recurring is still for recurring charges.