VibeFox Pesapal for WooCommerce — Ayuda
Requisitos
WordPress: 6.2 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Currency: el pedido debe estar en KES, UGX, TZS, ZMW, RWF o USD. Con otras monedas, el método de pago se oculta en la finalización de compra. El pedido se cobra en su propia moneda; el plugin no convierte monedas. Los importes se envían en unidades principales, redondeados a la precisión de la moneda (UGX y RWF sin decimales).
Pesapal account: necesitas la clave y el secreto de consumidor de una cuenta de comerciante de Pesapal. Las claves de sandbox y producción son distintas. Las de sandbox proceden de una cuenta de comerciante de demostración en cybqa.pesapal.com (Pesapal también publica claves de demostración en su portal para desarrolladores). Las de producción proceden de tu Panel de control de comerciante de Pesapal. No hay que configurar nada más en el Panel de control de Pesapal: el plugin registra su URL de notificación por sí mismo. Tu sitio debe ser accesible desde Internet porque Pesapal le envía las notificaciones de pago.
VibeFox license key: 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_pesapal_pay a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Pesapal > 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 la clave y el secreto de consumidor de sandbox, activa Enable/Disable, guarda y realiza un pedido de prueba.
6. Introduce la clave y el secreto de consumidor de producción, desmarca Sandbox mode y guarda para aceptar pagos reales.
Configuración
Todos los ajustes están en una página: WooCommerce > Settings > Payments > Pesapal. Encima de los campos, un distintivo muestra el modo: SANDBOX con Test payments on cybqa.pesapal.com — no real money is charged. o LIVE con Real payments on pay.pesapal.com. Aparece una advertencia cuando faltan las claves del modo actual (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., o lo mismo para producción) y cuando Pesapal no admite la moneda de tu tienda. En la lista de métodos de pago, Pesapal aparece marcado como modo de prueba mientras sandbox está activo.
Notificaciones de pago (IPN)
Este bloque muestra la URL de notificación de tu tienda. Tiene el formato https://your-site/wc-api/pesapal_pay/. La URL se registra automáticamente en Pesapal en el primer pago, por separado para sandbox y producción y para cada par de claves, por lo que no hay nada que configurar. Tras el primer pago, el bloque muestra Registered IPN ID: con el ID devuelto por Pesapal; antes indica Not registered yet for the current mode and keys. La URL debe ser accesible desde Internet: sin modo de mantenimiento, cortafuegos ni protección con contraseña que impidan el acceso.
Finalización de compra
Enable/Disable: Enable Pesapal activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ven los clientes al finalizar la compra. Predeterminado: Pesapal (M-Pesa, Airtel Money, cards).
Description: el texto que aparece bajo el método de pago al finalizar la compra. Predeterminado: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.
Credenciales de API
La sección explica dónde obtener las claves y enlaza a cybqa.pesapal.com y pesapal.com. Introduce las claves de sandbox y producción en sus respectivos campos. Todos los campos de claves son campos de contraseña.
Sandbox mode: Use the Pesapal sandbox (no real money). Cuando está activado, los nuevos pagos usan cybqa.pesapal.com con las claves de sandbox. Desmárcalo para aceptar pagos reales en pay.pesapal.com con las claves de producción. Predeterminado: activado.
Sandbox consumer key: la clave de consumidor de tu cuenta de comerciante de sandbox (demostración). Solo se usa en modo sandbox.
Sandbox consumer secret: el secreto de consumidor de tu cuenta de comerciante de sandbox. Solo se usa en modo sandbox.
Live consumer key: la clave de consumidor de tu Panel de control de comerciante de Pesapal. Se usa cuando el modo sandbox está desactivado.
Live consumer secret: el secreto de consumidor de tu Panel de control de comerciante de Pesapal. Se usa cuando el modo sandbox está desactivado.
Cambiar el modo o las claves nunca reutiliza un token de acceso ni un ID de notificación del otro modo o de otras claves. Un pago iniciado en un modo siempre se comprueba en ese modo, incluso después de cambiarlo.
Avanzado
Debug log: Log Pesapal requests and notifications escribe los detalles en WooCommerce > Status > Logs, fuente wcp_pesapal_pay. Los errores y las advertencias siempre se registran. Las claves, los tokens y los datos de clientes nunca se registran. Predeterminado: desactivado.
Delete data: Delete the plugin settings and logs when the plugin is deleted. Los datos de Pesapal guardados en los pedidos (ID de seguimiento, notas) son el historial de pagos y siempre se conservan. Desactivar el plugin nunca elimina nada. Predeterminado: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Pesapal (M-Pesa, Airtel Money, cards)) y realiza el pedido. En modo sandbox, el bloque de Finalizar compra muestra Sandbox mode: no real money will be charged. El plugin crea una solicitud de pago de Pesapal por el total del pedido en su moneda, con los datos de facturación del pedido, y añade una nota al pedido con el modo, el importe y el ID de seguimiento de Pesapal. El cliente es redirigido a la página de pago de Pesapal y paga con uno de los métodos que ofrece Pesapal, como M-Pesa, Airtel Money, MTN, tarjeta o banco.
El pedido solo se marca como pagado tras la confirmación de Pesapal. Las notificaciones de Pesapal y el retorno del cliente no contienen datos de pago ni firma, por lo que el plugin no confía en ellos: para cada uno consulta a Pesapal el estado de la transacción mediante una solicitud autenticada entre servidores, en el modo en el que se inició el pago. También comprueba que la transacción pertenece a este pedido y que el importe y la moneda pagados coinciden con el pedido.
Tras pagar, el cliente vuelve a la página de pedido recibido. Los pagos con dinero móvil pueden tardar un momento. Si el pago aún no está confirmado, la página muestra Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. La notificación de Pesapal completa el pedido más tarde. Si el pedido se ha puesto en espera, la página muestra Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.
Si el cliente cancela en la página de Pesapal, vuelve a la página Pay for order con The Pesapal payment was cancelled. You can try again or choose another payment method. Si el pago falla, el mensaje es The Pesapal payment was not successful. Please try again or choose another payment method. El cliente puede volver a pagar el mismo pedido. Se recuerda cada intento de pago del pedido, por lo que también se acepta un pago realizado más tarde en una página anterior de Pesapal del pedido.
Si Pesapal no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (claves incorrectas) o Pesapal could not start the payment: seguido del motivo de Pesapal. Los detalles técnicos se incluyen en las notas del pedido y el registro. El total del pedido debe ser mayor que cero.
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 el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El plugin no tiene formulario de pago en la propia página de finalización de compra (el cliente siempre paga en la página de Pesapal), tarjetas guardadas, suscripciones o pagos recurrentes ni conversión de monedas.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente ha sido redirigido a Pesapal y aún no ha pagado, o Pesapal aún no ha confirmado el pago.
Processing: Pesapal informa de que el pago está completado y el importe y la moneda coinciden. La nota del pedido muestra el importe, el método de pago, el código de confirmación de Pesapal y el ID de seguimiento. El ID de transacción del pedido es el ID de seguimiento de Pesapal. Cada pago se aplica una sola vez.
On hold: el importe o la moneda pagados difieren del pedido (nota Pesapal amount/currency mismatch — held for review), o ha llegado dinero para un pedido cancelado antes de pagarse. Comprueba el pago en el Panel de control de Pesapal y después completa el pedido o reembolsa el pago.
Failed: Pesapal informa de que el último intento de pago ha fallado. La nota indica el motivo de Pesapal. Si el cliente lo intenta de nuevo desde la página Pay for order y ese intento también falla, se añade otra nota con el motivo. El fallo de un intento anterior no modifica el pedido. El cliente puede volver a pagar.
Refunded: Pesapal informa de que el pago que abonó el pedido ha sido revertido. La anulación de otro intento solo se anota en el pedido.
Si también se completa un segundo intento de pago de un pedido ya pagado, el pedido no se modifica. Una nota te pide que reembolses el segundo pago en el Panel de control de Pesapal. Los pedidos cancelados y reembolsados nunca se reabren automáticamente.
Reembolsos
El plugin no envía reembolsos a Pesapal. Reembolsa el pago en el Panel de control de Pesapal y registra después el reembolso manualmente en WooCommerce.
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 > Pesapal. 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 eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Pesapal no se muestra a los clientes al finalizar la compra. Si se inicia un pago de todos modos, 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 mediante la notificación de Pesapal y el retorno del cliente.
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.
Resolución de problemas
Pesapal no aparece al finalizar la compra: comprueba que la licencia esté activa, Enable/Disable esté activado, se hayan introducido la clave y el secreto de consumidor del modo actual (Sandbox consumer key y Sandbox consumer secret en modo sandbox, Live consumer key y Live consumer secret en modo de producción) y la moneda del pedido sea KES, UGX, TZS, ZMW, RWF o USD. Las advertencias de la parte superior de los ajustes indican el problema. Los desarrolladores pueden cambiar la lista de monedas con el filtro pesapal_p_supported_currencies.
El pago se ha realizado, pero el pedido sigue Pendiente de pago: la notificación de Pesapal no ha llegado a tu tienda y el cliente no ha vuelto. Comprueba que la URL mostrada en Payment notifications (IPN) sea accesible desde Internet (sin modo de mantenimiento, cortafuegos ni protección con contraseña que impidan el acceso a /wc-api/pesapal_pay/). Consulta WooCommerce > Status > Logs, fuente wcp_pesapal_pay.
Cómo responde la tienda a las notificaciones: una notificación procesada recibe una respuesta HTTP 200. Cuando el plugin no puede procesarla, responde con un error y Pesapal vuelve a enviarla más tarde: 400 (ID de seguimiento ausente o mal formado), 404 (ningún pedido de esta tienda tiene ese ID de seguimiento), 409 (la transacción pertenece a otra referencia de comerciante; el pedido no se modifica), 502 (no se pudo contactar con la API de Pesapal en ese momento) y 503 (el retorno del cliente estaba actualizando el pedido al mismo tiempo).
El cliente ve Pesapal is not available at the moment: Pesapal ha rechazado la clave o el secreto de consumidor del modo actual. Comprueba que las claves correspondan al modo: las de sandbox solo funcionan en sandbox y las de producción solo en producción. La nota del pedido muestra el error de Pesapal.
El cliente ve Pesapal is temporarily unavailable: no se pudo contactar con Pesapal o registrar la URL de notificación. Lee la nota del pedido y el registro e inténtalo de nuevo.
El pedido está En espera tras el pago: lee la nota del pedido. El importe o la moneda pagados diferían del pedido, o el pago llegó después de que se cancelara el pedido. Comprueba el pago en el Panel de control de Pesapal y después procesa el pedido o reembolsa el pago.
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 ha cambiado la dirección del sitio, 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.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y elimínalo en la página Plugins. La clave y el estado de licencia de este plugin, los tokens de acceso de Pesapal en caché y los ID de notificación registrados siempre se eliminan. Los ajustes del plugin y sus registros (archivos de registro, incluidos los rotados, y entradas de registro de la fuente wcp_pesapal_pay en la base de datos) solo se eliminan si Delete data estaba activado. De lo contrario, se conservan para una futura reinstalación. Los pedidos existentes conservan sus notas de pago, ID de transacción e ID de seguimiento de Pesapal.
Pesapal es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Pesapal ni cuenta con su respaldo.