VibeFox Windcave 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.

Cuenta de Windcave: necesitas una cuenta de comerciante de Windcave con credenciales de la API REST: un nombre de usuario de la API y una clave de API. Windcave las emite por separado para el entorno de pruebas UAT (uat.windcave.com) y para producción (sec.windcave.com). Pídeselas al soporte de Windcave o a tu gestor de cuenta. Las claves de PxPay no funcionan con este módulo. Los métodos de pago que quieras ofrecer (tarjetas, monederos digitales y otros) deben estar habilitados en tu cuenta de Windcave.

Notificación: tu tienda debe ser accesible desde internet para que Windcave pueda enviar su notificación de pago. No hay que configurar nada en Windcave para ello.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 subida, haz clic en Configure, o busca más tarde VibeFox Windcave Payment Gateway en la lista de módulos y haz clic en Configure.

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

4. Introduce tu nombre de usuario y tu clave de la REST API: las credenciales UAT para el modo de prueba y las credenciales de producción para los pagos reales (consulta Configuración).

5. Elige el tipo de transacción y los métodos de pago, activa Enable/Disable y haz clic en Save. Haz un pago de prueba con Test mode activado y después desactiva Test mode para cobrar pagos reales.

Al instalar, el módulo crea el estado de pedido Windcave payment on hold. PrestaShop ofrece el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Mientras el modo de prueba está activado, la página muestra Test mode está activado: los pagos van al entorno UAT de Windcave y no se cobra dinero real. Si el módulo está activado pero el modo actual no tiene nombre de usuario ni clave de la API, la página avisa de que el método de pago está oculto en la finalización de compra, por ejemplo Windcave está activado, pero el nombre de usuario o la clave de la API UAT están vacíos: el método de pago está oculto en la finalización de compra. El Title no puede estar vacío: en ese caso la página muestra Introduce un título para el método de pago. y no se guarda nada.

Windcave

Enable/Disable: Enable Windcave payments activa o desactiva el método de pago. Por defecto: 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. Por defecto: Credit/Debit Card (Windcave). Obligatorio.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Introduce las credenciales de la REST API que te ha emitido Windcave (nombre de usuario y clave de API, no las claves de PxPay). Las credenciales de producción y de UAT pueden guardarse una junto a la otra. El modo de prueba usa solo las credenciales UAT, y el modo real solo las de producción. La sección enlaza con la documentación de la REST API de Windcave.

Test mode: usa el entorno de pruebas UAT de Windcave (uat.windcave.com). No se cobra dinero real. Los pagos nuevos usan las credenciales UAT. Los reembolsos y las capturas siempre se envían al entorno en el que se pagó el pedido. Por defecto: desactivado.

Production API username: el nombre de usuario de la REST API para sec.windcave.com.

Production API key: la clave de la REST API para sec.windcave.com.

UAT API username: el nombre de usuario de la REST API para uat.windcave.com (modo de prueba).

UAT API key: la clave de la REST API para uat.windcave.com (modo de prueba).

Las claves de API guardadas 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.

Clear saved keys: marca Production API key o UAT API key y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.

Notification URL: muestra la dirección a la que Windcave envía su notificación de pago (Fail-Proof Result Notification). Con URL amigables tiene este aspecto: https://tu-tienda/module/wcp_windcave_payment_gateway/notification. No hay nada que configurar en Windcave: el módulo envía sus direcciones de retorno y esta dirección de notificación con cada sesión de pago. La dirección debe ser accesible desde internet; si no lo es, los pedidos solo se confirman cuando el cliente vuelve de Windcave. Ni el regreso del cliente ni la notificación están firmados por Windcave, así que el módulo nunca se fía de ellos por sí solos: siempre lee el resultado de la sesión desde la REST API de Windcave, con las credenciales del entorno en el que se creó la sesión.

Payment

Transaction type: cómo se cobra el pago. Por defecto: Purchase.

Payment methods: los métodos que se muestran en la página de pago de Windcave: Cards, Account2Account (transferencia bancaria de Nueva Zelanda), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. Usa Ctrl o Cmd y haz clic para seleccionar varios. Los métodos deben estar habilitados en tu cuenta de Windcave. Deja el campo vacío para mostrar todos los métodos habilitados en la cuenta. Por defecto: Cards.

Advanced

Debug log: registra las peticiones a la API y los eventos de pago en logs/windcave_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Mientras esta opción está desactivada, solo se registran errores y avisos. Las claves de API, los datos de la tarjeta y los datos personales del cliente nunca se registran. Por defecto: desactivado.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Clean uninstall: elimina la configuración y los registros del módulo al desinstalarlo. Los datos de pago guardados con los pedidos (los ID de transacción de Windcave necesarios para los reembolsos) se conservan siempre. Por defecto: desactivado.

La versión del módulo aparece al final de la página.

Finalizar compra

En el paso de pago, el cliente elige el método de pago (por defecto Credit/Debit Card (Windcave)) con su descripción. En modo de prueba, el cliente también ve Test mode: los pagos van al entorno UAT de Windcave y no se cobra dinero real. Al confirmar, el módulo crea una sesión de pago de Windcave por el total del carrito en la moneda del carrito y envía al cliente a la Windcave Hosted Payment Page. El número de carrito se envía como referencia del comerciante, junto con el idioma de la tienda y el nombre, el correo electrónico, el teléfono y la dirección de facturación del cliente (y la dirección de entrega cuando el carrito necesita envío). En este punto todavía no existe ningún pedido.

Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo después de que Windcave lo confirme: el módulo pide a la REST API de Windcave el resultado de la sesión, tanto cuando el cliente vuelve como cuando llega la notificación de Windcave. Un bloqueo por carrito garantiza que el pago se aplique una sola vez. Después se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your Windcave payment has been received. Para un pedido en espera (una autorización o un pago que no coincide con el carrito), la página muestra Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.

Si el cliente vuelve tras un pago aprobado pero el resultado todavía no se conoce, una página de Payment confirmation muestra We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. y un botón Check again. La notificación crea el pedido en cuanto Windcave confirma el pago.

Si el cliente vuelve sin haber completado el pago, la página de finalización de compra muestra uno de estos mensajes. El carrito se conserva.

El cliente puede volver a intentarlo con el mismo carrito. Un nuevo intento comprueba primero la sesión anterior: si ya está pagada, se crea el pedido y no se inicia un segundo pago; si el cliente nunca usó la página de pago y el carrito no ha cambiado, se le devuelve a la misma página. Si el pago anterior se está confirmando en ese momento, el cliente ve Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

Si Windcave no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve: que Windcave no ha podido iniciar el pago con los datos de este pedido, o que el servicio de pago no está disponible temporalmente. El motivo se escribe en el registro. Si el modo actual no tiene credenciales, el cliente ve This payment method is not available at the moment. Please choose another payment method or contact us.

La notificación funciona aunque la tienda esté en modo mantenimiento y no la bloquea la restricción por país de tu tienda.

El módulo no tiene suscripciones ni pagos recurrentes, tarjetas guardadas, formulario de tarjeta integrado en tu sitio (el cliente siempre paga en la página de Windcave), soporte de la API PxPay 2.0, ni añade recargos. Si Windcave añade un recargo, el pedido se compara con la transacción principal.

Pedidos y reembolsos

Order statuses

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

Payment accepted: un pago Purchase fue confirmado y coincide con el carrito. El pago se registra con el ID de transacción de Windcave, y una nota muestra el importe, el ID de transacción, el código de autorización, el tipo de tarjeta con el número enmascarado y el entorno (UAT o producción).

Windcave payment on hold (authorised): un pago Auth fue aprobado pero todavía no se ha capturado. No se registra ningún pago en el pedido hasta que se capture. La nota explica cómo capturarlo o liberarlo.

Windcave payment on hold (does not match): Windcave informó de un importe, una moneda, una referencia del comerciante o un tipo de transacción distintos a los del carrito (por ejemplo, el carrito se cambió en otra pestaña después de empezar el pago). La nota enumera las diferencias. En un pago Purchase en la moneda del carrito, el pago se registra con el importe que Windcave cobró realmente. Comprueba el pago en Windcave Payline antes de enviar el pedido y reembólsalo si es necesario.

Refunded: el pago se reembolsó por completo o la autorización se liberó a través del módulo.

Si llega un pago aprobado para un pedido cancelado, o un segundo pago aprobado para un pedido que ya existe, el pedido no se modifica. Una nota con el ID de transacción te pide reembolsarlo en Windcave Payline (o restaurar manualmente el pedido cancelado).

Windcave payment block

La página del pedido muestra un bloque Windcave payment con el ID de transacción, el ID de sesión, el tipo de transacción y el estado con el entorno, el importe pagado, el código de autorización y la tarjeta, la transacción de captura o anulación, el total pagado y el importe reembolsado, una insignia Test mode (UAT) para los pagos de prueba, el historial de reembolsos, todas las sesiones de Windcave del carrito y las Windcave notes del pedido.

Capture (Auth mode)

Para un pedido en Windcave payment on hold con una autorización que todavía no se ha capturado ni liberado, el bloque muestra Capture Windcave payment con el importe. Haz clic y confirma Capture the authorised amount through Windcave now? Se captura el importe autorizado (el total del pedido, salvo que el pago no coincida con el pedido), el pedido pasa a Payment accepted y el pago se registra con el ID de la transacción de captura. Si Windcave no acepta la captura, el bloque muestra Windcave capture failed: con el motivo, el motivo se añade a las notas y el pedido sigue en espera.

Refunds

En el bloque Windcave payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Windcave. Confirma la pregunta Refund this amount through Windcave? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Los reembolsos se calculan sobre el importe y la moneda que Windcave aprobó, así que tras una discrepancia puedes reembolsar hasta lo que el cliente pagó realmente, y no el total del pedido. Un reembolso posterior a una captura va a la transacción de captura. El reembolso se envía al entorno (UAT o producción) y a la cuenta en la que se hizo el pago, por lo que las credenciales de ese entorno deben estar guardadas. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID de transacción de Windcave. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.

Para un pago Auth que no se ha capturado, el botón es Release authorisation (void) y solo se puede liberar el importe total. Un importe parcial da un error que te pide reembolsar el importe total o capturar antes el pago.

Si Windcave rechaza el reembolso, el bloque muestra Windcave declined the refund: con el motivo, y no se registra ningún reembolso. Si Windcave todavía está procesando el reembolso, el bloque muestra Windcave has not confirmed the refund yet. See the order notes. y el reembolso no se registra. Comprueba la transacción en Windcave Payline: si fue aprobada, registra el reembolso manualmente; si no, vuelve a intentarlo. Un nuevo intento del mismo reembolso no se envía dos veces a Windcave.

El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Windcave. Los reembolsos hechos en Windcave Payline no se comunican a la tienda.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Windcave Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox Windcave Payment Gateway > 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-windcave 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 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 contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un solo 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, Windcave no se muestra a los clientes en el paso de pago. 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 queda oculto para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en el paso de pago. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose con la notificación o cuando el cliente vuelve a la tienda, y las capturas y los reembolsos funcionan.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. 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 ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Windcave no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga las dos credenciales: UAT API username y UAT API key en modo de prueba, Production API username y Production API key en modo real. La página de configuración muestra un aviso si faltan. 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: el módulo todavía no pudo obtener el resultado de Windcave. Mira el campo Log de la página del módulo: los errores siempre se registran, por ejemplo cuando no se pudo verificar la sesión. Comprueba que las credenciales del entorno del pago estén guardadas y sean correctas. La comprobación se repite cuando Windcave vuelve a enviar la notificación (el módulo responde payment could not be verified yet, retry later con un código de error, para que Windcave reintente), cuando el cliente hace clic en Check again y cuando el cliente inicia un nuevo pago para el mismo carrito. Tu servidor debe aceptar las peticiones de Windcave a la Notification URL que aparece en la configuración.

La notificación responde order not found: la sesión no la creó esta tienda, por ejemplo una sesión de otra tienda que usa la misma cuenta de Windcave. Se ignora.

Authentication failed en el registro: el nombre de usuario o la clave de la REST API son incorrectos, o pertenecen al otro entorno. Las credenciales UAT solo funcionan en modo de prueba, y las de producción solo en modo real. Las claves de PxPay no funcionan.

El cliente ve que Windcave no pudo iniciar el pago con los datos de este pedido: Windcave rechazó la solicitud de sesión, por ejemplo por la moneda o por un método de pago que no está habilitado en tu cuenta. El motivo exacto está en el registro.

El pedido está en Windcave payment on hold después del pago: lee las notas del bloque Windcave payment. Bien el pago es una autorización Auth que espera la captura, o el importe pagado, la moneda o la referencia del comerciante no coinciden con el carrito. Captura, prepara o reembolsa el pago.

Pagos de prueba y pagos reales: UAT y producción están separados. Cada sesión se comprueba en el entorno en el que se creó, y los reembolsos y las capturas van al entorno del pago, aunque cambies Test mode más tarde.

Un reembolso falla con un mensaje sobre el entorno: el pago se hizo en UAT o en producción, y no hay credenciales guardadas para ese entorno. Introdúcelas y vuelve a intentarlo.

Falta Capture Windcave payment en el bloque del pedido: el botón solo aparece en pedidos Windcave payment on hold pagados con Auth que no se hayan capturado ni liberado, y solo para los empleados que pueden editar pedidos.

Dónde encontrar más detalles: los errores y los avisos se escriben siempre en el registro; activa Debug log para registrar también las peticiones a la API y los eventos de pago.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Windcave Payment Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Clean uninstall está activado, se eliminan la configuración del módulo y el registro. Si está desactivado, toda la configuración se conserva para una reinstalación posterior. Las sesiones, transacciones y reembolsos de Windcave y el estado de pedido Windcave payment on hold se conservan siempre, así que los pedidos pagados antes se pueden reembolsar y capturar después de reinstalar. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

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