VibeFox Paymob for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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 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.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Paymob Pay in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page 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).

5. In the Paymob dashboard set the callback URLs of your integration to the URL shown on the Configure page (see Callbacks).

6. Turn on Enable/Disable and click Save. Test a payment with the ID of a Paymob test integration, then enter the ID of your live integration.

On install the module creates two order statuses, Awaiting Paymob payment and Paymob payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences. A country enabled in your shop later must also be ticked there for this module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Paymob Pay > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when one of the four Paymob values is missing (until then Paymob is hidden at checkout) and when the default currency of the shop is not accepted by the selected Paymob country. A Callbacks box shows the callback URL with a Copy button and a link to the Paymob dashboard of the selected country.

Paymob

Enable/Disable: Enable Paymob turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Paymob.

Description: the text shown under the payment method at checkout. Default: Pay securely by card or mobile wallet on the Paymob payment page. Leave it empty to show no text.

Paymob account

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

Paymob country: the country of your Paymob account. It selects the API and payment page server, and the cart currency must be the currency of 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.

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: orders are created as paid only from callbacks signed with this secret.

Integration ID and iFrame ID must contain digits only. Spaces are removed. Any other value is rejected on save with the message that the field must contain digits only — the previous value was kept. The other fields are saved.

The saved API key and HMAC secret are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick API key or HMAC secret and click Save to remove it. An empty field keeps the saved value.

Callbacks

Paymob reports each transaction to your shop. In the Paymob dashboard open Developers > Payment Integrations, choose your integration, click Edit and set both Transaction processed callback and Transaction response callback to the URL shown in the Callbacks box. With friendly URLs it looks like https://your-shop/module/wcp_paymob_pay/callback, possibly with a language code such as /en/. The URL is built in the default language of the shop. Copy it with the Copy button. Set the URLs in every integration you use, including the test integration.

The transaction processed callback is sent by the Paymob server. The transaction response callback brings the customer back to your shop. Both are signed with your HMAC secret and checked by the module. 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 server callback works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Advanced

Debug log: writes the payment steps and callbacks to logs/paymob_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors and rejected callbacks are always logged, even when it is off. Keys, tokens and customer data are never written. Default: off.

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

Clean uninstall: when on, uninstalling the module deletes the module settings and logs. The Paymob IDs saved for orders (payment attempts) and the order statuses are always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Paymob) and confirms. The module registers a new Paymob order for the cart total in the cart currency, passes the customer's name, e-mail, phone and invoice 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. No order exists yet at this point.

After paying, the customer returns to your shop. The order is marked paid only after Paymob confirms it with a signed transaction. The order is then created and the customer sees the standard order confirmation page. A pending payment (for example cash or kiosk) or an authorized payment also creates the order, in a waiting status, and leads to the confirmation page.

If the order is being confirmed by the Paymob callback at the same moment, the customer sees a page with Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. For a pending payment the text is Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. The page has a Check again button and a Back to checkout button.

If the payment was declined, the customer is back at checkout with the same cart and the message Your Paymob payment was not completed. Please try again or choose another payment method. Every new attempt registers its own Paymob order, so the customer can pay the cart again. If the return from Paymob cannot be verified, the customer sees We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.

If Paymob cannot start the payment, the customer stays at checkout with a short message, for example Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. or Could not connect to Paymob. Please try again in a moment. The technical reason is written to the log.

The module takes one-time payments on the Paymob page. It has no saved cards, no subscriptions, no embedded card form on your site and no refunds from the back office.

Orders

Order statuses

No order yet: the customer was sent to Paymob and has not paid, the payment was declined, or Paymob has not confirmed the payment yet. Only the cart exists.

Payment accepted: Paymob confirmed the payment. The payment is recorded with the Paymob transaction ID as the transaction ID, and a note shows the transaction, the amount and the card type with the last four digits.

Awaiting Paymob payment: the payment is pending at Paymob, for example a cash or kiosk payment. The order moves to Payment accepted when Paymob confirms the payment.

Paymob payment on hold: Paymob only authorized the amount and has not captured it (capture it in the Paymob dashboard; the order moves to Payment accepted when the capture callback arrives); or the paid amount or currency differs from the cart (for example, the cart was changed after the payment started); or a payment arrived for an order that had been cancelled. The note explains the reason. Check the order and fulfil it or refund the payment in the Paymob dashboard.

If a second successful payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the duplicate in the Paymob dashboard. A payment for a cancelled order that had been paid before, or for a refunded order, only adds a note: the order is not reopened. A declined payment for an order that is not paid yet only adds a note.

Paymob payment block

The order page shows a Paymob payment block with each Paymob attempt of the order: the Paymob order, the merchant order ID and the country, the Paymob transaction ID, the status, the requested amount, the amount reported by Paymob with the card, and the Paymob message. Below them are the Notes of the module for this order.

Refunds

Refunds from the back office are not supported. Refund or void the payment in the Paymob dashboard. When Paymob reports a refund or void, a note is added to the order, and the order status is not changed. Update the order manually, for example its status or a credit slip.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paymob Pay is the first block on Modules > Module Manager > VibeFox Paymob Pay > Configure, 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 shop. Below them are the line Product: presta-payment-paymob and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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 customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Paymob does not appear at checkout: check that the license is active, Enable/Disable is on, all four values (API key, integration ID, iFrame ID, HMAC secret) are filled in and the cart currency is the currency of the selected Paymob country. The settings page shows a warning when something is missing. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: the callbacks do not reach your shop. Check that Transaction processed callback and Transaction response callback of the integration you use are exactly the URL shown in the Callbacks box, and that the HMAC secret is the one of the same Paymob account. Rejected callbacks are written to the log as warnings, even when Debug log is off. Look at the Log field on the module page.

Callback answers Invalid signature: the HMAC secret in the settings does not match the Paymob account, or the account of another country is selected. Copy the HMAC secret again.

Callback answers Not configured: the HMAC secret is empty. Enter the secret; Paymob retries the callback.

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 created (for example, the module is disabled). Paymob retries the callback. The reason is written to the log.

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

The customer sees an error when choosing Paymob: turn on Debug log and look at the log. Paymob payments are temporarily unavailable means a wrong API key or a missing value. Paymob could not start the payment means Paymob rejected the request, for example because of a wrong integration ID or incomplete billing data. This order cannot be paid with Paymob means the order total is zero. Paymob does not accept payments in followed by a currency means the cart currency is not the currency of the selected Paymob country.

The order is Paymob payment on hold or Awaiting Paymob payment after payment: read the notes in the Paymob payment block. The payment is pending (cash or kiosk), the transaction was only authorized (capture it in the Paymob dashboard), the amount or currency did not match, or the payment arrived after the order had been cancelled.

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.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Paymob Pay and choose Uninstall. The license key and license status of this module are always removed. If Clean uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Paymob payment attempts of orders and the order statuses Awaiting Paymob payment and Paymob payment on hold are always kept. Existing orders keep their payment notes, transaction IDs and Paymob IDs.

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