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.

Download paymob-integration.zip. Keep the file zipped.
In your Lovable workspace, open Settings → Skills.
Click Import, choose the ZIP tab, and upload paymob-integration.zip.
Open Paymob Integration and leave Automatic use enabled, or invoke it explicitly from chat with /paymob-integration.
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`

Open universal-prompt.md and copy the whole file.
Paste it into the assistant's system prompt / custom instructions (ChatGPT: Settings → Personalization → Custom instructions; Gemini: a Gem; Claude.ai: a Project's instructions).
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:

codex mcp add paymob --url https://mcp.paymob.com/mcp
claude mcp add --transport http paymob https://mcp.paymob.com/mcp

You authenticate in-session with your own Paymob API credentials (test mode first — it includes money-movement tools). It complements, but does not replace, the HMAC-verified webhook as the source of truth. Full setup, the tool catalog, and security notes: references/mcp-server.md.

Commands (Claude Code / Cowork)

Once the plugin is installed, these slash commands give direct access to the most common lookups without asking the agent to find the right reference file on its own. Each command reads from the same reference files the skill itself uses — there is no separate copy of the test cards, error table, or HMAC spec to drift out of sync.

Command	What it does
`/paymob-test-cards [card\|wallet\|kiosk\|bnpl]`	Prints sandbox test cards, wallet numbers, and OTPs from `references/test-credentials.md`, optionally filtered to one method. Always notes the 30-day sandbox expiry and that decline/error simulation isn't officially documented. For kiosk and BNPL it reports that sandbox can't test them at all, rather than offering a card as a stand-in.
`/paymob-explain-error <code, status, or message>`	Looks up a Paymob error against the Troubleshooting table in `SKILL.md`, explains the cause, and — for code fixes — pulls the corrected snippet from the matching `references/code-*.md` file for your stack. Falls back to `references/live-resources.md` for anything not in the table instead of guessing.
`/paymob-check-hmac [path]`	Statically audits your webhook HMAC verification against `references/hmac-verification.md`: SHA-512 (not SHA-256), exact field order, `body.obj` sourcing, no `obj.id`/`obj.order.id` mix-up, fail-closed behavior, and unique-constraint-backed idempotency. Never asks you to paste your HMAC secret or API key; only invoked manually, never automatically.

Examples:

/paymob-test-cards wallet
/paymob-explain-error 401 on intention create
/paymob-explain-error HMAC mismatch
/paymob-check-hmac src/webhooks/paymob.ts

Installation

Skill upload (Claude.ai / ChatGPT / Lovable)

Recommended: download the permanent release asset and upload it directly—do not extract it:

paymob-integration.zip

GitHub's Code → Download ZIP file is the full multi-agent plugin repository, so its canonical SKILL.md is intentionally nested at skills/paymob-integration/SKILL.md. That source archive is for cloning and plugin installation, not skill-upload screens.

To build the same upload package from a local checkout:

python scripts/package_skill.py

Then upload dist/paymob-integration.zip. Its structure is:

paymob-integration.zip
└── paymob-integration/
    ├── SKILL.md
    ├── agents/
    └── references/

paymob-integration/ is the ZIP's single top-level folder, so SKILL.md is not nested behind the repository folder and skills/. Pull-request CI also publishes this file as the paymob-integration-skill-upload workflow artifact for pre-release testing; extract an Actions artifact once, then upload the contained paymob-integration.zip.

This packaging step only copies the canonical skill into an ignored dist/ archive. It does not move or duplicate tracked source, so Codex, Claude Code/Cowork plugins, Cursor, Windsurf, Copilot, and other AGENTS.md consumers keep their existing installation paths.

A root-level copy, symlink, or shortcut to SKILL.md is intentionally not used: upload services may not follow links, while a copied file would create a second source of truth that can drift.

Ask your AI agent (any agent, no CLI)

Paste this to the agent you already use:

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

Verified on OpenAI Codex (installs via $skill-installer to ~/.codex/skills/paymob-integration) and Claude Code (installs as a personal skill in ~/.claude/skills/paymob-integration/ plus the slash commands in ~/.claude/commands/). Start a fresh session afterwards — skills and commands are read at session start.

Keep the /tree/main/skills/paymob-integration subdirectory in the URL; the repository root is a multi-agent plugin package, not a standalone skill directory. This path installs the skill only — it does not register the Paymob MCP server, so use the plugin install below if you want live account access.

OpenAI Codex (standalone skill)

In a Codex task, ask:

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

This repository also contains a valid .codex-plugin/plugin.json for marketplace packaging. During plugin development, validate the repository first and install it through a configured local marketplace; Codex CLI plugins are installed from marketplace sources.

Claude Code (CLI)

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

The repository's .claude-plugin/marketplace.json makes the GitHub repository a directly installable custom marketplace. To verify a local checkout before publishing, run claude plugin validate ..

Cowork (Desktop)

Add PaymobAccept/Paymob-AI-Integration-Skill as a custom marketplace source, then install Paymob Integration from that marketplace.

Cursor (Cursor Directory)

Listed at cursor.directory/plugins/paymob-integration. Use Add to Cursor on the listing for the skill, the paymob MCP server, and the three commands.

Install the Skill component alongside the commands. Each command resolves the skill's reference files at run time and stops rather than answering from memory if it can't reach them, so a command installed on its own is safe but inert.

Other agents (Windsurf, Copilot, …)

git clone https://github.com/PaymobAccept/Paymob-AI-Integration-Skill.git

Then follow the Works with any AI agent table — copy AGENTS.md or universal-prompt.md into your own project at the location your tool expects.

Local development (Claude Code)

claude --plugin-dir ./Paymob-AI-Integration-Skill

Validate the package before publishing:

python -m pip install -r requirements-dev.txt
python scripts/validate.py

Publishing the upload package (maintainers)

After merging a version change to main, push a tag that exactly matches .codex-plugin/plugin.json:

git tag vX.Y.Z
git push origin vX.Y.Z

The release workflow validates the repository, rebuilds the deterministic ZIP, verifies the tag/version match, and publishes paymob-integration.zip as a permanent GitHub Release asset. Never upload a hand-built archive or add a root SKILL.md copy.

Usage

Once installed, the agent activates on any Paymob request — or even a generic regional payment request ("add a payment gateway to my UAE store"). Try prompts like:

"Help me integrate Paymob card payments in my Next.js app"
"Add Vodafone Cash wallet payments to my Laravel backend"
"My Paymob HMAC validation keeps failing — here's my code..."
"Set up Paymob subscriptions with Python/FastAPI"
"Integrate Apple Pay with Paymob in my React Native app"
"Reconcile a Paymob order that's stuck pending"
"Add Paymob to my Shopify / WooCommerce store"

Repository structure

Paymob-AI-Integration-Skill/
├── AGENTS.md                          # Cross-agent entrypoint (Codex, Aider, Zed, Gemini CLI, …)
├── universal-prompt.md                # Portable prompt (Cursor, Windsurf, Copilot, ChatGPT, Gemini, …)
├── .mcp.json                          # Bundled Paymob MCP server (auto-registers when the plugin is enabled)
├── .codex-plugin/
│   └── plugin.json                    # Codex/ChatGPT plugin manifest (v3.3.0)
├── .claude-plugin/
│   ├── plugin.json                    # Claude Code plugin manifest (v3.3.0)
│   └── marketplace.json               # Claude custom marketplace catalog
├── commands/                          # Claude Code slash commands (additive, Claude-only)
│   ├── paymob-test-cards.md           # /paymob-test-cards — sandbox test cards/wallets
│   ├── paymob-explain-error.md        # /paymob-explain-error — error code → cause + fix
│   └── paymob-check-hmac.md           # /paymob-check-hmac — static HMAC verification audit
├── skills/
│   └── paymob-integration/
│       ├── SKILL.md                   # Workflow backbone + multi-agent safety
│       ├── agents/
│       │   └── openai.yaml            # Codex UI, invocation, and MCP metadata
│       └── references/
│           ├── shopify-apps.md        # Paymob Shopify apps (on-site / off-site / BNPL) + install path
│           ├── intention-api.md       # Create Intention spec, Unified Checkout, common errors
│           ├── mobile-sdks.md         # Native SDK flow (iOS / Android / Flutter / React Native)
│           ├── hmac-verification.md   # Transaction HMAC: field order, SHA-512, worked example
│           ├── transaction-inquiry.md # Pull-based status checks / reconciliation
│           ├── test-credentials.md    # Sandbox cards, wallets, OTPs
│           ├── advanced-features.md   # Subscriptions, saved cards (CIT/MIT), Auth/Cap, refund/void, split, fees
│           ├── live-resources.md      # llms.txt, dev docs, Integration Wizard, community — when/how to use
│           ├── mcp-server.md          # Official Paymob MCP server: connect, authenticate, tool catalog, security
│           ├── code-nodejs.md         # Node.js / TypeScript / Express / NestJS
│           ├── code-python.md         # Python / Django / Flask / FastAPI
│           ├── code-php.md            # PHP / Laravel
│           ├── code-dotnet.md         # .NET / C# / ASP.NET
│           ├── code-ruby.md           # Ruby / Rails
│           └── code-frontend.md       # React / Next.js / Vue + Unified Checkout / Pixel SDK
├── .gitignore                         # Excludes generated archives and Python caches
├── requirements-dev.txt               # PyYAML dependency for schema validation
├── scripts/
│   ├── package_skill.py               # Deterministic skill-only upload ZIP builder
│   └── validate.py                    # Cross-platform package and archive validation
├── LICENSE
└── README.md

Payment methods covered

Method	Regions	Notes
Cards (Visa, MC, Amex, MADA, OmanNet)	EGY, KSA, UAE, OMN	3DS, MOTO, Card-on-File, Auth/Cap
Mobile Wallets (Vodafone Cash, Orange Cash, e& money, WePay, StcPay)	EGY, KSA	—
BNPLs (Valu, Tabby, Tamara, Souhoola, Sympl, and more)	EGY, KSA, UAE	15+ providers
Apple Pay	EGY, KSA, UAE, OMN	Requires certificates
Google Pay	KSA, UAE, OMN	Not yet in Egypt
Bank Installments	EGY	Live IDs only
Kiosk (Aman, Masary)	EGY	No refund support

Supported regions

Region	Base URL
Egypt (EGY)	`https://accept.paymob.com`
Oman (OMN)	`https://oman.paymob.com`
Saudi Arabia (KSA)	`https://ksa.paymob.com`
UAE	`https://uae.paymob.com`

Security

Only the Public Key (pk_*) is safe in frontend code. The Secret Key, API Key, and HMAC Secret are server-side only — never commit them or ship them in a mobile binary.
The HMAC-verified webhook callback is the source of truth for payment status — never the browser redirect params or a mobile SDK result.
Always verify HMAC with SHA-512 and a timing-safe comparison, and process callbacks atomically: unique obj.id, compare-and-set order state, and a uniquely keyed transactional outbox; use order.id / special_reference only for correlation.

Staying current

Specs embedded here are known-good as of June 2026. Paymob changes endpoints, field orders, and SDK versions on its own schedule — the skill instructs the agent to cross-check the live docs (references/live-resources.md, especially the machine-readable llms.txt index) and lets the live docs win on any disagreement.

Support & resources

📚 Developer docs — https://developers.paymob.com/
🧭 Integration Wizard (roadmap, runnable samples, HMAC/webhook tester) — https://wizard.paymob.com/
💬 Community forum — https://community.paymob.com/
✉️ Support — support@paymob.com

Contributing

Contributions are welcome! If Paymob releases new APIs or you have improvements for a specific tech stack:

Fork this repo
Create a branch (git checkout -b feature/add-go-support)
Edit the relevant reference file (or add a new one) — keep SKILL.md, universal-prompt.md, and AGENTS.md in sync
Submit a pull request

License

MIT — see LICENSE for details.

Navigation Menu

Uh oh!

Repository files navigation

Paymob Integration Skill for AI Agents

Works with any AI agent

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

2. OpenAI Codex → install the standalone skill

3. Lovable → import the tested workspace skill

4. Cursor → install from the Cursor Directory

5. Coding agents → drop in `AGENTS.md`

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

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

8. Claude Code / Cowork → install the full plugin

What it does

Live access — Paymob MCP server

Commands (Claude Code / Cowork)

Installation

Skill upload (Claude.ai / ChatGPT / Lovable)

Ask your AI agent (any agent, no CLI)

OpenAI Codex (standalone skill)

Claude Code (CLI)

Cowork (Desktop)

Cursor (Cursor Directory)

Other agents (Windsurf, Copilot, …)

Local development (Claude Code)

Publishing the upload package (maintainers)

Usage

Repository structure

Payment methods covered

Supported regions

Security

Staying current

Support & resources

Contributing

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
commands		commands
scripts		scripts
skills/paymob-integration		skills/paymob-integration
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
requirements-dev.txt		requirements-dev.txt
universal-prompt.md		universal-prompt.md

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Paymob Integration Skill for AI Agents

Works with any AI agent

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

2. OpenAI Codex → install the standalone skill

3. Lovable → import the tested workspace skill

4. Cursor → install from the Cursor Directory

5. Coding agents → drop in AGENTS.md

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

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

8. Claude Code / Cowork → install the full plugin

What it does

Live access — Paymob MCP server

Commands (Claude Code / Cowork)

Installation

Skill upload (Claude.ai / ChatGPT / Lovable)

Ask your AI agent (any agent, no CLI)

OpenAI Codex (standalone skill)

Claude Code (CLI)

Cowork (Desktop)

Cursor (Cursor Directory)

Other agents (Windsurf, Copilot, …)

Local development (Claude Code)

Publishing the upload package (maintainers)

Usage

Repository structure

Payment methods covered

Supported regions

Security

Staying current

Support & resources

Contributing

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

5. Coding agents → drop in `AGENTS.md`

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