Module and release scope
This guide covers Paymob Unified 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 — Environment |
select | Yes | Default: "sandbox" Choices: sandbox = Sandbox, live = Live |
region — Merchant region |
select | Yes | Default: "EG" Choices: EG = Egypt (EGP), AE = United Arab Emirates (AED), SA = Saudi Arabia (SAR) |
secret_key — Intention secret key |
secret | Yes | Use the account-specific value described below. |
public_key — Unified Checkout public key |
text | Yes | Use the account-specific value described below. |
api_key — Account API key for transaction inquiry |
secret | Yes | Use the account-specific value described below. |
hmac_secret — Transaction callback HMAC secret |
secret | Yes | Use the account-specific value described below. |
merchant_id — Merchant profile ID |
text | Yes | Use the account-specific value described below. |
integration_ids — Approved payment integration IDs |
text | Yes | Comma-separated numeric IDs from the matching merchant region and test/live environment. |
verification_intention_id — Existing intention ID for connection test |
text | Yes | Enter an intention already created in the matching Paymob dashboard. Test retrieves it and authenticates the inquiry API; it never creates an order or payment. |
currencies — Approved invoice currencies |
text | Yes | Comma-separated currencies approved for this merchant. No currency conversion is performed. |
Creates an Intention and redirects to Paymob-hosted Unified Checkout. This release covers Egypt/EGP, United Arab Emirates/AED and Saudi Arabia/SAR. Each connection belongs to one regional merchant account. Oman/OMR and other three-decimal currencies are excluded because the current invoice ledger uses two decimals. This module does not claim global merchant coverage.
Configure
- Select the regional merchant country and sandbox/live environment. In Paymob Settings → API Keys, obtain the Intention secret key, public key and transaction callback HMAC secret. Enter the account API key used for inquiry authentication and the numeric merchant profile ID. The Intention secret key and account API key are different credentials.
- In Settings → Payment Integrations, obtain numeric approved integration IDs. Enter the IDs for the same region and test/live environment, comma-separated. Enable purchase/standalone payment integrations and read/inquiry permissions. This module does not invoke capture, void or refund APIs and does not support authorization-only integrations.
- For connection Test, enter an existing Intention ID created in the corresponding Paymob environment. Test retrieves that intention with the secret key and authenticates the inquiry API with the account API key. Token issuance is authentication only; it creates no payment/order/authorization. Public key ownership, integration setup and HMAC delivery still require a sandbox checkout/callback test.
- Configure the connection’s notification URL for Transaction Processed callbacks. The module also sends the exact HTTPS notification URL and signed return URL in each Intention. Callback HMAC is a lowercase SHA512 HMAC over the documented ordered transaction fields, received as
?hmac=.... Token callbacks and subscription notifications are not accepted as payments. - Enter the region’s approved currency, run Test and enable only after sandbox verification. Fixed regional origins are
accept.paymob.com,uae.paymob.comandksa.paymob.com. Unified Checkout is constructed only on that origin from the returned client secret and the merchant public key.
Customers need real first/last name, phone, street address, city, state and country in their billing profile. No dummy phone or address is generated. Intention extras contain attempt/invoice/amount/currency references; the module reads the authenticated order inquiry and compares those extras, merchant, integration, environment, full paid amount and standalone success state. The HMAC omits some business metadata, so the signed notification alone is insufficient. Browser returns use the application’s stored order ID, never success claims from query parameters. Wallet callback fields with null HMAC inputs stay unconfirmed for reconciliation rather than guessing Paymob’s serialization.
Installation and activation
The package contains generic product code only. Installation leaves the module disabled and does not create, enable or populate a merchant account. In System → Payments → Provider library, enable the module only when ready, add a connection, enter your own credentials, run Test and explicitly enable that connection. Keep sandbox and live accounts separate. Existing enabled gateways are unaffected.
Use the exact HTTPS webhook URL displayed on that saved connection; do not enter the storefront home page. One connection endpoint can serve invoices across storefront domains because payment attempts retain their connection and invoice identity. Keep it reachable without login or a browser challenge. Return URLs are generated and signed by the application per invoice; do not replace them with a static merchant callback.
The module never collects PAN, CVV or customer wallet credentials. Checkout creation is submitted once, with a unique attempt reference; a timeout requires reconciliation, not an automatic second charge. Browser success parameters never prove payment. Final amount, currency, checkout identity and application metadata are checked against authenticated provider reads. Notifications use stable payment IDs for duplicate protection. A partial or ambiguous payment stays under billing review.
No currency conversion is performed. Only the listed two-decimal invoice currencies are accepted, and only those explicitly entered under Approved invoice currencies are offered. Availability of cards, wallets and local methods remains subject to the merchant account, shopper location and provider checkout; installing a module does not enable provider payment products. Refund, recurring billing and token charging operations are not implemented.
Validation
Run php tests/gateway-growth.php for isolated HTTP fixtures covering checkout creation, server verification, signed notifications, exact amounts, identity mismatches, invalid URLs, incomplete billing profiles and no checkout POST retries. These checks do not certify credentials, merchant underwriting or a live payment. Complete a provider sandbox checkout and callback test before enabling live traffic.
Official implementation references
Reviewed 2026-10-21. Provider contracts may change; recheck these sources before changing API versions.
- https://developers.paymob.com/paymob-docs/developers/intention-apis/create-intention
- https://developers.paymob.com/paymob-docs/developers/transaction-inquiry-apis/transaction-inquiry/by-order-id-or-reference
- https://developers.paymob.com/paymob-docs/developers/transaction-callbacks
- https://developers.paymob.com/paymob-docs/developers/authentication-request-generate-auth-token-1
- https://github.com/PaymobAccept/paymob-java/blob/main/src/main/java/com/paymob/http/FetchingData.java
- https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/blob/main/skills/paymob-integration/references/hmac-verification.md