Intenciones de pago

Una intención de pago guía el ciclo de cobro de un pago. Usá exactamente una intención por pago para mantener trazabilidad clara.

Referencia API relacionada

• Crear un método de pago
• Crear una intención de pago
• Confirmar una intención de pago
• Obtener una intención de pago
• Capturar una intención de pago
• Cancelar una intención de pago
• Listar todas las intenciones de pago

Flujo básico

1. Creá o recolectá un método de pago para el comprador.
2. Creá una intención de pago con el monto y la moneda.
3. Confirmá la intención usando el paymentMethodId.
4. Escuchá los webhooks antes de marcar el pago como completado en tu sistema.

Crear un método de pago

Creá el método de pago desde el cliente con una publishable key o desde tu servidor con una secret key, según el tipo de integración que estés construyendo. Para tarjetas, el resultado devuelve un id que después enviás como paymentMethodId al confirmar la intención.

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": "María Rodríguez"
    },
    "billing": {
      "name": "María Rodríguez",
      "email": "maria@example.com",
      "address": {
        "country": "CR"
      }
    }
  }'

Crear una intención

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": "Orden #1001"
  }'

Confirmar la intención

Usá el id de la intención y el id del método de pago creado previamente.

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"
  }'

Estados comunes

Estado	Significado
requires_payment_method	Estado inicial. También se mantiene en este estado si una confirmación falla, por ejemplo por una tarjeta declinada.
requires_action	El método de pago necesita una acción adicional del comprador, como autenticación 3DS.
processing	ONVO está procesando el pago.
succeeded	El pago fue exitoso.
canceled	La intención fue cancelada.

Buenas prácticas

• Guardá el id de la intención junto a tu pago.
• Usá metadata para IDs internos de carrito, pago o cliente.
• Confirmá el estado final por webhook antes de entregar bienes digitales o marcar el pago como completado.