EN
EUR
Back

VibeFox Moyasar for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. With an older WooCommerce the plugin shows a notice and does not load.

PHP: 8.0 or later.

Currency: the store or order currency must be SAR, AED, USD, EUR, KWD, BHD or OMR. For any other currency the payment method is hidden at checkout.

Moyasar account: you need the secret API keys of your Moyasar account (test and live). Only the secret keys are used. The publishable key is not needed, because the payment happens on the Moyasar page. A webhook in the Moyasar Dashboard is recommended (see Configuration).

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_moyasar_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Moyasar > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Paste your Moyasar secret keys and save. Set up the webhook in the Moyasar Dashboard with the URL and shared secret shown in the settings (see Configuration).

6. Turn on Enable/Disable. Place a test order in test mode, then untick Test mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Moyasar. The page title shows a TEST MODE or LIVE badge. Above the fields the page warns you when the current mode has no secret key (the payment method is then hidden at checkout) or the store currency is not supported, and shows Test mode is active: payments are simulated, no money is charged. while test mode is on. In the list of payment methods, Moyasar is marked as needing setup until the current mode has a secret key. When you save, the plugin refuses a publishable key, a key of the other mode or a key with spaces, keeps the previous value and shows the reason. It also warns you when the gateway is enabled but the secret key of the current mode is empty.

General

Enable/Disable: Enable Moyasar turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Pay with Moyasar.

Description: the text shown under the payment method at checkout. Default: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. In test mode the checkout adds (Test mode: no real payment is made.).

API keys

Copy the secret keys from Moyasar Dashboard > Settings > API Keys. Test and live keys are separate. Test mode uses only the test key, live mode only the live key.

Test mode: Enable test mode uses the test secret key: payments are simulated and no money is charged. Default: on. Turn it off to accept real payments with the live secret key.

Test secret key: the secret key of the test mode. It starts with sk_test_.

Live secret key: the secret key of the live mode. It starts with sk_live_.

Payment notifications (webhook)

The webhook is recommended, not required. Orders are also confirmed when the customer returns to the store and by the invoice notification that Moyasar sends to your store automatically when the invoice is paid. The webhook covers customers who close the browser before returning and tells you about refunds made in the Moyasar Dashboard. In Moyasar Dashboard > Settings > Webhooks add a webhook with the URL and shared secret from this section, HTTP method POST.

Webhook URL: shown read-only with a Copy button. It looks like https://your-site/wp-json/moyasar_p/v1/webhook. HTTP method: POST.

Webhook shared secret: enter the same value as Shared secret of the webhook in Moyasar. Leave it empty and save to generate a random secret, then click Show and copy it to Moyasar. Webhooks without the correct shared secret are rejected.

Select these events for the webhook:

payment_paid: the customer paid the invoice.
payment_failed: the payment failed.
payment_refunded: the payment was refunded, for example in the Moyasar Dashboard.
payment_voided: the payment was voided.

Nothing in a webhook or notification is trusted directly: for each one, the plugin reads the invoice from the Moyasar API with the secret key of the order's mode and checks that it was created for this order. Payments of other integrations on the same Moyasar account are ignored.

Orders

Status after payment: the order status set after a confirmed payment. The status is set at once, without a second status change.

Processing: the WooCommerce default (default). Orders with only virtual downloadable products are completed automatically.
Completed: every paid order becomes Completed.
On hold: every paid order waits for your manual review.

Advanced

Debug log: Log API calls and notifications writes details to WooCommerce > Status > Logs, source wcp_moyasar_payment_gateway. Errors are always logged. API keys, card data and customer details are never logged. Default: off.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Payment details stored on orders (Moyasar invoice and payment IDs) are kept, so refunds remain traceable. Default: off.

Checkout

The customer chooses the payment method (by default Pay with Moyasar) and places the order. The plugin creates a Moyasar invoice for the order total in the order currency and sends the customer to its payment page. There the customer pays with any method active on your Moyasar account, for example mada, Visa, Mastercard, Apple Pay or STC Pay. The invoice shows Order, the order number and your site name.

The order is marked paid only after Moyasar confirms it: the plugin reads the invoice from the Moyasar API and checks that it is paid, belongs to this order and has the exact order amount and currency. After paying, the customer returns to the order received page of your store. If the customer comes back without paying (for example with the back button of the payment page), they go back to the checkout or the Pay for order page with one of these messages: 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. or, when the payment cannot be checked yet, 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.

A customer can pay an unpaid order again. If the open payment page of the order still has the same amount and currency, it is reused. If the order total changed, the old payment page is cancelled and a new one is created, so the old one can no longer be paid. If the previous invoice is already paid, the order is confirmed instead of creating a new payment.

If Moyasar cannot start the payment, the customer sees a short message, for example The Moyasar payment service is not responding. Please try again in a few minutes., and can choose another payment method. The details are written to the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments on the Moyasar page only. It has no card form on your own checkout, no saved cards or tokenization, no WooCommerce Subscriptions and no separate authorize and capture.

Orders and refunds

Order statuses

Pending payment: the invoice was created and the customer has not paid yet. The order note shows the invoice ID, the amount and the mode.

Processing, Completed or On hold: the payment was confirmed. The status follows Status after payment. The order note shows how the payment was confirmed (webhook, invoice notification, customer return or checkout), the invoice ID, the payment ID and the payment method. The transaction ID is the Moyasar payment ID.

On hold after payment: Moyasar reported a different amount or currency than the order total (the order is not marked paid), or the invoice was paid after the order had been cancelled. The order note explains it. Check the payment in the Moyasar Dashboard and fulfil the order or refund the payment.

On hold before payment: Moyasar holds the payment for review. The order is updated when Moyasar decides.

Failed: the latest invoice of an unpaid order failed, expired or was cancelled. The customer can try to pay again.

Cancelled: the order was cancelled by the customer, by you or by the WooCommerce stock hold timeout. The open Moyasar invoice of the order is cancelled too, so it can no longer be paid.

A paid, cancelled or refunded order is never changed by later events. If a second invoice of an order that is already paid is paid (for example from two browser tabs), the order is not changed again. A note asks you to refund the duplicate payment in the Moyasar Dashboard.

Refunds

Open the order, click Refund, enter the amount and click Refund via Pay with Moyasar (the button uses the payment method title). Full and partial refunds are supported for orders with a Moyasar payment. A full refund of a card payment made less than 2 hours ago is sent as a void (cancel before settlement); otherwise it is a refund. The refund uses the secret key of the mode the payment was made in (test or live), so that mode's key must be set. Before refunding, the plugin checks the payment at Moyasar: its currency, status and the amount still refundable. If Moyasar does not accept the refund, WooCommerce shows the error and no refund is recorded. A successful refund or void is added to the order notes.

Refunds and voids made in the Moyasar Dashboard arrive by the webhook. If Moyasar shows more refunded than WooCommerce, a note is added to the order. They are not recorded as WooCommerce refunds automatically. If needed, create a manual refund in WooCommerce without Refund via Pay with Moyasar.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Moyasar. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Moyasar is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Moyasar does not appear at checkout: check that the license is active, Enable/Disable is on, the current mode has a secret key (Test secret key in test mode, Live secret key in live mode) and the store or order currency is SAR, AED, USD, EUR, KWD, BHD or OMR. The settings page shows a warning when the key is missing or the currency is not supported.

The payment went through, but the order stays Pending payment: the confirmations did not reach your store. Set up the webhook: in the Moyasar Dashboard check that it exists, that its URL is exactly the Webhook URL from the settings, the method is POST, the four events are selected and its shared secret equals Webhook shared secret. The order is also confirmed when the customer returns to the store and when the customer tries to pay the same order again.

Webhook answers Unauthorized: the shared secret in Moyasar differs from Webhook shared secret. Click Show, copy the value and paste it into the webhook in Moyasar.

Webhook answers Webhook secret not configured: the settings have not been saved with a shared secret yet. Save the settings to generate one and copy it to Moyasar.

Webhook answers Key not configured: the order was paid in a mode (test or live) whose secret key is empty. Enter that key.

Webhook answers Verification failed or Try again later: the invoice could not be read from the Moyasar API, or the order was being updated by another request at the same moment. Moyasar retries the webhook.

Error on save about the key: a publishable key (pk_...) or a key of the other mode was pasted. The previous value was kept. Test keys start with sk_test_, live keys with sk_live_.

The customer sees an error when placing the order: turn on Debug log and look at WooCommerce > Status > Logs, source wcp_moyasar_payment_gateway. This payment method is temporarily unavailable. Please choose another payment method or contact us. usually means a wrong or missing secret key. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. means the order already has a paid invoice that needs your review.

Order is On hold after payment: read the order note. The paid amount or currency differed from the order, or the payment came after the order was cancelled. Fulfil the order or refund the payment.

Refund fails: read the message. If the payment was made in the other mode, enter that mode's secret key. If the amount is larger than the amount still refundable at Moyasar, part of the payment was already refunded, for example in the Moyasar Dashboard. If Moyasar did not confirm the refunded amount, check the payment in the Moyasar Dashboard before trying again.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Clean uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Moyasar is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Moyasar.