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.

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​