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
| Recurso | Descripción |
|---|---|
| Intención de pago | Representa el intento de cobrar una orden. |
| Método de pago | Instrumento utilizado por el comprador. |
| Cargo recurrente | Cobra periódicamente a un cliente usando un precio recurrente. |
| Reembolso | Devolución total o parcial de un pago. |
| Webhook | Evento 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.
Cómo interpretar reason
| Valor | Cuándo se usa |
|---|---|
issuer_declined | El emisor rechazó la verificación, por ejemplo por datos incorrectos o una restricción de la tarjeta. |
gateway_declined | El gateway o adquirente reportó explícitamente una regla no técnica de aceptación, autenticación, comercio o riesgo. |
onvo_declined | ONVO aplicó una regla de elegibilidad o seguridad, como una marca o BIN no permitido. |
processor_error | Un problema técnico, de comunicación o configuración impidió completar la verificación. |
unknown | No 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
- Revisá primero el
codesuperior para identificarcards.invalid_card_info. - Si existe
details.card, decidí la experiencia general conreason. - Mostrá una recomendación propia y segura al comprador; no expongás mensajes internos ni prometás que un reintento resolverá el rechazo.
- Registrá
declineCodeydeclineMessagesolo como contexto para diagnóstico y soporte.