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, 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-readablellms.txtdoc 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 inreferences/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.