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. 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.