Module and release scope
This guide covers Moyasar 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 |
secret_key — Secret API key |
secret | Yes | The secret sk_test_ or sk_live_ API key. A publishable key cannot verify payments. |
currencies — Enabled invoice currencies |
text | Yes | Default: "SAR" SAR by default. Add AED, QAR or USD only when Moyasar has enabled multi-currency for this merchant. |
Creates a Moyasar-hosted invoice and leaves payment-method collection to Moyasar. No browser card SDK is embedded in the application.
Account setup
Obtain a secret API key from the Moyasar dashboard, select Sandbox for sk_test_ or Live for sk_live_, and permit invoice creation, invoice reads and payment reads. Publishable pk_ keys cannot verify payments and are rejected. The fixed API is https://api.moyasar.com/v1; the key selects the environment.
SAR is the default. Additional AED, QAR and USD invoice currencies must be approved and enabled by Moyasar for that merchant before being entered in this connection. Moyasar's multi-currency offering is account-specific; merchant settlement can be converted to SAR by Moyasar, but the customer invoice and the verified payment must retain the same original invoice currency and amount. Three-decimal BHD/KWD are excluded. Hosted invoices require at least 100 minor units.
Test makes an authenticated read-only /invoices list request. Checkout posts /invoices. The response must contain the exact invoice identity/amount/currency and an official checkout.moyasar.com/invoices/{id} link. Older HTTP invoice links are upgraded to HTTPS after validating the exact host/path; the customer is only redirected over HTTPS.
Notifications and reconciliation
The module supplies the generated webhook URL as the hosted invoice's callback_url, and signed application URLs as success_url/back_url. Hosted invoice notifications are unsigned; their body is used only as an invoice locator. No posted status, amount or payment fields are trusted. The module retrieves /invoices/{id} and the unique successful /payments/{id}, checking that the payment belongs to the invoice, amount/currency agree, and no refund/void or incomplete capture exists. Authorized-only payments stay pending. Staff reconciliation repeats these reads. Separate generic dashboard webhooks with type/data envelopes are not processed by this invoice-callback implementation.
Provider documentation
- Secret key authentication and environments
- Create hosted invoice
- Fetch invoice and its payment attempts
- Multi-currency approval and settlement
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.