VibeFox Autopay for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Servicio de Autopay: necesitas el Service ID y la Shared key (clave hash) de tu servicio de Autopay. Aparecen en el portal de comerciante 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 carrito 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 peticiones POST. El modo de mantenimiento y la restricción por país de tu tienda no bloquean las notificaciones.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, haz clic en Configure o, más tarde, busca VibeFox Autopay Payment en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, dentro del bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).
4. Introduce el Service ID y la Shared key (de prueba y de 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 de tu servicio (ver Configuración).
6. Activa Enable/Disable y haz clic en Save. Haz un pedido de prueba en modo de prueba y, después, desactiva Test mode para los pagos reales.
Al instalarse, el módulo crea el estado de pedido Autopay payment on hold. PrestaShop habilita el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Autopay Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Sobre los campos, la página avisa si el Service ID o la Shared key del entorno seleccionado están vacíos, y si la moneda predeterminada de la tienda no está seleccionada en Currencies. En ambos casos, el método de pago se oculta en la finalización de compra (para la moneda que no esté seleccionada).
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. También es el nombre del método de pago guardado en el pedido. Predeterminado: Autopay. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.
Autopay service
El Service ID y la Shared key aparecen en el portal de comerciante de Autopay (portal.autopay.eu o testportal.autopay.eu, enlazados en esta sección).
Test mode: usa el entorno de pruebas de Autopay (testpay.autopay.eu) y las credenciales de prueba indicadas abajo. Predeterminado: activado. Desactívalo para aceptar pagos reales en pay.autopay.eu con las credenciales de producción.
Service ID (production): el identificador numérico del servicio de portal.autopay.eu.
Shared key (production): la clave hash del servicio de producción. Manténla en secreto.
Service ID (test): el identificador numérico del servicio de testportal.autopay.eu.
Shared key (test): la clave hash del servicio de prueba.
Al guardar, un Service ID con caracteres distintos de letras, dígitos, guiones o guiones bajos se rechaza con un error y no se guarda nada. 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 si quieres cambiarlo.
Clear saved keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Currencies: las monedas que acepta tu servicio de Autopay: PLN, EUR, GBP, USD, CZK. Autopay normalmente abre un servicio separado por moneda. El método de pago se ofrece solo cuando la moneda del carrito está seleccionada aquí. Predeterminado: PLN.
Notificaciones de pago (ITN) y dirección de retorno
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 esta sección. Con URLs amigables tienen este aspecto, posiblemente con un código de idioma como /en/:
Copia las direcciones exactamente como las muestran los ajustes. Sin la URL de ITN nunca se crean pedidos, porque PrestaShop crea el pedido solo cuando Autopay confirma el pago. Cada ITN se verifica con el hash SHA-256 generado con la Shared key del servicio indicado en la notificación. Las notificaciones sin hash válido o con un Service ID desconocido se rechazan. Una notificación se aplica a un carrito solo si su pago se inició con el mismo servicio de Autopay, así 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.
El módulo gestiona estos estados de pago en la ITN:
Avanzado
Logging: escribe los eventos de pago en logs/wc_ap_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos de 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.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Autopay) con su descripción y confirma. La página siguiente muestra Thank you. You are being redirected to Autopay to complete the payment. Your order is created as soon as Autopay confirms it. y envía al cliente a la página de pago de Autopay. Si el cliente vuelve con el botón atrás del navegador, la página muestra el botón Pay with Autopay en lugar de redirigir de nuevo. En este punto todavía no existe ningún pedido.
El módulo pasa el total del carrito en la moneda del carrito, el número del carrito como referencia del pedido, la descripción (Cart y el 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 se marca como pagado solo después de que Autopay lo confirme con una ITN firmada y de que el importe y la moneda coincidan con el carrito. Entonces se crea el pedido y el cliente recibe los correos estándar de pedido de PrestaShop. Tras pagar, el cliente vuelve a tu tienda. La dirección de retorno va firmada, pero nunca crea ni cambia un pedido. Si el pedido ya existe, el cliente ve la página estándar de confirmación de pedido. Si la ITN todavía no ha llegado, una página de Payment confirmation muestra Thank you. Your payment is being confirmed by Autopay — your order will be created as soon as Autopay confirms it, 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 The payment was not completed. You can try again or choose another payment method. El carrito se conserva. Si el pago no puede iniciarse, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo Autopay payments are not configured. Please choose another payment method or contact the store. o un aviso de que Autopay no puede aceptar pagos en esta moneda.
El módulo no admite reembolsos desde PrestaShop, ni suscripciones o pagos recurrentes, ni tarjetas guardadas, ni código BLIK ni formulario de tarjeta en la finalización de compra, ni elección de banco o canal de pago en la finalización de compra, y usa un solo Service ID por entorno.
Pedidos
Estados de pedido
No order yet: el cliente fue enviado a Autopay y no ha pagado, el pago falló o Autopay todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted: Autopay confirmó el pago y el importe y la moneda coinciden. El pago se registra con el ID de transacción de Autopay (remoteID) como ID de transacción, y una nota muestra el importe, la transacción de Autopay y la fecha del pago.
Autopay payment on hold: Autopay informó de un importe o una moneda distintos del total del carrito (por ejemplo, si el carrito se cambió después de iniciar el pago). El pedido no se marca como pagado. Revisa la transacción en el portal de Autopay y complétala o reembólsala 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 que había sido cancelado: el pago se registra y una nota te pide revisar el stock y preparar el pedido, o reembolsar el pago.
Un pedido pagado nunca se modifica por una notificación posterior de fallo. Si Autopay informa de otro pago correcto para un pedido pagado, una nota advierte de que el cliente puede 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 solo las ve el personal, en el bloque Autopay payment de la página del pedido.
Bloque de pago de Autopay
La página del pedido muestra un bloque Autopay payment con el OrderID de Autopay, el Service ID y el entorno, el importe y la moneda, el estado del pago, el ID de transacción de Autopay, una insignia Test mode para los pagos de prueba y las Autopay notes del pedido. El bloque es de solo lectura.
Reembolsos
Los reembolsos a través de Autopay no son compatibles. Reembolsa el pago en el portal de Autopay y luego regístralo en PrestaShop con las herramientas estándar de pedidos.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Autopay Payment es el primer bloque de Modules > Module Manager > VibeFox Autopay Payment > Configure, encima de los ajustes. Introduce 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: presta-payment-autopay y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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 con una fecha. Tras cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave de licencia activa, Autopay no se muestra a los clientes en la finalización de compra. Si un pago se inicia de todos modos, el cliente ve This payment method is not available. Please choose another one. La tienda no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: 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 ningún cron job. Desinstalar o restablecer el módulo elimina siempre 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 tenga Service ID y Shared key, y que la moneda del carrito esté seleccionada en Currencies. La página de configuración muestra un aviso si falta alguno de estos datos. En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: Autopay no entregó la ITN o la tienda la rechazó. Comprueba que la URL de ITN mostrada en la configuración esté establecida para el servicio en el portal de Autopay (producción o pruebas), que la función hash sea SHA-256 y que la Shared key del módulo coincida con el servicio. Comprueba que la tienda sea accesible desde internet. Activa Logging y revisa el campo Log en la página del módulo.
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 llegó de un servicio cuyo Service ID no está introducido en el módulo, o cuya Shared key está vacía.
El registro muestra could not lock the cart, Autopay will retry: otra notificación estaba procesando el carrito en ese mismo momento. La tienda responde para que Autopay vuelva a enviar la notificación. Lo mismo ocurre cuando no se pudo crear el pedido, por ejemplo porque el módulo está desactivado.
El pedido está en Autopay payment on hold con una nota de discrepancia: Autopay informó de un importe o una moneda distintos del total del carrito. Revisa la transacción en el portal de Autopay y completa o reembolsa el pedido manualmente.
Una nota dice 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 real. Revisa la transacción en el portal de Autopay.
Tras pagar, el cliente llega a la página de inicio: no se pudo verificar la dirección de retorno, por ejemplo porque el Service ID no está introducido en el módulo. El pedido no se ve afectado y depende de la ITN.
El cliente ve This payment method is not available.: el método de pago no se ofrece para este carrito (desactivado, sin credenciales, moneda no seleccionada o no permitido en Payment > Preferences).
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Autopay Payment y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Se eliminan los ajustes del módulo, incluidas las claves, y el registro. El módulo no tiene ninguna opción para conservar los ajustes. Los datos de pagos de Autopay y el estado de pedido Autopay payment on hold siempre se conservan. Los pedidos existentes mantienen sus notas de pago e ID de transacción.
Autopay es una marca comercial de su respectivo propietario. Este módulo no está afiliado ni respaldado por Autopay.