VibeFox Paymob for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

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 checkout 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. Add it in System > Localisation > Currencies if your store does not have it yet. 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_paymob_pay-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_paymob_pay.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_paymob_pay-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Paymob Pay and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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 in the Callbacks section (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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_paymob_pay.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Paymob Pay, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the Paymob keys and IDs and the callback URLs as in steps 3 to 6 for OpenCart 3. The settings page and its fields are the same in both versions. Only the callback URL is different (see Callbacks).

A new install starts with the payment method turned off.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 store is not accepted by the selected Paymob country.

When you save, Title must not be longer than 128 characters, Sort Order must be a whole number (negative numbers are allowed), Total a number, 0 or greater, and the selected geo zone and order statuses must exist; otherwise nothing is saved and the page names the field.

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, up to 128 characters. If it is empty, customers see Paymob. Default: Paymob.

Description: the text shown to the customer on the Confirm Order step, above the confirm button. Default: Pay securely by card or mobile wallet on the Paymob payment page. Leave it empty to show no text.

Sort Order: the position of Paymob among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Paymob only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones. On OpenCart 4, when the store asks for no payment address, the shipping address is used.

Total: the checkout total, in the default currency of the store, that an order must reach before Paymob is offered. Leave it empty to offer Paymob for any total.

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 checkout 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 marked as paid only by 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. To remove a saved value, tick Clear the saved API key on save or Clear the saved HMAC secret on save under the field and click Save.

Callbacks

Paymob reports each transaction to your store. 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 Callback URL shown in this section. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_paymob_pay/callback, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_paymob_pay/payment/wcp_paymob_pay.callback. It is built from the storefront address of your OpenCart installation. Copy it with the Copy button. The section also links to the Paymob dashboard of the selected country. 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 store. Both are signed with your HMAC secret and checked by the extension. 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 callback URL also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the callbacks and the customer's return through.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after Paymob has reported a correctly signed transaction. A declined payment leaves the order without a status; the customer goes back to the checkout with the cart kept. Each field below lists your OpenCart order statuses.

Order Status After Payment: the Paymob transaction is paid with the expected amount and currency. Default: Processing.

Awaiting Paymob Payment Status: the transaction is pending, for example a cash or kiosk payment. The order gets the status after payment when Paymob confirms it. Default: Pending.

Paymob Payment On Hold Status: Paymob only authorized the amount (capture it in the Paymob dashboard), the paid amount or currency differs from the order, or the payment arrived for a cancelled order. A note explains the reason. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

The next three fields tell the extension which statuses your store uses. The extension never sets them.

Payment Error Status: the status your store uses for orders with a payment error. A pending transaction may move such an order to the awaiting status. Default: Failed.

Cancelled Order Status: the status your store uses for cancelled orders. A payment received for such an order puts it on hold, or only adds a note if it was paid before. Default: Canceled.

Refunded Order Status: the status your store uses for refunded orders. A payment received for such an order only adds a note. Default: Refunded.

Advanced

Debug log: writes the payment steps and callbacks to paymob_p_debug.log.php in the OpenCart logs folder (storage/logs). 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 extension deletes the gateway settings and the log. The Paymob IDs saved for orders (payment attempts) are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The API key and HMAC secret are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved secrets are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Paymob). At the Confirm Order step the customer sees your description and the note You will be redirected to the secure Paymob payment page to pay by card or mobile wallet. OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. When the customer clicks Confirm Order, the extension registers a new Paymob order for the order total in the order currency, passes the customer's name, e-mail, phone and payment address (on OpenCart 4, when the store asks for no payment address, the shipping 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.

After paying, the customer returns to your store. The order is marked paid only after Paymob confirms it with a signed transaction. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success page. A pending payment (for example cash or kiosk) or an authorized payment also gives the order a status, the awaiting or the on-hold status, and leads to the success page.

If the order is still being confirmed when the customer comes back, a Payment confirmation page says 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. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 keeps one order for the checkout and updates it, so the customer pays the same order with a new attempt. 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 another order of the same cart has already been paid or is waiting for payment (for example from a second browser tab), the customer is taken to the success page instead of paying again. On OpenCart 4 the messages after the return from Paymob are shown above the checkout page.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example you cancelled it), the customer is sent back to the checkout with Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., and the next Confirm Order pays a new order. If that order already has a status and the cart now has other products or quantities, the customer is sent back to the checkout as well, and the new cart gets a new order.

If Paymob cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, 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 extension 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 admin.

Orders

Order statuses

No status (missing order): the customer was sent to Paymob and has not paid, the payment was declined, or Paymob has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

On OpenCart 4 an unpaid order of the checkout can get the status Voided, which OpenCart 4 sets when the customer comes back to the Confirm Order step. The extension treats such an order as an order without status, and a later payment still confirms it.

Order Status After Payment (default Processing): Paymob confirmed the payment. A note shows the transaction, the amount and the card type with the last four digits.

Awaiting Paymob Payment Status (default Pending): the payment is pending at Paymob, for example a cash or kiosk payment. The order moves to the status after payment when Paymob confirms the payment.

Paymob Payment On Hold Status (default Pending): Paymob only authorized the amount and has not captured it (capture it in the Paymob dashboard; the order moves to the status after payment when the capture callback arrives); or the paid amount or currency differs from the order; 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.

When an order that already has a status changes, OpenCart notifies the customer. If a second successful payment arrives for an order that is already paid, or a payment for a second order of an already paid cart, the paid order is not changed and 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 already has a status only adds a note.

Notes are entries in the order History that the customer does not see.

VibeFox Paymob Pay tab

In Sales > Orders open an order paid with Paymob. At the bottom of the order page, next to History and Additional, the VibeFox Paymob Pay tab shows each Paymob attempt of the order: the Paymob order with 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 extension for this order. The tab is shown to users who have access to the extension.

Refunds

Refunds from the admin 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.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paymob Pay is the first block on Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit, 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: opencart-payment-paymob and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. 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 customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 checkout currency is the currency of the selected Paymob country. The settings page shows a warning when something is missing. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: the callbacks do not reach your store. Check that Transaction processed callback and Transaction response callback of the integration you use are exactly the URL shown in the Callbacks section, 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 extension 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 status could not be set. 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 after Confirm Order: 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 order currency is not the currency of the selected Paymob country. This payment method is not available. means the checkout session no longer matches the order or the payment method was turned off meanwhile: the customer reloads the checkout.

The order is in the on-hold or awaiting status after payment: read the notes in the VibeFox Paymob Pay tab. 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 Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Paymob Pay. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. On OpenCart 4 the OpenCart event of the extension and its startup action, which lets the callbacks and the customer's return through in maintenance mode, are removed too. If Clean uninstall is on, the other gateway settings (title, description, country, keys and IDs, logging) and the log are removed. If it is off, they are kept for a later re-install. The Paymob payment attempts of orders are always kept. Existing orders keep their payment notes and Paymob IDs.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Paymob Pay in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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