VibeFox Barion for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Tienda en Barion: necesitas el POSKey (clave secreta) de tu tienda y la dirección de correo electrónico de la cartera de Barion que recibe los pagos. Ambos datos están en el portal de Barion: secure.barion.com para el modo real y secure.test.barion.com para el modo de prueba, en My stores y en tu tienda. Las credenciales de prueba y las reales son distintas.

Moneda: la moneda del pedido debe ser HUF, EUR, USD o CZK. Para otras monedas, el método de pago no aparece en la finalización de compra.

Tienda accesible: Barion llama a tu tienda después de cada pago, por lo que el sitio debe ser accesible desde internet, sin cortafuegos ni autenticación básica delante. El modo de mantenimiento no bloquea esa llamada: OpenCart 3 deja pasar las peticiones de las extensiones de pago, y en OpenCart 4 la extensión añade para ello una acción de inicio.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

El archivo descargado es un único zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_barion_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_barion_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_barion_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que no hace falta actualizar Extensions > Modifications. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions, elige el tipo Payments, busca VibeFox Barion Gateway y haz clic en Install (el botón verde +). Tu usuario administrador necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón con el lápiz) para abrir la página de configuración. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (consulta la sección Clave de licencia).

4. Introduce el POSKey de prueba y el correo de la cartera de prueba, deja Test Mode activado, activa Enable/Disable y haz clic en Save. Realiza un pedido de prueba.

5. Cuando todo funcione, introduce las credenciales reales y desactiva Test Mode.

OpenCart 4

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_barion_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas, en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions, elige el tipo Payments, busca VibeFox Barion Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón con el lápiz).

4. Introduce la clave de licencia y las credenciales de Barion y prueba el pago como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de callback es distinta (ver Callback URL).

La URL de callback se envía automáticamente a Barion con cada pago. No hay que configurar nada en el portal de Barion. Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, la página te avisa si el modo actual no tiene POSKey o correo del beneficiario (en ese caso, el método de pago no aparece en la finalización de compra) y si la moneda predeterminada de tu tienda no es compatible con Barion, con la lista de monedas admitidas. Mientras el modo de prueba esté activado, muestra Test mode is on: payments go to the Barion sandbox (api.test.barion.com), no real money is charged. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title debe tener de 1 a 128 caracteres, Sort Order debe ser un número entero y Total un número igual o mayor que 0. Si algún campo tiene un error, no se guarda nada y la página indica el campo.

Barion

Enable/Disable: Enable Barion Payment activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Barion. Obligatorio, hasta 128 caracteres.

Description: el texto que el cliente ve en el paso Confirm Order, encima del botón de confirmación. Predeterminado: Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

Sort Order: la posición de Barion entre los métodos de pago de la finalización de compra. Déjalo vacío o escribe un número entero.

Geo Zone: ofrece Barion solo para las direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el importe total de la compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca Barion. Déjalo vacío para ofrecer Barion con cualquier importe.

Credenciales de la tienda en Barion

Obtén tu POSKey y el correo de la cartera en el portal de Barion: secure.barion.com (real) o secure.test.barion.com (prueba), My stores, tu tienda (los portales están enlazados en esta sección). El modo de prueba usa solo las credenciales de prueba, y el modo real, solo las reales.

Test Mode: usa las credenciales de prueba indicadas abajo y el sandbox de Barion (api.test.barion.com). No se cobra dinero real. Predeterminado: activado. Desactívalo para aceptar pagos reales. Mientras está activado, los clientes ven Test mode: no real payment is taken. en el paso Confirm Order.

Test POSKey: la clave secreta (POSKey) de tu tienda en el sistema de pruebas de Barion (secure.test.barion.com, My stores).

Test Payee Email: la dirección de correo de tu cartera de prueba de Barion, que recibe los pagos de prueba.

Live POSKey: la clave secreta (POSKey) de tu tienda en el sistema real de Barion (secure.barion.com, My stores).

Live Payee Email: la dirección de correo de tu cartera de Barion, que recibe los pagos.

Los POSKey guardados no se vuelven a mostrar. El campo queda vacío y aparece el texto Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Para eliminar un POSKey guardado, marca Clear the saved POSKey on save debajo del campo y haz clic en Save.

Callback URL: la dirección que Barion llama después de cada pago. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_barion_gateway/callback, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_barion_gateway/payment/wcp_barion_gateway.callback. Se genera a partir de la dirección pública de tu instalación de OpenCart. Se envía a Barion con cada pago, así que no hay nada que configurar. Solo tiene que ser accesible desde internet.

Orders

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido incompleto). Recibe un estado solo cuando Barion ha informado del pago (mediante la llamada de retorno o al volver el cliente; el estado siempre se consulta en Barion). Cada campo siguiente muestra los estados de pedido de tu tienda OpenCart.

Order Status After Payment: el estado que se asigna tras un pago correcto y verificado. Predeterminado: Procesando.

Awaiting Barion Payment Status: el cliente terminó en la página de Barion, pero Barion todavía procesa el pago. Predeterminado: Pendiente de pago.

Barion Payment On Hold Status: el pago se realizó, pero el importe o la moneda no coinciden con el pedido. Una nota explica el motivo; revisa el pago manualmente. Predeterminado: Pendiente de pago, porque OpenCart no tiene el estado En espera. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Payment Failed Status: un pedido pendiente de pago cuyo pago en Barion ha fallado. Predeterminado: Fallido.

Payment Canceled Status: un pedido pendiente de pago cuyo pago en Barion ha sido cancelado o ha caducado. Predeterminado: Cancelado.

Refunded Status: se asigna cuando el pago se reembolsa por completo desde la página del pedido. Predeterminado: Reembolsado.

Advanced

Logging: escribe las peticiones y las llamadas de Barion en barion_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Las claves secretas y los correos de las carteras no se registran. Predeterminado: desactivado. Mientras esté desactivado no se escribe nada, tampoco los errores.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Delete Data on Uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los pedidos y sus datos de pago de Barion siempre se conservan. Predeterminado: desactivado.

Import / Export

Export: Download JSON guarda los ajustes en un archivo JSON. Los POSKey no se exportan.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. Los POSKey guardados se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto, Barion). En el paso Confirm Order, el cliente ve tu descripción y la nota You will be redirected to the secure Barion payment page. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión inicia un pago en Barion por el total del pedido en la moneda del pedido y envía al cliente a la página de pago de Barion. Los productos, el envío, otros gastos del pedido e impuestos aparecen en el pago; el número de pedido de OpenCart se envía como número de pedido, el correo del cliente se envía como referencia, y el idioma de la página sigue al del cliente cuando Barion lo admite (húngaro, alemán, francés, español, checo, eslovaco, esloveno o griego; en cualquier otro caso, inglés). En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra.

Después de pagar, el cliente vuelve a tu tienda, y Barion también llama a la URL de callback. Ninguna de las dos peticiones marca nada como pagado por sí sola: la extensión pide a Barion el estado del pago con el POSKey del modo en que se inició. El pedido se marca como pagado solo cuando Barion lo confirma, y únicamente si el importe y la moneda coinciden con el pedido. El enlace de retorno contiene un token aleatorio del intento de pago, y solo se comprueban los pagos iniciados para ese pedido. Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización de existencias. En OpenCart 4 el navegador no envía la sesión de la tienda cuando Barion devuelve al cliente, así que la extensión muestra primero una página breve que vuelve a abrir el mismo enlace de retorno desde tu tienda: el cliente conserva el carrito y el inicio de sesión.

Si el pago se ha realizado correctamente, el cliente ve la página de pedido completado de OpenCart. Si el pago sigue en curso en Barion, el pedido recibe el estado Awaiting Barion Payment Status y la página de éxito muestra el mensaje Your payment is being confirmed by Barion. You will receive an e-mail as soon as it is confirmed. Si Barion no responde cuando el cliente vuelve, o si el pago está hecho pero aún no se ha aplicado, aparece una página Payment confirmation con el mismo texto y un botón Check again; la llamada de retorno asigna el estado del pedido en cuanto Barion confirma el pago.

Si el pago no se completó (cancelado, caducado o fallido), el pedido se queda sin estado, el carrito se conserva y el cliente vuelve a la finalización de compra con el mensaje Payment was not completed. Please try again. Si el enlace de retorno no coincide con el pedido, el mensaje es Payment verification failed. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra. Cada nuevo intento crea un nuevo pedido en OpenCart 3. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza, por lo que el nuevo intento es un nuevo pago en Barion del mismo pedido. Barion no puede cancelar un pago iniciado, así que, antes de un nuevo pago, la extensión comprueba en Barion los pagos abiertos anteriores del carrito: si alguno está pagado o sigue en proceso, su pedido se confirma y el cliente va a la página de éxito sin volver a pagar. Si otro pedido del mismo carrito (los mismos productos en la misma visita) ya está pagado, el cliente también va a la página de éxito sin un nuevo pago; una compra nueva después de una completada es un carrito nuevo. Un pago tardío de un intento anterior del mismo pedido sigue confirmándolo, y un intento anterior que caduca no cancela el pedido. Si el cliente paga dos veces el mismo carrito (dos pestañas), el segundo pago no confirma su pedido: el pedido pagado recibe una nota que indica que se recibió un segundo pago para el mismo carrito, para que puedas reembolsarlo en el portal de Barion.

En OpenCart 4 el pedido se mantiene en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, porque su pago en Barion quedó cancelado o lo cancelaste tú), el siguiente Confirm Order devuelve al cliente a la finalización de compra con el mensaje Payment was not completed. Please try again., y la finalización de compra crea entonces un pedido nuevo del carrito. Si el pedido ya tiene un estado y el carrito ha cambiado desde entonces (otros productos o cantidades), el pedido sale de la finalización de compra y el carrito modificado recibe un pedido nuevo y su propio pago.

Si el pago no se puede iniciar, el cliente permanece en el paso Confirm Order con un mensaje breve encima del botón: The Barion payment could not be started. Please try again or choose another payment method., Barion does not support payments in la moneda del pedido, Barion payment is not available at the moment. Please choose another payment method. o Barion cannot process an order with a zero total. Los detalles se envían al registro si Logging está activado.

La extensión solo admite pagos inmediatos. No tiene pagos con reserva o captura diferida, ni suscripciones o pagos recurrentes, ni tarjetas guardadas, ni Barion Pixel, ni datos adicionales de 3-D Secure; Barion gestiona 3-D Secure en su página de pago.

Pedidos y reembolsos

Order statuses

No status (missing order): el cliente fue enviado a Barion y no ha pagado, el pago no se completó o Barion todavía no ha confirmado el pago. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status ajustado a Missing Orders.

Awaiting Barion Payment Status (default Pending): Barion informa de que el pago sigue en curso. Una nota muestra el PaymentId de Barion, el importe y, en modo de prueba, (test mode). El pedido pasa al estado de pagado cuando Barion confirma el pago.

Order Status After Payment (default Processing): Barion ha confirmado el pago. Una nota muestra el importe, el PaymentId y la transacción de Barion.

Barion Payment On Hold Status (default Pending): Barion ha informado de un importe o una moneda distintos del total del pedido. La nota muestra ambos importes. Revisa el pago en el portal de Barion y, después, completa el pedido o reembolsa el pago en el portal de Barion.

Payment Canceled Status (default Canceled): el último intento de pago de un pedido pendiente fue cancelado o caducó en Barion.

Payment Failed Status (default Failed): el último intento de pago de un pedido pendiente ha fallado.

Refunded Status (default Refunded): el pago se reembolsó por completo a través de la extensión.

Si un pago del pedido sigue siendo correcto después de que el pedido se cancelara o fracasara, el pedido pasa a pagado. Un pedido pagado o reembolsado nunca se modifica por una llamada posterior. Si otro pago se completa para un pedido pagado, una nota te pide que lo revises en el portal de Barion y lo reembolses si es un duplicado. Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Barion Gateway

En Sales > Orders, abre un pedido pagado con Barion. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Barion Gateway muestra el PaymentId con la etiqueta Test mode en los pagos de prueba, la Transaction de Barion, el Status del pago, los importes Paid / refunded, el formulario de reembolso, el historial de reembolsos y las Barion notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña VibeFox Barion Gateway, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via Barion. Confirma la pregunta ¿Reembolsar este importe a través de Barion? Esta acción no se puede deshacer. Se admiten reembolsos totales y parciales. Necesitas el permiso para modificar la extensión (se configura en System > Users > User Groups). El motivo se envía a Barion como comentario. Los reembolsos en HUF deben ser importes enteros. El reembolso se envía en el modo (prueba o real) en el que se realizó el pago, por lo que el POSKey de ese modo debe estar configurado. Si Barion no acepta o no confirma el reembolso, la pestaña muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con la transacción y el estado de Barion. Un reembolso total asigna al pedido el Refunded Status sin notificar al cliente y sin devolver productos al stock, igual que un cambio manual de estado. Un reembolso parcial no cambia el estado.

Los reembolsos están disponibles una vez que Barion ha confirmado el pago y el pedido está pagado por esa vía. Un pago con diferencia de importe o de moneda no se puede reembolsar desde OpenCart; reembólsalo en el portal de Barion. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Barion.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox Barion Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de esta tienda. Debajo aparecen la línea Product: opencart-payment-barion y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen el inglés y el ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Clave no encontrada, Esta clave pertenece a otro producto, Límite de dominios alcanzado o La licencia caducó el una fecha. Después de cambiar la dirección de la tienda, o de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda definida en la configuración de OpenCart. Eliminar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Barion no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (sin licencia: visible solo para administradores), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del panel de administración, así que sin una licencia activa el método de pago queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard del panel de administración o la página Edit: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No se necesita ninguna tarea cron. Al desinstalar la extensión se eliminan siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Barion no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el modo actual tenga un POSKey y un correo del beneficiario (la página de ajustes muestra un aviso si falta alguno) y que la moneda del pedido sea HUF, EUR, USD o CZK. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.

El pago se realizó, pero el pedido se queda sin estado: el pedido recibe su estado cuando Barion llama a la URL de callback o cuando el cliente vuelve a tu tienda. Asegúrate de que el sitio sea accesible desde internet (sin cortafuegos ni autenticación básica delante de la URL de callback). Comprueba que el POSKey del modo en que se realizó el pago sea correcto, porque la extensión pide a Barion el estado del pago con él. Activa Logging para ver la llamada.

La llamada de callback responde Busy, retry: el pedido se estaba procesando al mismo tiempo que el cliente regresaba, o no se pudo asignar el estado del pedido. Barion vuelve a llamar. Activa Logging para ver el motivo.

La llamada de callback responde API error: la tienda no pudo leer el estado del pago en Barion, o el POSKey del modo en que se realizó el pago no está configurado. Comprueba ese POSKey.

La llamada de callback responde Order not found: el PaymentId no fue iniciado por esta tienda. Las llamadas de Barion destinadas a otras tiendas o a sistemas de prueba se ignoran.

El cliente ve Payment verification failed.: el enlace de retorno no coincide con el pedido, por ejemplo porque se ha modificado. El estado del pago sigue confirmándose mediante la llamada de callback.

El cliente ve un error después de Confirm Order: activa Logging y revisa el campo Log de la página de la extensión. Un POSKey o un correo del beneficiario incorrectos producen The Barion payment could not be started. This payment method is not available. Please reload the checkout page. significa que la sesión de compra ya no coincide con el pedido, o que el método de pago se ha desactivado entretanto: el cliente debe recargar la finalización de compra.

El pedido está en el estado de retenido: lee la nota de diferencia en la pestaña VibeFox Barion Gateway, revisa el pago en el portal de Barion y, después, completa el pedido o reembólsalo en el portal de Barion.

¿Por qué no puedo reembolsar 10.50 HUF?: Barion procesa HUF sin decimales. Introduce un importe entero.

No aparece el formulario de reembolso en la pestaña: la pestaña indica el motivo: el pago aún no está confirmado, está reembolsado por completo, tu grupo de usuarios no tiene permiso para modificar la extensión o el POSKey del modo del pago no está configurado.

Para desarrolladores: la extensión dispara los eventos de OpenCart wcp_barion_supported_currencies (la lista de monedas) y wcp_barion_payment_request (la petición de pago y el pedido, antes de enviarlos a Barion).

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Barion Gateway. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart elimina siempre sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. El evento de OpenCart de la extensión también se elimina (en OpenCart 4, sus eventos y su acción de inicio, que deja pasar el callback en modo de mantenimiento). Si Delete Data on Uninstall está activado, se eliminan el resto de ajustes de la pasarela (título, descripción, modo de prueba, POSKey, correos de los beneficiarios, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de Barion siempre se conservan, así que los pedidos pagados antes pueden reembolsarse después de una reinstalación. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalarla, haz clic en Uninstall (el botón naranja −) junto a VibeFox Barion Gateway en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Barion es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Barion ni respaldada por esta empresa.