VibeFox eWAY for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con la versión 3.0.5.0) u OpenCart 4.0.2 o posterior (probado con la versión 4.1.0.3).

PHP: 8.0 o posterior, con la extensión cURL.

Moneda: AUD, NZD, SGD, HKD o MYR. Para otras monedas de la finalización de compra, el método de pago se oculta en la finalización de compra. El pago se cobra en la moneda del pedido.

Cuenta de eWAY: necesitas una cuenta de comerciante de eWAY con acceso a la API Rapid, y su clave y contraseña de la API Rapid, que encontrarás en MyeWAY, en Settings, API Key. Para hacer pruebas necesitas una cuenta sandbox de eWAY con su propia clave y contraseña. Las claves de sandbox y de producción son distintas. No hace falta configurar nada en MyeWAY: la URL de retorno se envía con cada pago.

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

Instalación

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_eway_payment_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_eway_payment_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 la administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_eway_payment_gateway-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 de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox eWAY Payment Gateway 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 tu clave y contraseña de la API sandbox, deja Sandbox Mode activado, activa Enable/Disable, haz clic en Save y realiza un pedido de prueba.

5. Introduce tu clave y contraseña de la API en vivo, desactiva Sandbox Mode y haz clic en Save.

6. Opcionalmente, añade la URL de cron que muestra la página de configuración a los cron jobs de tu servidor (ver Configuración).

OpenCart 4

1. En la administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_eway_payment_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 y elige el tipo Payments. Busca VibeFox eWAY Payment Gateway, 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, las claves de eWAY y la URL de cron como en los pasos 3 a 6 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de cron es diferente (ver Re-check of lost returns (cron)).

Una instalación nueva empieza con el método de pago desactivado y el modo sandbox activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > 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, una etiqueta indica el modo: SANDBOX — payments go to the eWAY sandbox, no real money is charged. o LIVE — real payments are taken with the live API key. La página avisa cuando faltan la clave o la contraseña de la API del modo actual (en ese caso el método de pago no se muestra en la finalización de compra) y cuando eWAY no admite la moneda predeterminada de la tienda. Sin permiso para 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 no negativo, y la zona geográfica y los estados de pedido seleccionados deben existir. Si no, no se guarda nada y la página indica qué hay que corregir.

eWAY

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

Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: Credit Card (eWAY). 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 securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

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

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

Credenciales de la API

La clave y la contraseña de la API Rapid están en MyeWAY, en Settings, API Key. eWAY tiene guías para las claves en vivo y sandbox, enlazadas en esta sección. Las claves de sandbox y en vivo son distintas. El modo sandbox usa solo las credenciales sandbox, y el modo en vivo, solo las credenciales en vivo.

Sandbox Mode: los pagos van al sandbox de eWAY con la clave y la contraseña sandbox. No se cobra dinero real. Predeterminado: activado. Desactívalo para cobrar pagos en vivo con la clave en vivo. Mientras está activado, el cliente ve Test mode: no real payment is taken. en el paso Confirm Order.

Live API Key: la clave de la API Rapid de tu cuenta de eWAY en vivo.

Live API Password: la contraseña de la API Rapid de tu cuenta de eWAY en vivo.

Sandbox API Key: la clave de la API Rapid de tu sandbox de eWAY (cuenta de socio/desarrollador).

Sandbox API Password: la contraseña de la API Rapid de tu cuenta sandbox de eWAY.

Las claves y contraseñas 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. Para eliminar un valor guardado, marca Clear the saved value on save debajo del campo y haz clic en Save.

Return URL: muestra la dirección de retorno de la extensión. Se envía automáticamente a eWAY con cada pago, junto con el pedido y una clave aleatoria del intento de pago, así que no hay que configurar nada en MyeWAY. El resultado de un pago siempre se consulta a eWAY de servidor a servidor.

Re-check of lost returns (cron): una URL de cron opcional, que aparece debajo de la URL de retorno. Llámala desde un cron job del servidor cada 15 minutos, por ejemplo con curl. Si un cliente paga y cierra el navegador antes de volver a la tienda, se pregunta a eWAY por el pago unos 60 minutos después de que el cliente fuera enviado a eWAY, y el pedido se actualiza. Si eWAY no responde, la comprobación se repite hasta tres veces. Mantén esta URL en privado: contiene un token secreto creado durante la instalación, y una llamada con un token incorrecto recibe la respuesta Forbidden. En OpenCart 4 la URL tiene esta forma: https://your-store/index.php?route=extension/wcp_eway_payment_gateway/payment/wcp_eway_payment_gateway.cron&token=(token).

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (pedido faltante). El pedido recibe un estado solo después de que eWAY haya confirmado el pago. Cada uno de los campos siguientes muestra los estados de pedido de tu OpenCart.

Order Status on Success: el estado que se asigna cuando eWAY confirma el pago. Predeterminado: En proceso.

eWAY payment on hold status: el estado de un pago aprobado que necesita tu revisión: el importe o la moneda no coinciden con el pedido, el pago se aprobó después de que el cliente pulsara Cancel en la página de eWAY, o el pedido ya tenía otro estado. Una nota en el historial del pedido explica el motivo. Predeterminado: Pendiente, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Refunded order status: el estado que se asigna después de reembolsar el pago por completo desde la página del pedido. Predeterminado: Reembolsado.

Avanzado

Debug log: escribe las llamadas a la API y los resultados de los pagos en eway_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al alcanzar 5 MB, se traslada a eway_p_debug.old.log.php. Los datos de tarjeta, las claves, las contraseñas, los correos electrónicos de los clientes y los códigos de acceso nunca se registran. Los errores siempre se registran. Predeterminado: desactivado.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Delete all extension data on uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los registros de pagos y reembolsos de eWAY de los pedidos siempre se conservan. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. Las claves y contraseñas de la API no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las claves y contraseñas de la API guardadas se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (predeterminado: Credit Card (eWAY)). En el paso Confirm Order, el cliente ve tu descripción y la nota You will be redirected to the secure eWAY payment page to pay by card. OpenCart crea el pedido en este paso, todavía sin estado. 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. Cuando el cliente hace clic en Confirm Order, la extensión pide a eWAY una página de pago por el total del pedido en la moneda del pedido, con OC- y el número del pedido como referencia de factura, y la dirección de pago y el correo electrónico del cliente; después envía al cliente a la página segura de eWAY (Responsive Shared Page). Allí, el cliente paga con tarjeta. El cobro se realiza de inmediato.

Después de pagar, el cliente vuelve a tu tienda. La extensión no se fía del navegador: pide a eWAY, de servidor a servidor, el resultado de la página de pago que creó este pedido. El pedido se marca como pagado solo cuando eWAY lo confirma y el importe y la moneda aprobados coinciden con el pedido. Después, el pedido recibe su estado de la forma habitual de OpenCart, con los correos electrónicos de pedido habituales y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart. En un pedido retenido, la página muestra además Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

Si en ese momento no se puede consultar a eWAY, aparece una página Payment confirmation con el texto We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again., con un botón Check again y un botón Back to checkout. El pedido recibe su estado cuando el cliente vuelve a comprobarlo o cuando se ejecuta la URL de cron.

Si el pago es rechazado, el cliente vuelve a la finalización de compra con el motivo, por ejemplo Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. El pedido queda sin estado. Si el cliente pulsa Cancel en la página de eWAY, la extensión comprueba antes con eWAY que no se haya pagado nada (por ejemplo, en otra pestaña). Después, el cliente ve You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. Si el pago no se completó, el mensaje es The payment was not completed. Please try again. En todos los casos, el carrito se conserva. En OpenCart 4, estos mensajes se muestran encima de la página de finalización de compra.

El cliente puede volver a intentarlo. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, y OpenCart 4 actualiza el pedido de la finalización de compra, de modo que un nuevo intento abre una nueva página de pago de eWAY para el mismo pedido. Antes de crear una nueva página de pago se comprueban con eWAY las páginas anteriores de este pedido y de otros pedidos del mismo carrito. Si alguna ya está pagada, se confirma ese pago en lugar de hacer un segundo cobro. Si eWAY no responde sobre ellas, el cliente ve We could not check the status of your previous payment attempt. Please try again in a moment. Si eWAY no puede crear la página de pago, el cliente permanece en el paso Confirm Order con un breve mensaje, por ejemplo Payment error: Unable to connect to eWAY. Please try again. o eWAY could not start the payment con los códigos de error de eWAY.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró entretanto sin pago (por ejemplo, si lo cancelaste), el cliente vuelve a la finalización de compra con el mensaje Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., y el siguiente Confirm Order paga un pedido nuevo del carrito. Si ese pedido ya está pagado pero el carrito ha cambiado desde entonces, incluida una nueva cantidad, el mensaje es Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. Un pedido pagado nunca se muestra como pagado para otro carrito.

Las URL de retorno y de cron también funcionan mientras la tienda está en modo mantenimiento, porque OpenCart 3 deja pasar las peticiones de las extensiones de pago, y la extensión añade para ellas una acción de inicio en OpenCart 4.

eWAY no envía notificaciones de servidor a servidor para la Shared Page: el resultado se obtiene cuando el cliente vuelve y mediante la URL de cron. La extensión no tiene campos de tarjeta en tu sitio, ni tarjetas guardadas ni suscripciones, ni autorización sin captura ni captura posterior, y no evalúa las puntuaciones de fraude de Beagle (las transacciones bloqueadas por las reglas antifraude de eWAY son rechazadas por el propio eWAY).

Pedidos y reembolsos

Estados del pedido

No status (missing order): el cliente fue enviado a eWAY y no ha pagado, ha cancelado, el pago fue rechazado o todavía no se ha podido obtener el resultado. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Order Status on Success (default Processing): el pago fue aprobado. Una nota muestra el ID de la transacción de eWAY, el código de autorización, la respuesta y el modo (sandbox o en vivo).

eWAY payment on hold status (default Pending): eWAY aprobó un importe o una moneda distintos de los del pedido (por ejemplo, Approved for partial amount), el pago se aprobó después de que el cliente lo hubiera cancelado en la página de eWAY, o se aprobó para un pedido al que ya habías asignado un estado, por ejemplo Canceled. El importe que eWAY cobró realmente queda registrado, y la nota lo explica. Revisa el pedido y cúmplelo o reembolsa el pago.

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

Si se aprueba un segundo pago para un pedido que ya está pagado, o para otro pedido del mismo carrito, el pedido pagado no cambia. Una nota te pide reembolsar el duplicado en MyeWAY. Un pago aprobado para otra referencia de factura nunca se aplica al pedido.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox eWAY Payment Gateway

En Sales > Orders, abre un pedido pagado con eWAY. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox eWAY Payment Gateway muestra el ID de la eWAY transaction con una etiqueta Sandbox o Live, el Auth code, la Response de eWAY, la Invoice reference, el Status del pago, los importes Paid / refunded, el formulario de reembolso, el historial de reembolsos y las eWAY notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via eWAY. Confirma la pregunta Refund this amount through eWAY? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para modificar la extensión (se configura en System > Users > User Groups). Los reembolsos se hacen en el importe y la moneda que eWAY cobró; por eso, después de una aprobación por un importe parcial, puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía en el entorno en que se hizo el pago (sandbox o en vivo), así que deben estar configuradas la clave y la contraseña de la API de ese entorno. Si eWAY rechaza el reembolso, la pestaña muestra eWAY refund failed: con los códigos de eWAY y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el ID de la transacción de reembolso de eWAY. Un reembolso total asigna al pedido el estado Refunded order status sin notificar al cliente y sin devolver los productos al stock, como un cambio de estado manual. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando eWAY ha aprobado el pago.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de eWAY. Los reembolsos hechos en MyeWAY no se sincronizan con OpenCart. Actualiza el pedido manualmente si es necesario.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox eWAY Payment Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > 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-eway y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios de administración con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma de la 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 y 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 el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.

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

Sin una clave activa, eWAY 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. Un usuario de administración que haya iniciado sesión en la administración 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 de la 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 de la 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 o la página Edit de la 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 hace falta ningún cron job. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

eWAY does not appear at checkout: comprueba que la licencia está activa, que Enable/Disable está activado, que la clave y la contraseña de la API del modo actual están establecidas (los campos sandbox en modo sandbox, y los campos en vivo en modo en vivo) y que la moneda de la finalización de compra es AUD, NZD, SGD, HKD o MYR. La página de ajustes muestra una advertencia cuando faltan las credenciales. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total de los ajustes.

The payment went through, but the order stays without a status: el cliente no volvió desde eWAY, o en ese momento no se pudo consultar a eWAY. eWAY no envía notificaciones para la Shared Page. Configura la URL de cron de Re-check of lost returns (cron): recoge el pago unas dos horas después. Comprueba la transacción en MyeWAY y mira el campo Log de la página de la extensión.

The cron URL answers Forbidden: el token de la URL es incorrecto. Copia la URL exactamente como la muestra la página de ajustes.

The customer sees This payment method is temporarily unavailable: faltan la clave o la contraseña de la API del modo actual, o eWAY las ha rechazado. Comprueba las credenciales del modo actual.

The customer sees eWAY could not start the payment: eWAY devolvió códigos de error, que aparecen en el mensaje. A menudo, los datos de facturación no son válidos.

The customer sees eWAY cannot take payments in a currency: la moneda del pedido no es una de las que admite eWAY. Usa AUD, NZD, SGD, HKD o MYR.

The customer sees We could not match this payment to an order: el enlace de retorno no pertenece a un pedido de esta tienda, o eWAY aprobó un pago para otra referencia de factura. Si el cliente fue cobrado, busca el pago en MyeWAY.

The customer sees This payment method is not available: la sesión de la finalización de compra ya no coincide con el pedido, o el método de pago se desactivó entretanto. El cliente recarga la finalización de compra.

Order is in the on hold status after payment: lee las eWAY notes de la pestaña VibeFox eWAY Payment Gateway (ver Estados del pedido) y, después, cumple el pedido o reembolsa el pago.

No refund form in the tab: la pestaña indica el motivo: no se encontró ningún ID de transacción de eWAY para el pedido, el pedido está reembolsado por completo, tu grupo de usuarios no tiene permiso para modificar la extensión, o no están configuradas las credenciales de la API del modo del pago.

Refund fails with a message about the sandbox or live mode: el pedido se pagó en ese entorno, y su clave y contraseña de la API no están configuradas. Introdúcelas e inténtalo de nuevo.

Refund fails with at most … can be refunded: el importe es mayor que lo que eWAY cobró menos los reembolsos ya realizados.

Para desarrolladores: la extensión activa los eventos de OpenCart wcp_eway_payment_gateway_supported_currencies (si tu cuenta de eWAY está habilitada para más monedas) y wcp_eway_payment_gateway_create_access_code_request (el cuerpo de la solicitud antes de crear la página de pago).

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox eWAY Payment Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre 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, que vuelven a sus valores predeterminados al reinstalar. El evento de OpenCart de la extensión también se elimina (en OpenCart 4, también sus eventos y su acción de inicio, que deja pasar las URL de retorno y de cron en modo mantenimiento). Si Delete all plugin data on uninstall está activado, se eliminan el resto de ajustes de la pasarela (título, descripción, modo sandbox, claves y contraseñas de la API, interruptor del registro de depuración, token de cron) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de eWAY siempre se conservan, de modo que los pedidos pagados antes pueden seguir reembolsándose tras 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 la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox eWAY Payment Gateway en la lista de extensiones instaladas y, después, en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

eWAY es una marca de su respectivo titular. Esta extensión no está afiliada a eWAY ni cuenta con su respaldo.