WooCommerce MyFatoorah Payment Gateway

1. Overview

WooCommerce MyFatoorah Payment Gateway by PatSaTECH connects your WooCommerce store to MyFatoorah, the payment gateway for businesses in Kuwait, Saudi Arabia, the UAE, Qatar, Bahrain, Oman, Jordan and Egypt. After placing the order the customer is sent to MyFatoorah’s secure Hosted Payment Page (in English or Arabic). It offers every method enabled on your account: KNET, mada, Visa / Mastercard, Apple Pay, Google Pay, Benefit, STC Pay and more. Card details are typed on MyFatoorah’s page and never reach your server.

An order is marked paid only after the payment has been read back from the MyFatoorah API (invoice, status, amount and currency). This happens on the customer’s return, from webhooks and in a final background check. Nothing in a redirect or webhook body is trusted on its own. Refunds, full and partial, are made from the WooCommerce order screen.

This is an independent PatSaTECH plugin with its own gateway IDs (patsatech_myfatoorah, patsatech_myfatoorah_knet, …_applepay, …_googlepay), classes and options, so it does not clash with MyFatoorah’s official plugin.

2. Features

• MyFatoorah Hosted Payment Page (API v3)
• English or Arabic payment page
• KNET, mada, Visa/Mastercard, AMEX, Benefit, STC Pay…
• Optional separate KNET, Apple Pay, Google Pay options
• Classic & Blocks checkout
• HPOS compatible
• 8 countries, live API host chosen automatically
• Token checked on save, enabled methods listed
• Webhook V2 with MyFatoorah-Signature (V1 accepted)
• Every payment re-read from the API
• Amount & currency verification
• Per-order lock, idempotent requests
• Full & partial refunds (currency converted)
• Portal refunds recorded in WooCommerce
• Friendly decline messages, retry on the same order
• Minimum amount checked before the order
• Payment links expire, unpaid orders cancelled
• Customer mobile sent in international format
• Debug log (tokens never logged)
• Translation-ready (.pot)

3. Requirements

Tested on: WordPress 7.1.3, WooCommerce 11.2.1 (classic and Blocks checkout), PHP 8.1.34, MyFatoorah test environment (KWD). See Tested on.

4. Installation

1. In WordPress admin go to Plugins → Add New → Upload Plugin.
2. Choose woomyfatoorah-1.0.0.zip and click Install Now.
3. Activate WooCommerce MyFatoorah Payment Gateway (PatSaTECH). WooCommerce must be active.

FTP: upload the woomyfatoorah folder to /wp-content/plugins/ and activate it.

5. Step-by-step setup with screenshots

Click any screenshot to open it full size. Tokens, webhook secrets, MyFatoorah payment / invoice / refund IDs, email addresses, phone numbers and IP addresses are blurred or left out.

Part A: MyFatoorah token

1. Get a test token

   For a first test, copy MyFatoorah’s public test token from docs.myfatoorah.com › API Key › Test (Demo) Token, or create a token in your own demo portal (Integration Settings › API Key). Full details: Getting your MyFatoorah token.

2. Optional: set the webhook

   In your own (demo or live) portal open Integration Settings › Webhook Settings, enable Webhook V2, set the endpoint to https://your-store.com/wc-api/patsatech_myfatoorah_webhook/, tick Transaction Status Changed and Refund Status Changed, and copy the secret key. Not possible with the public token, and not required: the plugin sends its webhook URL with each payment.

Part B: WordPress / WooCommerce

3. Upload and activate the plugin

   Plugins → Add New → Upload Plugin, choose woomyfatoorah-1.0.0.zip, install and activate.

   

   

4. Set the store currency

   WooCommerce → Settings → General: choose a MyFatoorah currency (the test site uses Kuwaiti dinar (KWD) with 3 decimals).

5. Paste the token

   Go to WooCommerce → Settings → Payments → MyFatoorah, tick Enable MyFatoorah, keep Test mode ticked, paste the Test API token and click Save changes. The plugin checks the token and lists your methods, for example “MyFatoorah Test token verified. Enabled payment methods: KNET, VISA/MASTER, AMEX, MADA, Apple Pay, Google Pay, Benefit, STC Pay…”.

   

   

   

6. Optional: KNET as its own option

   Enable MyFatoorah KNET (KWD stores) and, if they are enabled on your account, MyFatoorah Apple Pay and Google Pay. They use the same token. See Separate checkout options.

   

Part C: Test payment

7. Choose MyFatoorah at checkout

   Add a product to the cart, choose Pay online (KNET, mada, cards, Apple Pay) (or KNET) on the classic or Blocks checkout and click Place order.

   

   

8. Pay on the MyFatoorah page

   The customer is sent to MyFatoorah’s payment page. Test card 5123 4500 0000 0008, 01/39, CVV 100, then choose the success option in the 3-D Secure simulator. KNET: 8888 8800 0000 0001, expiry 09/30.

   

   

   

9. Order received

   After a successful payment the customer comes back to the order-received page. The plugin reads the payment from MyFatoorah before showing it as paid.

   

10. Order is Processing

    The order becomes Processing. The MyFatoorah payment ID is the order’s transaction ID, and a note records the method and how it was confirmed, for example “MyFatoorah payment … (VISA/MASTER (Mastercard •••• 0008)) completed (invoice …, test mode, confirmed by customer return).” or “… confirmed by webhook”.

    

    

6. Getting your MyFatoorah token and webhook secret

Test token (no sign-up needed)

1. Quickest: MyFatoorah publishes a public test token in its docs: docs.myfatoorah.com › API Key › Test (Demo) Token. Use the page’s copy button and paste it straight into WooCommerce → Settings → Payments → MyFatoorah (Test API token). It works with apitest.myfatoorah.com for payments, but it belongs to a shared account: you cannot test refunds with it or see its portal, and you cannot set its webhook secret.
2. Your own demo account (recommended for full testing): register at registertest.myfatoorah.com, sign in to the demo portal (demo.myfatoorah.com) and open Integration Settings › API Key. Create a token that is allowed to create and get payments and to Make Refund, then copy it. With your own demo account you can test refunds, signed webhooks and portal refunds.

Live token

1. Sign in to your live MyFatoorah portal (your account manager activates the account and the API after verification). If the portal asks for a one-time code (2FA / OTP), enter it yourself. The token itself doesn’t need 2FA.
2. Open Integration Settings › API Key and create or copy the token with the permissions above.
3. In the plugin choose the Live account country (it picks the API host), paste the Live API token and save. The plugin checks it and shows “MyFatoorah Live token verified. Enabled payment methods: …”.

Webhook and webhook secret (recommended)

1. In the portal open Integration Settings › Webhook Settings.
2. Tick Enable Webhook, choose Webhook V2, set the endpoint to https://your-store.com/wc-api/patsatech_myfatoorah_webhook/, and tick the events Transaction Status Changed and Refund Status Changed.
3. Turn on the secret key. V2 requires it. Copy the secret into the plugin’s webhook secret key field. Webhooks must then carry a valid MyFatoorah-Signature.
4. Without a secret, every webhook is accepted only after the payment or refund has been read back from MyFatoorah, which is just as safe. The plugin also sends its webhook URL with every payment (on by default), so events arrive even before the portal is set up.

7. Plugin settings

WooCommerce → Settings → Payments → MyFatoorah

8. KNET, Apple Pay and Google Pay as their own checkout options

Besides the main MyFatoorah option (all methods on one page), you can enable MyFatoorah KNET, MyFatoorah Apple Pay and MyFatoorah Google Pay under WooCommerce → Settings → Payments. Each sends the customer straight to that method on MyFatoorah and uses the main gateway’s token and settings. KNET is offered only for KWD orders. Apple Pay and Google Pay appear only if they are enabled on your MyFatoorah account, and Apple Pay only works in Safari or on Apple devices.

9. Webhooks

Webhooks let MyFatoorah tell the store about a payment even if the customer closes the browser before coming back. Set them in your portal under Integration Settings › Webhook Settings. The plugin also sends its URL with each payment.

Webhook endpoint: https://your-store.com/wc-api/patsatech_myfatoorah_webhook/

Other events (Balance Transferred, Supplier events, Recurring…) are acknowledged with HTTP 200 and ignored. Both Webhook V2 (recommended, signed) and the older V1 format are accepted. The shared demo account behind MyFatoorah’s public test token sends V1. Events for invoices that this site didn’t create are acknowledged quietly and never touch a order. A shared test account sends every merchant’s events, roughly every 15 seconds, and the plugin logs that only once per 10 minutes.

Every applied webhook writes a log line saying how it was verified, for example Webhook TransactionsStatusChanged (V1) for payment …, order 6538 (test, verified by API lookup …) or (… signature verified). When a payload can’t be recognised, the debug log records only its shape (key names, no values).

10. Payment flow & order statuses

11. Refunds

1. Open the order and click Refund.
2. Enter the amount (or line-item quantities), an optional reason, and click Refund … via MyFatoorah.
3. The refund request goes to MyFatoorah straight away. MyFatoorah completes refunds in the background (at once if Auto Refund is on for your account), so the first note says “Refund of … requested from MyFatoorah (refund …, status PENDING)…”. A second note follows when the refund is completed. If MyFatoorah cancels it, a warning and an admin notice say the customer was not refunded.

• Partial and full refunds both work, several times up to the amount paid. WooCommerce core refuses a refund above the order’s remaining refundable total, and the plugin also refuses more than is left on the MyFatoorah payment. Failed attempts don’t count.
• Currency: refunds are sent in your MyFatoorah account (base) currency. Other order currencies are converted using the payment’s own rate.
• Refunds made in the MyFatoorah portal are recorded in WooCommerce through the Refund Status Changed webhook.
• Every refund request and result is logged (failures as errors).
• If WooCommerce taxes are on, the refund box shows read-only tax lines. Enter the refund total as usual.

12. Declines, minimum amount and time limit

Declined payments

The customer comes back to the store with one clear message, for example “Your card has expired. Please use another card.”, “Your payment was declined: insufficient funds…” or “Card authentication (3-D Secure) was not completed…”. The order stays Pending payment with one note (reason and MyFatoorah code such as MF007), and the customer can pay again straight away. Each retry creates a new payment link. Only one failure note is added per payment, even when the webhook arrives as well.

Minimum amount

For a total below the minimum (default 0.100 KWD/BHD/OMR/JOD, 1.00 for the others), the checkout shows “The minimum amount for online payment is 0.100 KWD. Please add more items to your order.” before the order is created, on both the classic and the Blocks checkout. A store currency MyFatoorah doesn’t support gets “MyFatoorah cannot take payments in …”.

Time limit and abandoned payments

Each payment link expires after Cancel unpaid orders after (default 60 minutes). Two minutes after that, the order is checked with MyFatoorah once more. If nothing was paid it is Cancelled with the note “Unpaid order cancelled: no completed MyFatoorah payment 60 minutes after checkout.” There is only ever one check per order, timed from the latest payment link, and it is removed as soon as the order is paid, cancelled or refunded. A customer who opens a new link on the same order is not cancelled early.

13. Testing (test cards)

Test cards from MyFatoorah’s docs (Test Cards). Use any card-holder name (two words). They work only with a test token on apitest.myfatoorah.com.

• Apple Pay / Google Pay appear on the payment page only when they are enabled on the MyFatoorah account (Apple Pay only in Safari or on Apple devices).
• Test payments run in KWD, the test account currency. Other store currencies are converted at MyFatoorah’s rate.

14. Countries, currencies & payment methods

Who can use MyFatoorah. MyFatoorah serves businesses in Kuwait, Saudi Arabia, the UAE, Qatar, Bahrain, Oman, Jordan and Egypt. Each country has its own portal and API token, and the plugin picks the right live API host from the Live account country setting (Saudi Arabia, the UAE, Qatar and Egypt have their own hosts). A live account is opened with MyFatoorah: their account manager activates it after business verification (KYC).

Currencies. The store currency must be one of KWD, SAR, AED, QAR, BHD, OMR, JOD, EGP. MyFatoorah settles in your account (base) currency and converts other display currencies at its own rate. Refunds are sent in the base currency, and the plugin converts them using the payment’s own rate.

Minimum amount. The MyFatoorah API only requires an amount above zero and publishes no per-method minimums. The plugin has a Minimum amount setting: empty means 0.100 for KWD, BHD, OMR and JOD (3-decimal currencies) and 1.00 for the others. Below it the customer sees “The minimum amount for online payment is 0.100 KWD…” before anything is created (tested with a 0.050 KWD order).

Payment methods. Whatever is enabled on your MyFatoorah account: KNET, Visa / Mastercard, mada, AMEX, Benefit / BenefitPay, UAE and Qatar debit cards, Apple Pay, Google Pay, STC Pay, Tamara, Samsung Pay, Fawry, Meeza and others. When you save the token, the plugin lists the methods enabled on your account. You can limit the payment page to Cards, KNET, Apple Pay and Google Pay, or leave it empty to show everything.

Finding the payment in MyFatoorah

In your portal open Sales › Invoices or Transactions. Each WooCommerce payment has the external identifier wc-<order>-<attempt>-…, and the MyFatoorah payment ID is the order’s transaction ID.

15. Debug logs

Tick Debug log in the settings, then open WooCommerce → Status → Logs and choose the woomyfatoorah source. Errors, warnings, webhook receipts (with how each was verified) and refunds are always logged. Tokens, webhook secrets, card data and customer details are never logged.

16. Troubleshooting & FAQ

“The token does not have the required permissions” when saving

The plugin checks the token by listing your payment methods. Some tokens, including MyFatoorah’s public demo token, aren’t allowed to call the newer method list; the plugin then falls back to MyFatoorah’s v2 method list and still shows your methods. If the message stays, open Integration Settings › API Key and allow creating and getting payments (and Make Refund).

Paid on MyFatoorah but the order is still Pending payment

Check that Webhook URL per payment is on and the site uses https, or set the portal webhook to https://your-store.com/wc-api/patsatech_myfatoorah_webhook/. The return page and the expiry check also read the payment from MyFatoorah. WP-Cron / Action Scheduler must run. See the woomyfatoorah log.

“Webhook refused: MyFatoorah-Signature does not match”

The webhook secret in the plugin doesn’t match the portal’s secret for that mode. Paste it again, or clear it to use API lookups instead.

The log shows “not for an invoice of this site”

Normal with the shared public test token: its account sends every merchant’s events to the webhook URL. They are acknowledged and ignored, logged at most once per 10 minutes, and no order is touched.

A refund says “your MyFatoorah balance is too low”

MyFatoorah refunds come out of your available balance. Top it up, or refund the customer from the MyFatoorah portal (the refund is then recorded in WooCommerce). With the public test token this always happens; use your own demo account to test refunds.

Why is a refund “Pending”?

MyFatoorah completes refunds in the background. The order gets a note when it is completed, or a warning if MyFatoorah cancels it.

“The minimum amount for online payment is …”

Lower the Minimum order amount setting if your MyFatoorah contract allows smaller payments, or offer another method for tiny orders.

KNET / Apple Pay doesn’t appear

KNET is only offered for KWD orders. Apple Pay and Google Pay must be enabled on your MyFatoorah account. Apple Pay shows only in Safari or on Apple devices.

Does it work next to MyFatoorah’s official plugin?

Yes. The IDs, classes, options and endpoints are all different. Don’t enable both for the same checkout.

Subscriptions?

No. One-time payments only.

17. Tested on

• WordPress 7.1.3
• WooCommerce 11.2.1 (classic shortcode checkout and Cart/Checkout Blocks)
• PHP 8.1.34; PHP 7.4 or later required
• MyFatoorah test environment (apitest.myfatoorah.com) with the public demo token, store in KWD (3 decimals). Live payments not yet tested.
• Scenarios: card with 3-D Secure (Blocks), KNET declined and retried, AMEX declined, webhooks verified by API lookup (V1 format), other merchants’ events ignored, minimum amount before order creation (classic and Blocks), abandoned order with a single expiry check, refund refused for low balance and for over-refund
• Not yet tested live: successful refunds, signed Webhook V2, Apple Pay / Google Pay, live payments (need an own demo or live account)

18. Changelog

1.0.0 — 2026-10-19

• Initial release.
• MyFatoorah Hosted Payment Page (API v3), English or Arabic; optional separate KNET, Apple Pay and Google Pay options.
• HPOS compatible; classic and Blocks checkout.
• Test and live tokens checked on save (8 countries, live host by country); webhooks V2 (MyFatoorah-Signature) and V1, verified by signature or API lookup; webhook URL sent with each payment.
• Every payment re-read from the API under a per-order lock; amount and currency verified.
• Full and partial refunds with currency conversion and background status tracking; portal refunds recorded; clear messages when the MyFatoorah balance is too low.
• Minimum amount checked before the order is created; payment links expire and unpaid orders are cancelled; debug logging (no secrets).

19. Support

PatSaTECH · [email protected] · www.patsatech.com

Please include your WordPress, WooCommerce and PHP versions, the mode (test or live), the account country and the relevant log lines. Never send your token or webhook secret.