VibeFox ePayco for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

Moneda: peso colombiano (COP) o dólar estadounidense (USD). En los carritos con otras monedas, 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 sirven para el modo de prueba y para el de producción. Los métodos de pago que puede usar el cliente (tarjetas, PSE, redes de pago en efectivo, monederos) son los habilitados en tu cuenta de ePayco.

Sitio 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 dominio.

Instalación

1. En el back office, ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la carga, haz clic en Configure o, más tarde, busca VibeFox ePayco Payment en la lista de módulos y haz clic en Configure.

3. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (véase Clave de licencia).

4. Introduce las cuatro claves de ePayco y elige el tipo de finalización de compra (véase 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.

Al instalarse, el módulo crea dos estados de pedido: Awaiting ePayco payment y ePayco payment on hold. De forma predeterminada, PrestaShop habilita el nuevo método de pago para todas las monedas, países y grupos de clientes. Puedes restringirlo en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox ePayco Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te 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.

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 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: ePayco.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely with ePayco.

Claves de la cuenta de ePayco

Encuentra las cuatro claves en el panel de ePayco, en Integrations, API keys. P_CUST_ID_CLIENTE y P_KEY verifican las confirmaciones de pago; PUBLIC_KEY y PRIVATE_KEY crean las sesiones de finalización de compra. Las mismas claves sirven para el modo de prueba y para el 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 API de ePayco.

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

Las claves secretas 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.

Borrar las claves secretas guardadas: marca Secret Key (P_KEY) o Private Key (PRIVATE_KEY) y haz clic en Save para eliminar esa clave. Un campo vacío conserva el valor guardado.

Test Mode: las sesiones de finalización de compra 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. debajo del método de pago y en la página de pago.

Finalización de compra

Checkout Type: cómo se abre la finalización de compra 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. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_epayco_payment/confirmation, posiblemente con un código de idioma como /en/. Debe ser accesible desde internet, sin que la bloquee un cortafuegos ni la autenticación básica. Funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda.

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

Avanzado

Logging: escribe los errores de la API y las confirmaciones de pago en logs/epc_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. 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 últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Delete Data on Uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes del módulo y el registro. Los datos de ePayco guardados para los pedidos y los estados de pedido del módulo siempre se conservan, así que los pedidos existentes siguen funcionando. Predeterminado: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto ePayco) y confirma. El módulo crea una sesión de finalización de compra de ePayco por el total del carrito en la moneda del carrito, con los impuestos, el número de carrito y el nombre de facturación, la dirección, el correo electrónico y el teléfono. El pago aparece en ePayco como Cart # y el número de carrito. El idioma de la finalización de compra es español o inglés, según el idioma de la tienda. Todavía no existe ningún pedido en este punto.

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. La finalización de compra 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 clic en el botón de pago crea una nueva sesión de ePayco.

En la finalización de compra 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 solicitud del servidor a ePayco cuando el cliente vuelve. El regreso del cliente por sí solo nunca paga un pedido. Después se crea el pedido y el cliente ve la página estándar de confirmación del pedido.

En el caso de un pago pendiente (por ejemplo, PSE o efectivo), el pedido se crea en Awaiting ePayco payment y la página de confirmación muestra Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Si el pago pendiente se rechaza o caduca más tarde, la página muestra Your ePayco payment was not completed. Please contact us about this order. Si ePayco todavía no ha confirmado el pago cuando el cliente vuelve, aparece una página de Payment confirmation con We are waiting for ePayco to confirm your payment. This page does not need to stay open. y un 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 no se crea ningún pedido.

Si ePayco no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, 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.

El módulo solo admite pagos únicos. No incluye reembolsos desde la tienda, 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 del pedido

No order yet: el cliente fue enviado a ePayco y no ha pagado, ePayco todavía no ha confirmado el pago o el pago fue rechazado. Solo existe el carrito.

Payment accepted: ePayco aprobó el pago. El pago se registra con la referencia de ePayco (ref_payco) como ID de transacción, y una nota muestra la referencia, el estado, el importe, el método de pago y el código de aprobación.

Awaiting ePayco payment: ePayco informó del pago como pendiente o retenido, por ejemplo una transferencia PSE o un pago en efectivo. El pedido cambia automáticamente cuando ePayco lo aprueba o lo rechaza.

ePayco payment on hold: ePayco aprobó un pago cuyo importe o moneda no coincide con el pedido (por ejemplo, el carrito se cambió después de iniciar el pago), o aprobó un pago después de que el pedido se hubiera cancelado. El importe realmente pagado se registra en el pedido cuando la moneda coincide. No envíes el pedido sin revisar antes la transacción en el panel de ePayco.

Payment error: un pago pendiente fue rechazado, fallido, caducado o cancelado. La nota muestra el motivo de ePayco. Un nuevo pago aprobado para el carrito sigue pagando el pedido. Un fallo tardío nunca cambia un pedido pagado.

Refunded: ePayco revirtió el pago de 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 doble y que lo reembolses en ePayco si es necesario. Una transacción de prueba para un pedido realizado en modo de producción, y una transacción que ya pertenece a otro pedido, se ignoran con una nota.

Bloque de pago de ePayco

La página del pedido muestra un bloque ePayco payment con la referencia de ePayco (ref_payco), el ID de transacción, el estado, el método de pago, el código de aprobación, la fecha de la transacción, una etiqueta Test mode para los pagos de prueba y las ePayco notes del pedido. En un pedido en ePayco payment on hold, el bloque muestra una advertencia para revisar la transacción antes de enviar.

Reembolsos

Los reembolsos desde la tienda no son compatibles. Reembolsa el pago en el panel de ePayco y, si hace falta, actualiza el pedido manualmente en PrestaShop. Una reversión de la transacción de pago que informa ePayco pone el pedido en Refunded.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox ePayco Payment es el primer bloque de Modules > Module Manager > VibeFox ePayco Payment > Configure, por encima de los ajustes. Introduce 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 de ellos están la línea Product: presta-payment-epayco y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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 y una fecha. Después de que cambie 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 contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. 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, 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. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: 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 ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

ePayco no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que se han introducido las cuatro claves y que la moneda del carrito es COP o USD. La página de ajustes muestra una advertencia cuando faltan claves. En Payment > Preferences, comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo del cliente.

El pago se realizó, pero no se creó ningún pedido: la confirmación de ePayco no llega a tu tienda. Comprueba que la URL de confirmación que aparece en los ajustes se abre desde internet y que no la bloquea un cortafuegos, un módulo de seguridad o la autenticación básica. Mira el campo Log de la página del módulo; activa Logging para ver cada confirmación. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar.

La confirmación responde «Invalid signature»: Customer ID (P_CUST_ID_CLIENTE) o Secret Key (P_KEY) no coincide con la cuenta de ePayco que recibió el pago. Copia ambas de nuevo desde el panel de ePayco.

La confirmación responde «Gateway not configured»: P_CUST_ID_CLIENTE o P_KEY está vacío. Introdúcelos en los ajustes.

La confirmación responde «Order not found»: la confirmación se refiere a un carrito sin un pago de ePayco de esta tienda.

La confirmación responde «Busy, retry later»: el pedido estaba siendo actualizado por otra solicitud en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). ePayco reintenta la confirmación. El motivo está en el registro.

El cliente ve «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.

El cliente ve «ePayco could not start the payment»: ePayco no creó la sesión de finalización de compra. Lee el registro para ver el error de ePayco.

La finalización de compra de ePayco no se abre: el cliente ve The ePayco checkout could not be loaded. Please reload the page or choose another payment method. El script de la finalización de compra 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.

Un pago de prueba no pagó el pedido: las transacciones de prueba nunca pagan pedidos realizados en modo de producción. Realiza el pedido de prueba con Test Mode activado.

El pedido está en ePayco payment on hold: lee las notas del bloque ePayco payment (véase Estados del pedido) y revisa la transacción en el panel de ePayco antes de enviar.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox ePayco Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete Data on Uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los datos de ePayco guardados para los pedidos y los estados de pedido Awaiting ePayco payment y ePayco payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

ePayco es una marca comercial de su respectivo titular. Este módulo no está afiliado a ePayco ni cuenta con su aprobación.