VibeFox Autopay for OpenCart — Ayuda

Requisitos

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

PHP: 8.0 o posterior.

Servicio de Autopay: necesitas el Service ID y la Shared key (hash key) de tu servicio de Autopay. Se muestran en el portal de comerciantes de Autopay: portal.autopay.eu para producción y testportal.autopay.eu para pruebas. Los servicios de prueba tienen su propio Service ID y Shared key; pide a Autopay que abra uno. La función hash del servicio debe ser SHA-256.

Moneda: la moneda del pedido debe ser PLN, EUR, GBP, USD o CZK y estar aceptada por tu servicio de Autopay.

Tienda accesible: Autopay debe poder enviar notificaciones a tu tienda, así que debe ser accesible desde internet sin autenticación básica ni un cortafuegos que bloquee las solicitudes POST. El modo de mantenimiento no bloquea las notificaciones, porque OpenCart permite las solicitudes de las extensiones de pago.

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_autopay_payment-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_autopay_payment.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_autopay_payment-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también puedes copiar el contenido de la carpeta upload del archivo en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Autopay Payment y haz clic en Install (el botón verde +). Tu usuario de administración necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del 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 (ver Clave de licencia).

4. Introduce el Service ID y la Shared key (prueba y producción) y elige las monedas de tu servicio.

5. En el portal de Autopay, configura la URL de ITN, la URL de retorno y la función hash SHA-256 para tu servicio (ver Configuración).

6. Activa Enable/Disable y haz clic en Save. Realiza un pedido de prueba en modo de prueba y, después, desactiva Test mode para los pagos reales.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_autopay_payment.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 y elige el tipo de extensión Payments. Busca VibeFox Autopay Payment, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia y los ajustes como en los pasos 3 a 6 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo las direcciones de ITN y de retorno son distintas (ver ITN and return address).

Una instalación nueva empieza con el método de pago desactivado, el modo de prueba activado y PLN como única moneda.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda la página completa. Encima de los ajustes, la página te avisa cuando el Service ID o la Shared key del entorno seleccionado están vacíos (en ese caso el método de pago se oculta en la finalización de compra) y cuando la moneda predeterminada de la tienda no está seleccionada en Currencies (en ese caso el método de pago se oculta en esa moneda). Mientras el modo de prueba está activado, muestra Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. Sin el derecho a modificar la extensión, la página muestra los ajustes, pero no puede guardarlos.

Al guardar, Title debe tener entre 1 y 128 caracteres, Sort Order debe ser un número entero, Total debe ser un número igual o mayor que 0, y un Service ID solo puede contener letras, dígitos, guiones y guiones bajos. Si algún campo tiene un error, no se guarda nada y la página indica el campo.

Autopay

Enable/Disable: Enable Autopay payment gateway 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. Es también el nombre del método de pago que se guarda en el pedido. Predeterminado: Autopay. Obligatorio, hasta 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmación. Predeterminado: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

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

Geo Zone: muestra Autopay solo para 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 total de la finalización de compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar antes de que se ofrezca Autopay. Déjalo vacío para ofrecer Autopay con cualquier total.

Autopay service

El Service ID y la Shared key se muestran en el portal de comerciantes de Autopay (portal.autopay.eu o testportal.autopay.eu, enlazados en este apartado).

Test mode: usa el entorno de pruebas de Autopay (testpay.autopay.eu) y las credenciales de prueba indicadas más abajo. Predeterminado: activado. Desactívalo para aceptar pagos reales en pay.autopay.eu con las credenciales de producción. Mientras está activado, los clientes ven Test mode: no real payment is taken. en el paso Confirm Order.

Service ID (production): el identificador numérico del servicio en portal.autopay.eu.

Shared key (production): la clave hash del servicio de producción. Mantenla en secreto.

Service ID (test): el identificador numérico del servicio en testportal.autopay.eu.

Shared key (test): la clave hash del servicio de prueba.

Las Shared keys guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo. Para eliminar una clave guardada, marca Clear the saved key on save debajo del campo y haz clic en Save.

Currencies: las monedas que acepta tu servicio de Autopay: PLN, EUR, GBP, USD, CZK. Autopay normalmente abre un servicio independiente por moneda. El método de pago solo se ofrece cuando la moneda de la finalización de compra está seleccionada aquí. Predeterminado: PLN.

ITN and return address

Introduce estas direcciones en el portal de Autopay para tu servicio, tanto para producción como para pruebas. Las direcciones exactas se muestran en el campo Addresses de este apartado y se construyen a partir de la dirección de la tienda de tu instalación de OpenCart:

Estas son las direcciones de OpenCart 3. En OpenCart 4 son:

Copia las direcciones exactamente como las muestran los ajustes. Sin la URL de ITN, los pedidos nunca se confirman: OpenCart mantiene el pedido sin estado hasta que Autopay confirma el pago. Cada ITN se comprueba con el hash SHA-256 calculado con la Shared key del servicio indicado en la notificación. Las notificaciones sin un hash válido o con un Service ID desconocido se rechazan. Una notificación solo se aplica a un pedido si su pago se inició con el mismo servicio de Autopay, de modo que una notificación de prueba nunca confirma un pago de producción. Las notificaciones de pagos iniciados antes de cambiar Test mode se siguen verificando con la clave correcta, siempre que ambas credenciales sigan guardadas.

La extensión gestiona estos estados de pago en el ITN:

Orders

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido ausente). El pedido recibe un estado solo cuando Autopay confirma el pago (ITN SUCCESS). Un pago fallido o abandonado deja el pedido sin estado. En OpenCart 4, un pedido sin pagar de la finalización de compra puede recibir el estado Voided, que OpenCart 4 asigna cuando el cliente vuelve al paso Confirm Order; la extensión trata ese pedido como un pedido sin estado, y un ITN SUCCESS posterior sigue marcándolo como pagado. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: el estado que se asigna cuando Autopay confirma el pago con el importe y la moneda esperados. Predeterminado: Processing.

On Hold Status: el importe o la moneda pagados no coinciden con el pedido, o el pago llegó después de que el estado del pedido se hubiera cambiado (por ejemplo, cancelado). El pedido no se marca como pagado; una nota explica el motivo. Predeterminado: Pending, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Advanced

Logging: escribe los eventos de pago en wc_ap_debug.log.php, en la carpeta de logs de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al llegar a 5 MB, se mueve a wc_ap_debug.old.log.php. Las claves y los datos de los clientes nunca 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.

Import / Export

Export: Download JSON guarda los ajustes en un archivo JSON. Las Shared keys no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las Shared keys guardadas se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto, Autopay). En el paso Confirm Order, el cliente ve tu descripción y la nota You will be redirected to the secure Autopay payment page to complete the payment. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, el navegador envía a Autopay un formulario de pago firmado con el importe total del pedido en la moneda del pedido, el número de pedido de OpenCart como OrderID, la descripción Order seguida del número, y el correo electrónico del cliente. En la página de Autopay, el cliente elige el método de pago y paga.

El pedido solo se marca como pagado cuando Autopay lo confirma con un ITN firmado y el importe y la moneda coinciden con el pedido. Entonces el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock. Tras pagar, el cliente vuelve a tu tienda. La dirección de retorno está firmada, pero nunca cambia un pedido. Si el pedido ya tiene un estado, el cliente ve la página de éxito del pedido de OpenCart. Si el ITN todavía no ha llegado, una página de Payment confirmation muestra Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. con los botones Check again y Back to checkout.

Si Autopay informó de un pago fallido, el cliente vuelve a la finalización de compra con el mensaje The payment was not completed. You can try again or choose another payment method. El carrito se conserva. Cada nuevo intento crea un nuevo pedido de OpenCart (en OpenCart 4 el cliente paga de nuevo el mismo pedido, con un nuevo intento bajo el mismo OrderID). Si otro pedido del mismo carrito (los mismos productos en la misma visita) ya se ha pagado, el cliente va a la página de éxito en lugar de pagar de nuevo. Una nueva compra después de una completada es un carrito nuevo y se paga normalmente. Si no se puede iniciar el pago, el cliente se queda en el paso Confirm Order con un mensaje breve encima del botón, por ejemplo Autopay payments are not configured. Please choose another payment method or contact the store. o que Autopay no puede aceptar pagos en esta moneda.

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. El mensaje sobre un pago que no se completó se muestra encima de la página de finalización de compra. OpenCart 4 mantiene un solo pedido para la finalización de compra y lo actualiza. Si la tienda cerró ese pedido entretanto (por ejemplo, porque lo cancelaste), el cliente vuelve a la finalización de compra con The payment was not completed. You can try again or choose another payment method., o, si el pedido se había pagado a través de Autopay, con Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. Si el pedido de la finalización de compra ya está pagado para un carrito distinto, el mensaje es Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. El siguiente Confirm Order paga un pedido nuevo. Un cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago. El ITN también funciona cuando la tienda está en modo de mantenimiento: en OpenCart 4 la extensión añade una acción de inicio para ello.

La extensión no tiene reembolsos desde OpenCart, ni suscripciones o pagos recurrentes, ni tarjetas guardadas, ni código BLIK ni formulario de tarjeta en la página de finalización de compra, ni elección de banco o canal de pago en la página de finalización de compra, y utiliza un Service ID por entorno.

Pedidos

Order statuses

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

Order Status After Payment (default Processing): Autopay confirmó el pago y el importe y la moneda coinciden. Una nota muestra el importe, el ID de transacción de Autopay (remoteID) y la fecha del pago.

On Hold Status (default Pending): Autopay informó de un importe o una moneda diferentes del total del pedido. El pedido no se marca como pagado. Comprueba la transacción en el portal de Autopay y complétala o reembolsala manualmente. Una notificación posterior correcta para este pedido lo marca como pagado. El mismo estado se usa cuando llega un pago para un pedido cuyo estado hubieras cambiado mientras tanto, por ejemplo cancelado: una nota te pide que compruebes el stock y proceses el pedido, o que reembolses el pago.

Un pedido pagado nunca se modifica por una notificación de fallo posterior. Si Autopay informa de otro pago correcto para un pedido ya pagado, o si se paga un segundo pedido del mismo carrito, una nota advierte de que el cliente podría haber pagado dos veces. Una notificación de un pago iniciado con otro servicio de Autopay no se aplica, y una nota lo explica. Las notas son entradas del History del pedido que el cliente no ve.

VibeFox Autopay Payment tab

En Sales > Orders abre un pedido pagado con Autopay. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Autopay Payment muestra el OrderID at Autopay, el Service ID y el entorno, con una etiqueta Test mode en los pagos de prueba, el Amount, el estado del Payment attempt, el Autopay transaction ID y las Autopay notes del pedido. La pestaña es solo de lectura y se muestra a los usuarios que tienen acceso a la extensión.

Refunds

Los reembolsos a través de Autopay no son compatibles. Reembolsa el pago en el portal de Autopay y, después, actualiza el pedido en OpenCart manualmente.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Autopay Payment es el primer bloque de Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-payment-autopay 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 inglés y ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o después de liberar un 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 de la configuración de OpenCart. Eliminar la clave de la tienda no libera su dominio. Libera el dominio en tu cuenta de vibefox.net.

Sin una clave activa, Autopay 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 en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), 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 en el panel de administración, así que sin una clave activa el método de pago se oculta 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 siguen confirmándose.

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 cuando abres el Dashboard o la página Edit del panel de administración: 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 siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

Autopay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el entorno seleccionado tiene Service ID y Shared key, y que la moneda de la finalización de compra está seleccionada en Currencies. La página de ajustes muestra un aviso cuando falta alguno de estos elementos. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total configurado.

El pago se realizó, pero el pedido sigue sin estado: Autopay no envió el ITN, o la tienda lo rechazó. Comprueba que la URL de ITN mostrada en los ajustes está configurada para el servicio en el portal de Autopay (producción o prueba), que la función hash es SHA-256 y que la Shared key de la extensión coincide con el servicio. Comprueba que la tienda es accesible desde internet. Activa Logging y revisa el campo Log de la página de la extensión.

El registro muestra ITN rejected: invalid hash: la Shared key no coincide con el servicio, o la función hash del servicio no es SHA-256.

El registro muestra que el service ID no está configurado: la notificación procede de un servicio cuyo Service ID no está introducido en la extensión, o cuya Shared key está vacía.

El registro muestra could not lock the order, Autopay will retry: otra notificación estaba procesando el pedido en el mismo momento. La tienda responde para que Autopay vuelva a enviar la notificación.

La URL de ITN muestra METHOD_NOT_ALLOWED en el navegador: es normal. La URL acepta solo solicitudes POST de Autopay.

El pedido está en el estado de retención con una nota de discrepancia: Autopay informó de un importe o una moneda diferentes del total del pedido. Comprueba la transacción en el portal de Autopay y completa o reembolsa el pedido manualmente.

Una nota indica que la notificación NO se aplicó: el pago de este pedido no se inició con este servicio de Autopay, por ejemplo una notificación de prueba para un pedido de producción. Comprueba la transacción en el portal de Autopay.

Tras pagar, el cliente llega a la página de inicio: la dirección de retorno no pudo verificarse, por ejemplo porque el Service ID no está introducido en la extensión. El pedido no se ve afectado; sigue al ITN.

El cliente ve This payment method is not available. Please reload the checkout page.: la sesión de finalización de compra ya no coincide con el pedido, o el método de pago se desactivó o perdió sus credenciales en el intervalo. El cliente vuelve a cargar la finalización de compra.

Para desarrolladores: antes de firmar el formulario de pago, la extensión dispara el evento de OpenCart wc_ap_payment_params con los parámetros del formulario y el pedido; el servicio, el número de pedido, el importe y la moneda no pueden modificarse desde él.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Autopay Payment. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart elimina sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders. La extensión siempre elimina los demás ajustes de la pasarela, incluidos los Service ID y las Shared keys, y el registro. No tiene ninguna opción para conservar los ajustes. En OpenCart 4 también se eliminan los eventos de la extensión y su acción de inicio, que deja pasar el ITN en modo de mantenimiento. Los registros de pagos de Autopay siempre se conservan. 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 Autopay Payment en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

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