VibeFox ECPay 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.
Moneda: nuevo dólar taiwanés (TWD). ECPay cobra solo en TWD, así que el método de pago solo se muestra cuando el carrito del cliente está en TWD. Añade TWD en International > Localization > Currencies si tu tienda no lo tiene. Los importes se envían en TWD enteros, porque ECPay no acepta decimales: los totales del carrito se redondean al dólar más cercano. Usa 0 decimales en los precios en TWD para evitar redondeos.
Cuenta de ECPay: para pagos reales necesitas el MerchantID, el HashKey y el HashIV de tu cuenta de comerciante de ECPay, desde el back office de comerciante de ECPay (vendor.ecpay.com.tw). Para las pruebas no hace falta una cuenta de ECPay.
Acceso al sitio: tu tienda debe ser accesible desde internet por HTTP/HTTPS en el puerto 80/443, para que ECPay pueda enviar las notificaciones de pago. Un cortafuegos o una autenticación básica delante del sitio las bloquea.
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 busca más tarde VibeFox ECPay Payment Gateway en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Activa Enable/Disable, elige los métodos de pago y deja Test Mode activado para tus primeras pruebas. Haz clic en Save.
5. Para pagos reales introduce el Merchant ID, el Hash Key y el Hash IV (ver Configuración), desactiva Test Mode y haz clic en Save.
Al instalarse, el módulo crea dos estados de pedido: Awaiting ECPay payment y ECPay payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences; TWD debe seguir permitido para el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra un error cuando tu tienda no tiene la moneda TWD (entonces ECPay no aparece en la finalización de compra) o una advertencia cuando la moneda predeterminada no es TWD (entonces ECPay solo se muestra a los clientes que pagan en TWD). Muestra un error cuando el modo real no tiene MerchantID, HashKey y HashIV. Mientras el modo de prueba está activado, advierte de que los pagos van al sandbox de ECPay con el comerciante público de prueba 3002607, de que no se cobra dinero real y de que cualquiera que conozca las claves públicas del sandbox podría confirmar pedidos de prueba, por lo que el modo de prueba debe estar desactivado antes de aceptar pedidos reales.
ECPay (綠界)
Enable/Disable: Enable ECPay 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: ECPay (綠界). Obligatorio: la página no se guarda con el título vacío.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
Cuenta de ECPay
Encuentra tu MerchantID, HashKey y HashIV en el back office de comerciante de ECPay (vendor.ecpay.com.tw), en System development management > System integration settings (系統開發管理 > 系統介接設定).
Test Mode: envía los pagos al sandbox de ECPay (payment-stage.ecpay.com.tw) con el comerciante público de prueba de ECPay 3002607. No se cobra dinero real. Las credenciales de abajo solo se usan cuando el modo de prueba está desactivado. Predeterminado: activado. Mientras está activado, los clientes ven TEST MODE — ECPay sandbox, no real money is charged. debajo del método de pago.
Merchant ID: tu Merchant ID de ECPay (producción). Se ignora en el modo de prueba.
Hash Key: tu Hash Key de ECPay (producción). Se ignora en el modo de prueba.
Hash IV: tu Hash IV de ECPay (producción). Se ignora en el modo de prueba.
Los espacios y los saltos de línea en las credenciales pegadas rompen todas las firmas, así que se eliminan al guardar y la página te lo indica. Un Hash Key y un Hash IV guardados 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 secrets: marca Hash Key o Hash IV y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
Opciones de pago
Enabled Payment Methods: los métodos que se ofrecen a los clientes. Con más de uno, el cliente elige en la finalización de compra. Los pedidos de ATM, CVS y código de barras permanecen en Awaiting ECPay payment hasta que el cliente paga. Hay que seleccionar al menos un método; si no hay ninguno, se activa Credit Card y la página te lo indica. Predeterminado: Credit Card.
Default Payment Method: el método preseleccionado. Debe ser uno de los métodos activados; si no, se usa el primer método activado. Predeterminado: Credit Card.
Order Prefix: el prefijo del número de transacción de ECPay (MerchantTradeNo), de hasta 5 letras o dígitos. Los demás caracteres se eliminan al guardar, con un aviso. Es útil cuando varias tiendas comparten una cuenta de ECPay: asigna a cada tienda su propio prefijo. Predeterminado: EC.
Notificaciones de pago
ECPay envía los resultados de los pagos a tu tienda. Esta sección muestra la Notification URL. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_ecpay_payment_gateway/notify, posiblemente con un código de idioma como /en/. La URL se envía con cada pago, así que no hay que configurar nada en ECPay, pero debe ser accesible desde internet en el puerto 80/443, sin cortafuegos ni autenticación básica delante. El modo de mantenimiento y la restricción por país de tu tienda no la bloquean.
Cada notificación se verifica mediante su firma CheckMacValue con las claves del entorno (prueba o real) en el que se inició el pago, y mediante el MerchantID de ese pago. Las notificaciones sin firma válida se rechazan, y ECPay las vuelve a enviar. Sin la notificación no se crea ningún pedido; comprueba el pago en el back office de ECPay.
Avanzado
Enable Logging: escribe los IDs de pedido, los números de transacción, los importes y los códigos de retorno de ECPay en logs/ecpay_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. No se registran claves ni datos de clientes. Los errores siempre se registran, incluso cuando este interruptor está desactivado. Predeterminado: desactivado.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete Data on Uninstall: cuando está activado, al desinstalar el módulo se eliminan sus ajustes y el registro. Los registros de pagos de ECPay y los estados de pedido siempre se conservan, así que los pedidos existentes siguen funcionando tras una reinstalación. Predeterminado: desactivado.
Finalización de compra
En el paso de pago el cliente elige el método de pago (por defecto ECPay (綠界)). Con varios métodos activados, el cliente también elige Credit Card, ATM (Virtual Account), CVS (Convenience Store) o Barcode en Payment Method.
Tras confirmar, el cliente ve Redirecting to ECPay for payment. Please wait... y es enviado a la página de pago de ECPay, con un botón Proceed to ECPay por si la redirección no se inicia. El total del carrito se envía en TWD enteros, con los nombres y las cantidades de los productos. La página de ECPay se abre en chino tradicional para los idiomas taiwanés y de Hong Kong, en chino simplificado, coreano o japonés para esos idiomas, y en inglés para todos los demás, según el idioma de la tienda del cliente. Todavía no existe ningún pedido en este punto.
El pedido se crea solo después de que ECPay lo confirme mediante una notificación firmada del servidor. Cuando el cliente hace clic en el enlace de volver a la tienda de la página de ECPay y el pedido ya existe, se abre la página estándar de confirmación del pedido. Muestra Your ECPay payment has been received. para un pedido pagado, Your ECPay payment was received and is being reviewed by the store. para un pedido retenido, y las instrucciones de pago para un pedido ATM, CVS o de código de barras pendiente. Si la notificación todavía no ha llegado, una página de Payment confirmation muestra We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. con los botones Check again y Back to checkout. Si ECPay informó de que el pago falló, 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.
En ATM, CVS y código de barras el cliente primero recibe los datos de pago. El pedido se crea en Awaiting ECPay payment, y el código del banco y la cuenta virtual, el código de pago de la tienda de conveniencia o los códigos de barras, el importe y la fecha Pay before se muestran bajo ECPay payment instructions en la página de confirmación del pedido y en los detalles del pedido del cliente. Cuando el cliente paga, ECPay envía otra notificación y el pedido se marca como pagado. Las instrucciones de pago no se añaden a los correos electrónicos de PrestaShop.
Cada intento crea un nuevo número de transacción de ECPay, porque ECPay rechaza los números reutilizados. Así, los reintentos tras un pago fallido funcionan, y si el cliente vuelve atrás en el navegador a la página de redirección, se inicia un nuevo intento. Un carrito puede tener hasta 30 intentos de pago. Una vez que el carrito tiene un pedido, no se puede volver a pagar a través de la finalización de compra; un pedido ATM o CVS pendiente se paga con los datos ya emitidos.
Si el pago no puede iniciarse, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo The order total is too small for ECPay. cuando el total es inferior a 1 TWD tras el redondeo. Los límites de importe de ECPay para cada método se comprueban en la página de ECPay, no en la finalización de compra.
El módulo acepta pagos únicos solo en la página de ECPay. No tiene reembolsos desde PrestaShop, ni tarjetas guardadas, ni suscripciones o pagos periódicos (定期定額), ni pagos a plazos, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, facturas electrónicas ni logística, y no consulta el estado desde el servidor: si tu tienda no puede recibir la notificación, comprueba el pago en el back office de ECPay.
Pedidos
Estados del pedido
No order yet: el cliente fue enviado a ECPay y no ha pagado, o la notificación todavía no ha llegado. Solo existe el carrito.
Awaiting ECPay payment: el cliente eligió ATM, CVS o código de barras y recibió los datos de pago. La nota muestra el código del banco y la cuenta virtual, el código de pago o los códigos de barras, y la fecha límite.
Payment accepted: el pago fue confirmado. El pago se registra con el TradeNo de ECPay como ID de transacción, y una nota muestra el TradeNo, el tipo de pago, el importe y el número de transacción (con una marca de modo de prueba para los pagos de sandbox).
ECPay payment on hold: ECPay informó de un importe o una moneda distintos a los del carrito (por ejemplo, el carrito se cambió en otra pestaña después de iniciar el pago), un pago de sandbox llegó después de pasar al modo real (no se cobró dinero real), o el pago llegó después de que el pedido se hubiera cancelado (entonces el pago se registra). La nota lo explica. Compara con el back office de ECPay y tramita el pedido o reembolsa el pago allí.
Payment error: ECPay informó de que el último pago ATM, CVS o de código de barras de un pedido pendiente falló. La nota muestra el código de retorno y el mensaje de ECPay.
Las notificaciones repetidas se ignoran. Un pedido pagado, reembolsado o cancelado nunca se reabre por un fallo tardío. Un segundo pago de un pedido que ya está pagado, por ejemplo desde dos pestañas del navegador, se registra una sola vez como nota, para que puedas reembolsarlo en el back office de ECPay. Los pagos simulados iniciados desde el back office de ECPay solo se anotan y nunca marcan un pedido como pagado, porque ECPay no cobra dinero por ellos.
Bloque de pago de ECPay
La página del pedido muestra un bloque ECPay payment con cada intento de pago del pedido: el MerchantTradeNo con una insignia Test mode para los intentos de sandbox, el método, el importe en TWD, el estado, el TradeNo de ECPay, el tipo de pago y la fecha, y el código de retorno de ECPay. Debajo están las ECPay notes del pedido. Para un pedido en ECPay payment on hold, el bloque te recuerda que lo compares con el back office de ECPay.
Reembolsos
Los reembolsos desde PrestaShop no están disponibles. Reembolsa el pago en el back office de ECPay y después actualiza el pedido manualmente en PrestaShop. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de ECPay.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox ECPay Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox ECPay Payment Gateway > 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-ecpay y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del 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 seguido de una fecha. Después de 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 contactar con el 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 activa, ECPay no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda del lado del cliente 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 siguen confirmándose.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan 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 tras introducir la clave, y después una vez por semana. No hace falta 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
ECPay no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el carrito del cliente esté en TWD y que, en modo real, Merchant ID, Hash Key y Hash IV estén configurados. La página de ajustes muestra un mensaje en cada uno de estos casos. En Payment > Preferences comprueba que el módulo esté permitido para TWD, para el país del cliente y para el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: la notificación de ECPay no llegó a tu tienda (sitio caído, cortafuegos, autenticación básica). ECPay reintenta varias veces. También puedes comprobar la transacción en el back office de ECPay. Activa Enable Logging para ver las notificaciones que recibió el módulo; las notificaciones rechazadas se registran como errores en cualquier caso.
La notificación responde 0|CheckMacValue verification failed: la Hash Key o el Hash IV no coinciden con tu cuenta de ECPay, o el pago se inició en el otro entorno. Cópialos de nuevo desde el back office de ECPay.
La notificación responde 0|MerchantID mismatch: la notificación pertenece a un comerciante de ECPay distinto del que se usó para iniciar el pago.
La notificación responde 0|Order not found: el número de transacción no lo emitió esta tienda, por ejemplo cuando varias tiendas comparten una cuenta de ECPay. Asigna a cada tienda su propio Order Prefix.
La notificación responde 0|Retry: el carrito estaba siendo procesado por otra notificación en ese mismo momento, o el pedido no pudo crearse (por ejemplo, porque el módulo está desactivado). ECPay vuelve a enviar la notificación. Activa Enable Logging para ver el motivo.
La URL de notificación muestra 0|Method not allowed in the browser: es normal. La URL solo acepta solicitudes de ECPay.
El cliente ve «The order total is too small for ECPay.»: el total del carrito es inferior a 1 TWD tras el redondeo y no se puede pagar con ECPay.
El cliente ve «Too many payment attempts for this order»: el carrito llegó a 30 intentos de pago. Pide al cliente que inicie un carrito nuevo.
El pedido está en ECPay payment on hold: lee las notas del bloque ECPay payment (ver Estados del pedido), compara con el back office de ECPay y luego tramita el pedido o reembolsa el pago allí.
Desarrolladores: el hook actionEcpayPRequestParams permite que otro módulo cambie los parámetros enviados a ECPay; el comerciante, el número de transacción y el importe no pueden modificarse con él.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox ECPay Payment Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete Data on Uninstall está activado, se eliminan los ajustes y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos de ECPay y los estados de pedido Awaiting ECPay payment y ECPay payment on hold siempre se conservan, así que las notificaciones tardías de pagos antiguos siguen comprobándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.
ECPay es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por ECPay.