VibeFox Moyasar 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: la moneda del carrito debe ser SAR, AED, USD, EUR, KWD, BHD u OMR. Para cualquier otra moneda, el método de pago no aparece en la finalización de compra.

Cuenta de Moyasar: necesitas las claves API secretas de tu cuenta de Moyasar (prueba y producción). Solo se usan las claves secretas. La clave publicable no hace falta, porque el pago se realiza en la página de Moyasar. Se recomienda un webhook en Moyasar Dashboard (ver Configuración).

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

1. En el panel de administración 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 Moyasar Payment 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. Pega tus claves secretas de Moyasar y haz clic en Save. Configura el webhook en Moyasar Dashboard (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Haz un pedido de prueba en modo de prueba y después desactiva Test mode.

Al instalarse, el módulo crea dos estados de pedido: Awaiting Moyasar payment y Moyasar 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.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Moyasar Payment 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 el modo actual no tiene clave secreta (entonces el método de pago se oculta en la finalización de compra), cuando no hay un secreto compartido del webhook guardado (entonces el webhook rechaza todas las llamadas) o cuando la moneda predeterminada de la tienda no es compatible. Mientras el módulo esté activado en modo de prueba, muestra Test mode is active: payments are simulated, no money is charged. Al guardar, el módulo rechaza una clave publicable, una clave del otro modo o una clave con espacios, mantiene el valor anterior y muestra el motivo.

Moyasar

Enable/Disable: Enable Moyasar 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 que se guarda en el pedido. Por defecto: Pay with Moyasar. Obligatorio.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. En modo de prueba, la finalización de compra añade (Test mode: no real payment is made.)

Claves API

Copia las claves secretas desde Moyasar Dashboard > Settings > API Keys. Las claves de prueba y de producción son distintas. El modo de prueba usa solo la clave de prueba; el modo de producción, solo la clave de producción.

Test mode: usa la clave secreta de prueba: los pagos se simulan y no se cobra dinero. Por defecto: activado. Desactívalo para aceptar pagos reales con la clave secreta de producción.

Test secret key: la clave secreta del modo de prueba. Empieza por sk_test_.

Live secret key: la clave secreta del modo de producción. Empieza por sk_live_.

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.

Notificaciones de pago (webhook)

El webhook se recomienda, pero no es obligatorio. Los pedidos también se confirman cuando el cliente vuelve a la tienda y mediante la notificación de la factura que Moyasar envía automáticamente a tu tienda cuando se paga la factura. El webhook cubre a los clientes que cierran el navegador antes de volver y registra los reembolsos hechos en Moyasar Dashboard. Añádelo en Moyasar Dashboard > Settings > Webhooks.

Webhook URL: se muestra en modo de solo lectura con un botón Copy. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_moyasar_payment_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como aparece en los ajustes. Método HTTP: POST.

Webhook shared secret: introduce el mismo valor que Shared secret del webhook en Moyasar. Si no hay nada guardado, Save genera un secreto aleatorio; Generate a new secret sustituye el guardado. Un secreto generado se muestra una sola vez encima de los ajustes tras guardar y nunca más, así que cópialo en Moyasar de inmediato. Los webhooks sin el secreto compartido correcto se rechazan.

Selecciona estos eventos para el webhook (también aparecen en esta sección):

Ningún dato de un webhook o notificación se acepta directamente: en cada caso, el módulo lee la factura desde la API de Moyasar con la clave secreta del modo en que se creó la factura y comprueba que se creó para este carrito. Los pagos de otras integraciones de la misma cuenta de Moyasar se ignoran. Un solo secreto compartido sirve para ambos modos.

Pedidos

Status after payment: el estado del pedido que se asigna tras un pago confirmado. El pedido se crea directamente con este estado.

Avanzado

Clear saved secrets: marca Test secret key, Live secret key o Webhook shared secret y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

Debug log: registra las llamadas a la API y las notificaciones en logs/moyasar_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. Las claves API, los datos de tarjeta y los datos de los clientes nunca se registran. Por defecto: desactivado.

Log: muestra el tamaño actual y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Clean uninstall: si está activado, al desinstalar el módulo se borran los ajustes del módulo y el registro. Los datos de pago guardados con los pedidos (los ID de factura y de pago de Moyasar) se conservan, para que los reembolsos sigan siendo trazables. Por defecto: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto Pay with Moyasar) y confirma. El módulo crea una factura de Moyasar por el total del carrito en la moneda del carrito y envía al cliente a su página de pago. Allí el cliente paga con cualquier método activo en tu cuenta de Moyasar. La factura muestra Order #, el número del carrito y el nombre de tu tienda. En este punto todavía no existe ningún pedido.

El pedido se marca como pagado solo cuando Moyasar lo confirma: el módulo lee la factura desde la API de Moyasar y comprueba que está pagada, que pertenece a este carrito y que tiene exactamente el importe y la moneda del carrito. Entonces se crea el pedido y el cliente ve la página estándar de confirmación con Your payment with Moyasar has been received. Si Moyasar retiene el pago para revisión, la página muestra Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. Si el pedido queda retenido para tu revisión, la página indica que el pago se recibió y que el pedido se está revisando. Si un pago en revisión falla después, o si el pedido impagado se cancela, la página muestra Your Moyasar payment was not completed. Please contact us about this order.

Si el cliente vuelve sin pagar (por ejemplo, con el botón atrás de la página de pago), regresa a la finalización de compra con uno de estos mensajes: The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method. o, cuando el pago todavía no se puede comprobar, We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again. El carrito se conserva.

El cliente puede volver a intentarlo. Si la página de pago abierta del carrito todavía tiene el mismo importe y la misma moneda, se reutiliza. Si el total del carrito cambió, la página de pago anterior se cancela en Moyasar y se crea una nueva, de modo que la anterior ya no se puede pagar. Si resulta que la factura anterior ya estaba pagada, se crea el pedido en lugar de un nuevo pago.

Si Moyasar no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo The Moyasar payment service is not responding. Please try again in a few minutes., y puede elegir otro método de pago. Los detalles se escriben en el registro.

El webhook y la notificación de la factura funcionan mientras la tienda está en modo de mantenimiento y no los bloquea la restricción de países de tu tienda.

El módulo solo acepta pagos únicos en la página de Moyasar. No tiene formulario de tarjeta en tu propia finalización de compra, ni tarjetas guardadas ni tokenización, ni suscripciones, ni autorización y captura por separado.

Pedidos y reembolsos

Estados del pedido

Todavía no hay pedido: el cliente fue enviado a Moyasar y no ha pagado, o Moyasar aún no ha confirmado el pago. Solo existe el carrito.

Payment accepted, Delivered o Moyasar payment on hold: el pago fue confirmado. El estado sigue a Status after payment. El pago se registra con el ID de pago de Moyasar como ID de transacción, y una nota indica cómo se confirmó el pago (webhook, notificación de la factura, vuelta del cliente o finalización de compra), el ID de la factura, el ID del pago y el método de pago.

Awaiting Moyasar payment: Moyasar retiene el pago para revisión. El pedido pasa al estado de pagado cuando Moyasar confirma el pago.

Error de pago: el pago en revisión falló.

Moyasar payment on hold after payment: Moyasar informó de un importe o una moneda distintos del total del carrito (por ejemplo, el carrito se modificó en otra pestaña después de iniciar el pago), o la factura se pagó después de que cancelaras el pedido. El pedido no se marca como pagado, pero el importe realmente recibido se registra cuando está en la moneda del pedido. La nota lo explica. Comprueba el pago en Moyasar Dashboard y completa el pedido o reembolsa el pago.

Refunded: el pago fue reembolsado por completo a través del módulo.

Un pedido pagado nunca vuelve a cambiar por eventos posteriores. Si también se paga una segunda factura de un carrito que ya está pagado (por ejemplo, desde dos pestañas del navegador), el pedido no cambia. Una nota te pide que reembolses el pago duplicado en Moyasar Dashboard.

Bloque de pago de Moyasar

La página del pedido muestra un bloque Moyasar payment con el ID de la factura de Moyasar, el ID del pago, el método (por ejemplo, la marca de la tarjeta y los últimos cuatro dígitos), el estado, los importes pagado y reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las Moyasar notes del pedido.

Reembolsos

En el bloque Moyasar payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Moyasar. Confirma la pregunta Refund this amount through Moyasar? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Los reembolsos se hacen por el importe y en la moneda que cobró Moyasar, así que tras una diferencia de importe puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. Un reembolso total de un pago con tarjeta realizado hace menos de 2 horas se envía como anulación (cancelación antes de la liquidación, sin comisiones); en otro caso es un reembolso. El reembolso usa la clave secreta del modo en que se realizó el pago (prueba o producción), así que esa clave debe estar configurada. El módulo comprueba primero en Moyasar la moneda, el estado y el importe reembolsable del pago. Si Moyasar no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso o una anulación correctos se añaden al historial de reembolsos y a las notas. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando Moyasar ha confirmado el pago.

El módulo no crea facturas de abono. Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de Moyasar.

Los reembolsos y las anulaciones hechos en Moyasar Dashboard llegan mediante el webhook. Si Moyasar muestra más importe reembolsado del que registró el módulo, se añade una nota al pedido. El estado del pedido y las facturas de abono no cambian automáticamente. Actualízalos manualmente si hace falta, sin usar Refund via Moyasar.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Moyasar Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox Moyasar Payment 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 está activa la licencia 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-moyasar 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 el inglés y el 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, Moyasar 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 tienes sesión iniciada 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 los reembolsos funcionan.

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 hace falta ninguna tarea cron. Al desinstalar o restablecer el módulo, siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

Moyasar no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el modo actual tenga una clave secreta (Test secret key en modo de prueba, Live secret key en modo de producción) y que la moneda del carrito sea SAR, AED, USD, EUR, KWD, BHD u OMR. La página de ajustes muestra una advertencia cuando falta la clave o la moneda de la tienda no es compatible. 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.

El pago se realizó, pero no se creó ningún pedido: las confirmaciones no llegaron a tu tienda. Configura el webhook: en Moyasar Dashboard comprueba que existe, que su URL es exactamente la Webhook URL de los ajustes, que el método es POST, que los cuatro eventos están seleccionados y que su secreto compartido es igual al guardado en Webhook shared secret. El pedido también se crea cuando el cliente vuelve a la tienda o intenta pagar de nuevo el mismo carrito.

El webhook responde Unauthorized: el secreto compartido en Moyasar es distinto del guardado. Escribe el secreto del webhook de Moyasar en Webhook shared secret y guarda, o marca Generate a new secret, guarda y pega en Moyasar el secreto que aparece.

El webhook responde Webhook secret not configured: no hay ningún secreto compartido guardado, por ejemplo después de eliminarlo con Clear saved secrets. Haz clic en Save para generar uno y cópialo en Moyasar.

El webhook responde Key not configured: la factura se creó en un modo (prueba o producción) cuya clave secreta está vacía. Introduce esa clave.

El webhook responde Verification failed o Try again later: no se pudo leer la factura desde la API de Moyasar, otra petición estaba actualizando el carrito en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Moyasar reintenta el webhook. Activa Debug log para ver el motivo.

La URL del webhook muestra Method not allowed en el navegador: es normal. La URL solo acepta peticiones POST de Moyasar.

Error al guardar sobre la clave: se pegó una clave publicable (pk_...) o una clave del otro modo, o la clave contiene espacios. Se mantuvo el valor anterior. Las claves de prueba empiezan por sk_test_, y las de producción, por sk_live_.

El cliente ve un error al elegir Moyasar: activa Debug log y mira el campo Log de la página del módulo. This payment method is temporarily unavailable. Please choose another payment method or contact us. suele indicar una clave secreta incorrecta o que falta. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. significa que el carrito ya tiene una factura pagada que no se pudo convertir en pedido; revisa el registro.

Order is Moyasar payment on hold after payment: lee las Moyasar notes del bloque Moyasar payment. El importe o la moneda pagados eran distintos del carrito, o el pago llegó después de cancelar el pedido. Completa el pedido o reembolsa el pago.

Fallo de reembolso: lee el mensaje. Si el pago se hizo en el otro modo, introduce la clave secreta de ese modo. Si el importe es mayor que el que aún se puede reembolsar en Moyasar, parte del pago ya se reembolsó, por ejemplo en Moyasar Dashboard. Si Moyasar no confirmó el importe reembolsado, comprueba el pago en Moyasar Dashboard antes de volver a intentarlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Moyasar Payment Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Clean uninstall está activado, se borran los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las facturas, pagos y reembolsos de Moyasar, y los estados de pedido Awaiting Moyasar payment y Moyasar payment on hold, se conservan siempre, de modo que los pedidos antiguos se pueden reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

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