VibeFox PayFast 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: rand sudafricano (ZAR). PayFast liquida solo en rand, así que el carrito debe estar en ZAR. Añade la moneda en International > Localization > Currencies si tu tienda aún no la tiene. El importe mínimo del pedido es R5,00.
Cuenta de PayFast: el Merchant ID y la Merchant Key de tu cuenta de PayFast, desde Settings > Developer Settings en el panel de PayFast. Se recomienda encarecidamente una passphrase; si hay una configurada en PayFast, la misma passphrase debe introducirse en el módulo. Para las pruebas necesitas las credenciales del sandbox de PayFast.
Tienda accesible: la URL de notificación de pago debe ser accesible desde Internet, sin autenticación básica ni bloqueo del cortafuegos.
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 VibeFox PayFast Pay Gateway más tarde 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 (véase Clave de licencia).
4. Introduce el Merchant ID, la Merchant Key y la passphrase. Para las pruebas, deja Test mode activado e introduce tus credenciales del sandbox.
5. Activa Enable/Disable y haz clic en Save. Haz un pago de prueba y después desactiva Test mode para aceptar pagos reales.
Al instalarse, el módulo crea dos estados de pedido: Awaiting PayFast payment y PayFast payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences; asegúrate de que el módulo siga permitido para el rand.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa cuando las credenciales del modo actual están vacías (entonces PayFast se oculta en la finalización de compra), cuando la moneda predeterminada de la tienda no es ZAR, cuando el modo real usa el Merchant ID público de sandbox 10000100 y cuando no hay ninguna passphrase configurada. Mientras el modo de prueba está activado y el módulo habilitado, se muestra El modo de prueba está activado: los pedidos se pagan en el sandbox de PayFast y no se cobra dinero real. Si el campo Title está vacío, se rechaza con Introduce un título para el método de pago.
PayFast
Enable/Disable: Enable PayFast activa o desactiva el método de pago. Predeterminado: 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. Predeterminado: PayFast. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely by card, Instant EFT and other methods on the PayFast payment page.
Cuenta de PayFast (real)
Encuentra tu Merchant ID y tu Merchant Key en el panel de PayFast, en Settings > Developer Settings. Si configuraste una passphrase allí, introduce exactamente la misma passphrase aquí.
Merchant ID: tu Merchant ID real de PayFast.
Merchant Key: tu Merchant Key real de PayFast. Se envía a PayFast con cada formulario de pago, por eso es un campo de texto normal.
Passphrase: la passphrase de sal de PayFast, en Settings > Developer Settings. Muy recomendable: firma los pagos y las notificaciones.
Sandbox (modo de prueba)
En modo de prueba los pagos van al sandbox de PayFast y no se cobra dinero real. Las credenciales del sandbox se muestran después de iniciar sesión en el sandbox de PayFast (el comerciante de prueba público es 10000100 / 46f0cd694581a).
Test mode: Use the PayFast sandbox and the sandbox credentials below. Mientras está activado, el cliente ve MODO DE PRUEBA: los pagos van al sandbox de PayFast, no se cobra dinero real. debajo del método de pago. Predeterminado: activado.
Sandbox Merchant ID: el Merchant ID de tu cuenta de sandbox.
Sandbox Merchant Key: la Merchant Key de tu cuenta de sandbox.
Sandbox Passphrase: solo si hay una passphrase configurada en tu cuenta de sandbox.
Las passphrases guardadas 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 cambiarla.
Clear saved passphrases: marca Passphrase o Sandbox Passphrase y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Notificaciones de pago (ITN)
Notification URL: PayFast confirma cada pago con una notificación de servidor a servidor a la URL que se muestra aquí. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_payfast_pay/itn, posiblemente con el código de idioma del idioma predeterminado. La dirección se envía con cada pago, así que no hay que configurar nada en PayFast, pero debe ser accesible desde Internet. Los pedidos se crean solo con estas notificaciones verificadas; el cliente que vuelve a la tienda no crea ni paga un pedido.
Source check: acepta las notificaciones en modo real solo desde los servidores de PayFast. Las direcciones proceden de los registros DNS de PayFast (en caché durante 6 horas) y de los rangos de direcciones documentados por PayFast. Desactívala solo si tu tienda está detrás de un proxy o de una CDN que oculta la dirección del visitante. La firma y la confirmación del servidor siempre se comprueban. Las notificaciones de sandbox no se comprueban por dirección. Predeterminado: activado.
Avanzado
Debug log: registra los pasos del pago en logs/payfast_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, incluso con el interruptor desactivado. No se escriben passphrases ni datos de clientes. Predeterminado: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Uninstall: Delete the gateway settings when the module is uninstalled (ajustes, direcciones de PayFast en caché y registro). Los registros de pagos de PayFast, los pedidos y los estados de pedido siempre se conservan. Predeterminado: desactivado.
Finalización de compra
En el paso de pago el cliente elige el método de pago (por defecto PayFast) y confirma. Una página con Gracias por tu pedido. Te estamos redirigiendo a PayFast para completar el pago. envía automáticamente el formulario de pago firmado a PayFast. Si el navegador no continúa por sí solo, el cliente hace clic en Pay with PayFast; Cancel vuelve a la finalización de compra. El formulario lleva el total del carrito en ZAR, Cart # con el número de carrito, el nombre y el e-mail del cliente, la referencia del pago (número de carrito e intento) y un token aleatorio del intento. En este punto todavía no existe ningún pedido. Cada nuevo intento recibe una referencia y un token nuevos.
En la página de PayFast, el cliente paga con tarjeta, Instant EFT u otro método de tu cuenta de PayFast. PayFast envía después la notificación de pago (ITN) a tu tienda. El pedido solo se marca como pagado cuando PayFast lo confirma con una notificación que supera todas las comprobaciones:
Las notificaciones de un mismo carrito se procesan de una en una. Si se está procesando otra notificación del mismo carrito, PayFast recibe una respuesta de error y vuelve a enviar la notificación. La URL de notificación funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda.
Cuando el cliente vuelve y el pedido existe, se muestra la página estándar de confirmación del pedido. Si PayFast informó de que el pago está pendiente, muestra PayFast está confirmando tu pago. Recibirás un e-mail en cuanto se confirme; no es necesario volver a pagar. Si el pedido está en espera, muestra Tu pago está en revisión. Te contactaremos si se necesita algo más. Si un pago pendiente falló después, muestra Tu pago de PayFast no se completó. Ponte en contacto con nosotros sobre este pedido. Si la notificación todavía no ha llegado, aparece una página Payment confirmation que indica que PayFast está confirmando el pago y que el pedido se creará en cuanto PayFast lo confirme, con los botones Check again y Back to checkout.
Si el cliente cancela en la página de PayFast, vuelve a la finalización de compra con El pago de PayFast se ha cancelado. Puedes intentarlo de nuevo o elegir otro método de pago. Si PayFast informó de que el pago falló, el mensaje es El pago no se ha completado. Puedes intentarlo de nuevo o elegir otro método de pago. El carrito se conserva y puede pagarse de nuevo.
El método de pago se oculta cuando faltan las credenciales del modo actual, cuando la moneda del carrito no es ZAR o no está permitida para el módulo, o cuando el total es inferior a R5,00. Si el cliente llega igualmente al pago, aparece un mensaje breve que lo explica, por ejemplo PayFast acepta pagos a partir de R5,00. Elige otro método de pago.
El módulo acepta solo pagos únicos en ZAR. No tiene reembolsos desde la página del pedido, ni suscripciones, ni tarjetas guardadas (tokenizadas) ni pagos divididos.
Pedidos
Estados del pedido
No order yet: el cliente fue enviado a PayFast y la notificación de pago todavía no ha llegado, o PayFast informó de que el pago falló. Solo existe el carrito.
Payment accepted: PayFast confirmó el pago. El pago se registra con el ID de pago de PayFast como ID de transacción, y una nota muestra el ID de pago. Un pago en sandbox recibe la nota de que no se ha cobrado dinero real.
Awaiting PayFast payment: PayFast informó de que el pago está pendiente. El pedido pasa a Payment accepted cuando PayFast lo completa.
Payment error: un pago pendiente falló. Si PayFast lo completa más tarde, el pedido pasa a Payment accepted.
PayFast payment on hold: el importe pagado es distinto del total del carrito, o el carrito no está en ZAR; llegó un pago para un pedido que había sido cancelado o cuyo método de pago ya no es PayFast; o llegó un pago de sandbox mientras la pasarela está en modo real. El importe que recibió PayFast se registra en el pedido (no en el caso de un pago de sandbox), y la nota lo explica. Revisa el pedido y tu panel de PayFast, y después pon el pedido en Payment accepted o cancélalo y reembolsa el pago en PayFast.
Una notificación repetida del mismo pago no cambia nada. Las notificaciones tardías de fallo o pendiente nunca cambian un pedido pagado. Si llega otro pago completado para un pedido que ya está pagado, una nota te pide reembolsar el duplicado en PayFast. Un pago para un pedido reembolsado solo añade una nota.
Bloque de pago de PayFast
La página del pedido muestra un bloque PayFast payment con la referencia del pago (m_payment_id), el ID de pago de PayFast, el entorno (live o sandbox), el estado, los importes bruto, comisión y neto en ZAR, y las notas del módulo. En un pedido en espera muestra un recordatorio para revisar el pago.
Reembolsos
Los reembolsos desde la página del pedido no están disponibles. Reembolsa el pago en tu panel de PayFast y después actualiza el pedido en PrestaShop manualmente.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PayFast Pay Gateway es el primer bloque de Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure, 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 eliminar la clave de esta tienda. Debajo están la línea Product: presta-payment-payfast y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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 el servidor de licencias no está accesible, 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 plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, PayFast 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 se siguen confirmando.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren 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 a la 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
PayFast no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el Merchant ID y la Merchant Key del modo actual estén rellenados, que el carrito esté en ZAR y que el total del pedido sea de al menos R5,00. La página de ajustes muestra una advertencia cuando falta algo. En Payment > Preferences comprueba que el módulo esté permitido para el rand, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: PayFast no pudo entregar la notificación de pago, o fue rechazada. Consulta el campo Log en la página del módulo; los errores y las notificaciones rechazadas siempre se registran, y Debug log añade cada paso. Motivos habituales: la tienda no es accesible desde Internet (autenticación básica, cortafuegos), una passphrase distinta en PayFast y en el módulo o, en modo real detrás de un proxy o de una CDN, la comprobación de origen. En ese caso desactiva Source check.
La notificación responde Invalid signature: la passphrase del módulo no es la configurada en PayFast para el modo en que se hizo el pago.
La notificación responde Invalid source: la notificación no procede de una dirección de PayFast, o un proxy o una CDN oculta la dirección real. Desactiva Source check si tu tienda está detrás de un proxy o de una CDN.
La notificación responde Merchant mismatch o Order mismatch: el pago se hizo a otra cuenta de PayFast o no pertenece a este intento de pago. No se cambia nada.
La notificación responde Order not found: la referencia del pago no es conocida por esta tienda. No se cambia nada.
La notificación responde Confirmation unavailable, Busy o Temporary error: no se pudo contactar con PayFast para la confirmación del servidor, otra notificación del mismo carrito se estaba procesando en ese mismo momento, o el pedido no se pudo crear (por ejemplo, porque el módulo está desactivado). PayFast reintenta la notificación. El registro muestra el motivo.
La notificación responde Not configured: faltan las credenciales del modo en que se inició el pago. Vuelve a introducirlas, por ejemplo las credenciales del sandbox para un pago de prueba.
El cliente ve el mensaje PayFast solo acepta pagos en rand sudafricano (ZAR): el carrito está en otra moneda. Deja que el cliente pague en rand o que elija otro método de pago.
El pedido está en PayFast payment on hold: lee las notas del bloque PayFast payment (véase Estados del pedido) y tu panel de PayFast, y después acepta el pedido o reembolsa el pago.
Un pago de sandbox no pagó el pedido: la pasarela está en modo real. Los pagos de sandbox nunca pagan un pedido en modo real; una nota en el pedido lo indica.
Para desarrolladores: el hook actionPayfastPPaymentData puede cambiar los campos del formulario de pago antes de que se firmen. Las credenciales del comerciante, las URL, la referencia del pago, el importe y el token no pueden modificarse con él.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PayFast Pay Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete the gateway settings when the module is uninstalled está activado, se eliminan los ajustes de la pasarela, las direcciones de PayFast en caché y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos de PayFast, los pedidos y los estados de pedido Awaiting PayFast payment y PayFast payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
PayFast es una marca comercial de su respectivo titular. Este módulo no está afiliado a PayFast ni cuenta con su respaldo.