VibeFox Paymob for Adobe Commerce — Guida

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the curl extension for the Paymob API.

Paymob account: a merchant account in one of the supported countries: Egypt, United Arab Emirates, Saudi Arabia, Oman or Pakistan. You need four values from the Paymob dashboard: the API key, the integration ID of an online payment integration, the iFrame ID of the payment page and the HMAC secret.

Currency: the order (cart) currency must be the currency of your Paymob country: EGP for Egypt, AED for the UAE, SAR for Saudi Arabia, OMR for Oman, PKR for Pakistan. With another currency the payment method is hidden at checkout. Multi-currency Paymob accounts are not supported.

Reachable store: your store must be reachable from the internet, without password protection or a firewall blocking Paymob, so that the Paymob callbacks arrive.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-paymob-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PaymobPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PaymobPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Paymob Pay. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Choose the Paymob country and enter the API key, Integration ID, iFrame ID and HMAC secret (see Configuration). In the Paymob dashboard set both callback URLs of your integration to the Callback URL shown in the Callbacks row (see Callbacks). Set Enable to Yes and click Save Config. Test a payment with the ID of a Paymob test integration, then enter the ID of your live integration and click Save Config again.

The module adds the Paymob payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates its own tables for the Paymob payment attempts and the processed Paymob events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Paymob Pay, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Enable, Title and Description also for a store view. Debug log and Remove data on uninstall are read from the Default Config only. Save Config saves the whole page. The group has no sub-sections; below, its fields are grouped by purpose in the order of the page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Title is required and must not exceed 128 characters.); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a non-negative number.).

Integration ID and iFrame ID must contain digits only; spaces are removed. Any other value is not saved: Magento shows the warning Integration ID must contain digits only — the previous value was kept. (or the same for iFrame ID), and the other fields of the page are saved.

General

Enable: shows or hides Paymob at checkout. It is shown only when all four Paymob values are filled in. Default: No.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Paymob. Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely by card or mobile wallet on the Paymob payment page.

Paymob account

All values are in your Paymob merchant dashboard. There is no separate test mode: for test payments enter the integration ID of a Paymob test integration. No other setting changes.

Paymob country: the country of your Paymob account. It selects the Paymob API and payment page server, and the order currency must match this country. Default: Egypt.

API key: in the Paymob dashboard under Settings > Account info > API Key.

Integration ID: in the Paymob dashboard under Developers > Payment Integrations: the numeric ID of the online card or wallet integration. The payment methods offered on the Paymob page are those of this integration. Test payments use a test integration.

iFrame ID: in the Paymob dashboard under Developers > iframes: the numeric ID of the payment iFrame.

HMAC secret: in the Paymob dashboard under Settings > Account info > HMAC. Required: a payment is confirmed only from callbacks signed with this secret.

Magento stores the API key and HMAC secret encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved value, type a new value to change it. To delete a saved value, clear the field and click Save Config. The values are saved as entered (only spaces at the start and end are removed); quotes and backslashes are kept.

Callbacks

The Callbacks row shows the Callback URL with a Copy URL button. It looks like https://your-store/wcppaymobpay/checkout/callback/ and is built from the base URL of the default store view (with a website selected in Scope, of the default store view of that website). In the Paymob dashboard open Developers > Payment Integrations, choose your integration and set both Transaction processed callback and Transaction response callback to this URL. Copy the URL exactly as the settings show it. Set it in every integration you use, including the test integration. The row also has a Paymob dashboard link for the selected country and the note For test payments enter a Test integration ID. Capture and refund in the Paymob dashboard; record refunds manually in Magento.

The transaction processed callback is sent by the Paymob server. The transaction response callback brings the customer back to your store. Both are signed with your HMAC secret (SHA-512) and checked by the module with the HMAC secret of the store view where the order was placed. Callbacks without a valid signature are rejected and change nothing. If the server callback is late or lost, a signed customer return confirms the payment as well. The callbacks are handled even when Enable is No or the license is not active.

While Enable is Yes, the row also shows warnings: Enter the API key, integration ID, iFrame ID and HMAC secret: until then Paymob is hidden at checkout., and The store currency … is not accepted by the selected Paymob country (accepted: …): Paymob is hidden at checkout. when the base currency of the store is not the currency of the selected country.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Paymob for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Paymob only for billing addresses in these countries.

Minimum Order Total: offer Paymob only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Paymob only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number; negative values are allowed.

Advanced

Debug log: the module writes to var/log/paymob_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings, for example rejected callbacks and Paymob API errors, are always written. This setting adds the payment steps. Keys, tokens and customer data are never written. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes, its cache and the log (see Uninstall). The license key is always removed. The Paymob payment attempts, events and order history are always kept. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Paymob) and sees the description. Paymob is offered only when the cart currency is the currency of the selected Paymob country and the total is above zero. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module registers a new Paymob order for the order total in the order currency, passes the customer's name, e-mail, phone and billing address to Paymob and sends the customer to the Paymob payment page of your country. There the customer pays with one of the methods of your integration, for example a card or a mobile wallet. The payment link is valid for one hour.

The order is marked paid only after Paymob confirms it: the signature must verify with your HMAC secret, the transaction must belong to a Paymob order registered by this store, the integration ID must be the one of the payment, and the amount and currency must match the order. Magento then creates the invoice with the Paymob transaction ID as the transaction ID, the order moves to Processing and the order e-mail is sent. The customer sees the standard order success page with Paymob payment confirmed. A customer who comes back in another browser lands on the home page with the same message.

If the customer comes back before Paymob has confirmed the payment, the customer sees a page with Your Paymob payment is being confirmed. Do not pay again. and a Check again link. For a pending payment (for example cash or kiosk) the success page shows Your Paymob payment is pending. Complete it by following the instructions from Paymob. Do not pay again.; the order stays in Pending Payment until Paymob reports the payment. For an authorized payment or a payment that needs review the success page shows Your Paymob payment requires manual review. Do not pay again.

If the payment was declined, the order is cancelled (the stock goes back) when the customer returns, the cart is restored and the customer is back in the cart with Your Paymob payment was not completed. You can try again. Every new attempt registers its own Paymob order. If the return from Paymob cannot be verified, the customer is sent to the cart with We could not verify the Paymob response. Please check your order before retrying.

If Paymob cannot start the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart: Paymob payments are temporarily unavailable. Please choose another payment method. (wrong API key), Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. (Paymob rejected the request), This order cannot be paid with Paymob. or Could not connect to Paymob. Please try again in a moment. In the other cases (the module is disabled, the license is not active, a value is missing, the currency is not accepted) the message is Paymob could not start payment. Please check your order before retrying. The technical reason is written to the log.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If Paymob later reports a payment for a cancelled order, the order is not invoiced and not reopened: a note asks you to reconcile or refund the payment in the Paymob dashboard.

The module works with the standard Magento checkout. It takes one-time payments on the Paymob page. It has no saved cards, no subscriptions, no embedded card form on your site, no capture and no refunds from Magento. Paymob is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Paymob, but Paymob has not confirmed the payment yet. A pending payment (for example cash or kiosk) adds the note Paymob payment … is pending (for example a cash / kiosk payment). The order is completed when Paymob confirms the payment. There is no invoice.

Processing: Paymob confirmed the payment. The invoice is created with the Paymob transaction ID, and a note shows the transaction, the amount, the card type with the last four digits and whether it was confirmed by the callback or by the customer return.

On Hold: Paymob only authorized the amount and has not captured it: the authorization is recorded and the note asks you to capture it in the Paymob dashboard; when the capture callback arrives, the hold is released and the order is invoiced. Or the paid amount or currency differs from the order: no invoice is created and the note asks you to check the payment in the Paymob dashboard. If an order is on hold for another reason, for example set by you, a later payment only adds the note Paymob transaction … was received while the order is on manual hold. Review it before shipping.

Canceled: the payment was declined, the payment could not be started, the order stayed in Pending Payment too long, or the order was cancelled in Magento.

A paid order is never changed back, and repeated callbacks and returns, even at the same moment, never invoice an order twice. If a second successful payment arrives for a paid order or a paid cart, a note asks you to refund the duplicate in the Paymob dashboard. A declined payment only adds a note. The notes are order comments that the customer does not see.

Paymob payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after the payment, Paymob order, Paymob transaction, Paymob country and Payment card. On the Information tab a VibeFox Paymob Pay section lists every Paymob attempt of the order with Attempt, Paymob order, Merchant order ID, Paymob country, Status, Transaction, Requested amount, Reported amount, Payment card and Message. It is shown also when the module is disabled. The customer sees only the payment method title.

Refunds

Refunds and captures from Magento are not supported. Refund or void the payment in the Paymob dashboard, then record it in Magento with a credit memo and Refund Offline. When Paymob reports a refund or void, the module adds the note Paymob reported a refund or void (transaction …). The order status was not changed — update the order manually if needed. and creates no credit memo.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paymob Pay is the first row of the VibeFox Paymob Pay group in Stores > Configuration > Sales > Payment Methods (Default Config scope), above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-paymob and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Paymob is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees Paymob could not start payment. Please check your order before retrying. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Paymob does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that all four values (API key, Integration ID, iFrame ID, HMAC secret) are filled in and that the cart currency is the currency of the selected Paymob country. The Callbacks row shows a warning when something is missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the callbacks do not reach your store. Check that Transaction processed callback and Transaction response callback of the integration you use are exactly the Callback URL shown in the Callbacks row, that your store is reachable from the internet, and that the HMAC secret is the one of the same Paymob account, entered for the website of the store. Rejected callbacks are written to the log as warnings, even when Debug log is No. Read the Log field.

The callback answers Invalid signature: the HMAC secret in the settings does not match the Paymob account, or the account of another country is used. Copy the HMAC secret again. Nothing is changed.

The callback answers Not configured: the HMAC secret is empty. Enter the secret; Paymob may retry the callback.

The callback answers Invalid request: the request is not a Paymob transaction callback. Ignored answers a callback of another type, foreign a signed transaction that does not belong to a payment started in this store.

The callback answers locked or retry: the order was being updated by another request at the same moment, for example the customer return, or the order could not be updated. Paymob may retry the callback. The reason is written to the log.

Opening the callback URL in the browser leads to the cart with the could not verify message: this is normal. The URL accepts only signed requests from Paymob.

Callbacks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the callback URL too. The order is confirmed by the next callback or customer return that reaches the store.

The order is On Hold or stays Pending Payment after payment: read the order notes. The payment is pending (cash or kiosk), the transaction was only authorized (capture it in the Paymob dashboard), or the amount or currency did not match. Check the payment in the Paymob dashboard and process the order yourself.

Test payments: enter the ID of a Paymob test integration in Integration ID and set the callback URLs in that integration. For real payments enter the ID of your live integration again.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PaymobPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PaymobPayment to remove the data, then bin/magento module:disable Vibefox_PaymobPayment, delete the folder app/code/Vibefox/PaymobPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings of all scopes, its cache and the log are removed too. If it is No, the settings are kept for a re-install. The tables with the Paymob payment attempts and events are always kept, so late callbacks of old orders are still recognised after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

Paymob is a trademark of its respective owner. This module is not affiliated with or endorsed by Paymob.