paymob-integration

Paymob Integration Skill for AI Agents

Lovable

Claude.ai / ChatGPT / Lovable skill upload: Download paymob-integration.zip — do not use GitHub's Code → Download ZIP.

Give any AI coding agent expert, workflow-driven knowledge of the Paymob payment gateway across Egypt, UAE, KSA, and Oman. The agent routes the developer by platform, walks through onboarding, and produces correct, copy-ready code for accepting cards, mobile wallets, BNPLs, Apple Pay, Google Pay, kiosk, and bank installments — on any tech stack.

Ships as a native Codex/ChatGPT plugin, a Claude Code/Cowork plugin, a tested Lovable workspace skill, and a portable prompt (universal-prompt.md) + AGENTS.md for Cursor, Windsurf, GitHub Copilot, Gemini, and other agents.

Where it's listed. Published on the Cursor Directory. Not yet listed in Anthropic's plugin directory, OpenAI's, or Lovable's marketplace, and the Paymob MCP server is not yet in a vendor connector registry — so if you search one of those for "Paymob" and find nothing, that's expected rather than a mistake on your end. No listing is required either way: every method below installs straight from this repo (or its release ZIP), and the Claude Code path registers this repo as a custom marketplace.

---

Works with any AI agent

It's all plain Markdown — any AI assistant can use it. Find your tool below; most setups take a single step.

Using an “Upload skill” screen? Do not upload GitHub's full repository ZIP. Build or download the dedicated paymob-integration.zip described under Skill upload; it contains one top-level skill folder and leaves every plugin/editor entry point unchanged.

1. Any AI agent → just ask it to install the skill (easiest, recommended)

No CLI, no downloads, no config files. Paste this to your agent:

Install the Paymob integration skill from https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration

The agent fetches the skill and puts it wherever its own convention expects. Tested on both:

Agent	What you get
OpenAI Codex	Uses its $skill-installer; installs to ~/.codex/skills/paymob-integration
Claude Code	Installs as a personal skill in ~/.claude/skills/paymob-integration/, plus the three slash commands in ~/.claude/commands/

Keep the /tree/main/skills/paymob-integration part of the URL. The repository root is a multi-agent plugin package, not a standalone skill directory — an agent pointed at the bare root can install the wrong tree.

Then start a fresh session. Skills and commands are read at session start, so they won't show up in the session that installed them. This is the most common reason people think the install failed.

Two things this path deliberately does not do:

• It doesn't register the Paymob MCP server, so there's no live account access (payment links, transactions, balances, settlements). Agents leave it out on purpose — it's a persistent config change pointing at a live financial service. To get it, use the Claude Code plugin install (item 8 below), which bundles it, or add it yourself per Live access.
• It doesn't namespace the skill. Install it this way and as a plugin and you'll have two paymob-integration skills with identical descriptions; disable one to clear the ambiguity.

2. OpenAI Codex → install the standalone skill

Ask Codex:

Use $skill-installer to install https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration

Targeting the skills/paymob-integration subdirectory is required; the repository root is a multi-agent plugin package, not a standalone skill directory. The standalone skill includes all references. Add the optional live Paymob server separately with codex mcp add paymob --url https://mcp.paymob.com/mcp.

3. Lovable → import the tested workspace skill

Tested successfully with Lovable Workspace Skills.

1. Download paymob-integration.zip. Keep the file zipped.
2. In your Lovable workspace, open Settings → Skills.
3. Click Import, choose the ZIP tab, and upload paymob-integration.zip.
4. Open Paymob Integration and leave Automatic use enabled, or invoke it explicitly from chat with /paymob-integration.
5. The skill is shared with every project in the workspace. To disable it for one project only, use Project settings → Skills.

You need a workspace owner, admin, or editor role to import a custom skill. Although Lovable also supports public GitHub imports, use the release ZIP for this repository: Lovable accepts SKILL.md only at the repository root or inside one wrapping folder, while this multi-agent plugin intentionally keeps it at skills/paymob-integration/SKILL.md.

4. Cursor → install from the Cursor Directory

Listed at cursor.directory/plugins/paymob-integration. Open the listing and use Add to Cursor on the component you want:

Component	What it gives you
Skill paymob-integration	The full integration guidance
MCP Server paymob	Live account access — payment links, transactions, balances, settlements
Commands ×3	/paymob-test-cards, /paymob-explain-error, /paymob-check-hmac

The three commands read the skill's reference files at run time, so install the Skill component alongside them — on its own, a command will correctly refuse to answer rather than guess at a field order it cannot read.

5. Coding agents → drop in AGENTS.md

AGENTS.md is an open standard that coding agents read automatically from your project's root folder. Natively supported by OpenAI Codex, Cursor, GitHub Copilot, Windsurf, Gemini CLI, Aider, Zed, Jules, Devin, Factory, Amp, RooCode, Warp, JetBrains Junie, and more.

One step — copy this repo's AGENTS.md into the root of your project:

# run this from your project's root folder
curl -O https://raw.githubusercontent.com/PaymobAccept/Paymob-AI-Integration-Skill/main/AGENTS.md

• Already have an AGENTS.md? Just paste this one's contents into it under a ## Paymob heading.
• Now ask your agent in plain English — "Add Paymob card payments to my checkout" — and it follows the Paymob rules automatically.

6. Chat assistants (ChatGPT · Gemini · Claude.ai · Copilot Chat …) → paste universal-prompt.md

1. Open universal-prompt.md and copy the whole file.
2. Paste it into the assistant's system prompt / custom instructions (ChatGPT: Settings → Personalization → Custom instructions; Gemini: a Gem; Claude.ai: a Project's instructions).
3. Describe what you're building. It's fully self-contained — no other files needed.

7. Prefer a pinned editor rules file? (optional)

If you'd rather use your editor's native rules file instead of AGENTS.md, save universal-prompt.md as:

Tool	Save it as (in your project)
Cursor	.cursor/rules/paymob.mdc
Windsurf / Devin Desktop	.windsurf/rules/paymob.md
GitHub Copilot	.github/copilot-instructions.md
Cline · Continue · Roo	the tool's rules / context file

8. Claude Code / Cowork → install the full plugin

Pick this over item 1 when you want the bundled live Paymob MCP server (see below) and namespaced plugin commands. Add this repository as a marketplace, then install the plugin:

claude plugin marketplace add PaymobAccept/Paymob-AI-Integration-Skill
claude plugin install paymob-integration@paymob

A shell claude plugin install doesn't take effect in a session that's already running — run /reload-plugins in that session, or restart, before the skill and its commands appear.

Cowork and local-development options are under Installation.

One source of truth, no drift: the full skill lives in skills/paymob-integration/; universal-prompt.md is its self-contained portable copy; AGENTS.md is a short router to it.

---

What it does

When you ask the agent for help integrating Paymob, it provides:

• Platform routing first — detects Shopify, an official e-commerce plugin platform (WooCommerce, Magento, Odoo, OpenCart, PrestaShop, …), or a custom build, and steers you to the fastest correct path instead of hand-coding when a prebuilt integration already exists.
• Guided onboarding — merchant-status check, dashboard credential collection, and sandbox-first testing before go-live.
• Complete Intention API knowledge — the only official payment-creation flow, with Unified Checkout (redirect) and the Pixel SDK (embedded).
• Native Mobile SDK flow — iOS / Android / Flutter / React Native, keeping the Secret Key off the device.
• Corrected, copy-ready code in your stack — Node.js/TypeScript/NestJS, Python/Django/Flask/FastAPI, PHP/Laravel, .NET/C#, Ruby/Rails, and React/Next.js/Vue.
• All 3 HMAC types — transaction, card token, and subscription — with exact field orders, SHA-512, and timing-safe comparison.
• Reconciliation — a Transaction Inquiry fallback for callbacks that never arrive, stuck "pending" orders, and admin lookups.
• Core & advanced features — subscriptions, saved cards (CIT/MIT), Auth/Capture, refund/void, split features, convenience fees.
• Live-doc discipline — points at Paymob's llms.txt index, developer docs, Integration Wizard, and community forum so the agent can confirm anything that may have changed.
• Safe multi-agent execution — separates codebase mapping, live-doc verification, and security review while keeping file edits and all live payment actions serialized through one primary agent.
• Slash commands (Claude Code / Cowork) — /paymob-test-cards, /paymob-explain-error, and /paymob-check-hmac for direct access to sandbox credentials, error lookups, and a webhook HMAC audit. See Commands.

---

Live access — Paymob MCP server

Beyond generating code, agents can act on a merchant's real Paymob account through Paymob's official MCP server — creating payment intentions and links, pulling transactions/balances, exporting reports, requesting settlements, and opening support tickets (~25 tools). Great for interactive testing and reconciliation.

This plugin bundles it: the repo ships a root .mcp.json, so enabling the plugin registers the paymob server automatically. To add it to any other MCP client:

{
  "mcpServers": {
    "paymob": { "type": "http", "url": "https://mcp.paymob.com/mcp" }
  }
}

Or in Codex or Claude Code standalone: