VibeFox PayFast for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Currency: rand sudafricano (ZAR). PayFast liquida solo en rands, así que el pedido debe estar en ZAR. Añade la moneda en System > Localisation > Currencies si tu tienda todavía no la tiene. El importe mínimo del pedido es R5.00.

PayFast account: el Merchant ID y la Merchant Key de tu cuenta de PayFast, en Settings > Developer Settings del panel de PayFast. Se recomienda encarecidamente una frase de contraseña; si has configurado una en PayFast, debes introducir exactamente la misma en la extensión. Para las pruebas necesitas las credenciales del sandbox de PayFast.

Reachable store: la URL de notificación de pago debe ser accesible desde internet, sin autenticación básica ni bloqueo por cortafuegos.

VibeFox license key: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_payfast_pay-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_payfast_pay.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_payfast_pay-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox PayFast Pay Gateway y haz clic en Install (el botón verde +).

3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (ver la sección Clave de licencia).

4. Introduce el Merchant ID, la Merchant Key y la passphrase. Para hacer 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.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_payfast_pay.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox PayFast Pay Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia y las credenciales de PayFast, y prueba el pago como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. Solo cambia la URL de notificación (ver la sección Notification URL); también se envía a PayFast con cada pago.

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, la página te avisa cuando las credenciales del modo actual están vacías (en ese caso 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 del sandbox público 10000100 y cuando no hay ninguna passphrase configurada. Mientras el modo de prueba está activado, muestra Test mode is on: orders are paid in the PayFast sandbox, no real money is charged.

Al guardar, Title no puede estar vacío (hasta 128 caracteres), Sort Order debe ser un número entero (se admiten números negativos), Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido seleccionados deben existir; de lo contrario no se guarda nada y la página indica el campo. Si activas el método de pago sin las credenciales del modo actual, los ajustes se guardan con una advertencia.

PayFast

Enable/Disable: Enable PayFast activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: PayFast. Obligatorio.

Description: el texto que el cliente ve en el paso Confirm Order, encima del botón de confirmar. Predeterminado: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

Sort Order: la posición de PayFast entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece PayFast solo a las direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones. En OpenCart 4, cuando la tienda no pide una dirección de pago, se usa la dirección de envío.

Total: el total de la finalización de compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar para que se ofrezca PayFast. Déjalo vacío para ofrecer PayFast con cualquier total. PayFast en sí siempre requiere al menos R5.00.

Cuenta de PayFast (real)

Encontrarás tu Merchant ID y tu Merchant Key en el panel de PayFast, en Settings > Developer Settings (allí están los enlaces de la sección). Si configuras una passphrase allí, introduce aquí exactamente la misma.

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 lo que es un campo de texto normal.

Passphrase: la passphrase de salt 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 público de prueba es 10000100 / 46f0cd694581a).

Test mode: Use the PayFast sandbox and the sandbox credentials below. Mientras está activado, el cliente ve TEST MODE: payments go to the PayFast sandbox, no real money is charged. en el paso Confirm Order. 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. Para eliminar una passphrase guardada, marca Clear the saved passphrase on save debajo del campo y haz clic en Save.

Notificaciones de pago (ITN)

Notification URL: PayFast confirma cada pago mediante una notificación servidor a servidor a la URL que se muestra aquí. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. 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 solo reciben su estado a partir de estas notificaciones verificadas; que el cliente vuelva a la tienda no cambia el pedido.

Source check: acepta notificaciones reales solo de los servidores de PayFast. Las direcciones proceden de los registros DNS de PayFast (en caché durante 6 horas; la caché se restablece al guardar los ajustes) y de los rangos de direcciones documentados por PayFast. Desactívalo solo si tu tienda está detrás de un proxy o 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.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido ausente). Solo recibe un estado a partir de una notificación verificada de PayFast. Un pago cancelado, fallido o abandonado deja el pedido sin estado, y el cliente puede volver a pagar. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status (paid): el estado después de que PayFast confirme el pago y el importe y la moneda coincidan. Predeterminado: En proceso.

Awaiting PayFast payment: PayFast ha registrado el pago como pendiente (por ejemplo, Instant EFT). Pasa al estado de pagado cuando PayFast lo completa. Predeterminado: Pendiente.

PayFast payment on hold: un pago que necesita tu revisión (ver la sección Estados de pedido). Ese pedido no se marca como pagado; una nota explica el motivo. Predeterminado: Pendiente, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Payment failed: un pago pendiente ha fallado. Si PayFast lo completa más tarde, el pedido cambia al estado de pagado. Predeterminado: Fallido.

Avanzado

Debug log: registra los pasos del pago en payfast_p_debug.log.php, en la carpeta de logs de OpenCart (storage/logs). El archivo no se puede abrir desde la web, y al alcanzar 5 MB se traslada a payfast_p_debug.old.log.php. Los errores y las advertencias siempre se registran, aunque el interruptor esté desactivado. No se escriben contraseñas de paso, claves 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 extension is uninstalled (ajustes, direcciones de PayFast en caché y registro). Los registros de pagos de PayFast y los pedidos siempre se conservan. Predeterminado: desactivado.

Importar / exportar

Export: Download JSON guarda los ajustes como un archivo JSON. Las passphrases no se exportan.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las passphrases guardadas se conservan.

Finalización de compra

En el paso Payment Method el cliente elige el método de pago (por defecto, PayFast). En el paso Confirm Order el cliente ve tu descripción y la nota Thank you for your order. You will be redirected to PayFast to complete the payment. OpenCart crea el pedido en este paso, todavía sin estado. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque de métodos de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra. Cuando el cliente hace clic en Confirm Order, la extensión envía a PayFast el formulario de pago firmado. El formulario incluye el total del pedido en ZAR, Order # con el número de pedido, el nombre y el correo electrónico del cliente, la referencia del pago (número de pedido e intento) y un token aleatorio del intento. 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 entonces la notificación de pago (ITN) a tu tienda. El pedido se marca como pagado solo cuando PayFast lo confirma con una notificación que supera todas las comprobaciones:

Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock. Las notificaciones de un mismo carrito se procesan de una en una; si otra notificación del mismo carrito se está procesando, PayFast recibe una respuesta de error y vuelve a enviar la notificación. La URL de notificación también funciona cuando la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las solicitudes de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio que deja pasar la notificación y el regreso del cliente desde PayFast.

Cuando el cliente vuelve y el pedido ya tiene un estado, se muestra la página de éxito del pedido de OpenCart. Si PayFast registró el pago como pendiente, también muestra PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Si el pedido está retenido, muestra Your payment is being reviewed. We will contact you if anything else is needed. Si un pago pendiente falló después, muestra Your PayFast payment was not completed. Please contact us about this order. (en OpenCart 4, el cliente vuelve en su lugar a la finalización de compra, ver más abajo). Si la notificación todavía no ha llegado, aparece una página Payment confirmation que indica que PayFast está confirmando el pago, 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 mensaje The PayFast payment was cancelled. You can try again or choose another payment method. Si PayFast registró el pago como fallido, el mensaje es The payment was not completed. You can try again or choose another payment method. El carrito se conserva y puede pagarse de nuevo. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 mantiene un solo pedido para la finalización de compra y lo actualiza, así que, tras un pago cancelado o fallido, el cliente paga el mismo pedido con un intento nuevo. Si otro pedido del mismo carrito ya lo ha gestionado PayFast (por ejemplo, en una segunda pestaña del navegador), el cliente pasa a la página de éxito en lugar de volver a pagar.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago mientras tanto (por ejemplo, porque su pago pendiente falló o lo cancelaste), el cliente vuelve a la finalización de compra con Your previous order was cancelled or its payment failed. Please confirm the order again., y el siguiente Confirm Order paga un pedido nuevo. Si ese pedido ya tiene un estado y el carrito contiene ahora otros productos o cantidades, el mensaje es Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again.

El método de pago se oculta cuando faltan las credenciales del modo actual, cuando la moneda de la finalización de compra no es ZAR o cuando el total es inferior a R5.00. Si el cliente llega al pago de todos modos, un mensaje breve encima del botón lo explica, por ejemplo: PayFast accepts payments from R5.00. Please choose another payment method.

La extensión solo acepta pagos únicos en ZAR. No tiene reembolsos desde la página del pedido, ni suscripciones, ni tarjetas guardadas (tokenizadas), ni pagos divididos.

Pedidos

Estados de pedido

No status (missing order): el cliente fue enviado a PayFast y la notificación de pago todavía no ha llegado, o PayFast registró el pago como fallido. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

En OpenCart 4, un pedido sin pagar de la finalización de compra puede recibir el estado Voided, que OpenCart 4 asigna cuando el cliente vuelve al paso Confirm Order. La extensión trata ese pedido como un pedido sin estado, y un pago posterior sigue confirmándolo.

Order Status (paid) (default Processing): PayFast confirmó el pago. Una nota muestra el ID de pago de PayFast. Un pago de sandbox recibe la nota de que no se cobró dinero real.

Awaiting PayFast payment (default Pending): PayFast registró el pago como pendiente. El pedido pasa al estado de pagado cuando PayFast lo completa, o a Payment failed cuando el pago falla; el cliente recibe por correo electrónico la notificación de estos cambios.

Payment failed (default Failed): un pago pendiente ha fallado. Si PayFast lo completa más tarde, el pedido cambia al estado de pagado.

PayFast payment on hold (default Pending): el importe pagado no coincide con el total del pedido, o el pedido no está en ZAR; llegó un pago para un pedido cuyo estado habías cambiado mientras tanto (por ejemplo, cancelado) o cuyo método de pago ya no es PayFast; o llegó un pago de sandbox mientras la pasarela estaba en modo real. La nota lo explica. Revisa el pedido y tu panel de PayFast, y después pon el pedido en estado de pagado o cancélalo y reembolsa el pago en PayFast.

Una notificación repetida del mismo pago no cambia nada. Las notificaciones tardías de pagos fallidos o pendientes nunca modifican un pedido pagado. Si llega otro pago completado para un pedido que ya está pagado, o para un segundo pedido de un carrito ya pagado, una nota en el pedido pagado te pide reembolsar el duplicado en PayFast.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox PayFast Pay Gateway

En Sales > Orders abre un pedido pagado con PayFast. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox PayFast Pay Gateway muestra Payment reference (m_payment_id), el PayFast payment ID, el Environment (real o sandbox), el importe solicitado, el estado, los importes bruto, comisión y neto en ZAR y las PayFast notes. En un pedido retenido muestra un recordatorio para revisar el pago. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos desde la página del pedido no se admiten. Reembolsa el pago en tu panel de PayFast y después actualiza el pedido manualmente en OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox PayFast Pay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit, 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 eliminarla de esta tienda. Debajo aparecen la línea Product: opencart-payment-payfast y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify de la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen inglés y ruso).

Si la clave no es aceptada, 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 no se puede acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar 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. Un usuario administrador que haya iniciado sesión en el panel en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no detecta el inicio de sesión del panel, así que sin una clave activa el método de pago queda oculto para todos los usuarios. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del panel: 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 hace falta ninguna tarea cron. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

PayFast does not appear at checkout: 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 la moneda de la finalización de compra es ZAR y que el total del pedido es de al menos R5.00. La página de ajustes muestra una advertencia cuando falta algo. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total definido en los ajustes.

The payment went through, but the order stays without a status: PayFast no pudo entregar la notificación de pago, o la notificación fue rechazada. Revisa el campo Log de la página de la extensión; 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 la extensión, o, en modo real detrás de un proxy o CDN, la comprobación del origen. En ese caso, desactiva Source check.

The notification answers Invalid signature: la passphrase de la extensión no es la configurada en PayFast para el modo en el que se realizó el pago.

The notification answers Invalid source: la notificación no procede de una dirección de PayFast, o un proxy o CDN oculta la dirección real. Desactiva Source check si tu tienda está detrás de un proxy o CDN.

The notification answers Merchant mismatch or Order mismatch: el pago se hizo a otra cuenta de PayFast o no pertenece a este intento de pago. No se cambia nada.

The notification answers Order not found: la referencia del pago no es conocida por esta tienda. No se cambia nada.

The notification answers Confirmation unavailable, Busy or 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 momento, o no se pudo establecer el estado del pedido. PayFast reintenta la notificación. El registro muestra el motivo.

The notification answers Not configured: faltan las credenciales del modo en el que se inició el pago. Vuelve a introducirlas, por ejemplo las credenciales del sandbox para un pago de prueba.

The customer sees PayFast accepts payments in South African rand (ZAR) only: el pedido está en otra moneda. Haz que el cliente pague en rands o que elija otro método de pago.

The customer sees This payment method is not available. Please reload the checkout page. La sesión de la finalización de compra ya no coincide con el pedido, o el método de pago se desactivó entretanto. El cliente debe recargar la finalización de compra.

Order is in the on-hold status: lee las notas de la pestaña VibeFox PayFast Pay Gateway (ver la sección Estados de pedido) y tu panel de PayFast, y después pon el estado de pagado o reembolsa el pago.

A sandbox payment did not pay the order: 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: antes de firmar el formulario de pago, la extensión dispara el evento de OpenCart payfast_p_payment_data con los campos del formulario y el pedido. Las credenciales del comerciante, las URL, la referencia del pago, el importe y el token no pueden modificarse a través de él.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox PayFast Pay Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina los ajustes propios de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, sus eventos y su acción de inicio, que deja pasar la notificación y el regreso del cliente en modo de mantenimiento). Si Delete the gateway settings when the extension is uninstalled está activado, se eliminan los demás ajustes de la pasarela (título, descripción, credenciales, passphrases, modo de prueba, comprobación del origen y registro), las direcciones de PayFast en caché y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pagos de PayFast y los pedidos siempre se conservan. Los pedidos existentes mantienen sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalarla y haz clic en Uninstall (el botón naranja −) junto a VibeFox PayFast Pay Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

PayFast es una marca comercial de su respectivo titular. Esta extensión no está afiliada a PayFast ni respaldada por PayFast.