Skip to main content

MyFatoorah Payment Gateway

The ECOSIRE MyFatoorah Payment Gateway module connects Odoo's native payment framework to MyFatoorah, the leading Kuwait/GCC payment aggregator. Customers can pay via KNET, SADAD, BENEFIT, NAPS, Mada, Apple Pay, Samsung Pay, STC Pay, and international Visa/Mastercard cards through a hosted redirect checkout -- no PCI scope falls on the Odoo server. After the customer completes payment, Odoo performs a server-side status re-fetch before marking the transaction done; the redirect body is never trusted on its own.

Compatibility: Odoo 17 / 18 / 19 Price: $249 (one-time) License: LGPL-3 -- up to 3 domain activations

Key Features​

  • Native payment.provider integration -- works in eCommerce, customer portal, invoicing, and subscription payment flows
  • Hosted redirect checkout (MyFatoorah-managed payment page -- no PCI scope on your server)
  • Payment methods: KNET (Kuwait), SADAD + Mada (Saudi Arabia), BENEFIT (Bahrain), NAPS (Qatar/Oman), Visa/Mastercard (all GCC + international), Apple Pay, Samsung Pay, STC Pay (where enabled by your merchant account)
  • Server-side status polling via GetPaymentStatus -- redirect body is never trusted alone
  • Refunds processed directly from the Odoo refund flow via MakeRefund
  • Separate test and live API tokens -- sandbox hits apitest.myfatoorah.com, production hits api.myfatoorah.com
  • Optional callback shared-token guard (defence-in-depth anti-CSRF)
  • Correct currency precision: KWD/BHD/OMR/JOD at 3 decimals; SAR/AED/QAR/EGP/USD at 2 decimals
  • Supported currencies: KWD, SAR, AED, BHD, QAR, OMR, EGP, USD, JOD
  • ECOSIRE license enforcement via ecosire_license_client

Prerequisites​

  • Odoo 17, 18, or 19 (Community or Enterprise edition)
  • An active ECOSIRE license for this module (ecosire_license_client must be installed)
  • A live MyFatoorah merchant account to accept real payments -- sign up at portal.myfatoorah.com
  • A separate MyFatoorah test account/token for sandbox testing (credentials are not shared between environments)
Pakistani wallets (JazzCash / EasyPaisa) not included

JazzCash and EasyPaisa are not part of the verified MyFatoorah v2 API surface available to standard merchants. If your merchant account has integrator-gated access to these wallets, contact ECOSIRE support -- the connector will raise a clear error rather than silently calling unverified endpoints.

Installation​

  1. Download the module ZIP from your ECOSIRE Dashboard
  2. Extract to your Odoo addons directory: 
    unzip ecosire-payment-myfatoorah-*.zip -d /opt/odoo/addons/
  3. Restart the Odoo service: 
    sudo systemctl restart odoo
  4. Navigate to Apps, click Update Apps List
  5. Search for "ECOSIRE Payment MyFatoorah" and click Install
  6. Activate your ECOSIRE license when prompted (Settings > ECOSIRE License)

Configuration​

Step 1: Obtain Your MyFatoorah API Tokens​

  1. Log in to the MyFatoorah merchant portal
  2. Navigate to Settings > API Key
  3. Copy your Live API Token -- this is used when the provider is set to Enabled (production)
  4. Switch to your test account (or use the MyFatoorah demo portal at apitest.myfatoorah.com) and copy the Test API Token -- this is a separate credential; never reuse the live token in test mode
  5. Note which payment methods your merchant account has enabled (KNET, SADAD, BENEFIT, etc. -- available methods depend on your country setting and merchant agreement)

Step 2: Enable the Provider in Odoo​

  1. Navigate to Accounting > Configuration > Payment Providers (or Website > Configuration > Payment Providers for eCommerce)
  2. Click Create or find the MyFatoorah entry that was seeded on install
  3. On the Credentials tab, enter:
FieldDescription
myfatoorah_api_key -- Live API TokenBearer token from the MyFatoorah portal for production use
myfatoorah_test_api_key -- Test API TokenSeparate sandbox token; used when provider state is Test
myfatoorah_payment_method_id -- Default Payment Method IdSet to 0 to show the MyFatoorah hosted page with all enabled methods (recommended). Use a specific integer to pre-select a single method (e.g. KNET only).
myfatoorah_callback_token -- Callback Shared Token (optional)If set, this token is appended to the callback URL as cb_token=... and verified on inbound callbacks. The authoritative check is always a server-side GetPaymentStatus re-fetch; this is a defence-in-depth guard only.
  1. Set the State to Test while verifying your integration, then switch to Enabled for live payments
  2. Confirm your Supported Currencies match what your MyFatoorah merchant account allows (KWD, SAR, AED, BHD, QAR, OMR, EGP, USD, JOD are supported by the connector)

Step 3: Webhook and Return URLs​

Odoo registers two inbound routes automatically on install -- you do not need to configure these manually in most setups:

RoutePurpose
/payment/myfatoorah/returnCustomer redirect-back URL after payment on the hosted page. MyFatoorah appends ?paymentId=... here. Odoo calls GetPaymentStatus server-side before updating the transaction.
/payment/myfatoorah/webhookOptional server-to-server notification endpoint (JSON POST). Uses the same GetPaymentStatus re-fetch for authentication -- no inbound HMAC signature is relied upon because MyFatoorah's signature scheme is not reliably documented.

If your Odoo instance is behind a reverse proxy, ensure both routes are reachable from the public internet. In the MyFatoorah portal you may optionally register your webhook URL under Settings > Webhooks / Notifications, pointing to https://your-odoo-domain.com/payment/myfatoorah/webhook.

No HMAC signature verification

MyFatoorah does not publish a reliable inbound HMAC/signature header scheme. The connector authenticates all inbound callbacks by calling GetPaymentStatus server-side with the paymentId from the callback payload. This is the recommended approach per the MyFatoorah integration documentation and is more robust than a signature header.

Usage​

Checkout Flow​

  1. Customer adds items to cart and proceeds to checkout
  2. Odoo calls InitiatePayment to discover available payment methods for the transaction currency, then calls ExecutePayment to create the payment session
  3. Odoo stores the returned InvoiceId as the transaction reference (provider_reference) and redirects the customer to the MyFatoorah hosted page
  4. Customer selects their payment method (KNET, Visa, Apple Pay, etc.) and completes payment on the MyFatoorah-managed page
  5. MyFatoorah redirects the customer back to /payment/myfatoorah/return; Odoo immediately calls GetPaymentStatus server-side
  6. The transaction is marked Done (InvoiceStatus = Paid), Pending, Error (Failed), or Cancelled (Expired) based on the server-confirmed status

Refunds​

  1. Open the paid customer invoice in Odoo and click Credit Note
  2. Odoo calls MakeRefund via the MyFatoorah API
  3. The refund is credited back to the customer's original payment method
KNET partial refunds

Partial refunds may not be supported for KNET payments (Kuwait national debit network). Full refunds are always supported. If a partial refund is required on a KNET transaction, contact your MyFatoorah merchant support directly.

Test Mode​

Set the provider state to Test and use your Test API Token to run end-to-end test transactions without real charges. The connector hits https://apitest.myfatoorah.com in test mode. MyFatoorah provides test card numbers on their developer portal for simulating Paid, Failed, and Pending outcomes.

API Details​

FieldValue
Auth methodBearer token (Authorization: Bearer {api_token})
Live base URLhttps://api.myfatoorah.com
Test base URLhttps://apitest.myfatoorah.com (source-verified)
Implemented endpointsInitiatePayment, ExecutePayment, GetPaymentStatus, MakeRefund
Gated endpointsDirectPayment, ExecuteRecurringPayment, split payments (Suppliers array) -- raise a clear UserError until merchant-level enablement is confirmed
Key config fieldsmyfatoorah_api_key, myfatoorah_test_api_key, myfatoorah_payment_method_id, myfatoorah_callback_token
Return URL/payment/myfatoorah/return
Webhook URL/payment/myfatoorah/webhook
Supported currenciesKWD, SAR, AED, BHD, QAR, OMR, EGP, USD, JOD

Troubleshooting​

IssueSolution
"No MyFatoorah API token configured"Add the correct token on the provider's Credentials tab. Test mode requires the Test API Token; live mode requires the Live API Token.
Payment status stays Pending after redirectOdoo's GetPaymentStatus call may be failing. Check Odoo server logs for network errors reaching api.myfatoorah.com. Verify the paymentId query param is included in the return URL.
"MyFatoorah error: ..." in checkoutThe IsSuccess=false message from MyFatoorah is surfaced directly. Common causes: invalid token, unsupported currency for your merchant account, or expired payment session.
Callback token mismatch warningThe cb_token in the inbound callback does not match the Callback Shared Token on the provider. Either clear the field (disable this optional guard) or ensure the value in the portal matches exactly.
Currency not available at checkoutThe currency is not in the connector's supported list (KWD, SAR, AED, BHD, QAR, OMR, EGP, USD, JOD) or your merchant account does not have that currency enabled. Check your MyFatoorah merchant settings.
Refund fails on KNET transactionKNET may only support full refunds. Process the full refund instead of a partial one, or contact MyFatoorah merchant support.
"License not active" errorActivate your ECOSIRE license at Settings > ECOSIRE License. API calls are blocked until the license is confirmed.
Direct payment / recurring billing not availableDirectPayment and ExecuteRecurringPayment require PCI/tokenization enablement on your merchant account. These endpoints are intentionally gated; contact ECOSIRE support if you have confirmed merchant-level access.
Test payments going to liveConfirm the provider State is set to Test (not Enabled). In test mode the connector uses your Test API Token and hits apitest.myfatoorah.com.

Support​

Last updated on