PayTabs Hosted Checkout — setup and reference

Module and release scope

This guide covers PayTabs Hosted Checkout 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 — Profile environment	select	Yes	Default: "sandbox" Choices: sandbox = Test profile, live = Live profile
region — Account region	select	Yes	Default: "global" Choices: sa = Saudi Arabia, ae = United Arab Emirates, eg = Egypt, om = Oman, jo = Jordan, kw = Kuwait, iq = Iraq, ma = Morocco, qa = Qatar, global = Global
profile_id — Profile ID	text	Yes	Use the account-specific value described below.
server_key — Server key	secret	Yes	Use the server key issued for this profile and region, with payment request and query access.
currencies — Enabled invoice currencies	text	Yes	Default: "USD" Comma-separated two-decimal currencies approved for this profile. The invoice currency is sent unchanged.

Uses PayTabs Hosted Payment Page for an immediate sale and ecom transaction. All enabled methods offered by the account remain available on PayTabs' hosted page.

Account setup

In the PayTabs merchant dashboard, obtain the profile ID and its server key. Select the profile's region: Saudi Arabia, UAE, Egypt, Oman, Jordan, Kuwait, Iraq, Morocco, Qatar or Global. The module chooses the documented fixed regional API host. Choose Test or Live to label the profile correctly; PayTabs determines actual test/live processing from the profile and server key, not from an override sent with each request. Never put production credentials into a test profile.

Allow hosted-payment creation and transaction queries. Configure only currencies approved for this profile, selected from AED, SAR, QAR, EGP, USD, EUR, GBP, PKR, AUD, CAD, MAD and INR. Country approval and local payment methods belong to PayTabs. Three-decimal invoice currencies are excluded. Customers need a real billing name and country; other saved billing details are supplied when present.

Test sends /payment/query for an unissued cart reference. It accepts an empty successful array or the documented authenticated transaction-not-found response (HTTP 400, code 113). Authentication errors, rate limits and unknown responses do not pass. Checkout submits /payment/request. Captured credit requires an authenticated query showing this profile's Sale with response status A and matching cart/attempt metadata. Authorizations and follow-up refunds/captures are excluded.

Webhook and return

The application supplies the connection's public HTTPS webhook URL as callback and its signed return URL as return. No separate signing secret is needed: PayTabs signs callback/IPN raw request bytes with the profile server key using HMAC-SHA256 in the Signature header. Signatures must verify before a callback is queried. An authenticated query supplies settlement proof. Browser POST fields, including provider status and its own signature, are not used to credit money; the application's signed return and stored transaction ID locate the subsequent authenticated query.

Provider documentation

• Query Transaction and regional hosts
• Hosted transaction reference
• Callback signature verification
• Official SDK webhook guidance

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.