VibeFox ifthenpay for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Moneda: solo euro (EUR). La moneda EUR debe estar habilitada en tu tienda, y el método de pago solo se muestra cuando el cliente paga en EUR. ifthenpay acepta importes de 0,01 a 99.999,99 EUR.

Cuenta de ifthenpay: regístrate en ifthenpay.com. Necesitas la clave del método que ofreces: Multibanco, MB WAY o Credit Card (formato ABC-123456). Las claves se muestran en el backoffice de ifthenpay (backoffice.ifthenpay.com) o las envía ifthenpay cuando se activa el método para tu cuenta. ifthenpay también debe activar el callback para tu clave (véase Configuración), y tu tienda debe ser accesible desde internet.

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_ifthenpay_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_ifthenpay_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 el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_ifthenpay_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, 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 ifthenpay Gateway y haz clic en Install (el botón verde +). Tu usuario administrador necesita el permiso para modificar la lista de extensiones de pago. La extensión genera su clave anti-phishing al instalarse.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes. 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 (véase Clave de licencia).

4. Elige el Payment Method, introduce su clave de ifthenpay y haz clic en Save, para que la Callback URL coincida con el método elegido.

5. Copia la Anti-phishing Key y la Callback URL de la sección Callback y pide a ifthenpay que active el callback para tu clave (en el backoffice o a través del soporte de ifthenpay).

6. Activa Enable/Disable y haz clic en Save.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_ifthenpay_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 ifthenpay Gateway, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).

4. Introduce la clave de licencia, el método y su clave, y activa el callback como en los pasos 3 a 6 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. Solo la URL de callback es diferente (véase Callback).

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

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Sin la clave del método de pago seleccionado, el método no se muestra en la finalización de compra. Mientras la pasarela esté habilitada sin esa clave, la página muestra ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, el método de pago debe ser válido, el título puede tener como máximo 128 caracteres, Sort Order debe ser un número entero, Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido deben existir; de lo contrario no se guarda nada.

ifthenpay

Enable/Disable: Enable ifthenpay Payment activa o desactiva el método de pago. Por defecto: desactivado.

Title: el título del método de pago que se muestra en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: ifthenpay. Si lo dejas vacío, la finalización de compra mostrará ifthenpay.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmación. Por defecto: Pay via Multibanco, MB WAY or Credit Card. Cámbialo para que coincida con el método que ofreces.

Payment Method: el método que se ofrece en la finalización de compra. Solo se requiere la clave de este método.

Sort Order: la posición de ifthenpay 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 ifthenpay solo para direcciones de pago de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el total de la finalización de compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar antes de que se ofrezca ifthenpay. Déjalo vacío para ofrecer ifthenpay con cualquier total. ifthenpay solo se ofrece cuando el cliente paga en EUR, por importes de 0,01 a 99.999,99 EUR.

Claves de ifthenpay

Las claves (formato ABC-123456) se muestran en el backoffice de ifthenpay (la sección enlaza allí) o las envía ifthenpay cuando se activa el método de pago para tu cuenta.

Multibanco Key: tu clave de ifthenpay Multibanco (MB) para referencias dinámicas.

MB WAY Key: tu clave de ifthenpay MB WAY.

Credit Card Key: tu clave de ifthenpay Credit Card. También verifica la firma del retorno del cliente desde la página de la tarjeta.

Las claves guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo. Para eliminar una clave guardada, marca Clear the saved key on save debajo del campo y haz clic en Save.

Callback

El callback informa a tu tienda de que se ha realizado un pago. Pide a ifthenpay que active el callback para cada clave que uses, con la clave anti-phishing y la URL de callback de esta sección. Multibanco y MB WAY se confirman solo mediante el callback; los pagos con tarjeta también se confirman con el retorno firmado desde la página de la tarjeta.

Anti-phishing Key: generada por la extensión, se muestra para copiarla. ifthenpay la envía de vuelta en cada callback; los callbacks sin ella se rechazan.

Callback URL: la URL de callback del método de pago seleccionado, con los marcadores de posición de ifthenpay, se muestra para copiarla. En OpenCart 3 empieza así: https://your-store/index.php?route=extension/payment/wcp_ifthenpay_gateway/callback; en OpenCart 4, así: https://your-store/index.php?route=extension/wcp_ifthenpay_gateway/payment/wcp_ifthenpay_gateway.callback. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart y continúa con los parámetros del método. Copia la URL completa exactamente como la muestran los ajustes. Si cambias el Payment Method, guarda y copia la nueva URL.

La clave anti-phishing de cada callback se compara con la tuya. Una clave ausente o incorrecta recibe la respuesta 403 y el pedido no cambia. El callback también debe corresponder a un pago de esta extensión: en Multibanco, por entidad y referencia; en MB WAY, por el pedido y una de sus solicitudes de MB WAY; en Credit Card, por el pedido y una de sus solicitudes de tarjeta. Sin un callback que funcione, los pedidos de Multibanco y MB WAY nunca se confirman, y los pagos con tarjeta solo se confirman mediante el retorno firmado. El callback también funciona mientras la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las solicitudes de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio que deja pasar el callback y el retorno del cliente desde la página de la tarjeta.

Orders

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido ausente). Con Multibanco y MB WAY, el pedido recibe el estado de espera en cuanto ifthenpay ha emitido la referencia o la solicitud de MB WAY; con Credit Card, el pedido recibe un estado solo desde el callback o el retorno firmado. Un pedido se marca como pagado solo cuando el importe coincide con el total del pedido hasta el céntimo. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: el estado que se establece cuando se confirma el pago. Por defecto: En proceso.

Awaiting payment status: se emitió una referencia de Multibanco o una solicitud de MB WAY, y el cliente aún tiene que pagar. Los datos de Multibanco se envían con este estado, en el correo del pedido y en el historial de pedidos del cliente. Por defecto: Pendiente.

Payment on hold status: ifthenpay informó de un pago que no coincide con el pedido (importe, moneda), de un pago posterior a la cancelación del pedido, o de un pago de un pedido cuyo carrito ya estaba pagado. Una nota explica el motivo. Por defecto: Pendiente, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Avanzado

Test Mode: Credit Card y Multibanco usan los endpoints de sandbox de ifthenpay; no se cobra dinero real, y usas las claves de prueba que proporciona ifthenpay. MB WAY no tiene sandbox: pruébalo con una clave de prueba de ifthenpay. El paso Confirm Order muestra una insignia TEST MODE. Por defecto: desactivado.

Debug Log: las solicitudes de API y los callbacks se escriben en ifthenpay_p_debug.log.php, en la carpeta de logs de OpenCart (storage/logs). El archivo no se puede abrir desde la web y se rota al llegar a 5 MB. Los errores siempre se registran. Las claves, la clave anti-phishing y los números de teléfono completos nunca se registran. Por defecto: desactivado.

Log: muestra el tamaño y las últimas entradas del log. 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, la clave anti-phishing y el log. Los pedidos y los registros de pago de ifthenpay siempre se conservan. Por defecto: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes como archivo JSON. Las claves de ifthenpay no se exportan.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. Las claves guardadas se conservan.

Finalización de compra

En el paso Payment Method el cliente elige el método de pago (por defecto, ifthenpay). En el paso Confirm Order el cliente ve tu descripción y la indicación del método. 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.

Multibanco. El cliente ve You will receive a Multibanco reference to complete the payment. Cuando el cliente hace clic en Confirm Order, la extensión crea una referencia dinámica de Multibanco por el total del pedido, y el pedido recibe el Awaiting payment status. La página de éxito del pedido muestra Multibanco Payment Details: entidad, referencia e importe, con Please use these details to pay at any Multibanco ATM or through your online banking. Los mismos datos se envían en el correo del pedido y aparecen en el historial de pedidos del cliente. Si ya se emitió una referencia para el pedido con el mismo importe, se reutiliza. El pedido se paga cuando ifthenpay envía el callback de pago.

MB WAY. El cliente introduce el MB WAY phone number (912 345 678, +351 912 345 678, o 351#912345678 para otros países); el teléfono del pedido se rellena. La extensión envía una solicitud de pago al teléfono, y el pedido recibe el Awaiting payment status. La página de éxito del pedido dice A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. El pedido se paga cuando ifthenpay envía el callback. Solo se guarda un número de teléfono enmascarado. Por defecto, OpenCart 4 no pide un teléfono en la finalización de compra; el campo queda vacío y el cliente introduce el número.

Credit Card. El cliente ve You will be redirected to a secure page to enter your card details. y es enviado a la página de tarjetas de ifthenpay. El pedido permanece sin estado, y el carrito se conserva. Tras un pago correcto, el cliente vuelve a tu tienda. El retorno solo se acepta con una firma válida de ifthenpay, un secreto de ese intento y una solicitud de tarjeta del pedido; entonces el pedido se marca como pagado y el cliente ve la página de éxito del pedido de OpenCart. Si el retorno no se puede verificar, no cambia nada, y una página de Payment confirmation muestra Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. con los botones Check again y Back to checkout; el callback confirma el pago en cuanto llega. Si el pago con tarjeta falla o se cancela, el cliente vuelve a la finalización de compra con The card payment was not completed. You can try again or choose another payment method. o The card payment was cancelled. You can try again or choose another payment method. Cada intento de tarjeta del pedido se conserva, así que un pago hecho en una pestaña antigua también se acepta. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra.

Cuando se confirma el pago, el pedido recibe su estado de la forma estándar de OpenCart, con los correos de pedido habituales. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 actualiza el pedido del proceso de compra, así que tras un pago con tarjeta cancelado o fallido, o una solicitud de MB WAY rechazada, el cliente paga el mismo pedido con un nuevo intento. Si el mismo carrito ya tiene un pedido pagado o un pedido a la espera de un pago de Multibanco o MB WAY, el cliente va a la página de éxito de ese pedido en lugar de iniciar un nuevo pago. Los datos de Multibanco y la indicación de MB WAY solo se muestran en la página de éxito mientras el pedido está a la espera de pago. Un cambio del carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago.

OpenCart 4 mantiene el pedido en el proceso de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, cancelaste un pedido a la espera de un pago de Multibanco), el cliente vuelve a la finalización de compra con Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Si el pedido ya está realizado y el carrito ha cambiado desde entonces, el mensaje es Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. En ambos casos, el siguiente Confirm Order paga un pedido nuevo del carrito.

Si no se puede iniciar el pago, el cliente permanece en el paso Confirm Order con un breve mensaje encima del botón, por ejemplo The Multibanco reference could not be created. Please try again or choose another payment method., The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. o The payment service is temporarily unavailable. Please try again in a few minutes. El motivo técnico se escribe en el log.

La extensión ofrece un método de ifthenpay a la vez. No tiene Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX ni Pay-by-Link, ni suscripciones ni tarjetas guardadas, ni caducidad o cancelación automática de referencias de Multibanco no pagadas, ni consulta periódica del estado del pago.

Pedidos

Estados de pedido

No status (missing order): se inició un pago con tarjeta y aún no está confirmado, o ha fallado o se ha cancelado. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status establecido en Missing Orders.

Awaiting payment status (default Pending): se emitió una referencia de Multibanco o se envió una solicitud de MB WAY. Las referencias no pagadas y las solicitudes de MB WAY rechazadas no cancelan el pedido automáticamente; cancela tú mismo esos pedidos si es necesario.

Order Status After Payment (default Processing): el pago se confirmó. Una nota muestra la referencia de Multibanco, la transacción de MB WAY o el ID de la solicitud de tarjeta, y cómo se confirmó.

Payment on hold status (default Pending): el importe recibido era distinto del total del pedido (por ejemplo, el carrito se cambió después de iniciar un pago con tarjeta), el pago llegó después de cancelar el pedido, o otro pedido del mismo carrito ya estaba pagado. La nota lo explica, y no se pide al cliente que pague de nuevo. Comprueba el pago en el backoffice de ifthenpay y completa o reembolsa el pedido manualmente. Un pago posterior correcto de un pedido así no lo modifica.

Un segundo pago para un pedido que ya está pagado solo añade una nota para comprobar si hay un pago duplicado en el backoffice de ifthenpay. Un pedido que hayas pasado a otro estado (por ejemplo, reembolsado) nunca se reabre; se añade una nota.

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

Pestaña VibeFox ifthenpay Gateway

En Sales > Orders abre un pedido pagado con ifthenpay. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox ifthenpay Gateway enumera los intentos de pago del pedido (fecha, método, una etiqueta Sandbox para pagos de prueba, importe, entidad y referencia de Multibanco o el teléfono enmascarado de MB WAY, ID de solicitud de ifthenpay y estado), un aviso de Payment on hold mientras el pedido está en espera, y las ifthenpay notes del pedido. La pestaña es de solo lectura y se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos desde OpenCart no son compatibles. Reembolsa el pago en el backoffice de ifthenpay y regístralo manualmente en OpenCart. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de ifthenpay. Un callback de devolución (DEVOLVIDO) solo añade una nota. Los demás estados que informa ifthenpay también solo añaden una nota.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox ifthenpay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox ifthenpay 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-ifthenpay y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen el inglés y el 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 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, ifthenpay 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 administrador que haya iniciado sesión en el panel de 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 del administrador, 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 del panel de 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 del panel de 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 se necesita ningún cron job. Al desinstalar la extensión siempre se elimina la clave de licencia y el estado de la licencia.

Solución de problemas

ifthenpay no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que la clave del Payment Method seleccionado esté introducida, que el cliente pague en EUR y que el total esté entre 0,01 y 99.999,99 EUR. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.

El cliente pagó, pero el pedido se queda en el estado de espera o sin estado: el callback no llega a tu tienda. Comprueba que ifthenpay haya activado la URL de callback y la clave anti-phishing para la clave que usas, y que la URL sea la del método seleccionado. La tienda debe ser accesible desde internet, no en localhost ni detrás de un inicio de sesión. Activa Debug Log y revisa el campo Log de la página de la extensión.

El callback responde 403 Forbidden: la clave anti-phishing del callback falta o es distinta de la de los ajustes. Vuelve a enviar a ifthenpay la clave que se muestra en los ajustes.

El callback responde 503 Not configured: la clave anti-phishing todavía no se ha generado. Abre una vez los ajustes de la extensión; ifthenpay reintentará el callback.

El callback responde 503 Busy: el mismo pedido estaba siendo procesado por otra solicitud en ese momento. ifthenpay reintentará el callback.

El callback responde Order not found: la referencia o la solicitud no pertenece a un pago de esta extensión, o el pedido se realizó con otro método de pago.

¿Por qué se puso en espera un pedido pagado? El importe recibido era distinto del total del pedido, el pago llegó después de cancelar el pedido, o otro pedido del mismo carrito ya estaba pagado. Lee las notas de la pestaña VibeFox ifthenpay Gateway, comprueba el pago en el backoffice de ifthenpay y completa o reembolsa el pedido manualmente.

No se pudo enviar la solicitud de MB WAY: el número de teléfono no está vinculado a MB WAY o tiene un formato incorrecto. Usa 912 345 678, o 351#912345678 para números de otros países.

Modo de prueba y MB WAY: ifthenpay no tiene sandbox para MB WAY; usa una clave de prueba proporcionada por ifthenpay.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox ifthenpay 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. Se elimina también el evento de OpenCart de la extensión (en OpenCart 4, también sus eventos y su acción de inicio, que deja pasar el callback y el retorno del cliente en modo de mantenimiento). Si Delete Data on Uninstall está activado, se eliminan el resto de ajustes de la pasarela, la clave anti-phishing y el log; tras una reinstalación se genera una nueva clave anti-phishing que debe enviarse de nuevo a ifthenpay. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pago de ifthenpay (referencias e ID de solicitud) siempre se conservan, así que los callbacks de referencias emitidas antes siguen encontrando sus pedidos 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 tras la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox ifthenpay Gateway en la lista de extensiones instaladas, y luego en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

ifthenpay es una marca comercial de su respectivo titular. Esta extensión no está afiliada ni respaldada por ifthenpay.