VibeFox Flutterwave for WooCommerce — Ayuda

Requisitos

WordPress: 5.8 o posterior.

WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin WooCommerce.

PHP: 8.0 o posterior. El plugin no se activa con versiones anteriores de PHP.

Cuenta de Flutterwave: necesitas las claves secretas de tu cuenta de Flutterwave, disponibles en el panel de Flutterwave, en Settings, API keys: FLWSECK_TEST-… para el modo de pruebas y FLWSECK-… para el de producción. Solo se usan las claves secretas. No se necesitan las claves públicas ni de cifrado. También debes configurar un webhook con un hash secreto de tu elección (consulta Configuración).

Monedas: el pedido siempre se cobra en su moneda. El plugin no restringe países ni monedas; Flutterwave muestra un error si tu cuenta no admite la moneda.

Clave de licencia de VibeFox: comprada en vibefox.net. Una clave funciona en un dominio.

Instalación

1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_flutterwave_payment a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > Flutterwave > Manage, o haz clic en Settings bajo el nombre del plugin en la página de plugins.

4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.

5. Introduce tus claves secretas, configura el webhook en el panel de Flutterwave e introduce el mismo hash secreto en el plugin (consulta Configuración).

6. Activa Enable/Disable, prueba un pago en modo de pruebas y luego marca Live mode.

Configuración

Todos los ajustes están en una página: WooCommerce > Settings > Payments > Flutterwave. Encima de los campos se muestra Live mode: real payments are accepted. o Test mode: no real money is charged. Se te avisa cuando la clave secreta del modo actual está vacía, cuando el campo de clave de producción contiene una clave de pruebas (FLWSECK_TEST-…) en modo de producción o cuando el campo de clave de pruebas contiene una clave de producción (FLWSECK-…) en modo de pruebas; el método de pago queda oculto en la finalización de compra hasta que lo corrijas. También se te avisa si no hay un hash secreto del webhook: se rechazan los webhooks y los pagos solo se confirman cuando el cliente vuelve a tu tienda. En la lista de métodos de pago, Flutterwave se indica como pendiente de configuración hasta que el modo actual tenga una clave secreta, y muestra una insignia de modo de pruebas en dicho modo.

General

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

Title: el título del método de pago que ven los clientes al finalizar la compra. Predeterminado: Flutterwave.

Description: el texto que ven los clientes al finalizar la compra. Predeterminado: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

Claves de API

Copia las claves secretas del panel de Flutterwave, en Settings, API keys. El modo de pruebas y el de producción tienen claves distintas.

Live mode: Accept real payments (uncheck for test mode). El modo de pruebas usa la clave secreta de pruebas y no cobra dinero real. El modo de producción usa la clave secreta de producción. Predeterminado: off (modo de pruebas).

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

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

Webhook

El webhook confirma pagos incluso si el cliente no vuelve a tu tienda. En el panel de Flutterwave, en Settings, Webhooks, introduce la Webhook URL mostrada en esta sección y un hash secreto de tu elección, tanto en modo de pruebas como de producción. La URL tiene el formato https://your-site/wc-api/flw_p_webhook/. El plugin responde a este evento:

Los demás eventos se ignoran.

Secret Hash: el hash secreto del webhook. Debe coincidir con el valor de los ajustes del webhook en tu panel de Flutterwave. Flutterwave lo envía con cada webhook. Se rechazan los webhooks sin un hash secreto válido. Sin el webhook, un pago solo se confirma cuando el cliente vuelve a tu tienda.

Pago

Payment Options: métodos de pago separados por comas que se mostrarán 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 depura al guardar.

Autocomplete Orders: Automatically mark orders as completed after successful payment. Si está activado, los pedidos pasan a Completado en lugar de Procesando tras el pago, con un único cambio de estado. Predeterminado: off.

Avanzado

Debug log: Log Flutterwave API events for debugging en WooCommerce > Status > Logs, fuente wcp_flutterwave_payment. Los errores siempre se registran. Nunca se registran claves ni datos de clientes. Predeterminado: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Desactivar el plugin nunca elimina nada. Los datos de pago guardados en los pedidos siempre se conservan. Predeterminado: off.

Finalización de compra

El cliente elige el método de pago (por defecto Flutterwave) y realiza el pedido. En modo de pruebas, la finalización de compra muestra TEST MODE - no real payments will be processed. Se requiere un correo electrónico de facturación válido. El plugin crea un pago en Flutterwave por el total del pedido en su moneda, con el correo, teléfono y nombre del cliente y el nombre y logotipo de tu sitio, y envía al cliente a la página de pago de Flutterwave. Allí paga con uno de los métodos activados en tu cuenta (o indicados en Payment Options).

Tras pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando Flutterwave lo confirma: mediante el webhook o mediante una comprobación en el servidor cuando vuelve el cliente. Si el pago aún no está confirmado, por ejemplo una transferencia bancaria, USSD o dinero móvil pendiente, la página de pedido recibido muestra Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Si el dinero ha llegado pero el plugin ha puesto el pedido En espera para revisarlo, por ejemplo porque el importe pagado no coincide con el pedido, la página muestra Your payment was received and your order is being reviewed. We will contact you if anything is needed.

Si se rechaza el pago, el cliente vuelve a la finalización de compra (o a la página Pay for order) con Your payment was declined. You can try again or choose another payment method. Si cancela en la página de Flutterwave, se cancela el pedido realizado al finalizar la compra, un pedido creado manualmente queda sin pagar y se muestra Payment was cancelled. You can try again or choose another payment method. Si el pago no se ha completado, se muestra The payment was not completed. You can try again or choose another payment method.

El cliente puede volver a pagar un pedido sin pagar. Cada intento tiene su propia referencia y se sigue aceptando un enlace anterior que se pague más tarde. Si Flutterwave no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.

El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS). Los textos para clientes están traducidos al francés.

El plugin solo acepta pagos únicos. No incluye finalización de compra integrada ni modal en tu sitio, tarjetas guardadas, suscripciones, pagos divididos ni planes de pago. Los enlaces de pago alojados no pueden cancelarse mediante la API de Flutterwave, por lo que aún se puede pagar un enlace antiguo de un pedido.

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente ha sido enviado a Flutterwave y aún no ha pagado, o el pago sigue pendiente en Flutterwave.

Processing or Completed: el pago se ha confirmado. Se usa Completado cuando Autocomplete Orders está activado (los pedidos que solo contienen productos virtuales descargables también pasan a Completado, el comportamiento predeterminado de WooCommerce). La nota del pedido muestra el importe, el método de pago, la referencia de Flutterwave, la transacción y el modo. El ID de transacción del pedido es la referencia de Flutterwave.

On hold after payment: el importe o la moneda verificados no coincidían con el pedido, o el pago llegó después de cancelarlo. La nota lo explica. Tramita el pedido o reembolsa el pago. Un webhook repetido nunca reabre un pedido reembolsado o cancelado.

Failed: Flutterwave ha comunicado que el último intento de pago de un pedido pendiente ha fallado o se ha cancelado. La nota muestra el motivo.

Cancelled: el cliente canceló en la página de Flutterwave tras realizar el pedido al finalizar la compra, o el pedido lo cancelaste tú o el tiempo de espera de reserva de existencias de WooCommerce.

Si se recibe un segundo pago de un pedido ya pagado, el pedido no cambia. Una nota te pide reembolsar el duplicado en el panel de Flutterwave.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Flutterwave. Se admiten reembolsos totales y parciales. El reembolso se envía con la clave secreta del modo en que se hizo el pago (pruebas o producción), por lo que esa clave debe estar configurada. Si Flutterwave rechaza el reembolso, WooCommerce muestra el error y no registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con su ID y estado (completado, o iniciado con el estado comunicado por Flutterwave).

Los reembolsos realizados en el panel de Flutterwave no se sincronizan con WooCommerce. Si es necesario, crea un reembolso manual en WooCommerce sin Refund via Flutterwave.

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Flutterwave. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que está activa la licencia y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Flutterwave no se muestra a los clientes al finalizar la compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página de plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose y los reembolsos funcionan.

Cuando caduca una licencia, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.

Solución de problemas

Flutterwave no aparece al finalizar la compra: comprueba que la licencia esté activa, Enable/Disable esté activado y la clave secreta del modo actual esté rellenada y corresponda al modo: una clave de pruebas (FLWSECK_TEST-…) en modo de pruebas y una de producción (FLWSECK-…) en modo de producción. En caso contrario, la página de ajustes muestra un aviso.

El pago se ha realizado, pero el pedido sigue Pending payment: el webhook no funciona. En el panel de Flutterwave comprueba que la URL del webhook sea exactamente la mostrada en los ajustes, en el modo que usas (pruebas o producción), y que su hash secreto coincida con Secret Hash en el plugin. Las transferencias bancarias, USSD y el dinero móvil pendientes siguen pendientes hasta que Flutterwave los confirma. Activa Debug log y consulta WooCommerce > Status > Logs, fuente wcp_flutterwave_payment.

El webhook responde Invalid hash o Secret hash not configured: el hash secreto del panel de Flutterwave difiere del del plugin, o el plugin no tiene ninguno. Introduce el mismo valor en ambos sitios.

El webhook responde Verification failed o Busy, retry later: no se ha podido contactar con Flutterwave para verificar el pago, la transacción aún no es visible o otra solicitud estaba actualizando el pedido. Flutterwave reintenta el webhook.

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

El cliente ve We could not match this payment to an order: el enlace de retorno contiene una referencia que esta tienda no creó. Si se ha cobrado al cliente, busca el pago en el panel de Flutterwave.

Flutterwave muestra un error en su página: puede que tu cuenta de Flutterwave no admita la moneda del pedido o las opciones de pago seleccionadas.

El pedido queda On hold tras el pago: lee la nota del pedido. El importe o la moneda verificados no coincidían con el pedido, o el pago llegó después de cancelarlo. Tramita el pedido o reembolsa el pago.

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

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio cambió, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.

Para desarrolladores, la documentación del plugin enumera los filtros flw_p_payment_request (datos enviados a Flutterwave), flw_p_currency_decimals (precisión de la moneda) y flw_p_icon (icono en la finalización de compra).

Desinstalación

Al desactivar el plugin se conservan todos los datos. Para quitarlo, desactívalo y elimínalo en la página Plugins. La clave y el estado de licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros solo se eliminan si Delete data on uninstall estaba activado. En caso contrario, se conservan para una reinstalación posterior. Los datos de Flutterwave guardados en los pedidos siempre se conservan. Los pedidos existentes mantienen sus notas de pago e ID de transacción.

Flutterwave es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Flutterwave ni cuenta con su respaldo.