Skip to main content

Connecting Paymob, Kashier or Fawry to WooCommerce or Laravel, plus InstaPay Manual Payments

T
Tarek Ibrahim
•
Connecting Paymob, Kashier or Fawry to WooCommerce or Laravel, plus InstaPay Manual Payments

Most payment projects in Egypt do not fail on the gateway. They fail on everything around it: an order that is marked paid before the money is confirmed, a callback that nobody verifies, a currency mismatch that only appears on the first live transaction, or a manual transfer process that depends on one person checking WhatsApp screenshots. This guide walks through how Paymob, Kashier and Fawry connect to a WooCommerce store or a Laravel application, where each integration tends to break, and how to handle InstaPay transfers that have no gateway behind them.

Everything below is based on the gateways’ public developer documentation at the time of writing. Field names, plugin options and endpoints change, so treat this as an architecture guide and check the current documentation of your provider before you write code. We have not run live transactions for this article, and we do not quote fees, because fees are agreed per merchant contract.

Start with the decision, not the plugin

There are two questions to settle before anyone installs anything. The first is whether the checkout is a standard shop or a custom flow. A standard catalogue with a cart, shipping and coupons fits WooCommerce well, and every major Egyptian gateway offers a WooCommerce plugin or a documented route to one. A flow with deposits, instalments tied to contract milestones, B2B credit limits or booking holds usually belongs in a custom application, and Laravel is where we build those.

The second question is which payment methods your customers actually use. Cards are only one part of the picture in Egypt. Wallets, cash collection at a retail point, bank instalments and direct bank transfers all carry real volume depending on the audience. A gateway that covers your customers’ preferred methods is worth more than one with a slightly nicer dashboard. Ask each provider for the exact method list on your merchant account, because what is described in documentation and what is enabled on your account can differ.

If you are still scoping the store itself, our notes on ecommerce website cost in Egypt and our ecommerce development page cover the wider picture. This article stays on payments.

The shape of every gateway integration

Whatever the brand, a hosted or redirect-style integration follows the same sequence, and understanding it makes every provider easier to read.

  • Your server creates an order in your own database with a status such as pending payment, and a unique reference.
  • Your server calls the gateway with the amount, currency, customer details and your reference, using secret credentials that never reach the browser.
  • The gateway returns something the browser can use: a payment URL, a client secret, or a token.
  • The customer pays on the gateway’s hosted page, so card data never touches your server.
  • The customer returns to your site. This return is only a courtesy to the customer. It is not proof of payment.
  • The gateway sends a server-to-server notification, usually called a callback or webhook. Your server verifies it and only then marks the order as paid.

The last two steps are where most defects live. The browser redirect can be interrupted, replayed or forged. The signed server notification is the source of truth. Every design decision below follows from that rule.

Paymob: intention, redirect, verified callback

Paymob’s current documentation centres on a Create Intention API with a unified checkout. The flow, as documented, works like this.

For the latest request fields, authentication requirements and supported checkout flow, check Paymob’s official Payment Intention documentation before implementing the integration.

Credentials and environments

You work with a secret key and a public key from the Paymob dashboard, one or more integration IDs (each tied to a payment method and a currency), and a separate HMAC secret used to verify callbacks. Test and live are separate modes, and the documentation states that the live or test status of your integration IDs must match the secret key you use. Mixing them is a common first-day error, and it produces confusing failures that look like a code bug.

Creating the intention

Your server calls the Create Intention endpoint with an Authorization header in the form Token followed by a space and your secret key. The body carries the amount in cents (so 250.00 EGP is sent as 25000), the currency, which must match the currency of the integration ID you select, a payment_methods array listing integration IDs, items, billing data, and optional extras. Two fields deserve attention. The special_reference field is your own unique reference and comes back in the transaction callback as merchant_order_id, which is how you find the right order. The extras object lets you carry your own parameters through to the callback.

The documentation also notes that the notification URL is supported only with card integration IDs, and that the redirection URL is supported for card and wallet only. If you offer a method outside those, plan for a way to confirm status that does not rely on that notification, such as checking the transaction in the dashboard or through an inquiry call described in the API reference.

Sending the customer to pay

The response includes a client_secret. For the redirect experience, you send the customer’s browser to the checkout host for their region, with your public key and the client secret as query parameters. For Egypt the documented host is eg.checkout.paymob.com. The customer completes payment there.

Verifying the callback with HMAC

Paymob signs transaction callbacks. The documented method is a SHA-512 HMAC, keyed with your HMAC secret, calculated over a concatenation of specific callback fields in a fixed order: amount_cents, created_at, currency, error_occured, has_parent_transaction, the transaction id, integration_id, is_3d_secure, is_auth, is_capture, is_refunded, is_standalone_payment, is_voided, the order id, owner, pending, source_data.pan, source_data.sub_type, source_data.type, and success. You build the string with no separators, compute the HMAC, and compare it with the hmac value that arrives with the callback. The field names differ slightly between the processed callback (a POST with a JSON body) and the response callback (a GET with query parameters), so write a small mapper for each rather than one function that guesses.

Two implementation notes from engineering experience, independent of Paymob. Compare signatures with a constant-time comparison function. In PHP that is hash_equals. And treat the boolean fields carefully: the string you hash must use the same text representation the gateway used, so test with a real sample callback from the sandbox instead of assuming how true and false are rendered.

Paymob in WooCommerce and in Laravel

For WooCommerce, check whether Paymob provides an official plugin for your WooCommerce version and whether it supports the intention-based checkout. If it does, installation is mostly credentials, integration IDs, and the callback URLs registered in the Paymob dashboard. If you need behaviour the plugin does not offer, such as splitting orders or custom order statuses, a small custom gateway class extending the WooCommerce payment gateway base is cleaner than patching a vendor plugin.

For Laravel, build a payment service class with three responsibilities: create the intention, build the redirect URL, and verify the callback. Store the Paymob order or intention ID on your payment record, make the callback route idempotent, and push the actual order state change into a queued job. Our Laravel development work follows this pattern on booking and portal projects.

Kashier: plugin-first, with an embedded option

Kashier publishes WooCommerce plugins, and the documentation distinguishes three routes: a plugin for the classic checkout, a plugin for the block-based checkout, and an embedded form option that is distributed through Kashier support for cases such as connected accounts or WooCommerce Subscriptions.

What to check before installing

The first check is which checkout your store uses. WooCommerce stores on the block-based checkout need the block plugin, and a mismatch is the most common reason a payment method does not appear at checkout. The second check is High-Performance Order Storage. The documentation tells merchants on WooCommerce 8 or later to enable HPOS under WooCommerce, Settings, Advanced, Features before installing. The third check is currency. The plugin pages list EGP, USD, GBP and EUR, and they describe an Enforce EGP Payment option: when enabled, payments are settled in EGP even if the storefront displays another currency, and you must supply an exchange rate greater than 1. Decide who owns that rate and how often it is updated, because a stale rate becomes a pricing error.

Configuration

You take the API key and secret key from the Integration page of the Kashier merchant dashboard, and a Merchant ID that is entered in each enabled payment method’s settings. After uploading and activating the plugin, the payment methods appear under WooCommerce, Settings, Payments, and each method you enable needs its own credentials, title and description. Keep test mode on while you test with the test cards from Kashier’s testing guide, then replace the test keys with live keys and switch test mode off. Do that as a deliberate release step with a named person, not as a casual edit on a Friday night.

Webhooks

The WooCommerce plugin page we reviewed does not cover webhooks or callbacks. Do not assume the plugin handles every status change in your environment. Read Kashier’s webhook documentation, confirm with their support how failed, refunded and expired payments are reported, and test them. For a custom Laravel build on Kashier, use the hosted payment page route from their integration guide, and apply the same rule as before: the signed server notification decides the order status, not the browser return.

Fawry: signed charge requests and cash-at-store payments

Fawry stands apart because of Pay at Fawry, where the customer receives a reference number and pays in cash at a Fawry point. That changes the order lifecycle, because an order can sit unpaid for hours or days.

The charge request

Public integration guides describe a charge request carrying merchantCode, merchantRefNum (your reference), customerMobile, customerEmail, amount with two decimals, currencyCode, language, chargeItems with itemId, description, price and quantity, a paymentMethod such as PAYATFAWRY or CARD, a description, and a signature. Optional fields include customerProfileId, customerName and an orderWebHookUrl. For card payments, the guides add card details, a returnUrl, an enable3DS flag, and options for card tokens and bank instalment plans.

The signature is a SHA-256 hash of merchantCode, merchantRefNum, customerProfileId (an empty string when absent), paymentMethod, amount formatted with two decimals, and your secure key, concatenated in that order. The status inquiry uses a similar hash of merchantCode, merchantRefNumber and the secure key. Because the signature depends on exact string formatting, an amount sent as 250 in one place and 250.00 in another produces a different hash. Centralise the formatting in one function.

Statuses and notifications

The documented order statuses include NEW, PAID, EXPIRED, CANCELED, REFUNDED and FAILED. Fawry sends a server-to-server HTTP POST to a configured endpoint whenever status changes, and the per-order webhook option covers events such as paid, expired and refund. For Pay at Fawry, your system must handle the unpaid-then-expired path cleanly: release reserved stock or booking slots when the reference expires, and tell the customer clearly how long the reference stays valid.

Fawry in WooCommerce and Laravel

For WooCommerce, confirm with Fawry which plugin or integration package they currently support for your version. Third-party plugins exist, and the quality varies, so review any plugin that handles money as carefully as you would review code you wrote yourself. In Laravel, wrap the charge, the signature builder and the webhook handler in one service, store merchantRefNum and the Fawry reference number against your payment record, and write a scheduled job that checks the status of orders that remain unpaid past an expected window, using the status inquiry as a safety net for missed notifications.

InstaPay and manual transfers: build the process, not just the instructions

Many Egyptian merchants accept InstaPay transfers directly: the customer sends money to the merchant’s payment address, then sends proof. There is no gateway callback in this model, which means no automatic proof of payment. We are not describing an API here, because the manual route does not have one. What you can build is a controlled process around it.

  • Create the order with a unique short reference and show it prominently, with the exact amount and the payment address, on the thank-you page and in the confirmation email.
  • Give the order a dedicated status, such as awaiting transfer, so it does not look like a paid order or a failed one.
  • Let the customer submit the transfer reference or a screenshot through a form tied to the order, instead of through scattered chat messages.
  • Match the incoming transfer to the order in your bank app or statement, then change the status manually, and record who approved it and when.
  • Set an expiry. After a defined period, cancel the order and release stock automatically, with a reminder before it happens.
  • Reconcile daily. Compare the list of orders marked paid by transfer against the actual bank movements.

Manual transfer is acceptable for low volume and for B2B customers who prefer to pay by bank. It does not scale well, and it is the payment path where mistakes and disputes concentrate. If volume grows, move the common cases to a gateway method and keep the transfer path as an exception.

The rules that apply to every integration

Idempotency

Gateways can deliver the same notification more than once, and customers can refresh the return page. Your handler must be safe to run twice: look up the payment by your reference, check the current state, and only transition from pending to paid once. A unique database constraint on the gateway transaction ID prevents duplicates when two requests arrive at the same moment.

Amount and currency checks

When a notification arrives, compare the amount and currency against the order in your database. A valid signature proves the message came from the gateway. It does not prove the amount matches what you expected for that order. Reject and flag any mismatch.

Order state design

Define states explicitly: pending payment, awaiting transfer, paid, failed, expired, refunded, partially refunded. Decide which transitions are allowed. A refunded order should never return to paid because a late notification arrived out of sequence.

Secrets and logging

API keys and HMAC secrets belong in environment configuration, not in the repository, not in theme files and not in the database in plain text on a shared admin screen. Log every notification with its raw payload, the verification result and the action taken, but never log full card details, and mask what you do not need. When something goes wrong at three in the morning, those logs are what let you answer a customer in minutes.

Refunds and reconciliation

Plan refunds before launch. Know whether your gateway supports partial refunds, which payment methods can be refunded through the API, and which require contacting the provider. Fawry’s cash-based references, for example, are described in public guides as needing support involvement for refunds. Then reconcile settlements: compare what the gateway reports as settled against your order totals on a fixed schedule, so fees, chargebacks and failed payouts are visible early.

Egyptian pound and display currency

If you show prices in dollars or euros to international visitors but settle in EGP, decide where conversion happens, who sets the rate, and what the customer sees on the receipt. Mismatched displayed and charged amounts trigger disputes and chargebacks.

A test plan you can run before going live

Use the gateway’s sandbox and test cards, and run a fixed checklist rather than a single happy-path purchase.

  • A successful payment, with the order moving to paid only after the verified notification.
  • A declined payment, and a customer who abandons the hosted page.
  • A customer who closes the browser after paying and never returns to your site.
  • The same notification sent twice, and two notifications arriving out of order.
  • A notification with a wrong signature, which must be rejected and logged.
  • A notification with a correct signature but a different amount.
  • A refund, partial and full, through the route your provider supports.
  • An expired cash reference or an unpaid transfer reaching its expiry.
  • The switch from test keys to live keys, followed by one small real transaction that you refund.

Choosing between the three

A practical way to decide is to score each provider against your own constraints instead of a general ranking. List the payment methods your customers use and confirm each is enabled on your merchant account. Check the checkout type your store runs and whether a maintained plugin exists for it. Look at the documented callback and verification model, and ask what the provider offers for refunds, instalments and reconciliation reports. Ask about settlement timing and the contract terms in writing. A cash-heavy audience points toward Fawry, a store that wants a plugin-led setup with a managed hosted page points toward Kashier, and a team building a custom Laravel flow that wants API control often finds Paymob’s intention model convenient. Those are starting points to test, not rules, and some merchants run two gateways so that a failure at one does not stop sales.

When the project involves a custom checkout, a booking engine or a portal, the integration is part of the system design from day one, not an add-on at the end. If you want an architecture review of an existing checkout, or a build that treats payments as a first-class module with verified callbacks, logging and reconciliation, our team can scope it with you, starting from the order states and the failure cases rather than from the brand of the gateway.

Share:
Free Website Review

Send us your website and we will tell you what is holding it back on Google and with visitors.

Free, with no obligation. We only look at your public pages, so you do not need to share any logins.

What does the review cover?
Report language

The report reaches you on WhatsApp within two working days

Planning Your Next Website Project?

Tell us about your goals. We'll review your requirements, recommend the right approach and send a clear quotation. We reply within one business day.