Paymob Integration Skill for AI Agents

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, a standard skill folder for Replit GitHub import, and a portable prompt (universal-prompt.md) + AGENTS.md for Cursor, Windsurf, GitHub Copilot, Gemini, and other agents. Replit guidance is checked against official documentation; a successful Replit import and payment flow must be verified in the user's project.

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. Agents with skill-install support → ask them to install the skill

For agents that support fetching and installing skills, paste this:

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

Install behavior depends on the host. The documented standalone install locations are:

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.

Verify the installation. Ask the agent to read the installed SKILL.md and one task-specific reference. Reload/start a fresh session if that host requires it. Replit's GitHub import is described below; merely pasting a URL into chat does not prove the skill was installed or loaded.

Two things this path deliberately does not do:

• It doesn't register the Paymob MCP server or install Claude slash commands. The selected folder contains only the skill and its references/metadata; the repository-root commands and MCP configuration are separate. Use the full Claude plugin for those, or configure optional MCP separately per Live access. MCP is not required to implement the app's checkout backend.
• 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. Replit → import the skill from GitHub

1. In Replit Agent, select + → Use a skill → Add from GitHub.
2. Paste https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration.
3. Select Preview skills, select paymob-integration, then Import.
4. Select the imported skill and ask Agent to read its SKILL.md, references/replit.md, and the reference matching your backend. A preview only checks structure; verify the agent can actually read the supporting files.

The skill adds guidance; it does not add Paymob to Replit's built-in payment connector catalog or connect MCP. If the payment picker offers Stripe/Whop, ask Agent to inspect whether a custom external API integration is permitted rather than assuming a missing catalog entry prohibits it. Respect an enforced host restriction and preserve the user's provider choice.

See Replit setup and troubleshooting for project-level installation, Secrets, callback URLs, and a verification prompt. This route is documentation-verified, not an end-to-end Replit payment certification.

4. Lovable → import the tested workspace skill

<a href="https://docs.lovable.dev/features/skills"><img src="https://lovable.dev/favicon.ico" alt="Lovable" width="18" height="18"></a> 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.

5. Cursor → install from the Cursor Directory

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

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

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

First inspect any existing project rules. If the project has no AGENTS.md, download this repo's entrypoint into the project root:

# run this from your project's root folder
test ! -e AGENTS.md && curl -fL https://raw.githubusercontent.com/PaymobAccept/Paymob-AI-Integration-Skill/main/AGENTS.md -o AGENTS.md

• Already have an AGENTS.md? Merge the relevant Paymob routing/rules into it under a ## Paymob heading; never overwrite the project's own instructions. In Replit, preserve the project-root replit.md too.
• Now ask your agent in plain English — "Add Paymob card payments to my checkout" — and it follows the Paymob rules automatically.

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

1. Open universal-prompt.md and copy the whole file.
2. Provide it as project context or an attached instruction file. Use a system/custom-instruction field only if its size limit accepts the whole file; do not truncate payment or security rules to fit.
3. Describe what you're building. It's fully self-contained — no other files needed.

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

9. 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.
• Guided test payments — the agent stops to offer a test payment, shows only the sandbox details for the methods you enabled, and explains how to test your integration type (custom web, Pixel, mobile, Shopify test mode, plugin Test Mode, Payment Links).
• Public webhook URL help — explains why localhost never receives callbacks and offers hooks.paymob.com to inspect callbacks live, or a tunnel/deployed URL to test your handler.
• Capabilities menu — ask "what can you do?" and get a short list of what fits your platform, plus a one-line next step after each milestone.
• Complete Intention API knowledge — the only official payment-creation flow, with Unified Checkout (redirect) and the Pixel SDK (embedded), plus no-code Payment Links.
• Native Mobile SDK flow — iOS / Android / Flutter / React Native, keeping the Secret Key off the device.
• Stack-specific adaptation templates — Node.js/TypeScript/NestJS, Python/Django/Flask/FastAPI, PHP/Laravel, .NET/C#, Ruby/Rails, and React/Next.js/Vue. Reuse your framework bootstrap and implement the required durable persistence adapters; the skill is not a runnable application by itself.
• 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.
• Post-integration management — Paymob's go-live stages and a merchant-side go-live checklist, go-live document upload, day-to-day Dashboard operations (transactions, orders, links, users & roles), refunds in ops, balances and disputes, monitoring and daily reconciliation, key rotation, and plugin/SDK updates.
• Diagnose & get support — routes each symptom to the right Paymob tool (Code Lab, HMAC Signature Troubleshooter, Postman export, Virtual Showroom, Store Check, Mobe, hooks.paymob.com) and drafts a redacted support ticket for the wizard's Contact Support form, [email protected], or the MCP server.
• Live-doc discipline — points at Paymob's llms.txt index, developer docs, Integration Wizard (Code Lab, Store Check, Mobe, Contact Support), 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, /paymob-check-hmac, /paymob-go-live-check, and /paymob-support-ticket for sandbox credentials, error lookups, a webhook HMAC audit, a go-live readiness audit, and a redacted support-ticket draft. 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.

Examples:

/paymob-test-cards wallet
/paymob-explain-error 401 on intention create
/paymob-explain-error HMAC mismatch
/paymob-check-hmac src/webhooks/paymob.ts
/paymob-go-live-check src/payments
/paymob-support-ticket card payments failing since this morning in live

Installation

Skill upload (Claude.ai / ChatGPT / Lovable)

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

paymob-integration.zip

Check the release tag against the version badge above. The latest published release can lag main; importing a GitHub folder reads the selected source ref, while a release download reads that tagged snapshot. After maintainers merge an update, publish the matching version tag before advertising the release ZIP as current. Existing installations should be updated/re-imported deliberately, not assumed to follow main automatically.

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
    ├── LICENSE
    ├── 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 an agent with skill-install support

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

Standalone skill paths are documented for OpenAI Codex (~/.codex/skills/paymob-integration) and Claude Code (~/.claude/skills/paymob-integration/). The folder-only install does not include repository-root slash commands or MCP setup; use the full Claude plugin for those. Verify file access and reload/start a fresh session if required by the host.

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.

Replit

Use the GitHub import steps above. For a project-level filesystem install, copy the complete skills/paymob-integration folder into .agents/skills/paymob-integration/, retaining SKILL.md, agents/, and every reference file. Workspace-managed imports may expose a host-provided location instead. Preserve existing skills and project rules. Replit requires no new plugin manifest or root-level duplicate SKILL.md for the standard folder import.

Check installation first:

Use the imported paymob-integration skill. Read SKILL.md, references/replit.md,
and the backend reference matching this project. Report which files you read
and whether this app has a backend. Do not request credentials or modify the app yet.

Then request implementation:

I want Paymob for this app. Check whether a custom external API integration is
permitted here, separately from the built-in connector catalog. Follow the skill's
custom web/API route using the existing backend and durable database, Replit Secrets,
and a reachable HTTPS callback URL. Confirm country, account status, methods, and
test credentials first. Missing credentials permit scaffolding and mocked tests only.
If an enforced host restriction blocks Paymob, explain the exact blocker and supported
next step; do not bypass it or substitute another provider without my choice.

Full agent instructions: references/replit.md. MCP is optional; importing the skill does not authenticate a Paymob account. Review published-app secrets and APP_URL separately from the test workspace. Replit documentation sources and the distinction between structural checks and host runtime testing are listed in that reference.

Want the MCP account tools too? Add Paymob MCP to Replit, then confirm the connection in Replit. This documented install link contains only the public endpoint, not credentials. Manual setup and secure-authentication limitations are in references/mcp-server.md.

You can start both steps with one request:

Set up the Paymob integration skill from
https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration
and connect Paymob MCP at https://mcp.paymob.com/mcp using Replit's supported setup flow.
Verify skill/reference loading and MCP tool discovery separately. If settings require
my action, show me the import steps and Add to Replit link. Guide secure test-account
authentication without requesting keys in chat. Report which steps succeeded or remain
blocked. Do not create payments, move money, or deploy as part of setup.

This is a combined setup request, not an automatically authenticated single-command install. Replit may still require import/connection confirmation and merchant authentication; the Paymob MCP connection has not been runtime-tested here.

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 available 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"
• "Are we ready to go live with Paymob?"
• "Help me open a Paymob support ticket for a missing callback"
• "My WooCommerce Paymob payments broke after an update"

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.4.1)
├── .claude-plugin/
│   ├── plugin.json                    # Claude Code plugin manifest (v3.4.1)
│   └── 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
│   ├── paymob-go-live-check.md        # /paymob-go-live-check — go-live readiness audit
│   └── paymob-support-ticket.md       # /paymob-support-ticket — redacted ticket draft + channel routing
├── skills/
│   └── paymob-integration/
│       ├── SKILL.md                   # Workflow backbone + multi-agent safety
│       ├── agents/
│       │   └── openai.yaml            # Codex UI, invocation, and MCP metadata
│       └── references/
│           ├── replit.md              # Replit import verification, host restrictions, Secrets, callback setup
│           ├── 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
│           ├── testing-guide.md       # Test checkpoint + how to test each integration type
│           ├── advanced-features.md   # Subscriptions, saved cards (CIT/MIT), Auth/Cap, refund/void, split, fees
│           ├── post-integration.md    # Go-live, Dashboard ops, monitoring, diagnostics tools, support tickets, key rotation
│           ├── live-resources.md      # llms.txt, dev docs, Integration Wizard (Code Lab, Store Check, Mobe, support), community, hooks.paymob.com
│           ├── 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

Supported regions

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 (post-integration and Integration Wizard coverage checked September 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, Code Lab, HMAC Signature Troubleshooter, Store Check, Mobe, Contact Support, go-live documents) — https://wizard.paymob.com/
• 🩺 Store Check (WordPress/WooCommerce store diagnostics) — https://wizard.paymob.com/store-doctor/
• 🪝 Webhook inspector (see callbacks live, test only) — https://hooks.paymob.com
• 💬 Community forum — https://community.paymob.com/
• ✉️ Support — [email protected]

Contributing

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

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

License

MIT — see LICENSE for details.