VibeFox ECPay for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo.
PHP: 8.0 o posterior.
Moneda de la tienda: nuevo dólar taiwanés (TWD). ECPay solo cobra en TWD, y el método de pago se oculta cuando la tienda, o el pedido que se está pagando, usa otra moneda. Los importes se envían en TWD enteros, porque ECPay no acepta decimales: los totales del pedido se redondean al dólar más cercano. Usa 0 decimales para los precios en TWD para evitar el redondeo.
Cuenta de ECPay: para pagos reales necesitas el MerchantID, la HashKey y la HashIV de tu cuenta de comerciante de ECPay, desde el panel de comerciante de ECPay (vendor.ecpay.com.tw). Para las pruebas no se necesita ninguna cuenta de ECPay.
Acceso al sitio: tu sitio debe ser accesible desde internet por HTTP/HTTPS en el puerto 80/443, para que ECPay pueda entregar las notificaciones de pago. El modo de mantenimiento, un firewall o la autenticación básica delante del sitio las bloquean.
Clave de licencia de VibeFox: comprada en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_ecpay_payment_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate. WooCommerce debe estar activo.
3. Abre los ajustes: WooCommerce > Settings > Payments > ECPay (綠界) > Manage, o haz clic en Settings bajo el nombre del plugin en la página de Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia en la parte superior de la página y haz clic en Activate.
5. Activa Enable/Disable, elige los métodos de pago y mantén activado Test Mode para tus primeras pruebas. En el sandbox puedes pagar con la tarjeta de prueba de ECPay 4311-9522-2222-2222 (cualquier fecha de caducidad futura, CVV 222, código 3-D Secure de la página del sandbox).
6. Para pagos reales introduce el MerchantID, la HashKey y la HashIV (ver Configuración) y desmarca Test Mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > ECPay (綠界). Encima de los campos, la página muestra un error cuando la moneda de la tienda no es TWD (ECPay no se muestra entonces en la finalización de compra) y cuando el modo real no tiene MerchantID, HashKey y HashIV. Mientras el modo de prueba está activado, advierte que los pagos van al sandbox de ECPay con el comerciante de prueba público 3002607, que no se cobra ningún dinero, y que cualquiera que conozca las claves públicas del sandbox podría confirmar pedidos de prueba, por lo que el modo de prueba debe desactivarse antes de aceptar pedidos reales.
General
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. Predeterminado: ECPay (綠界).
Description: el texto que se muestra bajo el 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 panel de comerciante de ECPay (vendor.ecpay.com.tw) en System development management > System integration settings (系統開發管理 > 系統介接設定).
Test Mode: Enable sandbox/test mode envía los pagos al sandbox de ECPay (payment-stage.ecpay.com.tw) con el comerciante de prueba público de ECPay 3002607. Sin dinero real. Las credenciales de abajo solo se usan cuando el modo de prueba está desactivado. Predeterminado: activado.
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 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.
Opciones de pago
Enabled Payment Methods: los métodos ofrecidos a los clientes. Con más de uno, el cliente elige en la finalización de compra. Los pedidos de ATM, CVS y Barcode permanecen En espera hasta que el cliente paga. Debe seleccionarse al menos un método; si no se selecciona ninguno, se activa Credit Card. Predeterminado: Credit Card.
Default Payment Method: el método preseleccionado. Debe ser uno de los métodos activados; de lo contrario se usa el primer método activado. Predeterminado: Credit Card.
Order Prefix: el prefijo del número de transacción de ECPay (MerchantTradeNo), hasta 5 letras o cifras. Otros caracteres se eliminan al guardar. Útil cuando varias tiendas comparten una cuenta de ECPay: da a cada tienda su propio prefijo. Predeterminado: EC.
Notificaciones de pago
ECPay envía los resultados de pago a tu tienda. Esta sección muestra la URL de notificación. Tiene este aspecto: https://your-site/wc-api/ecpay_p_callback/. 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 modo de mantenimiento, firewall ni autenticación básica delante.
Cada notificación se comprueba mediante su firma CheckMacValue con las claves del entorno (prueba o real) en el que se inició el pago. Las notificaciones sin una firma válida se rechazan, y ECPay las envía de nuevo. Sin la notificación, ningún pedido se marca como pagado; comprueba el pago en el panel de ECPay.
Avanzado
Enable Logging: Log payment events and API calls escribe los ID de pedido, números de transacción, importes y códigos de retorno de ECPay en WooCommerce > Status > Logs, origen wcp_ecpay_payment_gateway. No se registran claves ni datos de clientes. Predeterminado: desactivado.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Elimina todos los ajustes, registros y metadatos de pedido de este plugin. Predeterminado: desactivado.
Finalización de compra
El cliente elige el método de pago (de forma predeterminada ECPay (綠界)). Con varios métodos activados, el cliente también elige Credit Card, ATM (Virtual Account), CVS (Convenience Store) o Barcode. Mientras el modo de prueba está activado, el método de pago muestra TEST MODE — ECPay sandbox, no real money is charged.
Después de realizar el pedido, 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 pedido se envía en TWD enteros con los nombres y cantidades de los artículos. La página de ECPay se abre en chino tradicional para los idiomas de sitio 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.
El pedido se marca como pagado solo después de que ECPay lo confirme con una notificación de servidor firmada. Cuando el cliente vuelve a la página de pedido recibido antes de que llegue la confirmación, la página muestra We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: con un botón Pay.
Para ATM, CVS y Barcode el cliente recibe primero los detalles de pago. El pedido se pone En espera, y el código bancario y la cuenta virtual, el código de pago en tienda de conveniencia o los códigos de barras, el importe y la fecha Pay before se muestran en ECPay payment instructions en la página de agradecimiento, en My account > Orders y en el correo de pedido en espera. Cuando el cliente paga, ECPay envía otra notificación y el pedido se marca como pagado.
Cada visita a la página de pago crea un nuevo número de transacción de ECPay, porque ECPay rechaza los números reutilizados. Así, la página Pay for order y los reintentos tras un pago fallido funcionan, y las notificaciones de cualquiera de estos números se asocian al pedido. Un pedido puede tener hasta 30 intentos de pago.
Los límites de importe propios de ECPay por método, por ejemplo para los pagos en tienda de conveniencia, se comprueban en la página de ECPay, no en la finalización de compra.
El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El plugin solo acepta pagos únicos en la página de ECPay. No tiene reembolsos desde WooCommerce, ni tarjetas guardadas, ni suscripciones o pagos periódicos (定期定額), ni pagos a plazos, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, facturas electrónicas o logística, ni consulta de estado en el servidor: si tu sitio no puede recibir la notificación, comprueba el pago en el panel de ECPay.
Pedidos
Estados del pedido
Pending payment: el cliente fue enviado a ECPay y aún no ha pagado, o la notificación aún no ha llegado.
On hold, waiting for payment: el cliente eligió ATM, CVS o Barcode y recibió los detalles de pago. La nota del pedido muestra el código bancario y la cuenta virtual, el código de pago o los códigos de barras y la fecha límite.
Processing: el pago se confirmó (el valor predeterminado de WooCommerce; los pedidos con solo productos descargables virtuales pasan a Completado). La nota del pedido muestra el TradeNo de ECPay, el tipo de pago, el importe y el número de transacción. El ID de la transacción es el TradeNo de ECPay.
On hold after payment: ECPay informó un importe o una moneda distintos a los del pedido, llegó un pago de sandbox después de cambiar al modo real (no se cobró dinero real), o el pago llegó después de que el pedido se hubiera cancelado. La nota del pedido lo explica. Compara con el panel de ECPay y completa o reembolsa el pedido manualmente.
Failed: ECPay informó que el último intento de pago falló. La nota muestra el código y el mensaje de retorno de ECPay. El cliente puede intentarlo de nuevo.
Las notificaciones repetidas se ignoran. Un pedido pagado, cancelado o reembolsado nunca se reabre por una notificación antigua. Un segundo pago para un pedido ya pagado, por ejemplo desde dos pestañas del navegador, se registra como una nota de pedido, para que puedas reembolsarlo en el panel de ECPay. Los pagos simulados iniciados desde el panel de ECPay solo se anotan y nunca marcan el pedido como pagado, porque ECPay no cobra dinero por ellos.
Reembolsos
Los reembolsos desde WooCommerce no están disponibles. Reembolsa el pago en el panel de ECPay y luego registra el reembolso manualmente en WooCommerce.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > ECPay (綠界). Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libera la plaza 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. Los gestores de tienda con sesión iniciada siguen viendo el método de pago, marcado (unlicensed — visible to admins only), así que puedes configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se comprueba de nuevo automáticamente en segundo plano.
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 la moneda de la tienda es TWD y que, en modo real, están configurados el Merchant ID, la Hash Key y la Hash IV. La página de ajustes muestra un error en cada uno de estos casos.
El pago se realizó, pero el pedido permanece en Pendiente de pago: la notificación de ECPay no llegó a tu sitio (sitio caído, firewall, modo de mantenimiento, autenticación básica). ECPay reintenta varias veces. También puedes comprobar la transacción en el panel de ECPay y completar el pedido manualmente. Activa Enable Logging para ver las notificaciones que recibió el plugin.
La notificación responde 0|CheckMacValue verification failed: la Hash Key o la Hash IV no coincide con tu cuenta de ECPay. Cópialas de nuevo desde el panel de ECPay.
La notificación responde 0|MerchantID mismatch: la notificación pertenece a otro comerciante de ECPay distinto de aquel con el que se inició el pago.
La notificación responde 0|Order not found: el número de transacción no fue emitido por esta tienda, por ejemplo cuando varias tiendas comparten una cuenta de ECPay. Da a cada tienda su propio Order Prefix.
El cliente ve The order total is too small for ECPay.: el total del pedido está por debajo de 1 TWD después del redondeo y no se puede pagar con ECPay.
El pedido está En espera con una nota de descuadre de importe: el importe que informa ECPay difiere del total del pedido, por ejemplo porque el pedido se editó después de que el cliente empezara a pagar. Compara con el panel de ECPay y completa o reembolsa el pedido manualmente.
El pedido está En espera después de un pago de sandbox: el pago se realizó en modo de prueba, pero la tienda está ahora en modo real. No se cobró dinero real. Comprueba el pedido manualmente.
El cliente ve Too many payment attempts for this order: el pedido alcanzó 30 intentos de pago. Pide al cliente que haga un nuevo pedido.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio cambió, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y elimínalo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes, los datos de ECPay almacenados en los pedidos y los registros se eliminan solo si Delete Data on Uninstall estaba activado. En caso contrario, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
ECPay es una marca comercial de su respectivo propietario. Este plugin no está afiliado a ECPay ni cuenta con su respaldo.