MyFatoorah
MyFatoorah is a hosted checkout used across Kuwait, Saudi Arabia, the UAE, Qatar, Bahrain, Oman, Jordan and Egypt. Shoppers pay on MyFatoorah's page — cards, KNET, mada, Apple Pay and the other methods enabled on your MyFatoorah account — and return to your store. Which methods appear is decided in your MyFatoorah account, not in TakeTheme.
Connecting
Settings → Payments → MyFatoorah.
| Credential | Required | Where to find it |
|---|---|---|
| API Token | Yes | MyFatoorah portal → Integration Settings → API Key |
| Country | Yes | The country your MyFatoorah account was opened in — the token only works on that country's server. kuwait also covers Bahrain, Jordan and Oman. Choose test only with a sandbox token |
| Webhook Secret Key | No | MyFatoorah portal → Integration Settings → Webhook Settings (Webhook V2). See below |
Orders are created when the shopper returns from MyFatoorah: TakeTheme looks the payment up with MyFatoorah on the way back, so nothing needs to be registered for the normal flow. TakeTheme also asks MyFatoorah to send a webhook for every payment on its own, which creates the order if the shopper pays and then closes the tab.
If you enable Webhook V2 with a secret key in the MyFatoorah portal, paste that secret into Webhook Secret Key and every delivery is signature-checked.
Use the test country with a sandbox token from registertest.myfatoorah.com to try the flow without real money.
Settings
| Setting | Default | What it does |
|---|---|---|
| Checkout label | empty | Customer-facing name at checkout (e.g. "Card, KNET or Apple Pay"). Blank shows "MyFatoorah" |
| Transaction fee | none | Flat or percentage surcharge added to the order when this method is chosen |
| Payment discount | none | Discount applied when the shopper picks this method |
| Send payment confirmation email | on | Emails the customer when payment succeeds |
| Notify on payment failures (emails) | empty | Alerts your team when a checkout fails |
Currency
TakeTheme creates the MyFatoorah invoice in your store currency, and MyFatoorah converts it into your account's settlement currency. MyFatoorah documents SAR, BHD, AED, QAR, OMR, KWD, JOD and EGP; if your store currency is not one your account accepts, checkout shows MyFatoorah's own error instead of a payment link.
If MyFatoorah reports a paid amount that differs from the order total, TakeTheme logs the difference for reconciliation but does not reject the payment.
Payment flow
- Shopper picks MyFatoorah and submits the checkout.
- TakeTheme creates a MyFatoorah invoice (tagged with an internal reference) and redirects the shopper to MyFatoorah's page.
- Shopper pays with any method your account offers.
- MyFatoorah sends the shopper back to TakeTheme (
GET /v1/payment/myfatoorah/return/<reference>?paymentId=…). TakeTheme reads that payment from MyFatoorah with your API token and checks that it belongs to this exact checkout — the page the shopper saw is never treated as proof — then creates the order, already Paid. - The shopper lands on your store's thank-you page.
MyFatoorah also POSTs a webhook:
POST https://<your-api-host>/api/v1/payment/webhook/myfatoorah
A webhook never decides the outcome by itself: it only tells TakeTheme which payment to look up, and the status is re-read from MyFatoorah. If you set a Webhook Secret Key, an unsigned or mismatched delivery is rejected with 403. Whichever of the return and the webhook arrives first creates the order — never both.
Failed and abandoned payments
A declined payment sends the shopper back with a failed result and they see Payment Failed and can try again. MyFatoorah lets a shopper retry on the same invoice, so a failed attempt is recorded but a later successful attempt on that invoice still creates the order. An invoice that is never paid creates no order.
Refunds
Refunds are recorded in TakeTheme only — no refund call reaches MyFatoorah. Issue it in the MyFatoorah portal and record it here. See Refunds.
Troubleshooting
Checkout says MyFatoorah rejected the API token. The token and the Country don't match — a token only works on the server of the country its account was opened in. Re-select the country, or paste a fresh token (masked values are ignored on save).
The shopper paid but no order appeared.
Open the order's payment record: if the lookup could not reach MyFatoorah, the storefront keeps checking and the order appears as soon as it can. If you have a webhook secret set, a 403 in the webhook log means the stored secret doesn't match the one in the MyFatoorah portal.
A payment method is missing from the MyFatoorah page. Methods are enabled per account on MyFatoorah's side; TakeTheme sends no method filter.