/paymob-integration

name: paymob-integration
description: Integrate Paymob payments for web, mobile, Shopify, and backend apps in Egypt, UAE, KSA, and Oman. Use for checkout, Intention API, HMAC webhooks, reconciliation, SDKs, subscriptions, and refunds.

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`. The server is bundled when this skill is installed as a Claude or Codex plugin.

Live Paymob action safety

These rules apply to every authenticated account action, whether the host uses one agent or many:

• Keep credentials and authenticated Paymob tools with the primary agent. Never give secrets or live-tool access to a subagent.
• Before each live write, obtain the user's explicit confirmation for the current account, test/live mode, operation, target, amount, and currency. Do not reuse a broad or earlier approval for a different operation.
• Read the current remote state first. Build a stable operation fingerprint from the account, mode, operation, target, amount, currency, and merchant reference; reuse the same merchant reference/idempotency key for the same intended action.
• Never automatically retry a write after a timeout or ambiguous response. Query Paymob by the reference/fingerprint to learn whether the first request succeeded; retry only after the result is known and the user reconfirms if the action could duplicate or move money.
• After a write, query and report the resulting remote object/status. A successful tool call is not by itself proof of the intended financial outcome.

Multi-agent coordination

For a broad integration or audit, delegate only independent, bounded work when the host supports subagents:

• Have one read-only agent map the merchant's platform, stack, checkout flow, and existing payment code.
• Have one read-only agent verify current Paymob API, SDK, and HMAC details against `references/live-resources.md`.
• Have one security-focused agent review secret handling, webhook verification, idempotency, and reconciliation.
• Keep one primary agent responsible for requirements, final code integration, tests, and the user-facing answer.

By default, subagents receive no Paymob credentials, cannot call authenticated Paymob tools, and return findings only with file/line references. The primary agent owns all final edits, tests, and live actions. If edit delegation is necessary, assign exclusive non-overlapping paths and merge through the primary agent. Never let multiple agents create intentions, payment links, refunds, voids, captures, or settlements against the same account.

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 byp