VibeFox ePayco 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: peso colombiano (COP) o dólar estadounidense (USD). Cuando el cliente paga en otra moneda, el método de pago no se muestra en la finalización de compra.

Cuenta de ePayco: necesitas las cuatro claves de tu cuenta de ePayco: P_CUST_ID_CLIENTE, P_KEY, PUBLIC_KEY y PRIVATE_KEY. Están en el panel de ePayco, en Integrations, API keys. Las mismas claves funcionan en modo de prueba y en modo de producción. Los métodos de pago que puede usar el cliente (tarjetas, PSE, redes de efectivo, billeteras) son los que estén habilitados en tu cuenta de ePayco.

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

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

Instalación

La descarga es un archivo ZIP con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_epayco_payment-oc3-(versión).ocmod.zip y el paquete de OpenCart 4 wcp_epayco_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 el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_epayco_payment-oc3-(versión).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 ePayco 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 las cuatro claves de ePayco y elige el tipo de finalización de compra (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Prueba un pago con Test Mode activado y con tarjetas de prueba de ePayco, y después desactiva Test Mode.

OpenCart 4

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_epayco_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 ePayco 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 cuatro claves de ePayco y los ajustes como en los pasos 3 a 5 de OpenCart 3. La página de configuración y sus campos son iguales en ambas versiones. Solo la URL de confirmación es diferente (véase URL de confirmación).

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba desactivado. La URL de confirmación se envía a ePayco con cada pago, así que no hay que configurar nada en el panel de ePayco.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox ePayco Payment > Edit. Las secciones aparecen a la izquierda; el botón Save bajo la lista guarda toda la página. Encima de los ajustes, la página explica que el pedido recibe un estado solo después de que ePayco confirme la transacción. Avisa cuando no se han introducido las cuatro claves (en ese caso, el método de pago no se muestra en la finalización de compra) y cuando la moneda predeterminada de tu tienda no es COP ni USD, y muestra Test mode is on: customers pay with ePayco test cards and no real money is charged. mientras el modo de prueba está activado. Sin el 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 inferior a cero, y la zona geográfica y los estados de pedido deben existir. Si no, aparece un error que indica el campo y no se guarda nada.

ePayco

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

Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Hasta 128 caracteres; si se deja vacío, los clientes verán ePayco. Predeterminado: ePayco.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmar. Predeterminado: Pay securely with ePayco.

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

Claves de la cuenta de ePayco

Encuentra las cuatro claves en el panel de ePayco, en Integrations, API keys (la sección enlaza con el panel). P_CUST_ID_CLIENTE y P_KEY verifican las confirmaciones de pago; PUBLIC_KEY y PRIVATE_KEY crean las sesiones de pago. Las mismas claves funcionan en modo de prueba y en modo de producción.

Customer ID (P_CUST_ID_CLIENTE): tu ID de cliente de ePayco (numérico).

Secret Key (P_KEY): se usa para verificar la firma de las confirmaciones de pago de ePayco. Manténla en secreto.

Public Key (PUBLIC_KEY): tu clave pública de la API de ePayco.

Private Key (PRIVATE_KEY): tu clave privada de la API de ePayco. Manténla en secreto.

Las claves guardadas Secret Key (P_KEY) y Private Key (PRIVATE_KEY) no 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 una clave guardada, marca Clear saved secret on save debajo del campo y haz clic en Save.

Test Mode: las sesiones de pago se crean como transacciones de prueba. Los clientes pagan con tarjetas de prueba de ePayco y no se cobra dinero real. Las transacciones de prueba nunca pagan pedidos creados en modo de producción. Predeterminado: desactivado. Mientras está activado, los clientes ven TEST MODE — use ePayco test cards, no real money is charged. en el paso Confirm Order y en la página de pago.

Finalización de compra

Checkout Type: cómo se abre el checkout de ePayco.

URL de confirmación

La URL de confirmación indica a tu tienda el resultado de un pago. Se envía a ePayco automáticamente con cada pago, así que no hay nada que configurar en el panel de ePayco. La sección muestra la URL. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_epayco_payment/confirmation, y en OpenCart 4, el de https://your-store/index.php?route=extension/wcp_epayco_payment/payment/wcp_epayco_payment.confirmation. Se construye a partir de la dirección pública de tu instalación de OpenCart. Debe ser accesible desde internet, sin que la bloquee un cortafuegos ni la autenticación básica. También funciona mientras la tienda está en modo de mantenimiento, porque OpenCart 3 deja pasar las peticiones de las extensiones de pago y la extensión añade en OpenCart 4 una acción de inicio para ello.

Cada confirmación debe llevar una firma válida hecha con tu P_CUST_ID_CLIENTE y P_KEY. Las confirmaciones sin firma válida se rechazan y no cambian nada. Sin la confirmación, un pedido recibe su estado solo cuando el cliente vuelve a la tienda después de pagar.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido faltante). El pedido recibe un estado solo después de que ePayco haya confirmado la transacción. Un pago rechazado o abandonado deja el pedido sin estado y el carrito se conserva. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: ePayco aprobó el pago, y el importe y la moneda coinciden con el pedido. Predeterminado: Procesando.

Awaiting Payment Status: ePayco informó que el pago está pendiente o retenido (transferencia PSE, redes de efectivo). El pedido cambia automáticamente cuando ePayco lo aprueba o lo rechaza. Predeterminado: Pendiente.

On Hold (Review) Status: ePayco aprobó un pago cuyo importe o moneda difiere del pedido, o lo aprobó después de que el pedido recibiera otro estado (por ejemplo, Cancelado). Una nota explica el motivo. No envíes el pedido antes de revisar la transacción en el panel de ePayco. Predeterminado: Pendiente, porque OpenCart no tiene el estado En espera. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Payment Failed Status: un pago pendiente fue rechazado, fallido, expirado o cancelado. Un nuevo pago aprobado sigue pagando el pedido. Predeterminado: Fallido.

Reversed Status: ePayco revirtió el pago del pedido. Predeterminado: Reembolsado.

Avanzado

Logging: registra los errores de la API y las confirmaciones de pago en epc_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al llegar a 5 MB, se mueve a epc_p_debug.old.log.php. Las claves y los datos de los clientes no se registran. Predeterminado: desactivado. Los errores siempre se registran, incluso con esta opción desactivada.

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 extensión y el registro. Los datos de ePayco guardados para los pedidos siempre se conservan. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. Las claves secretas no se exportan.

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

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto, ePayco). En el paso Confirm Order, el cliente ve tu descripción y la nota After confirming the order you pay securely in the ePayco checkout (cards, PSE, cash, wallets). 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 crea una sesión de pago de ePayco por el total del pedido en la moneda del pedido, con los impuestos, el número de pedido y el nombre de facturación, la dirección, el correo electrónico y el teléfono. El pago aparece en ePayco como Order # y el número de pedido. El idioma del checkout es español o inglés, según el idioma de la tienda del cliente.

Después, el cliente ve la página ePayco payment con Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. El checkout de ePayco se abre como ventana emergente o como redirección, según Checkout Type. La página también tiene el botón Pay with ePayco y el enlace Choose another payment method. Cada nuevo Confirm Order crea una nueva sesión de ePayco (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). Si un pedido anterior del mismo carrito ya está pagado o pendiente de ePayco, el cliente pasa a la página de pedido completado y no se le vuelve a cobrar.

En el checkout de ePayco, el cliente paga con uno de los métodos habilitados en tu cuenta de ePayco. Después, ePayco envía la confirmación a tu tienda y devuelve al cliente. El pedido se marca como pagado solo cuando ePayco lo confirma: mediante la confirmación firmada o mediante una petición del servidor a ePayco cuando el cliente vuelve. El regreso del cliente por sí solo nunca paga un pedido. Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock, y el cliente ve la página de pedido completado de OpenCart.

Para un pago pendiente (por ejemplo, PSE o efectivo), el pedido recibe Awaiting Payment Status y la página de éxito muestra Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Si, cuando el cliente vuelve, el pago pendiente ya fue rechazado o ha expirado, la página muestra Your ePayco payment was not completed. Please contact us about this order. Si ePayco aún no ha confirmado el pago cuando el cliente vuelve, aparece la página Payment confirmation con We are waiting for ePayco to confirm your payment. This page does not need to stay open. y el botón Check again.

Si el pago fue rechazado, el cliente vuelve a la finalización de compra con Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. Si el cliente vuelve sin haber pagado, el mensaje es The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. El carrito se conserva y el pedido queda sin estado. En OpenCart 4 estos mensajes aparecen encima de la página de finalización de compra.

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ó sin pago de ePayco entretanto (por ejemplo, el pago pendiente falló o lo cancelaste), el cliente vuelve a la finalización de compra con el mensaje sobre el pago rechazado, y el siguiente Confirm Order paga un pedido nuevo del carrito. Si ese pedido ya tiene un estado pero el carrito ha cambiado desde entonces, incluida una nueva cantidad, el cliente vuelve a la finalización de compra, y el siguiente Confirm Order paga el carrito nuevo con un pedido nuevo. Un pedido pagado nunca se muestra como pagado para un carrito distinto.

Si ePayco no puede iniciar el pago, el cliente se queda en el paso Confirm Order con un mensaje breve encima del botón, por ejemplo We could not connect to ePayco. Please try again in a moment or choose another payment method. El motivo técnico se escribe en el registro.

La extensión solo admite pagos únicos. No tiene reembolsos desde la tienda, ni tarjetas guardadas, suscripciones ni pagos divididos, y no consulta a ePayco las transacciones pendientes: los pedidos se actualizan con la confirmación de ePayco y con el regreso del cliente.

Pedidos

Estados de pedido

Sin estado (pedido faltante): el cliente fue enviado a ePayco y no ha pagado, ePayco aún no ha confirmado el pago, o el pago fue rechazado. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Order Status After Payment (default Processing): ePayco aprobó el pago. Una nota muestra la referencia de ePayco, el estado, el importe, el método de pago y el código de aprobación.

Awaiting Payment Status (default Pending): ePayco informó que el pago está pendiente o retenido, por ejemplo una transferencia PSE o un pago en efectivo. Cuando ePayco lo aprueba, el pedido pasa a Order Status After Payment; cuando se rechaza, falla, expira o se cancela, el pedido pasa a Payment Failed Status. OpenCart envía correos al cliente sobre estos cambios.

On Hold (Review) Status (default Pending): ePayco aprobó un pago cuyo importe o moneda difiere del pedido, o aprobó un pago después de que asignaras al pedido otro estado (por ejemplo, Cancelado). La nota lo explica. Revisa la transacción en el panel de ePayco antes de enviar.

Payment Failed Status (default Failed): un pago pendiente no se completó. La nota muestra el motivo de ePayco. Un nuevo pago aprobado sigue pagando el pedido. Un fallo tardío nunca cambia un pedido pagado.

Reversed Status (default Refunded): ePayco revirtió el pago que pagó este pedido.

Si ePayco informa de otro pago aprobado para un pedido que ya está pagado, el estado no cambia. Una nota te pide que compruebes si hay un cobro duplicado y que lo reembolses en ePayco si es necesario. Si el cliente paga un segundo pedido del mismo carrito (por ejemplo, desde dos ventanas de ePayco abiertas), ese pedido no recibe estado, el cliente ve la página de pedido completado, y el pedido pagado recibe una nota que te pide reembolsar el segundo pago en ePayco. Se ignoran una transacción de prueba de un pedido realizado en modo de producción y una transacción que ya pertenece a otro pedido. Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox ePayco Payment

En Sales > Orders, abre un pedido pagado con ePayco. Al final de la página del pedido, junto a History y Additional, la pestaña VibeFox ePayco Payment muestra la ePayco reference (ref_payco), el Transaction ID, el State, el Payment method, el Approval code, la Transaction date, el Mode (con la etiqueta Test mode en los pagos de prueba), el Attempt status y las ePayco notes del pedido. En un pedido en revisión, la pestaña muestra una advertencia para revisar la transacción antes de enviar. La pestaña es de solo lectura y se muestra a los usuarios con acceso a la extensión.

Reembolsos

Los reembolsos desde la tienda no son compatibles. Reembolsa el pago en el panel de ePayco y, si es necesario, actualiza el pedido manualmente en OpenCart. Una reversión de la transacción de pago que informe ePayco pone el pedido en Reversed Status. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de ePayco.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox ePayco Payment es el primer bloque de Extensions > Extensions > Payments > VibeFox ePayco 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-epayco 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 inglés y ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.

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

Sin una clave activa, ePayco 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. 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 necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres 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 ninguna tarea cron. Al desinstalar la extensión, siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

ePayco does not appear at checkout: comprueba que la licencia esté activa, que Enable/Disable esté activado, que se hayan introducido las cuatro claves y que el cliente pague en COP o USD. La página de ajustes muestra un aviso cuando faltan claves. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total definido en los ajustes.

The payment went through, but the order stays without a status: la confirmación de ePayco no llega a tu tienda. Comprueba que la URL de confirmación que muestran los ajustes sea accesible desde internet y que no la bloquee un cortafuegos, una extensión de seguridad o la autenticación básica. Revisa el campo Log en la página de la extensión; activa Logging para ver cada confirmación. El pedido también recibe su estado cuando el cliente vuelve a la tienda después de pagar.

Confirmation answers Invalid signature: Customer ID (P_CUST_ID_CLIENTE) o Secret Key (P_KEY) no coinciden con la cuenta de ePayco que recibió el pago. Copia ambos de nuevo desde el panel de ePayco.

Confirmation answers Gateway not configured: P_CUST_ID_CLIENTE o P_KEY están vacíos. Introdúcelos en los ajustes.

Confirmation answers Order not found: la confirmación se refiere a un pedido sin un pago de ePayco de esta tienda.

Confirmation answers Busy, retry later: otra petición estaba actualizando el pedido en ese mismo momento. ePayco vuelve a intentar la confirmación. El motivo está en el registro.

The customer sees We could not connect to ePayco: ePayco rechazó PUBLIC_KEY y PRIVATE_KEY. El registro muestra la respuesta de ePayco. Copia de nuevo ambas claves.

The customer sees ePayco could not start the payment: ePayco no creó la sesión de pago. Lee el registro para ver el error de ePayco.

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

The ePayco checkout does not open: el cliente ve The ePayco checkout could not be loaded. Please reload the page or choose another payment method. El script del checkout de ePayco no se pudo cargar en la página de pago. El cliente puede recargar la página o usar Choose another payment method.

A test payment did not pay the order: las transacciones de prueba nunca pagan pedidos realizados en modo de producción. Haz el pedido de prueba mientras Test Mode está activado.

Order is in the review status after payment: lee las notas de la pestaña VibeFox ePayco Payment (ver Estados de pedido) y revisa la transacción en el panel de ePayco antes de enviar.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox ePayco Payment. La clave de licencia y el estado de 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 en una reinstalación. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, además, sus eventos y su acción de inicio, que deja pasar la confirmación y el regreso del cliente en modo de mantenimiento). Si Delete Data on Uninstall está activado, se eliminan los demás ajustes (título, descripción, claves, modo de prueba, tipo de checkout, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los datos de ePayco guardados para los pedidos siempre se conservan, así que las confirmaciones tardías 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 tras la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox ePayco Payment en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

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