MyFatoorah Hosted Invoices — setup and reference

Module and release scope

This guide covers MyFatoorah Hosted Invoices 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

Key / label	Type	Required	Default / guidance
mode — Environment	select	Yes	Default: "sandbox" Choices: sandbox = Sandbox, live = Live
country — Merchant country	select	Yes	Default: "SA" Choices: SA = Saudi Arabia · SAR, AE = United Arab Emirates · AED, QA = Qatar · QAR, EG = Egypt · EGP Country-specific token and matching base-currency invoices only. Kuwait, Bahrain, Oman and Jordan use three-decimal currencies and are excluded.
api_token — API token	secret	Yes	Generate a country-specific key with Create Payments, Get Payment Details and GetPaymentStatus access.
probe_payment_id — Existing payment ID for connection test	text	Yes	A payment from this merchant account. Test reads its base currency only; it never charges or changes it. The public KWD sandbox account is incompatible with the product’s two-decimal ledger.

Uses current v3 POST /v3/payments with OperationType=PAY. Omitting PaymentMethod/DisplayPaymentMethods lets MyFatoorah show all methods enabled for that account.

Account setup and currency

Generate a country-specific API key under Integration Settings → API Key. Grant access to Create Payments, Get Payment Details and the legacy GetPaymentStatus read endpoint used for invoice-to-payment reconciliation. Select the merchant country and matching token: Saudi Arabia/SAR, UAE/AED, Qatar/QAR or Egypt/EGP. API and portal hosts are fixed to MyFatoorah's documented country hosts; the application never accepts a custom API URL.

Enter an existing payment ID belonging to this merchant. Test retrieves that payment with GET /v3/payments/{paymentId} and checks the actual Amount.BaseCurrency. It never charges or changes that payment. This extra read is also made before creating a checkout, preventing an incorrectly selected country from charging another currency. The customer needs a real billing name.

Kuwait, Bahrain, Oman and Jordan's three-decimal base currencies are excluded because the product ledger uses two decimals. The public sandbox is normally KWD, so it correctly fails the currency check; request a supported two-decimal country test account from MyFatoorah. Never work around the check by relabeling a KWD token as SAR. No API keys or public demo credentials are embedded in this module.

Return and payment confirmation

The application sets the signed return URL in IntegrationUrls.Redirection. MyFatoorah appends paymentId, which is a locator only. Confirmation reads that payment using the merchant token and requires Invoice.Status=PAID, Transaction.Status=SUCCESS, matching stored invoice ID and merchant attempt metadata, and identical base/display/pay currencies and exact amounts. Authorize-only results, errors and converted currencies are not credited.

Staff reconciliation locates the successful payment using the documented read-only /v2/GetPaymentStatus invoice inquiry, then rechecks all money evidence with current /v3/payments/{paymentId}. Legacy responses never directly credit an invoice. This implementation ignores unsigned webhook claims; use browser return and staff reconciliation. No webhook secret is required by this implementation. Enable provider-side card/wallet/local methods with your MyFatoorah account manager.

Provider documentation

• Current hosted flow
• Create Payment
• Authenticated payment details
• API keys, permissions and country hosts
• Invoice inquiry

Reviewed 21 October 2026.

Install and enable

Requires EmailaBiller 1.3.6 or newer within the 1.3 release line.

Upload the signed package through System → Payments → Install, verify its checksum/publisher and install it. New modules and connections remain disabled. Enable the module, create a connection, enter your own credentials, run Test, then enable that connection and assign it to the intended storefront. No merchant details, credentials, existing connections or business defaults ship in this package.

Payment safety

Customers enter payment details on the provider's HTTPS page. The application never collects a PAN, CVV or reusable card token. API destinations are fixed; returned checkout URLs must match the official provider hosts. Checkout creation is submitted once, without automatic retries. After a timeout, reconcile the original checkout before creating another.

A browser return supplies no payment authority. The module verifies settlement through authenticated reads, then the core checks the stored checkout, attempt, exact amount/currency and invoice. Pending payments, uncaptured authorisations, refunds, errors and identity mismatches do not produce payment credit. Provider transaction IDs produce stable event keys, so repeating a verified notification or reconciliation does not create a second ledger entry. Only two-decimal invoice currencies are supported; there is no exchange-rate calculation or invoice conversion.

Run php tests/gateway-middle-east.php for isolated mocked API/security checks. Tests do not contact a provider or use a live database. Before enabling production, complete the provider's merchant onboarding and exercise the intended methods using your merchant's sandbox facilities. Available cards, wallets and local methods depend on country, currency, account approval and shopper/device eligibility.