VibeFox Moyasar for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo. Con una versión anterior de WooCommerce, el plugin muestra un aviso y no se carga.
PHP: 8.0 o posterior.
Moneda: la moneda de la tienda o del pedido debe ser SAR, AED, USD, EUR, KWD, BHD u OMR. Para cualquier otra moneda, el método de pago se oculta en la finalización de compra.
Cuenta de Moyasar: necesitas las claves API secretas de tu cuenta de Moyasar (de prueba y de producción). Solo se usan las claves secretas. La clave publicable no es necesaria, porque el pago se realiza en la página de Moyasar. Se recomienda un webhook en Moyasar Dashboard (consulta Configuración).
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un único dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_moyasar_payment_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Moyasar > Manage, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Pega tus claves secretas de Moyasar y guarda. Configura el webhook en Moyasar Dashboard con la URL y el secreto compartido que se muestran en los ajustes (consulta Configuración).
6. Activa Enable/Disable. Haz un pedido de prueba en modo de prueba y, después, desmarca Test mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Moyasar. El título de la página muestra un distintivo TEST MODE o LIVE. Encima de los campos, la página te avisa cuando el modo actual no tiene clave secreta (en ese caso, el método de pago se oculta en la finalización de compra) o cuando la moneda de la tienda no es compatible, y muestra Test mode is active: payments are simulated, no money is charged. mientras el modo de prueba está activado. En la lista de métodos de pago, Moyasar aparece como pendiente de configuración hasta que el modo actual tenga una clave secreta. Al guardar, el plugin rechaza una clave publicable, una clave del otro modo o una clave con espacios, conserva el valor anterior y muestra el motivo. También te avisa cuando la pasarela está activada pero la clave secreta del modo actual está vacía.
General
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. Por defecto: Pay with Moyasar.
Description: el texto que aparece 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.).
API keys
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, y el modo de producción solo la clave de producción.
Test mode: Enable 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_.
Notificaciones de pago (webhook)
El webhook es recomendable, no obligatorio. Los pedidos también se confirman cuando el cliente vuelve a la tienda y mediante la notificación de factura que Moyasar envía automáticamente a tu tienda cuando la factura se paga. El webhook cubre a los clientes que cierran el navegador antes de volver e informa de los reembolsos hechos en Moyasar Dashboard. En Moyasar Dashboard > Settings > Webhooks, añade un webhook con la URL y el secreto compartido de esta sección, con método HTTP POST.
Webhook URL: se muestra de solo lectura con un botón Copy. Tiene este aspecto: https://your-site/wp-json/moyasar_p/v1/webhook. Método HTTP: POST.
Webhook shared secret: introduce el mismo valor que Shared secret del webhook en Moyasar. Déjalo vacío y guarda para generar un secreto aleatorio; luego haz clic en Show y cópialo en Moyasar. Los webhooks sin el secreto compartido correcto se rechazan.
Selecciona estos eventos para el webhook:
No se da por válida directamente ninguna notificación ni webhook: en cada caso, el plugin lee la factura desde la API de Moyasar con la clave secreta del modo del pedido y comprueba que se creó para este pedido. Los pagos de otras integraciones de la misma cuenta de Moyasar se ignoran.
Pedidos
Status after payment: el estado del pedido tras un pago confirmado. El estado se establece de inmediato, sin un segundo cambio de estado.
Avanzado
Debug log: Log API calls and notifications escribe los detalles en WooCommerce > Status > Logs, origen wcp_moyasar_payment_gateway. Los errores siempre se registran. Las claves API, los datos de tarjeta y los datos de los clientes nunca se registran. Por defecto: desactivado.
Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Los datos de pago guardados en los pedidos (ID de factura y de pago de Moyasar) se conservan, para que los reembolsos sigan siendo trazables. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Pay with Moyasar) y realiza el pedido. El plugin crea una factura de Moyasar por el total del pedido en la moneda del pedido 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, por ejemplo mada, Visa, Mastercard, Apple Pay o STC Pay. La factura muestra Order, el número de pedido y el nombre de tu sitio.
El pedido se marca como pagado solo cuando Moyasar lo confirma: el plugin lee la factura desde la API de Moyasar y comprueba que está pagada, que pertenece a este pedido y que tiene el importe y la moneda exactos del pedido. Tras pagar, el cliente vuelve a la página de pedido recibido de tu tienda. Si el cliente regresa sin pagar (por ejemplo, con el botón atrás de la página de pago), vuelve a la finalización de compra o a la página Pay for order 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.
Un cliente puede volver a pagar un pedido no pagado. Si la página de pago abierta del pedido todavía tiene el mismo importe y la misma moneda, se reutiliza. Si cambió el total del pedido, la página de pago anterior se cancela y se crea una nueva, de modo que la anterior ya no se puede pagar. Si la factura anterior ya está pagada, el pedido se confirma en lugar de crear un nuevo pago.
Si Moyasar no puede iniciar el pago, el cliente ve 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 método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El plugin acepta pagos únicos solo 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 WooCommerce Subscriptions, ni autorización y captura por separado.
Pedidos y reembolsos
Order statuses
Pending payment: la factura se creó y el cliente todavía no ha pagado. La nota del pedido muestra el ID de la factura, el importe y el modo.
Processing, Completed or On hold: el pago se confirmó. El estado sigue a Status after payment. La nota del pedido muestra cómo se confirmó el pago (webhook, notificación de factura, vuelta del cliente o finalización de compra), el ID de la factura, el ID del pago y el método de pago. El ID de transacción es el ID de pago de Moyasar.
On hold after payment: Moyasar informó de un importe o una moneda distintos al total del pedido (el pedido no se marca como pagado), o la factura se pagó después de cancelar el pedido. La nota del pedido lo explica. Revisa el pago en Moyasar Dashboard y completa el pedido o reembolsa el pago.
On hold before payment: Moyasar retiene el pago para su revisión. El pedido se actualiza cuando Moyasar decida.
Failed: la última factura de un pedido no pagado falló, expiró o se canceló. El cliente puede intentar pagar de nuevo.
Cancelled: el cliente, tú o el tiempo de espera de retención de stock de WooCommerce cancelaron el pedido. La factura abierta de Moyasar del pedido también se cancela, de modo que ya no se puede pagar.
Un pedido pagado, cancelado o reembolsado nunca cambia por eventos posteriores. Si se paga una segunda factura de un pedido que ya está pagado (por ejemplo, desde dos pestañas del navegador), el pedido no vuelve a cambiar. Una nota te pide que reembolses el duplicado en Moyasar Dashboard.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Pay with Moyasar (el botón usa el título del método de pago). Se admiten reembolsos totales y parciales de pedidos con un pago de Moyasar. 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); en otro caso, es un reembolso. El reembolso usa la clave secreta del modo en el que se hizo el pago (prueba o producción), así que esa clave debe estar configurada. Antes de reembolsar, el plugin comprueba el pago en Moyasar: su moneda, su estado y el importe que todavía se puede reembolsar. Si Moyasar no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso o una anulación correctos se añaden a las notas del pedido.
Los reembolsos y anulaciones hechos en Moyasar Dashboard llegan mediante el webhook. Si Moyasar muestra más importe reembolsado que WooCommerce, se añade una nota al pedido. No se registran automáticamente como reembolsos de WooCommerce. Si es necesario, crea un reembolso manual en WooCommerce sin usar Refund via Pay with Moyasar.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Moyasar. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un único dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Moyasar 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. Los gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
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 tiene una clave secreta (Test secret key en modo de prueba, Live secret key en modo de producción) y que la moneda de la tienda o del pedido es SAR, AED, USD, EUR, KWD, BHD u OMR. La página de ajustes muestra un aviso cuando falta la clave o la moneda no es compatible.
El pago se realizó, pero el pedido sigue en Pending payment: 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 a Webhook shared secret. El pedido también se confirma cuando el cliente vuelve a la tienda y cuando intenta pagar de nuevo el mismo pedido.
El webhook responde Unauthorized: el secreto compartido en Moyasar es distinto de Webhook shared secret. Haz clic en Show, copia el valor y pégalo en el webhook de Moyasar.
El webhook responde Webhook secret not configured: los ajustes aún no se han guardado con un secreto compartido. Guarda los ajustes para generar uno y cópialo en Moyasar.
El webhook responde Key not configured: el pedido se pagó 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, o otra solicitud estaba actualizando el pedido en ese mismo momento. Moyasar vuelve a intentar el webhook.
Error al guardar sobre la clave: se pegó una clave publicable (pk_...) o una clave del otro modo. 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 realizar el pedido: activa Debug log y revisa WooCommerce > Status > Logs, origen wcp_moyasar_payment_gateway. This payment method is temporarily unavailable. Please choose another payment method or contact us. suele significar 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 pedido ya tiene una factura pagada que necesita tu revisión.
El pedido está en On hold after payment: lee la nota del pedido. El importe o la moneda pagados eran distintos a los del pedido, o el pago llegó después de cancelarlo. Completa el pedido o reembolsa el pago.
El reembolso falla: 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 todavía se puede reembolsar en Moyasar, parte del pago ya se reembolsó, por ejemplo en Moyasar Dashboard. Si Moyasar no confirmó el importe reembolsado, revisa el pago en Moyasar Dashboard antes de volver a intentarlo.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros solo se eliminan si Clean uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Moyasar es una marca comercial de su respectivo titular. Este plugin no está afiliado a Moyasar ni cuenta con su respaldo.