Saltar al contenido principal

Pagos

El flujo de pagos de ONVO se apoya en intenciones de pago, métodos de pago, reembolsos y eventos asincrónicos.

Referencia API relacionada​

Recursos principales​

RecursoDescripción
Intención de pagoRepresenta el intento de cobrar una orden.
Método de pagoInstrumento utilizado por el comprador.
Cargo recurrenteCobra periódicamente a un cliente usando un precio recurrente.
ReembolsoDevolución total o parcial de un pago.
WebhookEvento enviado por ONVO cuando el estado cambia.

Para la mayoría de integraciones, creá una intención por orden y escuchá webhooks para confirmar el resultado final.

Para aceptar transferencias desde una billetera crypto, seguí la guía de Crypto por API. Incluye los datos requeridos del comprador, la redirección al formulario de ONVO y la confirmación asincrónica del pago.

Rechazos al verificar tarjetas​

Cuando creás o actualizás un método de pago de tipo card, ONVO tokeniza y verifica la tarjeta antes de guardar los datos. Si la verificación falla, la respuesta conserva el error general cards.invalid_card_info y puede incluir details.card con información estructurada para el comercio.

details.card es opcional. Cuando está presente, contiene estos campos:

  • reason: categoría estable para decidir el tratamiento general.
  • declineCode: código seguro del gateway o emisor, o un valor de respaldo de ONVO.
  • declineMessage: texto informativo seguro para registro o soporte.

Por ejemplo, un rechazo puede devolver esta respuesta:

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

Cómo interpretar reason​

ValorCuándo se usa
issuer_declinedEl emisor rechazó la verificación, por ejemplo por datos incorrectos o una restricción de la tarjeta.
gateway_declinedEl gateway o adquirente reportó explícitamente una regla no técnica de aceptación, autenticación, comercio o riesgo.
onvo_declinedONVO aplicó una regla de elegibilidad o seguridad, como una marca o BIN no permitido.
processor_errorUn problema técnico, de comunicación o configuración impidió completar la verificación.
unknownNo hubo información suficiente para atribuir el rechazo de forma segura.

Usá reason para la lógica general. declineCode no pertenece a un espacio universal de códigos y puede variar según el proveedor; no construyás reglas globales asumiendo que el mismo código siempre tiene el mismo significado. declineMessage también es informativo: no lo analices para tomar decisiones ni dependás de él para localizar mensajes.

Cuando no hay información específica sobre el rechazo, ONVO devuelve los valores predeterminados: unknown en reason, generic_decline en declineCode y un mensaje genérico en declineMessage.

Manejo recomendado​

  1. Revisá primero el code superior para identificar cards.invalid_card_info.
  2. Si existe details.card, decidí la experiencia general con reason.
  3. Mostrá una recomendación propia y segura al comprador; no expongás mensajes internos ni prometás que un reintento resolverá el rechazo.
  4. Registrá declineCode y declineMessage solo como contexto para diagnóstico y soporte.

Referencia y ejemplos​