Payment intents

A payment intent guides the lifecycle of a payment. Use exactly one intent per payment to keep traceability clear.

Related API reference

• Create a payment method
• Create a payment intent
• Confirm a payment intent
• Retrieve a payment intent
• Capture a payment intent
• Cancel a payment intent
• List all payment intents

Basic flow

1. Create or collect a payment method for the buyer.
2. Create a payment intent with the amount and currency.
3. Confirm the intent using the paymentMethodId.
4. Listen for webhooks before marking the payment as complete in your system.

Create a payment method

Create the payment method from the client with a publishable key or from your server with a secret key, depending on the integration you are building. For cards, the response returns an id that you later send as paymentMethodId when confirming the intent.

curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "card": {
      "number": "4242424242424242",
      "expMonth": 12,
      "expYear": 2028,
      "cvv": "123",
      "holderName": "Maria Rodriguez"
    },
    "billing": {
      "name": "Maria Rodriguez",
      "email": "maria@example.com",
      "address": {
        "country": "CR"
      }
    }
  }'

Create an intent

curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "CRC",
    "description": "Order #1001"
  }'

Confirm the intent

Use the intent id and the id from the payment method created earlier.

curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "cl502zv0d0127ebdp3zt27651"
  }'

Common states

State	Meaning
requires_payment_method	Initial state. The intent also stays in this state if confirmation fails, for example because a card is declined.
requires_action	The payment method needs an additional buyer action, such as 3DS authentication.
processing	ONVO is processing the payment.
succeeded	The payment succeeded.
canceled	The intent was canceled.

Best practices

• Store the intent id with your payment.
• Use metadata for internal cart, payment, or customer IDs.
• Confirm the final state by webhook before delivering digital goods or marking the payment as complete.