VibeFox EveryPay for OpenCart — Ayuda

Requisitos

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

PHP: 8.0 o posterior.

Cuenta de EveryPay: necesitas el nombre de usuario de la API, el secreto de la API y el nombre de la cuenta de procesamiento de tu tienda online. Aparecen en el EveryPay Merchant Portal, en la configuración de la tienda online. El portal de demostración (modo de prueba) y el portal en vivo tienen credenciales independientes. Los métodos de pago que puede usar el cliente (tarjetas, Apple Pay, Google Pay, enlaces bancarios) son los que están habilitados para tu cuenta de EveryPay.

Moneda: una cuenta de procesamiento cobra una sola moneda. El nombre de la cuenta empieza por el código de su moneda; por ejemplo, EUR3D1 cobra en euros. EveryPay solo se ofrece cuando el cliente paga en esa moneda.

Sitio público: la URL de callback de tu tienda debe ser accesible desde internet, sin que la bloqueen la autenticación básica ni un cortafuegos.

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_everypay_payment-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_everypay_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 la administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_everypay_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 de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox EveryPay 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 nombre de usuario de la API de prueba, el secreto de la API de prueba y el nombre de la cuenta de procesamiento del portal de demostración. Copia la Callback notification URL en el EveryPay Merchant Portal (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Realiza un pedido de prueba en modo de prueba; después, introduce las credenciales en vivo y desactiva Test Mode.

OpenCart 4

1. En la administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_everypay_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 Payments. Busca VibeFox EveryPay 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, las credenciales de EveryPay y el callback como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. Solo la URL del callback es diferente (ver Notificaciones de pago (callback)).

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

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox EveryPay 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 muestra Test mode is on: payments go to the EveryPay demo environment, no real money is charged. mientras el modo de prueba esté activado. Avisa cuando el método de pago está activado pero falta el nombre de usuario de la API, el secreto de la API o la cuenta de procesamiento del modo actual (en ese caso el método de pago no se muestra en la finalización de compra), y cuando la moneda de la cuenta de procesamiento es distinta de la moneda predeterminada de tu tienda. Sin permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title debe tener como máximo 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 deben existir. Si no es así, un error indica el campo y no se guarda nada. Los espacios y los saltos de línea de los nombres de usuario, los secretos y el nombre de la cuenta se eliminan.

EveryPay

Enable/Disable: Enable EveryPay 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. Hasta 128 caracteres; si se deja vacío, el cliente verá EveryPay. Predeterminado: EveryPay.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmación. Predeterminado: Pay securely by card or bank link on the EveryPay payment page.

Sort Order: la posición de EveryPay 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 EveryPay 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 EveryPay. Déjalo vacío para ofrecer EveryPay con cualquier total.

Cuenta de EveryPay

El nombre de usuario de la API, el secreto de la API y el nombre de la cuenta de procesamiento aparecen en el EveryPay Merchant Portal (configuración de la tienda online): el portal de demostración para el modo de prueba y el portal en vivo para los pagos reales (la sección incluye enlaces a ambos). Los entornos de prueba y en vivo tienen credenciales independientes.

Test Mode: los pagos van al entorno de demostración de EveryPay con las credenciales de prueba; no se cobra dinero real. Predeterminado: activado. Desactívalo para cobrar pagos reales con las credenciales en vivo. Mientras está activado, el cliente ve TEST MODE: EveryPay demo environment, no real money is charged. en el paso Confirm Order.

Test API Username: el nombre de usuario de la API del entorno de demostración.

Test API Secret: el secreto de la API del entorno de demostración.

Live API Username: el nombre de usuario de la API del entorno en vivo.

Live API Secret: el secreto de la API del entorno en vivo.

Processing Account Name: tu cuenta de procesamiento de EveryPay, por ejemplo EUR3D1. La cuenta define la moneda de cobro: el método de pago solo se ofrece para pedidos en esa moneda.

Los secretos de la API 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. Para eliminar un secreto guardado, marca Clear the saved API secret on save debajo del campo y haz clic en Save.

Notificaciones de pago (callback)

El callback informa a tu tienda de que un pago se ha finalizado, de modo que los pedidos se confirman aunque el cliente cierre el navegador. Copia la URL que muestra el ajuste Callback notification URL en la URL de callback de tu tienda online, en el EveryPay Merchant Portal, tanto en el portal de demostración como en el portal en vivo. En OpenCart 3, la URL tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_everypay_payment/callback. En OpenCart 4 tiene este aspecto: https://your-store/index.php?route=extension/wcp_everypay_payment/payment/wcp_everypay_payment.callback. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. Copia la URL exactamente como la muestran los ajustes.

El callback solo contiene las referencias de pago. La extensión nunca se fía de él por sí solo: pide a la API de EveryPay el estado del pago con las credenciales del modo en que se hizo el pago. Un callback de un pago que esta tienda no creó se rechaza sin ninguna petición a EveryPay. El callback también funciona 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 ello una acción de inicio en OpenCart 4 (también para el retorno del cliente). Sin el callback, un pedido recibe su estado cuando el cliente vuelve a la tienda o cuando haces clic en Check EveryPay payment status en la página del pedido.

Pedidos

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

Order Status After Payment: el estado del pedido que se asigna tras un pago verificado como liquidado o autorizado. Predeterminado: En proceso.

Manual Review Status: el pago se realizó, pero el importe o la moneda no coinciden con el pedido, el pedido se canceló entretanto o usa otro método de pago. Una nota explica el motivo y el pedido no se marca como pagado. Predeterminado: Pendiente, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Cancelled Order Status: un pago que llega para un pedido con este estado se pone en revisión manual en lugar de pagar el pedido. Predeterminado: Cancelado.

Avanzado

Debug log: registra los eventos de pago en wc_evp_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 wc_evp_debug.old.log.php. Los errores y las advertencias siempre se registran. Los secretos de la API, los correos electrónicos y los datos de tarjetas nunca 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 data on uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los datos de pago de EveryPay de los pedidos siempre se conservan. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. Los secretos de la API no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Los secretos de la API guardados se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (predeterminado: EveryPay). En el paso Confirm Order, el cliente ve tu descripción y la nota You will be redirected to the secure EveryPay payment page. 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 de métodos 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 crea un pago único de EveryPay por el total del pedido en la moneda del pedido, con el correo electrónico y la dirección de pago del cliente, y envía al cliente a la página de pago de EveryPay. El idioma de esa página sigue el idioma de la tienda del cliente (inglés, estonio, ruso, letón, lituano, finés o alemán; en otro caso, inglés). Allí, el cliente paga con uno de los métodos habilitados para tu cuenta de EveryPay.

Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando EveryPay lo confirma: la extensión pide a la API de EveryPay el estado del pago al volver y en el callback. 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. Si EveryPay todavía está procesando el pago, o si su API no responde en ese momento, aparece una página Payment confirmation con el texto Your payment is being confirmed by EveryPay. You will receive an e-mail as soon as the order is confirmed. y un botón Check again; el callback asigna el estado del pedido en cuanto EveryPay confirma el pago.

Si el pago falló, el cliente vuelve a la finalización de compra con Your EveryPay payment was not successful. Please try again or choose another payment method. Si el cliente salió de la página de pago sin pagar, el mensaje es The EveryPay payment was not completed. You can try again or choose another payment method. El carrito se conserva y el pedido queda sin estado. En OpenCart 4, estos mensajes se muestran encima de la página de finalización de compra.

OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 actualiza el pedido de la finalización de compra, de modo que un nuevo intento paga el mismo pedido con un nuevo pago de EveryPay. EveryPay no puede cancelar un pago una vez creado. Por eso, antes de un pago nuevo, la extensión comprueba con la API de EveryPay los intentos abiertos de este pedido y de otros pedidos del mismo carrito. Si uno de ellos ya está pagado, o si otro pedido del mismo carrito ya está pagado, el cliente va a la página de éxito sin hacer un segundo pago. Cada intento queda registrado, de modo que un pago hecho con un enlace antiguo también se reconoce. Si el cliente paga de todos modos un segundo pedido del mismo carrito (por ejemplo, desde dos pestañas abiertas del navegador), ese pedido no recibe estado, el cliente ve la página de éxito del pedido y el pedido pagado recibe una nota que te pide reembolsar el segundo pago en el EveryPay Merchant Portal.

En OpenCart 4, el pedido se mantiene 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, lo cancelaste), el cliente vuelve a la finalización de compra con Your previous order was cancelled. Please confirm the order again., 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 is already paid. Please confirm the order again: the cart will be paid with a new order. Un pedido pagado nunca se muestra como pagado para un carrito distinto.

Si EveryPay no puede iniciar el pago, el cliente permanece en el paso Confirm Order con un breve mensaje encima del botón, por ejemplo EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. Los detalles están en el registro.

La extensión solo admite pagos únicos. No ofrece reembolsos ni capturas desde la tienda, tarjetas guardadas ni pagos con un solo clic, suscripciones ni pagos recurrentes, campos de tarjeta integrados ni multimoneda.

Pedidos

Estados del pedido

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

Order Status After Payment (default Processing): EveryPay informó de que el pago está liquidado o autorizado. Una nota muestra el importe, la moneda y la referencia del pago. En el caso de un pago autorizado, la nota indica que los fondos están reservados: si tu cuenta no captura automáticamente, captura el pago en el EveryPay Merchant Portal. Cuando se liquida más tarde, una nota lo indica.

Manual Review Status (default Pending): el pago necesita revisión manual. El importe o la moneda pagados no coinciden con el pedido, el pedido tenía el estado Cancelled Order Status antes de que llegara el pago, o el pedido usa ahora otro método de pago. La nota lo explica y dice que el pedido no se marcó como pagado. Comprueba el pago en el EveryPay Merchant Portal y cumple o reembolsa el pedido manualmente. Los callbacks posteriores de este pago no completan el pedido automáticamente; un pago correcto de otro intento del mismo pedido sí lo paga.

Si se completa un segundo pago para un pedido que ya está pagado, el pedido no cambia. Una nota te pide reembolsar el pago duplicado en el EveryPay Merchant Portal. Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox EveryPay Payment

En Sales > Orders, abre un pedido pagado con EveryPay. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox EveryPay Payment muestra EveryPay payments of this order: Payment reference, Order reference, Mode (prueba o en vivo), Amount, EveryPay state, Result y Date de cada intento. Debajo aparecen las EveryPay notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Check EveryPay payment status: el botón de la pestaña lee desde la API el estado de cada pago de EveryPay del pedido, del más reciente al más antiguo, con las credenciales de su modo; aplica el resultado como se ha descrito y añade una nota con el estado de cada pago. Después, la pestaña se recarga. Necesitas el permiso para modificar pedidos (System > Users > User Groups); no hace falta el permiso para modificar la extensión. Úsalo cuando un callback nunca llegó, por ejemplo para ver una captura o un reembolso posterior. Un estado asignado con este botón se registra como un cambio de estado manual en la administración, sin los correos electrónicos de pedido ni la actualización del stock de la finalización de compra.

Reembolsos

Los reembolsos y las capturas desde la tienda no son compatibles. Reembolsa en el EveryPay Merchant Portal y, después, actualiza el estado del pedido en OpenCart. Cuando EveryPay informa de que un pago está reembolsado o ha sido objeto de un contracargo, la extensión solo añade una nota al pedido; el estado del pedido no cambia. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de EveryPay.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox EveryPay Payment es el primer bloque de Extensions > Extensions > Payments > VibeFox EveryPay 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-everypay 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, EveryPay 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 queda oculto 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.

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

EveryPay does not appear at checkout: comprueba que la licencia está activa, que Enable/Disable está activado, que el nombre de usuario de la API, el secreto de la API y el Processing Account Name del modo actual están establecidos, y que el cliente paga en la moneda de la cuenta de procesamiento. La página de ajustes muestra una advertencia en estos casos. 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 callback no funciona. Comprueba que la URL de Callback notification URL está configurada en el EveryPay Merchant Portal del modo que usas (demostración o en vivo) y que se abre desde internet. El pedido también recibe su estado cuando el cliente vuelve a la tienda después de pagar. Revisa el campo Log de la página de la extensión: los errores siempre se registran.

Callback answers Unknown payment, Unknown payment reference, Payment cannot be verified or Payment does not belong to this order: el pago no lo creó esta tienda o no se creó para este pedido, o la respuesta de EveryPay no coincide con él. No se cambia nada.

Callback answers Missing or invalid payment_reference: la solicitud no contenía una referencia de pago válida, por ejemplo cuando la URL se abre en un navegador.

Callback answers Not configured: faltan las credenciales del entorno donde se creó el pago, por ejemplo, un pago de prueba después de eliminar las credenciales de prueba. Vuelve a introducirlas; EveryPay reintenta el callback.

Callback answers Payment status unavailable, Busy, please retry or Processing error, please retry: no se pudo acceder a la API de EveryPay, otra solicitud estaba procesando el pedido en ese mismo momento, o el procesamiento falló. El motivo está en el registro. EveryPay reintenta el callback.

The customer sees This payment method is not available right now: faltan las credenciales o la cuenta de procesamiento del modo actual.

The customer sees EveryPay is temporarily unavailable or Unable to start the EveryPay payment: EveryPay rechazó las credenciales o no se pudo acceder a EveryPay. Comprueba el nombre de usuario y el secreto de la API del modo actual.

The customer sees This payment method does not support the order currency: la moneda del pedido es distinta de la moneda de la cuenta de procesamiento.

The customer stays on the Payment confirmation page: EveryPay todavía no ha finalizado el pago. El pedido recibe su estado mediante el callback, o cuando el cliente hace clic en Check again después de que EveryPay confirme el pago.

Order is in the review status: lee las EveryPay notes de la pestaña VibeFox EveryPay Payment. El importe o la moneda no coincidían, el pedido se había cancelado antes de que llegara el pago, o usa otro método de pago. Comprueba el pago en el EveryPay Merchant Portal y cumple o reembolsa el pedido manualmente.

Para desarrolladores: antes de crear el pago, la extensión activa los eventos de OpenCart wc_evp_oneoff_request (modificar la solicitud de pago) y wc_evp_locale (cambiar el idioma de 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 EveryPay Payment. 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. En OpenCart 4, también se eliminan el evento de la extensión (el mensaje de la finalización de compra) y su acción de inicio, que deja pasar el callback y el retorno del cliente en modo mantenimiento. Si el interruptor Uninstall de Advanced está activado, se eliminan el resto de ajustes de la pasarela (título, descripción, modo de prueba, credenciales, cuenta de procesamiento, registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los datos de pago de EveryPay de los pedidos siempre se conservan, de modo que los callbacks tardíos de pedidos antiguos siguen funcionando 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 y haz clic en Uninstall (el botón naranja −) junto a VibeFox EveryPay Payment en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

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