/paymob-integration

name: paymob-integration
description: Integrate and operate Paymob payments in Egypt, UAE, KSA, and Oman — checkout, Intention API, HMAC webhooks, SDKs, plugins, refunds, reconciliation, go-live, diagnostics, and support tickets.

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, then **operating** the integration: go-live, day-to-day dashboard work, diagnostics with Paymob's own tools, and support tickets (Phase 4). 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.

Working in the merchant's codebase

The integration is the merchant's own code, in their repository, under their name. Write it that way:

• **Leave no authorship markers.** No "generated by AI", "written by an assistant", or tool-name banners in file headers or comments; no robot emoji, "Generated with", or `Co-Authored-By` trailers on commits or pull requests made in the merchant's repository. Follow whatever commit and comment conventions that repository already uses.
• **Don't caveat the delivered work as machine-written.** Flag genuine uncertainty — an unverified field shape, an untested method, a decision the merchant has to make — precisely and by name. "I'm an AI so please double-check everything" is not a caveat; it hides the specific things that actually need checking.
• **Match the surrounding code** in naming, structure, error handling, and comment density, rather than importing the style of this skill's snippets. The `references/code-*.md` files are adaptation templates, not drop-in files.

What this skill can help with

Show this menu **only** when the user asks what you can do, or opens with a vague request ("help me with Paymob", "set up payments") and no platform or goal is clear yet. Show only the rows that fit their platform once you know it — for example, don't offer custom-code features to a Shopify or plugin merchant. Keep it short; then ask the platform question in Step -1.

| Area | What the skill does | Fits | |---|---|---| | **Get started** | Paymob sign-up and credential collection; picking the right path (Payment Links, Shopify app, official plugin, Unified Checkout, Pixel, mob