VibeFox Moyasar for Adobe Commerce — Yardım

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Currency: the 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-moyasar-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/MoyasarPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_MoyasarPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Moyasar Payment Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Paste your Moyasar secret keys and set up the webhook in the Moyasar Dashboard (see Configuration). Set Enable to Yes and click Save Config. Place a test order in test mode, then set Test mode to No.

The module adds the Pay with Moyasar payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Moyasar invoices and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Moyasar Payment Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; there are no settings per store view. Remove settings and log on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a payment title of up to 128 characters.); a Sort order that is not a whole number; a Minimum order total or Maximum order total that is not a number of 0 or greater (Enter a non-negative order total.).

When a secret key is refused, only that key keeps its previous value; the other settings are saved, and Magento shows a warning such as Moyasar: A publishable key (pk_) cannot be used. Enter the secret key (sk_). The previous secret was kept; other valid settings were saved. The reasons are a publishable key, a live key in the test field, a test key in the live field, or a key with spaces.

After Save Config, while Enable is Yes, the page warns you: Moyasar: enter the secret key of the selected mode. (Moyasar is then hidden at checkout), Moyasar: no webhook shared secret is saved; webhook calls are rejected., Moyasar: the store currency is unsupported. and, in test mode, Moyasar test mode is active; no real money is charged.

General

Enable: shows or hides Moyasar at checkout. It is shown only when the secret key of the current mode is set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Pay with Moyasar. Required, at most 128 characters.

Description: shown in the payment method list at checkout, when the customer selects Moyasar. Default: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay.

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: uses the test secret key: payments are simulated and no money is charged. Default: Yes. Set it to No to accept real payments with the live secret key. While it is on, customers see Test mode: no real payment is made. under the payment method.

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

Clear saved test secret key: set it to Yes and click Save Config to delete the saved test key. The field goes back to No after saving.

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

Clear saved live secret key: the same for the live key.

Magento stores the keys and secrets encrypted and shows only a mask (******) after saving. Leave the field as it is, or empty, to keep the saved value (Leave empty to keep the saved secret.); type a new value to change it. To delete a saved value, use the matching Clear saved … field.

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 for each invoice (Invoice notifications and customer return are configured automatically for each invoice.). The webhook covers customers who close the browser before returning and reports refunds made in the Moyasar Dashboard. Add it in Moyasar Dashboard > Settings > Webhooks.

Payment notifications: shows the webhook URL with a Copy URL button. It is the storefront address of the default store view and looks like https://your-store/wcpmoyasarpaymentgateway/webhook/index/. Copy the URL exactly as the settings show it. HTTP method: POST.

Webhook shared secret: enter the same value as the shared secret of the webhook in Moyasar. If nothing is saved yet, Save Config generates a random secret. A generated secret is shown once after saving, in the message New Moyasar webhook secret (shown once):, and never again, so copy it into Moyasar at once. Webhooks without the correct shared secret are rejected. One shared secret serves both modes. The webhook uses the secret of the website where the order was placed.

Clear saved webhook shared secret: set it to Yes and click Save Config to delete the saved secret. The webhook then rejects every call until a new secret is saved.

Generate a new webhook secret: set it to Yes and click Save Config to replace the saved secret with a new random one. The new secret is shown once after a successful save. Copy it to Moyasar Dashboard.

Select these events for the webhook (they are also listed in this section):

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

Orders

Status after payment: the order status set after a confirmed payment.

Amount or currency mismatches and payments that Moyasar holds for review always go to On Hold without an invoice.

Conditions

Payment from applicable countries: All Allowed Countries offers Moyasar for every country your store allows, Specific Countries only for the countries below.

Payment from specific countries: offer Moyasar only for billing addresses in these countries.

Minimum order total: offer Moyasar only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum order total: offer Moyasar only up to this order total, in the base currency. Empty or 0 means no maximum.

Sort order: the position among the payment methods at checkout. A whole number.

Advanced

Debug log: logs API calls and notifications to var/log/moyasar_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. API keys, card data and customer details are never logged. Default: No. The log is limited to 5 MB; the older part is kept in one previous file.

Log: shows the current size and the latest entries of the log. Click Clear log to empty it.

Remove settings and log on uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). The license key is always removed. The Moyasar invoices and refunds always stay, so old orders can still be refunded. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Pay with Moyasar) and sees its description. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then 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. The invoice shows Order #, the order number and your store name: Store Name in Stores > Configuration > General > General > Store Information (if it is empty, the name of the store in Stores > All Stores).

The order is marked paid only after Moyasar confirms it: the module reads the invoice from the Moyasar API and checks that it is paid, belongs to this cart and has the exact order amount and currency. This happens when the customer comes back, when Moyasar sends the invoice notification and when the webhook arrives, whichever comes first. Magento then creates the invoice with the Moyasar payment ID as the transaction ID, sets the status from Status after payment and sends the order e-mail. The customer sees the standard order success page. If Moyasar holds the payment for review, the order goes On Hold and the success page shows Your Moyasar payment is being reviewed. Do not pay again. The order is invoiced automatically when Moyasar confirms the payment.

If the payment cannot be confirmed yet, the customer sees the page Payment confirmation with We could not confirm your payment yet. If you completed it, your order will be updated automatically. Please do not pay again. and the buttons Check again and Back to checkout. A customer who comes back in another browser lands on the home page with Your Moyasar payment status was checked. Contact the shop to view the order.

If the customer comes back without paying (for example with the back button of the payment page), or Moyasar reports the invoice as failed, expired or cancelled, the order is cancelled (the stock goes back), the cart is restored and the customer sees Moyasar payment was not completed. Please try again or choose another payment method. in the cart. On a new attempt an open Moyasar invoice of the same order with the same amount and currency is reused; otherwise the previous open invoice of the cart is cancelled at Moyasar before a new one is created, so the old one can no longer be paid. If the previous invoice turns out to be paid already, that payment is confirmed instead of a new one.

If Moyasar cannot start the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Moyasar refused the invoice request. Choose another payment method. or Moyasar is temporarily unavailable. Please try another payment method. If the outcome of the request is unknown, the order stays in Pending Payment and the customer sees the Payment confirmation page, so the cart is not paid twice. The details are written to the log.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its open Moyasar invoice is cancelled and can no longer be paid.

The module works with the standard Magento checkout. It takes one-time payments on the Moyasar page only. It has no card form on your own checkout, no saved cards or tokenization, no subscriptions and no separate authorize and capture. Moyasar is not offered for orders created in the Admin or for multishipping checkout.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Moyasar, but Moyasar has not confirmed the payment yet. There is no invoice.

Processing, Complete or On Hold: the payment was confirmed. The status follows Status after payment. The invoice is created with the Moyasar payment ID as the transaction ID, and a note shows the invoice ID, the payment ID, the payment method, the mode and how the payment was confirmed (webhook, invoice notification, customer return, checkout or status check).

On Hold without an invoice: Moyasar holds the payment for review (the order is invoiced when Moyasar confirms it), Moyasar reported a different amount or currency than the order total, or a test invoice was paid while live mode is on. The note starts with Moyasar payment requires review: and ends with No paid invoice was created. Check the payment in the Moyasar Dashboard, then fulfil the order or refund the payment.

Canceled: the customer did not complete the payment, the invoice failed or expired, the payment could not be started, or the order was cancelled in Magento. If a payment arrives after the order was cancelled, the order is not invoiced and a review note is added.

Closed: the payment was fully refunded with a credit memo.

If a second invoice of a cart that is already paid is paid too (for example from two browser tabs), no second invoice is created. A note asks you to refund the duplicate in the Moyasar Dashboard. The notes are order comments that the customer does not see.

Moyasar payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Moyasar invoice ID, Moyasar payment ID, Moyasar mode, Moyasar status, Moyasar payment source, Moyasar card brand, Moyasar last4 and Moyasar refund history. The customer sees only the payment method title.

Below it, the Moyasar transactions section lists the Moyasar invoices of the cart with their mode and status. Check Moyasar payment status reads the invoice from Moyasar again, applies the result and adds a note. The section is shown to Admin users whose role allows editing orders.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Moyasar. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Moyasar.

The refund is made in the order currency, up to the amount Moyasar charged minus the amounts already refunded. A full refund of a card payment made less than 2 hours ago is sent as a void (cancel before settlement); STC Pay payments, older payments and partial refunds are sent as 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. The module first checks the currency, status and refundable amount of the payment at Moyasar. If Moyasar does not accept the refund, Magento shows the error, for example Moyasar refused the refund; the native Credit Memo was not saved., and the credit memo is not created. After a successful refund the credit memo records it, and the refund history is updated. A full refund closes the order.

Refund uninvoiced charge: when an order has no invoice but Moyasar charged money (for example On Hold after an amount mismatch, or a payment that arrived after cancellation), the Moyasar transactions section shows This charge has no paid invoice. Its actual amount can be refunded without creating a Credit Memo. Enter the Refund amount (the amount not refunded yet is filled in) and optionally a Reason, and click Refund uninvoiced charge. A full refund cancels the order. This needs the Admin permission for credit memos.

Refunds and voids made in the Moyasar Dashboard arrive by the webhook. If Moyasar shows more refunded than Magento recorded, a note is added to the order. The order and credit memos are not changed automatically. Create a credit memo with Refund Offline or update the order manually if needed. After a refund in the Moyasar Dashboard, further refunds of that order are not sent online: make them in the Moyasar Dashboard as well.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Moyasar Payment Gateway is the first row of the VibeFox Moyasar Payment Gateway group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-moyasar and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Moyasar does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the current mode has a secret key (Test secret key in test mode, Live secret key in live mode) and that the order currency is SAR, AED, USD, EUR, KWD, BHD or OMR. The settings page shows a warning after saving when the key is missing or the store currency is not supported. Check Payment from applicable countries and Payment from specific countries against the customer's billing address, and Minimum order total and Maximum order total.

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 one shown in Payment notifications, the method is POST, the four events are selected and its shared secret equals the one saved in Webhook shared secret for the website of the order. The order is also confirmed when the customer returns to the store, with Check again, or with Check Moyasar payment status on the order page.

Webhook answers unauthorized: the shared secret in Moyasar differs from the saved one. Type the secret of the Moyasar webhook into Webhook shared secret and click Save Config, or set Generate a new webhook secret to Yes, save and paste the secret shown into Moyasar.

Webhook answers not_configured: no shared secret is saved, for example after Clear saved webhook shared secret. Click Save Config to generate one and copy it to Moyasar.

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

Webhook answers busy, unavailable or retry: 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. Turn on Debug log to see the reason.

The webhook URL shows POST required in the browser: this is normal. The URL accepts only POST requests from Moyasar.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Moyasar retries the webhook later, and the order is also confirmed when the customer returns.

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

The customer is back in the cart with an error after Place Order: turn on Debug log and look at the Log field in the Advanced section. Moyasar is not available for this order. usually means a missing secret key or an unsupported currency. This cart already has a paid order. Do not pay again. means the cart was already paid with another order. A previous Moyasar invoice needs verification. Do not pay again. means an earlier attempt had an unknown result; check the payment in the Moyasar Dashboard. The order of that attempt is cancelled.

Test payments do not confirm orders: a test invoice paid while live mode is on puts the order On Hold without an invoice. Switch Test mode to the mode you want and use that mode's key.

Order is On Hold after payment: read the order notes (see Order statuses), then 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. The refund exceeds the amount still refundable at Moyasar. or Moyasar Dashboard refunds differ from the native journal. Reconcile before another online refund. means part of the payment was already refunded in the Moyasar Dashboard: refund the rest there and record it with Refund Offline. If the result of a refund is unknown (The Moyasar refund outcome is unknown. Check Dashboard before trying again.), online refunds of that order stay blocked (A previous Moyasar refund needs verification before trying again.): check the payment in the Moyasar Dashboard and complete the refund there.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) is refunded with Refund uninvoiced charge or in the Moyasar Dashboard.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_MoyasarPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_MoyasarPayment to remove the data, then bin/magento module:disable Vibefox_MoyasarPayment, delete the folder app/code/Vibefox/MoyasarPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove settings and log on uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Moyasar invoices and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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