VibeFox Ozow 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). El método de pago solo se muestra para carritos en ZAR. Ozow cobra en céntimos enteros, así que la moneda debe usar 2 decimales.

Cuenta de Ozow: una cuenta de comerciante de Ozow con el Site Code y la Private Key de tu sitio de Ozow, obtenidos en tu panel de comerciante de Ozow. La API Key es opcional, pero recomendable. Ozow usa el mismo Site Code y las mismas claves para los pagos de prueba y los reales.

Tienda accesible: tu tienda debe ser accesible desde Internet, sin protección con contraseña ni cortafuegos que bloquee a Ozow, para que lleguen las notificaciones de Ozow. La notificación se acepta incluso mientras la tienda está en modo mantenimiento.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 Ozow Pay más tarde en la lista de módulos y haz clic en Configure.

3. Pega tu clave de licencia de VibeFox en License key, dentro del bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).

4. Introduce el Site Code y la Private Key, y preferiblemente la API Key, obtenidos en tu panel de comerciante de Ozow.

5. Activa Enable/Disable y haz clic en Save. Haz un pago de prueba con Test mode activado y después desactiva el modo de prueba para aceptar pagos reales.

Al instalarse, el módulo crea dos estados de pedido: Awaiting Ozow payment y Ozow payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences; allí ZAR debe estar permitido para el módulo. Un país habilitado más tarde también debe marcarse para el módulo en ese mismo lugar.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Ozow Pay > Configure. Cada sección con un botón Save guarda la página completa. Encima de los campos, la página te avisa cuando faltan el Site Code o la Private Key (entonces Ozow queda oculto en la finalización de compra), cuando la moneda predeterminada de la tienda no es ZAR, cuando la moneda tiene más de 2 decimales (ponla en 2 en International > Localization > Currencies), y muestra Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. mientras el modo de prueba esté activado.

Ozow

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

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 guardado en el pedido. Predeterminado: Instant EFT (Ozow).

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. En modo de prueba se añade debajo la línea TEST MODE: no money will be charged. (solo si la descripción no está vacía).

Credenciales de Ozow

Copia el Site Code, la Private Key y la API Key desde tu panel de comerciante de Ozow (Merchant details / Sites). La sección enlaza con la documentación de integración de Ozow en hub.ozow.com.

Site Code: el Site Code del sitio de Ozow que recibe los pagos. Las respuestas de otro Site Code se rechazan.

Private Key: firma cada solicitud de pago y verifica cada respuesta de Ozow. Manténla en privado. Sin ella, el método de pago queda oculto y no se acepta ninguna respuesta de Ozow.

API Key (recommended): opcional. Con una API Key, cada pago correcto también se confirma con la API GetTransaction de Ozow antes de marcar el pedido como pagado. La API debe indicar que el pago está completo, para este carrito, con el mismo importe, moneda y Site Code.

Las claves guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.

Clear saved secrets: marca Private Key o API Key y guarda para eliminar una clave guardada. Un campo vacío mantiene el valor guardado.

Test mode: Ozow usa el mismo Site Code y las mismas claves para las pruebas: los pagos se crean con IsTest=true y no se mueve dinero. Los pedidos pagados en modo de prueba reciben un mensaje en el pedido; no los envíes. Desactiva el modo de prueba para aceptar pagos reales. Un pago de prueba nunca paga un pedido en modo real. Predeterminado: on.

Notificaciones de pago

Las URL de notificación, éxito, cancelación y error se envían a Ozow con cada pago, así que no hay que configurar nada en el panel de Ozow, salvo que tu sitio de Ozow tenga URL fijas. La sección muestra las cuatro URL: Notification URL, Success URL, Cancel URL y Error URL. Son enlaces de módulo de tu tienda (controladores notify y return). Si tu sitio de Ozow usa URL fijas, cópialas exactamente como las muestran los ajustes.

Avanzado

Debug log: registra las solicitudes de pago y las respuestas de Ozow en logs/ozow_p_debug.log.php, dentro de la carpeta del módulo (no legible desde la web). Los errores y las advertencias siempre se registran. Las claves, hashes, tokens y datos de clientes nunca se registran. Predeterminado: off.

Log: muestra el tamaño actual y el final del registro, con un botón Clear log.

Delete data on uninstall: elimina los ajustes y los registros de este módulo al desinstalarlo (los datos de Ozow guardados en los pedidos se conservan). Predeterminado: off.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto Instant EFT (Ozow)) y confirma el pedido. El módulo envía al cliente a la página de pago alojada de Ozow con una solicitud firmada por el total del carrito en ZAR. La referencia del extracto bancario es Cart y el número del carrito (hasta 20 letras latinas, dígitos, espacios y guiones). El nombre del cliente se pasa a Ozow. En este momento todavía no existe ningún pedido. En la página de Ozow, el cliente elige un banco sudafricano y aprueba el pago en la app de su banco.

Después, Ozow notifica a la tienda y devuelve al cliente. Ambos envían la misma respuesta firmada y se procesan del mismo modo, así que el pedido se crea aunque se pierda uno de los dos. El pedido se marca como pagado solo después de que Ozow lo confirme: el hash debe verificarse con tu Private Key, el Site Code debe ser el tuyo, la respuesta debe pertenecer a este intento de pago del carrito, y el importe y la moneda deben coincidir con el carrito. Con una API Key, el pago también se comprueba con la API GetTransaction.

Tras un pago correcto, el cliente ve la página estándar de confirmación del pedido. Si Ozow o el banco todavía están investigando el pago, la página dice We are waiting for Ozow to confirm 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á en espera, dice Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. Si un pago investigado falla más tarde o el pedido sin pagar se cancela, dice Your Ozow payment was not completed. Please contact us about this order. Si Ozow todavía no ha confirmado el pago cuando el cliente vuelve, aparece una página con el texto de espera y los botones Check again y Back to checkout.

Si el cliente cancela en la página de Ozow o el pago falla, no se crea ningún pedido. El cliente vuelve a la finalización de compra con el mismo carrito y ve The Ozow payment was cancelled. You can try again or choose another payment method. o The Ozow payment was not completed. You can try again or choose another payment method.

Si el carrito no está en ZAR, el cliente ve Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

El módulo acepta solo pagos únicos en ZAR. No admite reembolsos desde PrestaShop, ni suscripciones, ni cuentas bancarias guardadas ni tokenización, ni enlaces de pago enviados desde el back office.

Pedidos y reembolsos

Estados del pedido

Todavía sin pedido: el cliente fue enviado a Ozow y no ha pagado, ha cancelado o Ozow todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted: el pago fue confirmado. El mensaje del pedido muestra el importe, el ID de transacción de Ozow y si el pago fue confirmado por la API GetTransaction. El ID de transacción del pago del pedido es el TransactionId de Ozow. Un pago de prueba recibe el mensaje TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment: Ozow o el banco están investigando el pago. El pedido se actualiza cuando Ozow envía el estado final.

Ozow payment on hold: el mensaje del pedido indica el motivo: el importe o la moneda pagados difieren del carrito; llegó un pago para un pedido que ya había sido cancelado; o, con una API Key, la API GetTransaction todavía no ha podido confirmar el pago o lo contradice. Comprueba el pago en tu panel de Ozow y cambia el estado del pedido. Si la API no pudo responder, la siguiente notificación de Ozow completa el pedido.

Error de pago: un pago que estaba en investigación fue cancelado, abandonado o falló. Una respuesta correcta posterior de Ozow para ese pago todavía marca el pedido como pagado.

Un pedido ya pagado nunca vuelve a cambiar, y un pedido cancelado o reembolsado nunca se vuelve a abrir. Si llega un segundo pago para un pedido ya pagado, un mensaje te pide reembolsar el duplicado en tu panel de Ozow. Si un pedido está en espera por otro motivo, por ejemplo porque lo has puesto tú, un pago posterior solo añade un mensaje y tú pones el pedido en Payment accepted.

Bloque de pago de Ozow

La página del pedido muestra un bloque Ozow payment con la referencia y el intento de la transacción, el ID de transacción de Ozow, el estado, el importe solicitado, el importe indicado por Ozow, el mensaje de Ozow y una marca TEST MODE en los pagos de prueba.

Reembolsos

Los reembolsos desde PrestaShop no son compatibles. Reembolsa el pago en tu panel de comerciante de Ozow y después registra el reembolso 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 Ozow Pay es el primer bloque de Modules > Module Manager > VibeFox Ozow Pay > Configure, 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-ozow 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 de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al 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 plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Ozow no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, 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 tras introducir la clave, y después una vez por semana. No se necesita ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Ozow no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el Site Code y la Private Key están rellenados y que la moneda del carrito es ZAR. En Payment > Preferences comprueba que el módulo está permitido para ZAR, para el país del cliente y para el grupo del cliente. La página de ajustes muestra una advertencia cuando falta algo.

El pago se realizó, pero no se creó ningún pedido: la notificación de Ozow no llegó a la tienda y el cliente no volvió. Comprueba que tu tienda es accesible desde Internet (sin protección con contraseña ni cortafuegos que bloquee a Ozow). Si tu sitio de Ozow usa URL fijas, comprueba que sean exactamente las que se muestran en Payment notifications. Activa Debug log y lee el registro en la página Configure.

La notificación responde Invalid hash: la Private Key de los ajustes no pertenece al sitio de Ozow que envió la respuesta. Cópiala de nuevo desde el panel de comerciante de Ozow. No se cambia nada.

La notificación responde Unknown site: la respuesta vino de otro sitio de Ozow. Comprueba el Site Code.

La notificación responde Order mismatch o Order not found: la respuesta no pertenece a un pago iniciado en esta tienda. No se cambia nada.

La notificación responde Gateway not configured: falta el Site Code o la Private Key. Introdúcelos; Ozow puede volver a intentarlo.

La notificación responde Payment not confirmed yet: la respuesta todavía no se pudo aplicar. Con una API Key, la API GetTransaction no pudo confirmar el pago (el pedido queda en espera y la siguiente notificación lo completa; si sigue en espera, comprueba la API Key y el pago en tu panel de Ozow). Es también la respuesta cuando el regreso del cliente se estaba procesando para el mismo carrito en ese momento, o cuando no se pudo crear el pedido; consulta el registro.

Un pago de prueba no pagó el pedido: el módulo está en modo real. Los pagos de prueba nunca pagan un pedido en modo real; el mensaje del pedido o el registro lo indican.

El pedido queda en Ozow payment on hold tras el pago: lee el mensaje del pedido y comprueba el pago en tu panel de Ozow; después pon el pedido en Payment accepted o reembolsa el pago en Ozow.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Ozow Pay y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos de Ozow y los estados de pedido Awaiting Ozow payment y Ozow payment on hold siempre se conservan, de modo que las notificaciones tardías de pedidos antiguos se siguen reconociendo tras una reinstalación. Los pedidos existentes conservan sus mensajes de pago y sus ID de transacción.

Ozow es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Ozow ni respaldado por Ozow.