VibeFox Pesapal 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: el carrito debe estar en KES, UGX, TZS, ZMW, RWF o USD. En otras monedas, el método de pago no aparece en la finalización de compra. El carrito se cobra en su propia moneda; el módulo no convierte monedas. Los importes se envían en unidades principales, redondeados a la precisión de la moneda (UGX y RWF sin decimales).

Cuenta de Pesapal: necesitas la clave y el secreto de consumidor de una cuenta de comerciante de Pesapal. Las claves de sandbox y de producción son distintas. Las claves 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 claves de producción proceden de tu panel de comerciante de Pesapal. No hay que configurar nada más en el panel de Pesapal: el módulo registra por sí mismo su URL de notificación. Tu tienda debe ser accesible desde Internet, porque Pesapal le envía las notificaciones de pago.

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 subida, haz clic en Configure, o busca más tarde VibeFox Pesapal Pay Gateway en la lista de módulos y haz clic en Configure.

3. Introduce 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 (ver Clave de licencia).

4. Introduce la clave y el secreto de consumidor de sandbox, activa Enable/Disable, haz clic en Save y haz un pedido de prueba.

5. Introduce la clave y el secreto de consumidor de producción, desactiva Sandbox mode y haz clic en Save para aceptar pagos reales.

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

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, una etiqueta muestra el modo: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. o LIVE — 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 live) y cuando Pesapal no admite la moneda predeterminada de tu tienda.

Pesapal

Enable/Disable: Enable Pesapal activa o desactiva el método de pago. Por defecto: 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 guardado en el pedido. Por defecto: Pesapal (M-Pesa, Airtel Money, cards). Obligatorio: un título vacío no se guarda y se mantiene el anterior.

Description: el texto que aparece debajo del método de pago en la finalización de compra. Por defecto: 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 de producción, cada una en su propio campo.

Sandbox mode: Use the Pesapal sandbox (no real money). Cuando está activado, los pagos nuevos usan cybqa.pesapal.com con las claves de sandbox. Desactívalo para aceptar pagos reales en pay.pesapal.com con las claves de producción. Por defecto: activado.

Sandbox consumer key: la clave de consumidor de tu cuenta de comerciante de sandbox (demo). Se usa solo en el modo sandbox.

Sandbox consumer secret: el secreto de consumidor de tu cuenta de comerciante de sandbox. Se usa solo en el modo sandbox.

Live consumer key: la clave de consumidor de tu panel de comerciante de Pesapal. Se usa cuando el modo sandbox está desactivado.

Live consumer secret: el secreto de consumidor de tu panel de comerciante de Pesapal. Se usa cuando el modo sandbox está desactivado.

Las claves y los secretos guardados 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.

Clear saved consumer keys and secrets: marca la casilla y haz clic en Save para eliminar las cuatro claves y secretos guardados.

Guardar los ajustes elimina los tokens de acceso de Pesapal en caché. Cambiar de modo o de 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 cambiar.

Notificaciones de pago (IPN)

IPN URL: muestra la URL de notificación de tu tienda. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_pesapal_pay/webhook, posiblemente con un código de idioma como /en/. La URL se registra automáticamente en Pesapal con el primer pago, por separado para sandbox y producción y para cada par de claves, así que no hay nada que configurar. Tras el primer pago, la sección muestra Registered IPN ID: con el ID que devolvió Pesapal; antes, indica Not registered yet for the current mode and keys. La URL debe ser accesible desde Internet: sin cortafuegos ni protección con contraseña delante. Sigue funcionando mientras la tienda está en modo de mantenimiento y no la afecta la restricción de países de tu tienda.

Avanzado

Debug log: Log Pesapal requests and notifications. Escribe los detalles en logs/pesapal_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, aunque el interruptor esté desactivado. Las claves, los tokens y los datos de los clientes nunca se registran. Por defecto: desactivado.

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

Delete data: Delete the module settings and logs when the module is uninstalled. Los datos de Pesapal guardados en los pedidos (ID de seguimiento, notas) forman parte del historial de pagos y siempre se conservan. Desactivar el módulo nunca borra nada. Por defecto: desactivado.

Finalizar compra

En el paso de pago, el cliente elige el método de pago (por defecto Pesapal (M-Pesa, Airtel Money, cards)) y ve su descripción. Al confirmar, el módulo crea una solicitud de pago de Pesapal por el total del carrito en la moneda del carrito, con los datos de facturación de la dirección de facturación, y envía al cliente a la página de pago de Pesapal. La descripción del pago que se envía a Pesapal es Cart, el número del carrito y el nombre de la tienda. Allí el cliente paga con uno de los métodos que ofrece Pesapal, como M-Pesa, Airtel Money, MTN, tarjeta o banco. En este punto todavía no existe ningún pedido.

El pedido se marca como pagado solo después de que Pesapal lo confirme. Las notificaciones de Pesapal y el retorno del cliente no contienen datos de pago ni firma, así que el módulo 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 que se inició el pago. También comprueba que la transacción pertenece a este carrito y que el importe y la moneda pagados coinciden con el carrito. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido.

Los pagos por dinero móvil pueden tardar un momento. Si Pesapal aún no ha confirmado el pago cuando el cliente vuelve, una página de Payment confirmation 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. con los botones Check again y Back to checkout. La notificación de Pesapal crea el pedido en cuanto se confirma el pago. Si el pedido se ha puesto en espera, la página de confirmación 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 finalización de compra 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 carrito se conserva y el cliente puede volver a pagar. Se recuerda cada intento de pago del carrito, así que un pago hecho más tarde en una página anterior de Pesapal del carrito también se acepta.

Si Pesapal no puede iniciar el pago, el cliente se queda en la finalización de compra con 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. El motivo técnico se escribe en el registro. El total del pedido debe ser mayor que cero.

El módulo no tiene formulario de pago en tu propio sitio (el cliente siempre paga en la página de Pesapal), ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni conversión de moneda.

Pedidos y reembolsos

Estados de pedido

Todavía sin pedido: el cliente fue enviado a Pesapal y no ha pagado, el pago falló o Pesapal aún no ha confirmado el pago. Solo existe el carrito.

Payment accepted: Pesapal indica el pago como completado y el importe y la moneda coinciden. El pago se registra con el ID de seguimiento de Pesapal como ID de transacción, y una nota muestra el importe, el método de pago, el código de confirmación de Pesapal y el ID de seguimiento. Cada pago se aplica una sola vez.

Pesapal payment on hold: el importe o la moneda pagados no coinciden con el carrito (nota Pesapal amount/currency mismatch — held for review), o llegó dinero para un pedido que había sido cancelado. El importe realmente pagado se registra en el pedido cuando está en la moneda del pedido. Comprueba el pago en el panel de Pesapal y luego completa el pedido o reembolsa el pago.

Refunded: Pesapal indica que el pago que pagó el pedido ha sido revertido. La reversión de otro intento solo se anota en el pedido.

Si un segundo intento de pago de un carrito que ya está pagado también se completa, el pedido no cambia. Una nota te pide que reembolses el segundo pago en el panel de Pesapal. Los pedidos cancelados y reembolsados nunca se reabren automáticamente.

Bloque de pago de Pesapal

La página del pedido muestra un bloque Pesapal payment con una etiqueta Sandbox o Live, el ID de seguimiento, la referencia del comerciante, el estado de Pesapal, el método de pago, el código de confirmación, el importe solicitado y el importe pagado, el motivo de una revisión, todos los Payment attempts del carrito y las Payment notes del pedido. El bloque es solo de lectura.

Reembolsos

El módulo no envía reembolsos a Pesapal. Reembolsa el pago en el panel de Pesapal y después registra el reembolso manualmente en PrestaShop.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Pesapal Pay Gateway es el primer bloque de Modules > Module Manager > VibeFox Pesapal Pay 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-pesapal 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 un hueco 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 hueco de dominio. Libera el hueco en tu cuenta de vibefox.net.

Sin una clave activa, Pesapal 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. 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, y las notificaciones de Pesapal sobre pagos existentes, incluidas las reversiones, se siguen aplicando.

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 por semana. No se necesita 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

Pesapal no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que la clave y el secreto de consumidor del modo actual están introducidos (Sandbox consumer key y Sandbox consumer secret en modo sandbox, Live consumer key y Live consumer secret en modo live) y que la moneda del carrito es KES, UGX, TZS, ZMW, RWF o USD. Las advertencias de la parte superior de los ajustes indican el problema. 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. Los desarrolladores pueden cambiar la lista de monedas con el hook actionPesapalSupportedCurrencies.

El pago se realizó, pero no se creó ningún pedido: la notificación de Pesapal no llegó a tu tienda y el cliente no volvió. Comprueba que la URL que aparece en IPN URL es accesible desde Internet (sin cortafuegos ni protección con contraseña delante). Activa Debug log y revisa el campo Log de la página del módulo.

Cómo responde la tienda a las notificaciones: una notificación procesada recibe HTTP 200. Cuando el módulo no puede procesarla, responde con un error y Pesapal vuelve a enviar la notificación más tarde: 400 (ID de seguimiento ausente o mal formado), 404 (ningún carrito de esta tienda tiene ese ID de seguimiento), 409 (la transacción pertenece a otra referencia de comerciante; no se cambia nada), 502 (no se pudo contactar con la API de Pesapal en ese momento, o faltan las claves del modo en que se inició el pago) y 503 (el cliente estaba actualizando el carrito con el retorno del cliente en ese mismo momento, o no se pudo crear el pedido, por ejemplo porque el módulo está desactivado).

El cliente ve Pesapal is not available at the moment: Pesapal rechazó la clave o el secreto de consumidor del modo actual. Comprueba que las claves pertenecen a ese modo: las claves de sandbox solo funcionan con sandbox, y las de producción solo en modo live. El registro muestra el error de Pesapal.

El cliente ve Pesapal is temporarily unavailable: no se pudo contactar con Pesapal o no se pudo registrar la URL de notificación. Revisa el registro y vuelve a intentarlo.

Los pagos de un modo anterior no se confirman tras cambiar: un pago se comprueba con las claves del modo en que se inició. Mantén introducidas las claves de ese modo hasta que sus pagos se confirmen.

El pedido está en Pesapal payment on hold tras el pago: lee las notas del bloque Pesapal payment. El importe o la moneda pagados no coincidían con el carrito, o el pago llegó después de que el pedido se cancelara. Comprueba el pago en el panel de Pesapal y luego procesa el pedido o reembolsa el pago.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Pesapal Pay Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Los tokens de acceso de Pesapal en caché y los ID de notificación registrados siempre se eliminan. Si Delete data está activado, también se eliminan los ajustes y el registro del módulo. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los intentos de pago de Pesapal y el estado de pedido Pesapal payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago, IDs de transacción e IDs de seguimiento de Pesapal.

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