La API de OnePay utiliza códigos de estado HTTP para indicar la naturaleza de los errores que pueden ocurrir durante el procesamiento de una solicitud. Estos códigos de estado son acompañados por un cuerpo de respuesta estandarizado que proporciona detalles adicionales para facilitar la resolución de problemas. A continuación, se detalla cómo interpretar y manejar estos errores eficazmente.

Formato Estándar de Respuesta de Error Cuando ocurre un error, la API responde con un código de estado HTTP 4XX y un cuerpo de respuesta en formato JSON estructurado de la siguiente manera:

{
  "message":"Descripción del error en texto.",
  "code":"Código numérico del mensaje de error",
  "code_name":"Código en texto para el mensaje de error",
  "erros": [
    {
      "key": "name",
      "description": "El campo name, es un campo requerido"
    }
  ]
}
  • message: Proporciona una descripción comprensible del error, diseñada para ser leída por desarrolladores.
  • code: Un código numérico que identifica de manera única el error específico que ha ocurrido.
  • code_name: Un identificador textual que representa el tipo de error, facilitando su rápida identificación sin necesidad de referenciar documentación adicional.
  • errors: es el resultado del proceso de validación de cada uno de los campos cuando intentas consumir el api.

Guía para la Resolución de Errores

Los errores devueltos por nuestra API están pensados para ofrecer suficiente información que permita a los desarrolladores identificar y corregir el problema de manera eficiente. A continuación, se ofrecen algunas recomendaciones generales para el manejo de estos errores:

  • Análisis del Código de Estado HTTP: Comience por revisar el código de estado HTTP para obtener una comprensión general de la naturaleza del error (p.ej., errores de cliente 4XX, errores de servidor 5XX).
  • Revisión del Mensaje de Error: El campo message en la respuesta proporciona una explicación detallada del error. Este debe ser el primer recurso para entender el problema específico.
  • Consultar el Código Específico del Error: Utilice el code y code_name para buscar en la documentación de la API detalles adicionales y posibles soluciones para el error indicado.
  • Implementar un manejo de errores detallado y específico no solo mejora la robustez de las integraciones con la API de OnePay, sino que también asegura una experiencia de usuario final más fluida y predecible. Se recomienda a los desarrolladores diseñar sus aplicaciones para que respondan de manera adecuada a los distintos errores, proporcionando retroalimentación útil al usuario final cuando sea necesario.

Errores de procesamiento de pagos

Código en textoCódigo numéricoDescripción
internal_error10101Error interno. Comunícate con soporte para resolver el problema.
card_cvv10102CVV inválido.
insufficient_funds10103Fondos insuficientes.
card_number10104Número de tarjeta inválido.
fraudulent10105Transacción fraudulenta.
stolen10106Tarjeta robada.
currency_not_supported10107Moneda no soportada.
card_velocity10108Se ha excedido la cantidad de intentos de pago permitidos para esta tarjeta.
card_date10109Fecha de expiración inválida.
transaction_not_found10110Transacción no encontrada.
min_amount10111El monto de la transacción es menor al mínimo permitido.
account_not_connected10112El usuario ha desconectado su cuenta.
account_blocked10113La cuenta ha sido bloqueada.
account_closed10114La cuenta ha sido cerrada.
account_does_not_belong_to_customer10115La cuenta no pertenece al usuario.
transaction_expired10116El usuario no ha completado la transacción en el tiempo permitido.
card_generic_error10117Error genérico al procesar el pago con tarjeta, el banco no proporcionó más información.
transaction_rejected10118El usuario no aceptó o rechazó la transacción en el banco.
unknown10119Error desconocido. Comunícate con soporte para resolver el problema.
bank_is_not_available10120El banco no se encuentra disponible para iniciar la transacción.
card_restricted10121Tarjeta restringida, pídele al usuario que se comunique con su banco.
card_expired10122Tarjeta expirada, pídele al usuario que actualice su tarjeta.
account_is_not_authorized10123La cuenta no está autorizada para realizar cargos.
transaction_temporally_blocked10124La transacción ha sido bloqueada temporalmente.
account_failed10125Esta cuenta no ha sido aceptada.
customer_data_invalid10126Datos del cliente inválidos.
max_amount10127La transacción supera el monto máximo permitido para este método de pago.