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
• Requisito para cuentas de Perú
• 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 del lado del cliente con una publishable key. Para tarjetas, el resultado devuelve un id que después enviás como paymentMethodId al confirmar la intención desde tu servidor.

Alcance PCI

Para reducir tu alcance PCI, recolectá los datos de tarjeta del lado del cliente usando una publishable key, Checkout o el SDK web. No enviés datos de tarjeta sin tokenizar por tu servidor. Si tu backend recibe o transmite PAN, CVV o datos completos de tarjeta, esa integración queda dentro de tu alcance PCI y puede requerir validación SAQ D.

Requisito para cuentas de Perú

important

Para cuentas de comercio creadas en Perú, el cliente asociado al método de pago debe tener correo electrónico al crear métodos de pago.

Podés cumplir este requisito de dos formas:

• Enviá customer.email en el payload de creación del método de pago para crear y asociar el cliente en la misma solicitud.
• Enviá customerId de un cliente creado previamente con el atributo email.

Ejemplo de tarjeta y validaciones

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

Para evitar errores 400 de validación antes de tokenizar la tarjeta, validá estos campos en tu formulario:

• card.holderName: texto no vacío.
• card.number: string con solo dígitos, sin espacios ni separadores, y con un número que pase validación Luhn.
• card.expMonth: entero entre 1 y 12.
• card.expYear: entero entre 2023 y 2100. También validá que la tarjeta no esté vencida antes de enviarla.
• card.cvv: string de 3 o 4 dígitos cuando lo enviés.

Si el payload no cumple estas reglas, ONVO responde 400 con un error de validación. Por ejemplo, un número de tarjeta inválido puede devolver:

{
  "statusCode": 400,
  "message": ["card.number Card number is invalid"],
  "error": "Bad Request"
}

Cuando creás un método de pago de tipo card, ONVO tokeniza y verifica la tarjeta antes de crear el objeto. Si la tokenización falla por datos inválidos, el endpoint responde 400 y no se crea ningún método de pago.

{
  "code": "cards.invalid_card_info",
  "path": "/v1/payment-methods",
  "type": "OnvoAPIError",
  "message": "There was an error with the card information provided. Please review card number, expiration date and cvv",
  "timestamp": "2026-04-29T17:36:28.477Z",
  "statusCode": 400
}

Mostrá el mensaje al comprador y pedile revisar el número de tarjeta, fecha de expiración y CVV antes de intentar crear el método de pago nuevamente.

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.