Online Payments with Paymob

What is the Paymob integration?

Paymob is a payment gateway that lets your storefront customers pay online by card, mobile wallet, and other local payment methods in Egypt, the UAE, Saudi Arabia, and Oman. Once connected, checkout gains a Pay Online option: the customer is redirected to a secure Paymob page, completes the payment, and the order is marked paid automatically. You never confirm these payments by hand.

Before you start

You need a Paymob merchant account with these values from the Paymob dashboard under Settings > API Keys and Settings > Payment Integrations:

Connect Paymob to a store

1. Go to Settings > Integrations in the business portal.
2. On the Paymob card, click Connect Paymob.
3. Choose the Store to connect.
4. Choose the Paymob country of your account. Only countries matching your store currency are offered: Egypt (EGP), UAE (AED), Saudi Arabia (SAR), or Oman (OMR).
5. Paste the API Key, Secret Key, Public Key, and HMAC Secret.
6. Add your Integration IDs, one entry per payment method.
7. Optionally set an Order fee (see below).
8. Save. Your keys are checked live with Paymob before anything is stored. If a key is wrong, the save is rejected with the exact reason, so fix the key and save again. The same live check runs every time you update the keys or settings later.

Add the callback link in Paymob

After saving, the integration page shows a Callback URL with a copy button. Paste this link in your Paymob dashboard so Paymob can notify us the moment a payment happens:

1. In the Paymob dashboard, open Settings > Payment Integrations and edit each integration you use.
2. Paste the link into both Transaction processed callback and Transaction response callback.
3. Save.

Payment fee (optional)

You can add a fee or a discount that applies only when the customer pays online:

The fee appears as its own line in the checkout totals before the customer confirms, and it is included in the amount charged by Paymob.

Enable Online Payment for the storefront

Once the Paymob connection is active:

1. Go to Settings > Stores, open the store, and select the Payments tab, then the Storefront section.
2. Enable Online Payment and save.

The storefront checkout now shows Pay Online. Before a gateway is connected, the Online Payment switch stays off and shows a Configure payment gateway shortcut instead. You also cannot disable or delete the gateway while Online Payment is still enabled.

How online-paid orders behave

Online payments are controlled by the system from start to finish:

• The order starts as Pending while the customer pays on the Paymob page.
• The payment is confirmed with Paymob directly, then the order flips to Paid automatically. The order page shows the gateway, the Paymob transaction number, and the card or wallet used.
• Manual payment actions are disabled for these orders: no recording payments by hand, no editing amounts, and no manual refunds. This keeps your records exactly in sync with Paymob.
• If a payment attempt fails, the customer can retry from the storefront. Every attempt is tracked on the order.
• An unpaid order whose payment never completes cancels itself automatically after a few hours, so abandoned checkouts never pile up as pending orders.

Refunds for online-paid orders

Refunds for gateway payments are always processed through Paymob and always for the full paid amount:

• Cancelling a paid order automatically sends the full refund through Paymob. No extra steps.
• Creating a refund from the order page sends the same full refund through Paymob.
• The refund is marked Completed only after Paymob confirms the money moved. Until then it shows as Processing.
• Refunding an order you have not fulfilled yet cancels it automatically once Paymob confirms the refund. Orders already fulfilled keep their completed state.

Troubleshooting

Related

• Storefront Payment Methods: Enable and order checkout payment options
• Online Checkout Flow: The full customer journey
• Order Payments: How payments appear on orders