VibeFox Paymob for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

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

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

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_paymob_pay folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Paymob > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Choose the Paymob country and enter the API key, integration ID, iFrame ID and HMAC secret (see Configuration).

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

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

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Paymob. 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 store currency is not accepted by the selected Paymob country. A box shows the callback URL with a Copy button and a link to the Paymob dashboard of the selected country.

General

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

Title: the payment method name customers see at checkout. 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.

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

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 URL shown on the settings page. It looks like https://your-site/wc-api/paymob_pay/. 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 store. Both are signed with your HMAC secret and checked by the plugin. 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.

Advanced

Debug log: Log payment steps and callbacks writes the payment steps and callbacks to WooCommerce > Status > Logs, source wcp_paymob_pay. Errors and rejected callbacks are always logged. Keys, tokens and customer data are never written. Default: off.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. Paymob IDs saved on orders are kept. Default: off.

Checkout

The customer chooses the payment method (by default Paymob) and places the order. The plugin 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.

After paying, the customer returns to your store. The order is marked paid only after Paymob confirms it with a signed transaction. A paid, pending or authorized payment leads the customer to the order received page.

If the payment was declined, the customer comes back to the checkout (or to the Pay for order page, if the payment was started there) with 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 retry the same order. 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 sees a short message and can choose another payment method, 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 payment method works on the classic checkout, on the Checkout block and on the Pay for order page. On the Pay for order page the order currency is checked instead of the store currency. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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 WooCommerce.

Orders

Order statuses

Pending payment: the customer was sent to Paymob and has not paid yet, or Paymob has not confirmed the payment yet.

Processing: Paymob confirmed the payment. Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the Paymob transaction, the amount and the card type with the last four digits. The transaction ID is the Paymob transaction ID.

On hold: the payment is pending at Paymob, for example a cash or kiosk payment; or Paymob only authorized the amount and has not captured it (capture it in the Paymob dashboard, the order is completed 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 order note explains the reason.

Failed: Paymob declined the payment of a pending order. The customer can pay again.

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.

Refunds

Refunds from WooCommerce 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 with a manual refund in WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Paymob. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store currency is the currency of the selected Paymob country. The settings page shows a warning when something is missing. Developers with a multi-currency Paymob account can extend the accepted currencies with the filter paymob_p_supported_currencies.

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 URL shown on the settings page, and that the HMAC secret is the one of the same Paymob account. Rejected callbacks are logged as warnings under WooCommerce > Status > Logs, source wcp_paymob_pay, even when the debug log is off.

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: the order was being updated by another request at the same moment, for example the customer return. Paymob retries the callback.

The customer sees an error when placing the 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.

The order is On hold after payment: read the order note. 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Clean uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and Paymob IDs.

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