VibeFox Flutterwave for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.

Cuenta de Flutterwave: necesitas las claves secretas de tu cuenta de Flutterwave, en el panel de Flutterwave bajo Settings, API keys: FLWSECK_TEST-… para el modo de prueba y FLWSECK-… para el modo de producción. Solo se usan las claves secretas. Las claves públicas y de cifrado no son necesarias. También configuras un webhook con un hash secreto que elijas (ver Configuración).

Monedas: el carrito siempre se cobra en la moneda del carrito. El módulo no restringe países ni monedas por sí mismo; Flutterwave muestra un error si tu cuenta no admite la moneda. Puedes limitar monedas, países y grupos de clientes en Payment > Preferences.

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 busca VibeFox Flutterwave Payment más tarde en la lista de módulos y haz clic en Configure.

3. Pega tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (consulta Clave de licencia).

4. Introduce tus claves secretas, configura el webhook en el panel de Flutterwave e introduce el mismo hash secreto en el módulo (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Prueba un pago en modo de prueba y después activa Live mode.

Al instalarse, el módulo crea dos estados de pedido, Awaiting Flutterwave payment y Flutterwave payment on hold. PrestaShop ofrece un 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 Flutterwave Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Live mode: real payments are accepted. o Test mode: no real money is charged. Avisa cuando la clave secreta del modo actual está vacía, cuando el campo de la clave de producción contiene una clave de prueba (FLWSECK_TEST-…) en modo producción, o cuando el campo de la clave de prueba contiene una clave de producción (FLWSECK-…) en modo prueba; en ese caso el método de pago se oculta en la finalización de compra hasta que se corrija. También avisa cuando no hay ningún hash secreto de webhook configurado: los webhooks se rechazan y los pagos solo se confirman cuando el cliente vuelve a tu tienda. El título de la primera sección muestra el modo actual, TEST o LIVE.

Flutterwave

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

Title: el título del método de pago que ven los clientes durante la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Flutterwave. Obligatorio.

Description: el texto que ven los clientes debajo del método de pago durante la finalización de compra. Por defecto: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

Claves de API

Copia las claves secretas desde el panel de Flutterwave bajo Settings, API keys (la sección tiene un enlace). El modo de prueba y el modo de producción tienen claves distintas.

Live mode: acepta pagos reales. Desactívalo para usar el modo de prueba. El modo de prueba usa la clave secreta de prueba y no se cobra dinero real. El modo de producción usa la clave secreta de producción. Por defecto: desactivado (modo de prueba). Mientras el modo de prueba está activo, los clientes ven TEST MODE - no real payments will be processed. debajo del método de pago.

Test Secret Key: tu clave secreta de prueba de Flutterwave (FLWSECK_TEST-...).

Live Secret Key: tu clave secreta de producción de Flutterwave (FLWSECK-...).

Las claves guardadas y el hash secreto 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.

Webhook

El webhook confirma los pagos incluso cuando el cliente no vuelve a tu tienda. En el panel de Flutterwave, bajo Settings, Webhooks, introduce la URL que aparece en Webhook URL de esta sección y un hash secreto que elijas, tanto en modo de prueba como en modo de producción. Con URL amigables, la URL tiene este aspecto: https://your-shop/module/wcp_flutterwave_payment/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes. El módulo reacciona a este evento:

Los demás eventos se ignoran.

Secret Hash: el hash secreto del webhook. Debe coincidir con el valor de la configuración del webhook en tu panel de Flutterwave. Flutterwave lo envía con cada webhook, y se usa el mismo valor para el modo de prueba y el de producción. Los webhooks sin un hash secreto válido se rechazan. Sin el webhook, un pago solo se confirma cuando el cliente vuelve a tu tienda.

Clear saved secrets: marca Test Secret Key, Live Secret Key o Secret Hash y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

Pago

Payment Options: métodos de pago separados por comas que se muestran en la página de Flutterwave, por ejemplo card, banktransfer, ussd, mobilemoney. Déjalo vacío para mostrar todos los métodos activados en tu cuenta. La lista se limpia al guardar (minúsculas, sin duplicados).

Autocomplete Orders: los pedidos pagados reciben el estado Delivered en lugar de Payment accepted, con un solo cambio de estado. Por defecto: desactivado.

Avanzado

Debug log: registra los eventos de la API de Flutterwave con fines de depuración en logs/flwv_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y advertencias siempre se registran. Las claves, el hash secreto y los datos de los clientes nunca se registran. Por defecto: 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: elimina los ajustes y los registros del módulo al desinstalarlo. Los datos de pago guardados en los pedidos se conservan siempre. Por defecto: desactivado.

Finalización de compra

En el paso de pago el cliente elige el método de pago (por defecto Flutterwave) y confirma. Se requiere una dirección de correo electrónico válida. El módulo crea un pago de Flutterwave por el total del carrito en la moneda del carrito, con el correo electrónico del cliente, el teléfono y el nombre de la dirección de facturación, el nombre y el logotipo de tu tienda, y envía al cliente a la página de pago de Flutterwave. Allí el cliente paga con uno de los métodos activados en tu cuenta (o indicados en Payment Options). 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 Flutterwave lo confirme: mediante el webhook o mediante una comprobación en el servidor cuando el cliente regresa. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido. Si el pago sigue pendiente, por ejemplo una transferencia bancaria, un pago USSD o de dinero móvil, el pedido se crea en Awaiting Flutterwave payment y la página muestra Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Si el pedido se pone en espera para revisión, por ejemplo porque el importe pagado no coincide con el carrito, la página muestra Your payment was received and your order is being reviewed. We will contact you if anything is needed. Si un pago pendiente falla más tarde y el cliente vuelve a abrir la página de confirmación, esta muestra Your Flutterwave payment was not completed. Please contact us about this order.

Si Flutterwave no responde cuando el cliente regresa, una página Payment confirmation muestra Your payment is being confirmed by Flutterwave. Your order will be created as soon as it is confirmed — please do not pay again. con los botones Check again y Back to checkout. El webhook crea el pedido en cuanto llega.

Si el pago es rechazado, el cliente vuelve a la finalización de compra con Your payment was declined. You can try again or choose another payment method. Si el cliente cancela en la página de Flutterwave, el mensaje es Payment was cancelled. You can try again or choose another payment method. Si el pago no se completó, el mensaje es The payment was not completed. You can try again or choose another payment method. El carrito se conserva y el cliente puede volver a pagar. Cada intento tiene su propia referencia, y un enlace de pago anterior que se pague más tarde sigue siendo aceptado.

Si Flutterwave no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. El motivo técnico se escribe en el registro.

Si el carrito cambia entre el pago y su confirmación, por ejemplo en otra pestaña del navegador, los importes ya no coinciden y el pedido pasa a Flutterwave payment on hold con una nota.

El webhook funciona mientras la tienda está en modo de mantenimiento y no está bloqueado por la restricción de países de tu tienda.

El módulo solo acepta pagos únicos. No ofrece finalización de compra integrada ni modal en tu sitio, ni tarjetas guardadas, suscripciones, pagos divididos ni planes de pago. Los enlaces de pago alojados no se pueden cancelar mediante la API de Flutterwave, así que un enlace antiguo de un carrito todavía se puede pagar.

Pedidos y reembolsos

Estados del pedido

Sin pedido todavía: el cliente fue enviado a Flutterwave y no ha pagado, o Flutterwave aún no ha confirmado el pago. Solo existe el carrito.

Payment accepted or Delivered: el pago fue confirmado. Delivered se usa cuando Autocomplete Orders está activado. El pago se registra con la referencia de Flutterwave (flw_ref) como ID de transacción, y una nota muestra el importe, el método de pago, la referencia, la transacción y el modo.

Awaiting Flutterwave payment: el cliente volvió mientras el pago seguía pendiente en Flutterwave. El pedido pasa al estado de pagado cuando Flutterwave confirma el pago.

Flutterwave payment on hold: el importe o la moneda verificados no coincidían con el carrito, o el pago llegó después de que el pedido se hubiera cancelado. El pago se registra con el importe realmente pagado (no con lo que Flutterwave cobró en otra moneda). La nota lo explica. Procesa el pedido o reembolsa el pago. Un pedido reembolsado o cancelado nunca se reabre por un webhook repetido.

Error de pago: Flutterwave informó de que el último intento de pago de un pedido pendiente falló o fue cancelado. La nota muestra el motivo.

Canceled: lo estableces tú. Si Flutterwave informa después un pago de un pedido cancelado, el pedido pasa a Flutterwave payment on hold (ver arriba).

Refunded: el pago fue reembolsado en su totalidad a través del módulo.

Si se recibe un segundo pago para un pedido que ya está pagado, el pedido no cambia. Una nota pide que reembolses el duplicado en el panel de Flutterwave.

Bloque Flutterwave payment

La página del pedido muestra un bloque Flutterwave payment con la referencia (tx_ref), el ID de transacción y la referencia de Flutterwave, el modo, el estado y el método de pago, el importe pagado y reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las Flutterwave notes del pedido.

Reembolsos

En el bloque Flutterwave payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Flutterwave. Confirma la pregunta Refund this amount through Flutterwave? 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 hacen por el importe y en la moneda que cobró Flutterwave, así que tras un desajuste de importe o moneda puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. El reembolso se envía con la clave secreta del modo en que se hizo el pago (prueba o producción), por lo que esa clave debe estar configurada. Si Flutterwave rechaza el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID y el estado del reembolso (completed, o initiated con el estado que indique Flutterwave). Un reembolso total cambia el pedido a Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez que Flutterwave ha confirmado el pago.

El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Flutterwave.

Los reembolsos realizados en el panel de Flutterwave no se sincronizan con PrestaShop. Actualiza el estado del pedido manualmente si es necesario.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Flutterwave Payment es el primer bloque de Modules > Module Manager > VibeFox Flutterwave Payment > Configure, 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 están la línea Product: presta-payment-flutterwave 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. Tras cambiar la dirección de la tienda, o después de liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al 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 hueco de dominio. Libéralo en tu cuenta de vibefox.net.

Sin una clave activa, Flutterwave 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 siguen confirmándose y los reembolsos funcionan.

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 tras introducir la clave, y después una vez a la semana. No se necesita 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

Flutterwave no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que la clave secreta del modo actual esté rellenada y corresponda al modo: una clave de prueba (FLWSECK_TEST-…) en modo de prueba, una clave de producción (FLWSECK-…) en modo de producción. La página de ajustes muestra una advertencia en caso contrario. En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo de clientes.

El pago se realizó, pero no se creó ningún pedido: el webhook no funciona. En el panel de Flutterwave comprueba que la URL del webhook sea exactamente la que aparece en Webhook URL, en el modo que uses (prueba o producción), y que su hash secreto sea el mismo que Secret Hash en el módulo. Las transferencias bancarias, USSD y de dinero móvil pendientes siguen así hasta que Flutterwave las confirme. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar. Activa Debug log y revisa el campo Log en la página del módulo.

El webhook responde Invalid hash o Secret hash not configured: el hash secreto del panel de Flutterwave es distinto del que está en el módulo, o el módulo no tiene ninguno. Introduce el mismo valor en ambos lugares.

El webhook responde Verification failed, Busy, retry later o Order could not be created, retry later: no se pudo contactar con Flutterwave para verificar el pago, la transacción aún no es visible, otra solicitud estaba procesando el carrito, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Flutterwave vuelve a intentar el webhook. El registro muestra el motivo.

La URL del webhook muestra Empty body en el navegador: es normal. La URL solo acepta webhooks de Flutterwave.

El cliente ve Payment gateway is not properly configured: la clave secreta del modo actual falta o pertenece al otro modo.

El cliente ve We could not match this payment to an order: el enlace de retorno lleva una referencia que no pertenece al carrito del cliente. Si el cliente fue cobrado, busca el pago en el panel de Flutterwave.

Flutterwave muestra un error en su página, o el cliente ve Flutterwave could not start the payment: es posible que tu cuenta de Flutterwave no admita la moneda del carrito o las opciones de pago seleccionadas.

El pedido está en Flutterwave payment on hold después del pago: lee las notas del bloque Flutterwave payment (ver Estados del pedido) y después procesa el pedido o reembolsa el pago.

El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o de producción, y la clave secreta de ese modo no está configurada. Introdúcela e inténtalo de nuevo.

El reembolso responde Another operation on this payment is running: en ese momento se estaba enviando otro reembolso del mismo pedido. Espera un momento, revisa el historial de reembolsos e inténtalo de nuevo si es necesario.

Para desarrolladores, el README del módulo enumera los hooks actionWcpFlutterwavePaymentRequest (datos enviados a Flutterwave) y actionWcpFlutterwaveCurrencyDecimals (precisión de la moneda).

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Flutterwave 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 pago de Flutterwave y los reembolsos de los pedidos, así como los estados de pedido Awaiting Flutterwave payment y Flutterwave payment on hold, se conservan siempre, de modo que los pedidos pagados antes se pueden reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Flutterwave es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Flutterwave ni avalado por esta empresa.