Paymob integration

Paymob Payment Gateway Integration

This skill guides an AI coding agent (Claude Code, Codex, Replit, Lovable, etc.) through integrating a merchant's project with Paymob, covering Shopify app installation, the Intention API for web/backend (via Unified Checkout), and Mobile SDKs for native iOS/Android/Flutter/React Native apps. Paymob operates in Egypt, UAE, KSA, and Oman.

If the user asked for "a payment gateway" generically (without naming Paymob) for a business in one of these four markets, briefly confirm Paymob is the right fit (or ask if they already have a different provider in mind) before proceeding — don't silently assume.

Stay current. This skill embeds known-good specs as of 2026-06, but Paymob updates endpoints, field orders, and SDK versions independently of this file. Before finalizing code for exact request shapes, HMAC field orders, or SDK method signatures, cross-check the live docs — see Live Paymob resources at the bottom of this file (references/live-resources.md), especially the machine-readable llms.txt doc index. When the embedded spec and the live docs disagree, the live docs win.

Live account access (optional). Paymob also runs an official MCP server (https://mcp.paymob.com/mcp) that lets you act on the merchant's real account from inside the agent — create intentions/payment links, pull transactions/balances, export reports, request settlements — using the merchant's own API credentials. It's ideal for interactive testing and reconciliation, but it does not replace the HMAC-verified webhook as the source of truth for the merchant's app. Connection, authentication, and the full tool list are in references/mcp-server.md. If you're running as the bundled Claude Code plugin, this server is already registered for you.

Step -1 — Check the platform first

Before anything else, find out what the store is built on. If it's not already obvious from context, ask:

"Is your store on Shopify or another e-commerce platform (WooCommerce, Magento, Odoo, …), or is this a custom-built site/app?"

Platform	Go to
Shopify	Shopify path (below) — skip Step 0 and Phases 1–3 entirely; this is app installation, not custom code
Other e-commerce platform with an official Paymob plugin (WooCommerce/WordPress, Magento 2, Odoo, OpenCart, PrestaShop, WHMCS, CS-Cart, ZenCart, Joomla, Laravel-Bagisto, osCommerce, Drupal, Staah)	Prebuilt-plugin path (below) — install Paymob's official plugin instead of hand-coding
Custom-built (Node, Next.js, Django, PHP, mobile app, etc.)	Continue to Step 0 below

Shopify path

Read references/shopify-apps.md in full before responding. In short: Paymob ships as installable Shopify apps, not a custom API integration —

• Paymob - Native Card Checkout (on-site/embedded) — cards only, no wallets/BNPL/installments
• Paymob Accept (off-site/redirect to Unified Checkout) — all Paymob methods
• Sympl and valU (off-site, Egypt only) — standalone BNPL apps, installed separately

Ask which payment methods the merchant wants, recommend the matching app(s) per the reference file, and hand them the install link(s) directly — each install flow handles Paymob onboarding itself, so the merchant doesn't need the standalone onboarding link below. Do not write Intention API, HMAC, or webhook code for a standard Shopify checkout — the apps handle that. Only fall through to the phases below if the merchant is explicitly building a custom/headless checkout (web or mobile app) that intentionally bypasses Shopify's native checkout and these apps.

Prebuilt-plugin path (WooCommerce, Magento, Odoo, and other platforms)

Paymob maintains official plugins/extensions for WooCommerce/WordPress, Magento 2, Odoo, OpenCart, PrestaShop, WHMCS, CS-Cart, ZenCart, Joomla, Laravel-Bagisto, osCommerce, Drupal, and Staah. If the merchant is on one of these, the fastest correct path is to install and configure Paymob's official plugin for that platform — it already handles Intention creation, Unified Checkout, callbacks, and HMAC. Do not hand-write Intention API / HMAC / webhook code for a standard checkout on these platforms.

• Point the merchant to the plugin for their platform (search "Paymob {platform}" in that platform's marketplace/extension directory, or use the developer docs in references/live-resources.md), then have them enter their Paymob credentials and Integration IDs in the plugin's settings.
• Only fall through to Step 0 and the phases below if the merchant is building a custom/headless checkout that intentionally bypasses the platform's native checkout and its Paymob plugin.

---

Step 0 — Determine merchant status (custom-built stores only)

Before writing any code, ask the merchant/user this single question (don't assume):

"Do you already have a Paymob merchant account with API credentials (API Key, Secret Key, Public Key) and at least one Integration ID? Or do you need to register/onboard first?"

Route based on the answer:

Merchant status	Go to
Not registered with Paymob, or registered but verification/business docs incomplete	Phase 1: Onboarding (below)
Already registered, has credentials and Integration ID(s)	Skip to Step 0.5 (below)

Do not proceed to writing integration code until Phase 1 is confirmed complete (see exit criteria below) — the agent will not have a Secret Key or Integration ID to use otherwise.

---

Phase 1 — Onboarding (new merchants)

Goal: get the merchant a Paymob account, verified business, and live + test credentials.

1. Send the merchant to Paymob's onboarding flow, using the link that matches whichever AI coding agent is running this skill (so Paymob can attribute the signup correctly):

   Running in...	Onboarding link
   Claude (Claude Code, Claude.ai, Cowork)	https://onboarding.paymob.com/auth/country-selection/?partner=claude
   OpenAI Codex	https://onboarding.paymob.com/auth/country-selection/?partner=codex
   Replit Agent	https://onboarding.paymob.com/auth/country-selection/?partner=replit
   Lovable	https://onboarding.paymob.com/auth/country-selection/?partner=lovable
   Any other AI agent / unknown	https://onboarding.paymob.com/auth/country-selection/?partner=aiflow (generic AI-assistant tag)

   Each link starts with the same country-selection step, then walks through business info → document upload (commercial registration / ID, bank account) → choosing payment methods to enable.

   • Fallback link (if the merchant hits an error on their agent-specific link, or is in a region where it doesn't resolve): https://accept.paymob.com/portal2/en/register
   • Self-serve interactive helper: the merchant can also use Paymob's Integration Wizard at https://wizard.paymob.com/ for a guided, personalized roadmap, runnable code samples, and an HMAC/webhook tester (see references/live-resources.md).
   • Document verification can take up to ~3 business days. They'll get an email when it's done.

2. While waiting, the agent can still scaffold the codebase (env var placeholders, route stubs, DB schema for orders) — just don't hardcode real keys yet.

3. Wait/checkpoint: ask the merchant to confirm they've received the "verification complete" email before continuing, OR confirm they already have test-mode credentials (test credentials are often available immediately, even before full live verification — ask the merchant to check Dashboard → Settings → API Keys).

4. Once verified, instruct the merchant to collect these from the Paymob Dashboard:

   • API Key, Secret Key, Public Key, HMAC Secret — Dashboard → Settings → API Keys (click "View" to reveal each)
   • Integration ID(s) — Dashboard → Settings → Payment Integrations (one ID per payment method, e.g. Cards, Wallets, Kiosk; each has a Test and Live version)
   • Note: every account starts in Test mode. Switch the toggle in the dashboard top-left to Live only after the integration is tested end-to-end (see Phase 3).

5. Tell the merchant to store these as environment variables (never hardcode):

   PAYMOB_SECRET_KEY=
   PAYMOB_PUBLIC_KEY=
   PAYMOB_API_KEY=
   PAYMOB_HMAC_SECRET=
   PAYMOB_INTEGRATION_ID_CARD=
   # add one var per enabled payment method (wallet, kiosk, etc.)
   

   (PAYMOB_API_KEY is only needed for the Transaction Inquiry / reconciliation flow — see references/transaction-inquiry.md.)

Exit criteria for Phase 1: merchant has Secret Key, Public Key, HMAC Secret, and at least one Integration ID (Test mode is enough to proceed). Then continue below.

---

Step 0.5 — Web/API or Mobile App?

Before moving to integration, find out what the merchant is building, if not already obvious:

"Is this for a website/backend (API integration) or a native mobile app (iOS/Android/Flutter/React Native)?"

Target	Go to
Website, backend, headless storefront	Phase 2A: Web/API Integration (below)
Native mobile app	Phase 2B: Mobile SDK Integration (below)

Both branches share the same Phase 1 onboarding and the same Phase 3 testing — only the checkout-launch step differs.

---

Phase 2A — Web/API Integration (Intention API + Unified Checkout)

Read references/intention-api.md for the full request/response spec, field names, and error handling before writing code. Then use the stack-specific code reference that matches the merchant's backend (clean, copy-ready, correct interpolation and auth headers):

Stack	Reference file
Node.js / TypeScript / Express / NestJS	references/code-nodejs.md
Python / Django / Flask / FastAPI	references/code-python.md
PHP / Laravel	references/code-php.md
.NET / C# / ASP.NET	references/code-dotnet.md
Ruby / Rails	references/code-ruby.md
Frontend (React / Next.js / Vue / Unified Checkout redirect)	references/code-frontend.md

Key shape of the flow:

1. Ask the merchant which payment methods to support (Cards, Mobile Wallets, Apple/Google Pay, BNPL, Kiosk) if not already specified — each needs its own Integration ID from Phase 1 step 4.
2. Backend: Create a Payment Intention — POST to the Intention endpoint with amount (in cents), currency, the Integration ID(s), items, billing_data, and your notification_url / redirection_url. Returns a client_secret. Send your own order id as special_reference so you can correlate the callback later.
3. Frontend: Launch checkout — redirect the customer to Paymob's Unified Checkout: https://{base_url}/unifiedcheckout/?publicKey={PUBLIC_KEY}&clientSecret={client_secret} (e.g. https://accept.paymob.com/unifiedcheckout/?publicKey=pk_test_...&clientSecret=csk_test_... for Egypt). See references/intention-api.md for the full breakdown and per-region base URLs.
4. Customer pays — Paymob handles card entry, 3D Secure, wallet OTP, etc. You don't touch raw card data.
5. Backend: Handle the callback (webhook) — Paymob POSTs the full transaction result to your notification_url. This callback, not the redirect, is the source of truth for payment status. Read references/hmac-verification.md and implement HMAC verification before trusting any callback data — reject/ignore any callback whose computed HMAC doesn't match.
6. Update order state based on the verified success field, idempotently (key on order.id / special_reference), and only then trigger fulfillment.
7. Add a Transaction Inquiry fallback. Don't rely on the callback alone — read references/transaction-inquiry.md and add a way for the merchant's backend to actively pull a transaction/order's status. Use it for: orders stuck "pending" past an expected window, a periodic reconciliation job, and support/admin lookups. This uses a different auth flow (API Key → short-lived auth token) than the Intention API's Secret Key.

Always implement HMAC verification — never mark an order paid based on the redirect URL alone, since redirect parameters are not authenticated.

For subscriptions, saved cards (CIT/MIT), Auth/Capture, refunds/void, split payments, or convenience fees, see references/advanced-features.md.

---

Phase 2B — Mobile SDK Integration (iOS / Android / Flutter / React Native)

Read references/mobile-sdks.md in full before writing code — the backend half (Intention creation, callbacks, HMAC) is identical to Phase 2A (reuse the same references/code-*.md backend code), but the checkout UI is presented natively in-app via Paymob's SDK instead of a browser redirect. Key shape of the flow:

1. Ask which payment methods to support, same as the web flow.
2. Backend: Create a Payment Intention — identical request to Phase 2A. Always create it from your backend (using the Secret Key) — never from inside the mobile app, so the Secret Key never ships in the app binary.
3. Mobile app: Initialize the SDK with the client_secret returned from your backend.
4. Mobile app: Present checkout — ask the merchant whether they want Normal (Hosted) Checkout (SDK shows Paymob's full screen) or Embedded Checkout (SDK renders inside a view in the merchant's own screen).
5. Backend: Handle the callback (webhook) — same as Phase 2A: HMAC-verify it (references/hmac-verification.md) and treat it as the source of truth.
6. Mobile app: Handle the SDK result — use this only to update the UI (success/failure screen); never to confirm payment or trigger fulfillment, since it isn't independently authenticated the way the backend callback is.
7. Add a Transaction Inquiry fallback, same as Phase 2A (references/transaction-inquiry.md).
8. Pull current SDK setup details (package name, install method, init code) from the platform-specific SDK docs before writing app code — don't guess method signatures, since they're versioned independently of this skill (see references/live-resources.md).

Set the expectation that Mobile SDK integration takes longer (days–weeks) and is more technical than the web/Unified Checkout path (days).

---

Phase 3 — Test the integration

Before going live, validate the whole flow in sandbox using Paymob's test credentials:

1. Confirm the merchant is using Test mode keys/Integration IDs (status must match between Secret Key and Integration ID, or you'll get a 404).
2. Run through: create intention → checkout → pay with a test card → confirm callback fires → confirm HMAC verifies → confirm order updates.
3. Use the test cards and wallet numbers in references/test-credentials.md to simulate success scenarios (decline/error simulation isn't officially documented by Paymob — confirm with the merchant if they need failure-path testing, and note that sandbox test data expires after 30 days).
4. Have the merchant inspect the raw callback payload (log it) the first time, to confirm field names match what the code expects, then verify the HMAC matches manually against references/hmac-verification.md if anything looks off. The Integration Wizard's HMAC validator / webhook tester (https://wizard.paymob.com/) is handy for confirming your HMAC logic in isolation.
5. Also exercise the Transaction Inquiry fallback (references/transaction-inquiry.md) during testing — generate an auth token, then look up the test transaction you just made by transaction ID/order ID, and confirm the merchant system can reconcile correctly if a callback were ever missed.
6. For Mobile SDK integrations (Phase 2B): run through the same test cards inside the SDK's native checkout UI, on both a real device and simulator/emulator if possible, and confirm the backend callback (not just the SDK's in-app result) is what your test asserts on.
7. Only after a full successful test run should the merchant flip Dashboard to Live mode and swap in live keys/Integration IDs (same code, same base URL — only the keys/IDs change).

---

Troubleshooting

Symptom	Likely cause / fix
401 Unauthorized on intention create	Wrong/expired Secret Key, or Authorization header missing the literal word Token (it's Token <key>, not Bearer)
404 "Integration ID does not exist"	Test/Live mismatch between Secret Key and Integration ID, wrong region base URL, or ID not on this account
400 missing field	billing_data.phone_number missing, or an items entry missing name/amount
HMAC mismatch	Wrong secret, wrong field order, or SHA-256 used instead of SHA-512; POST uses obj.id/obj.order.id, GET redirect uses id/order_id
Amount wrong by 100x	Amount must be in cents/piasters (10000 = 100.00 EGP)
Checkout not rendering	Wrong publicKey (must be Public Key, not Secret) or stale/reused client_secret (it's single-use)
Order stuck "pending"	Callback never arrived — use the Transaction Inquiry fallback (references/transaction-inquiry.md)
Need a human / deeper help	Paymob developer community forum (https://community.paymob.com/) or [email protected] — see references/live-resources.md

---

Reference files

Integration paths & security (verbatim, current as of 2026-06):

• references/shopify-apps.md — Paymob's Shopify apps (on-site, off-site, Sympl, valU), install links, which to recommend when
• references/intention-api.md — Create Intention endpoint, request/response fields, Unified Checkout redirect, common errors
• references/mobile-sdks.md — Native mobile SDK flow (iOS/Android/Flutter/React Native), Hosted vs Embedded checkout, backend callback vs SDK result
• references/hmac-verification.md — Callback payload, exact field order for HMAC, SHA-512 calculation, worked example
• references/transaction-inquiry.md — Pull-based status checks (by order ID, transaction ID, or merchant order ID), reconciliation jobs, auth-token flow
• references/test-credentials.md — Sandbox test cards, wallet numbers, OTPs

Ready-to-use code (corrected, copy-ready):

• references/code-nodejs.md — Node.js / TypeScript / Express / NestJS
• references/code-python.md — Python / Django / Flask / FastAPI
• references/code-php.md — PHP / Laravel
• references/code-dotnet.md — .NET / C# / ASP.NET
• references/code-ruby.md — Ruby / Rails
• references/code-frontend.md — React / Next.js / Vue / Unified Checkout redirect

Advanced & live resources:

• references/advanced-features.md — Subscriptions, saved cards (CIT/MIT), Auth/Capture, refund/void/capture, split payments, convenience fees
• references/live-resources.md — Live Paymob developer resources: llms.txt doc index, developer docs, Integration Wizard, community forum — and exactly when/how the agent should use each
• references/mcp-server.md — Official Paymob MCP server: how to connect (plugin/CLI/.mcp.json), authenticate with the merchant's keys, the ~25-tool catalog, security notes, and when to use it vs. the code references

---

Live Paymob resources (always-current)

When you need authoritative, current details that may have changed since this skill was packaged, use these (full details and usage rules in references/live-resources.md):

• llms.txt doc index — https://developers.paymob.com/paymob-docs/getting-started/overview/llms.txt — machine-readable map of all Paymob docs. Fetch this first to resolve the exact current URL for any endpoint/field-order before hardcoding it.
• Developer docs — https://developers.paymob.com/ — the authoritative API reference.
• Integration Wizard — https://wizard.paymob.com/ — interactive roadmap, runnable code samples, HMAC validator + webhook tester, and an AI assistant ("Mobe"). Point the merchant here for self-serve help and for debugging HMAC/webhooks.
• Community forum — https://community.paymob.com/ — Discourse Q&A for troubleshooting and escalation.
• MCP server — https://mcp.paymob.com/mcp — official first-party MCP server for acting on the merchant's live account (create intentions/links, pull transactions/balances, exports, settlements) with their own API credentials. Full setup and tool catalog in references/mcp-server.md.

Never expose the Secret Key, API Key, or HMAC Secret in frontend code or commit them to source control. Only the Public Key is safe client-side.