From d4118d203b9e7cd8c9d6f706c666d9c753078d7d Mon Sep 17 00:00:00 2001 From: MRagabMob Date: Wed, 23 Sep 2026 19:19:52 +0300 Subject: [PATCH 1/3] Add webhook URL, testing guide, and Pixel update to references (BBK-2/3/4) Part 1 of 3 (references). notification_url works for all methods + reachability section; new testing-guide.md; Shopify test mode; Wizard/Store Check/hooks.paymob.com in live-resources; Pixel sample rewritten from current docs. --- .../references/code-frontend.md | 78 +++++++++++++++---- .../references/intention-api.md | 14 +++- .../references/live-resources.md | 50 +++++++++--- .../references/shopify-apps.md | 3 +- .../references/test-credentials.md | 2 + .../references/testing-guide.md | 68 ++++++++++++++++ 6 files changed, 189 insertions(+), 26 deletions(-) create mode 100644 skills/paymob-integration/references/testing-guide.md diff --git a/skills/paymob-integration/references/code-frontend.md b/skills/paymob-integration/references/code-frontend.md index d7f6da3..9570b78 100644 --- a/skills/paymob-integration/references/code-frontend.md +++ b/skills/paymob-integration/references/code-frontend.md @@ -91,28 +91,78 @@ function PaymentComplete() { ## Option B — Embedded Pixel SDK (checkout inside your page) -When you want the payment form embedded rather than a full redirect. You still create the Intention on the backend and pass the `client_secret` + Public Key to the SDK. +Source: https://developers.paymob.com/paymob-docs/developers/checkout-experiences/pixel-embedded (last updated by Paymob: September 7, 2026) + +Use Pixel when the merchant wants the payment form embedded in their own page (or a WebView) instead of a redirect. Pixel supports **card**, **Google Pay**, and **Apple Pay**. Everything else stays the same: the backend creates the Intention, the frontend gets only the Public Key and the `client_secret`, and payment status still comes from the HMAC-verified callback. ```html - -
- + +
+ + + ``` -> The embedded SDK's exact script URL, init options, and callback names are versioned by Paymob and can change. Pull the current embed snippet from `developers.paymob.com` (or the Integration Wizard's code lab) rather than relying on this sample verbatim — see `live-resources.md`. +Key options (full list in the docs above): + +| Option / hook | What it does | +|---|---| +| `publicKey`, `clientSecret` | From your backend. `client_secret` is unique per order and expires in an hour | +| `paymentMethods` | Any of `"card"`, `"google-pay"`, `"apple-pay"` | +| `elementId` | ID of the element Pixel renders into | +| `disablePay` | `true` hides Pixel's own Pay button; dispatch the `payFromOutside` event to pay | +| `showSaveCard` / `forceSaveCard` | Offer card saving / save without asking | +| `cardValidationChanged(isValid)` | Fires when card validity changes — use it to enable your own button | +| `beforePaymentComplete` / `afterPaymentComplete(response)` | Your logic before / after Paymob processes the payment (after = UI only) | +| `onPaymentCancel` | Apple Pay only — customer closed the Apple Pay sheet | +| `updateIntentionData` | Refresh Pixel after the intention changes (backend calls the Intention Update API) | +| `customStyle` | Fonts, colors, sizes, spacing, and Arabic/RTL text | + +> **Check before shipping.** Paymob's own sample loads `paymob-pixel@latest` from jsDelivr. For production, consider pinning a specific version so a new release can't change the checkout unexpectedly, and re-check the option names against the doc page above. Paymob's docs sample puts the Secret Key in the page for testing only — never do that; the Secret Key stays on the backend. ## Per-region base URL diff --git a/skills/paymob-integration/references/intention-api.md b/skills/paymob-integration/references/intention-api.md index f4b4bc7..c0cd68e 100644 --- a/skills/paymob-integration/references/intention-api.md +++ b/skills/paymob-integration/references/intention-api.md @@ -31,7 +31,7 @@ Header: `Authorization: Token ` (note the literal word "Token", not | `extras` | object | no | Arbitrary custom merchant data; echoed back in callbacks under the payment `claims` object | | `special_reference` | string | no | Your own internal order ID — returned in the transaction callback as `merchant_order_id`. Use this to correlate orders | | `expiration` | number | no | Intention expiry in seconds | -| `notification_url` | string | no | Your webhook endpoint — receives the POST callback with full transaction details. **Card Integration IDs only** | +| `notification_url` | string | no | Your webhook endpoint — receives the POST callback with full transaction details. Works for **all payment methods** (cards, wallets, kiosk, BNPL, …). Must be a **publicly reachable HTTPS URL** — Paymob cannot call `localhost` (see *Making `notification_url` reachable* below) | | `redirection_url` | string | no | Where the customer is redirected after payment, with transaction details as query params. **Card and Wallet methods only**. Not authenticated — don't trust it for order state | ### Example request @@ -116,3 +116,15 @@ Fix: always populate `billing_data.phone_number`. ## After payment: callbacks are the source of truth Paymob sends a `notification_url` POST with full transaction details once the payment is processed (success or fail), and separately redirects the customer via `redirection_url`. **Always treat the callback as authoritative and verify its HMAC before updating order state** (see `hmac-verification.md`) — the redirect is for UX only and its query params are not signed/verifiable the same way. + +## Making `notification_url` reachable + +Paymob's servers POST to `notification_url` from the internet, so the URL must be public HTTPS. A `localhost`, `127.0.0.1`, LAN, or VPN-only address silently never receives the callback — the checkout succeeds, but the order stays pending. Pick the option that matches what you're doing: + +| Goal | Use as `notification_url` | Notes | +|---|---|---| +| **See the raw callback** (payload shape, `hmac` query param, redirect params) | `https://hooks.paymob.com/` — Paymob's own webhook inspector | The user opens `https://hooks.paymob.com`, copies the unique Hook URL it shows, and pastes it back to the agent (the agent cannot generate one). It shows POST, GET, and PUT requests live, so it also works as `redirection_url`. **No retention** — keep the page open while the test payment runs, or the request is not seen. Paste the captured payload into the Integration Wizard's HMAC checker (`https://wizard.paymob.com/`) to confirm the HMAC logic. | +| **Test the merchant's own webhook handler end to end** | A tunnel to the local server (e.g. `ngrok http 3000`, `cloudflared tunnel --url http://localhost:3000`) or a deployed preview URL | Hosted builders (Replit, Lovable, Vercel/Netlify previews) already expose a public HTTPS URL — use it. Tunnel URLs usually change on restart; update `notification_url` when they do. | +| **Live** | The merchant's own production HTTPS endpoint | Never leave a hooks.paymob.com or tunnel URL in live config. | + +hooks.paymob.com **only displays** requests — it does not forward them to the merchant's server, so their HMAC verification and order-update code never runs. Seeing a callback there proves Paymob sends it; it does **not** complete Phase 3 testing, which needs the merchant's own handler to receive, verify, and process the callback. diff --git a/skills/paymob-integration/references/live-resources.md b/skills/paymob-integration/references/live-resources.md index 10b4668..90f26e6 100644 --- a/skills/paymob-integration/references/live-resources.md +++ b/skills/paymob-integration/references/live-resources.md @@ -1,6 +1,6 @@ # Live Paymob Resources — what each is, and when/how to use it -This skill embeds known-good specs, but Paymob changes endpoints, HMAC field orders, and SDK versions on its own schedule. These four live resources let the coding agent (and the merchant) stay current. **When an embedded spec in this skill disagrees with the live docs, the live docs win.** +This skill embeds known-good specs, but Paymob changes endpoints, HMAC field orders, and SDK versions on its own schedule. These live resources let the coding agent (and the merchant) stay current. **When an embedded spec in this skill disagrees with the live docs, the live docs win.** --- @@ -33,19 +33,33 @@ This skill embeds known-good specs, but Paymob changes endpoints, HMAC field ord --- -## 3. Integration Wizard — interactive roadmap + code lab + tester + AI assistant +## 3. Integration Wizard — roadmap, code lab, sandbox tools, Store Check, AI assistant **URL:** `https://wizard.paymob.com/` -**What it is:** an interactive, AI-guided onboarding tool that: -- generates a **personalized integration roadmap** from the merchant's business type, platform, tech stack, and market; -- provides a **code laboratory** with tabbed, runnable SDK code samples and developer utilities — notably an **HMAC signature validator**, a **webhook tester**, and linting; -- includes an **AI assistant ("Mobe")** for real-time integration Q&A; -- offers **support ticket submission** for deeper help. +**What it is:** Paymob's interactive onboarding planner for merchants and developers. It: +- builds a **personalized setup guide** from the merchant's country, account status (no account / partial credentials / ready), platform (Shopify, WooCommerce, Magento 2, other plugins, custom web, mobile app, or no-code Payment Links), tech stack, and payment methods; +- covers every integration path, including **Unified Checkout** (redirect), **Pixel** (embedded in the merchant's page), **Payment Links** (no code), plugins, and mobile SDKs; +- provides a **code lab** with runnable samples, a **Test Cards** tab, a sandbox **Payment Links** creator, and a **"Pay with test card"** demo that creates a payment matching the chosen path and mode (with a Test/Live switch); +- includes an **HMAC checker**: paste the received `hmac`, the full webhook payload JSON, and the HMAC secret — the diagnosis runs entirely in the browser; +- includes **Store Check** (see below); +- has an AI assistant ("Mobe") and support ticket submission. + +### Store Check (WooCommerce / WordPress) + +Store Check audits a live storefront's Paymob setup: +- **Public scan** — enter the store's website address; no login needed. +- **Connected check** — deeper diagnosis of gateway settings and orders. Needs the **Paymob Wizard Connector** WordPress plugin: + 1. Download it from `https://wizard.paymob.com/store-doctor/downloads/paymob-wizard-connector.zip`. + 2. In wp-admin: **Plugins → Add New → Upload Plugin**, upload the zip, and activate it. + 3. Open Store Check from the **Paymob Wizard** menu in WordPress, or sign in on the wizard with the store URL and WordPress username. No WordPress application password is needed, and none is ever put in a URL. + +The Wizard Connector is a **standalone helper** for diagnosis. It is **not** the Paymob WooCommerce payment plugin and does not process payments — the merchant still needs the official Paymob payment plugin installed and configured. Don't confuse the two when giving install steps. **How the agent should use it:** - **Point the merchant here for self-serve onboarding** and a tailored roadmap (complements Phase 1 in `SKILL.md`). -- **For debugging HMAC/webhook issues**, recommend the Wizard's HMAC validator and webhook tester — the merchant can confirm in isolation that their computed signature matches Paymob's before suspecting their app code (see Phase 3 testing). +- **For HMAC/webhook debugging**, recommend the HMAC checker — the merchant can confirm in isolation that their computed signature matches before suspecting their app code. Pair it with `https://hooks.paymob.com` (section 5) to capture a real payload first. +- **For WooCommerce merchants**, suggest Store Check after the payment plugin is configured (see `testing-guide.md`). - It is a **human-facing interactive tool**, not a programmatic API — don't try to script it. Hand the merchant the link and tell them what to do there. **How to wire it into code:** not a code dependency. It is a complementary tool for the human in the loop. @@ -66,13 +80,29 @@ This skill embeds known-good specs, but Paymob changes endpoints, HMAC field ord --- +## 5. Webhook inspector — hooks.paymob.com + +**URL:** `https://hooks.paymob.com` + +**What it is:** Paymob's webhook tester. Opening the page gives the visitor a unique Hook URL (`https://hooks.paymob.com/`) and shows every POST, GET, or PUT sent to it as it arrives. Paymob-operated, safe to recommend publicly, and it keeps **no data** — requests appear only while the page is open. + +**How the agent should use it:** +- When the merchant is developing locally and has no public URL yet, or wants to see the exact callback Paymob sends, suggest it as the intention's `notification_url` (and optionally `redirection_url`) in **test mode**. +- The agent cannot create the Hook URL itself — ask the user to open the page, copy the Hook URL, and paste it back. Tell them to keep the tab open while the test payment runs. +- It only **displays** requests; it does not forward them. For an end-to-end test of the merchant's own handler, use a tunnel or deployed URL — see *Making `notification_url` reachable* in `intention-api.md`. + +**How to wire it into code:** never. It's a test-time inspection aid; never ship it as a production `notification_url`. + +--- + ## Summary: include in the skill, not in the merchant's runtime | Resource | Role | Used by | In production app's code? | |---|---|---|---| | `llms.txt` | Doc index for the agent | Coding agent (authoring) | No | | developer docs | Authoritative spec | Coding agent (authoring) | No | -| Integration Wizard | Roadmap, code lab, HMAC/webhook tester, AI assistant | Merchant (human) | No | +| Integration Wizard | Roadmap, code lab, sandbox tools, HMAC checker, Store Check, AI assistant | Merchant (human) | No | | Community forum | Q&A / escalation | Merchant (human) | No | +| hooks.paymob.com | Live webhook inspector (test mode) | Merchant (human) | No — never as a production `notification_url` | -All four are **authoring- and support-time aids**, not runtime services the integration calls. The only Paymob endpoints the merchant's app actually calls are the Intention API, the Unified Checkout URL / Mobile SDK, the webhook callback you expose, and (optionally) the Transaction Inquiry API. +All of these are **authoring-, testing-, and support-time aids**, not runtime services the integration calls. The only Paymob endpoints the merchant's app actually calls are the Intention API, the Unified Checkout URL / Mobile SDK, the webhook callback you expose, and (optionally) the Transaction Inquiry API. diff --git a/skills/paymob-integration/references/shopify-apps.md b/skills/paymob-integration/references/shopify-apps.md index b1574d3..3b1fcc1 100644 --- a/skills/paymob-integration/references/shopify-apps.md +++ b/skills/paymob-integration/references/shopify-apps.md @@ -27,7 +27,8 @@ Since this is app installation, not code integration, your job is to: 1. Confirm which app(s) fit the merchant's needs (above). 2. Give them the exact install link(s) — these go through Shopify's own login/redirect flow straight to the alternative-payment-providers settings page for that specific app, so just hand the merchant the link; there's nothing to build. 3. Tell them: installing the app starts the **Paymob merchant onboarding flow as part of the install process** — they do not need to separately complete the standalone web onboarding flow (the `onboarding.paymob.com` link) when going the Shopify route. The app's own setup screens collect the business/verification info needed. -4. After installation, remind them to check in **Shopify Admin → Settings → Payments** that the new provider shows as active, and to verify it's in the correct mode (test vs live, if the app exposes that toggle) before going live. +4. After installation, remind them to check in **Shopify Admin → Settings → Payments** that the new provider shows as active. + **Test before going live:** the Paymob Shopify app has a **test mode** button in its settings. Have the merchant turn it on, place a storefront order paid with the sandbox test details for their enabled methods (see `testing-guide.md` — card numbers come only from `test-credentials.md`), confirm the order shows as paid in Shopify admin and the transaction appears in the Paymob dashboard, then **turn test mode off** before real customers check out. 5. There is no HMAC verification, callback handling, or Intention API code for the merchant to write in this path — Shopify and the Paymob app handle the payment flow and order status updates internally. Do not write custom webhook/HMAC code for a Shopify store going through these apps — only suggest custom Intention API code (Phase 2 in the main skill) if the merchant explicitly wants a fully custom backend instead of these apps (uncommon for a standard Shopify store). 6. If the merchant wants to combine more than one app (e.g. Paymob Accept + valU + Sympl), just walk them through installing each — there's no extra glue code required between them; Shopify lists each as an independent payment option at checkout. diff --git a/skills/paymob-integration/references/test-credentials.md b/skills/paymob-integration/references/test-credentials.md index 8230c8b..7ab60e9 100644 --- a/skills/paymob-integration/references/test-credentials.md +++ b/skills/paymob-integration/references/test-credentials.md @@ -52,6 +52,8 @@ What that means in practice: ## Using them +For **when** to prompt a test payment, **which** of these to show for the merchant's enabled methods, and **how** to test each integration type (custom web, Pixel, mobile SDK, Shopify, WooCommerce and other plugins, Payment Links), see `testing-guide.md`. + 1. Make sure the Integration ID used in the Intention request is the **Test** version of the relevant payment method (Cards or Wallets), and that the Secret Key used is also Test mode — mismatched modes cause a 404 on intention creation (see `intention-api.md`). 2. Go through the real checkout flow (Unified Checkout redirect) and enter the test card / wallet details above as if you were the customer. 3. Confirm: diff --git a/skills/paymob-integration/references/testing-guide.md b/skills/paymob-integration/references/testing-guide.md new file mode 100644 index 0000000..be41dee --- /dev/null +++ b/skills/paymob-integration/references/testing-guide.md @@ -0,0 +1,68 @@ +# Testing Guide — prompt for a test payment, show the right test details + +This file tells the agent **when** to stop and ask for a test payment, **which** test details to show, and **how** to test each integration type. The test card and wallet numbers themselves live only in `test-credentials.md` — read that file and copy from it. Never list test numbers from memory. + +## 1. The test checkpoint + +Run this checkpoint once the integration is set up — after the code is written (custom builds), after the plugin or app is configured (Shopify / WooCommerce / other plugins), or after the first Payment Link is created. Don't skip it and don't bury it in a long summary. + +1. Ask the user directly: **"Ready to run a test payment?"** +2. Confirm test mode is on for their integration type (section 3). +3. Show **only** the test details for the payment methods they enabled (section 2), copied from `test-credentials.md`. +4. Tell them what a passing test looks like for their integration type (section 3), then wait for the result. +5. If it fails, go to Troubleshooting in `SKILL.md`, or use `/paymob-explain-error` / `/paymob-check-hmac` where available. + +Always carry over the two caveats from `test-credentials.md`: sandbox data expires after **30 days**, and Paymob publishes no decline-simulation cards. + +## 2. Which test details to show + +| Enabled method | What to show | +|---|---| +| Cards | The Mastercard and Visa test cards from `test-credentials.md` | +| Mobile wallets | The test wallet number, MPIN, and OTP from `test-credentials.md` | +| Kiosk, BNPL (Valu, Souhoola, Tabby, Tamara, Sympl, …) | The **no sandbox test path** message from `test-credentials.md`. Say the card test covers the shared integration code, and list the first-live-transaction checks from Phase 3 step 7 in `SKILL.md`. Don't substitute a test card and call the method tested. | +| Apple Pay, Google Pay, bank installments | Say sandbox support isn't confirmed in this skill, and point to `support@paymob.com` or the live docs. Don't invent a test path. | + +If the merchant enabled several methods, show each matching block — and nothing for methods they didn't enable. + +## 3. How to test each integration type + +### Custom web — Unified Checkout (redirect) or Pixel (embedded) + +- **Test mode:** Test Secret Key + Test Public Key + **Test** Integration IDs (mismatched modes → 404 on intention creation). +- **Webhook URL:** `notification_url` must be public HTTPS. To just see the callback, use `https://hooks.paymob.com` (the user opens it and pastes back their Hook URL). To test the merchant's own handler, use a tunnel or deployed preview URL. Details: *Making `notification_url` reachable* in `intention-api.md`. +- **Run:** create an intention → open Unified Checkout (or render Pixel) → pay with the test details from section 2. +- **Passes when:** the merchant's handler receives the POST callback, the HMAC verifies, and the order updates once (a replayed callback changes nothing). Seeing the callback on hooks.paymob.com alone is not a pass. +- Also run a Transaction Inquiry lookup for the test transaction (`transaction-inquiry.md`). + +### Mobile SDK (iOS / Android / Flutter / React Native) + +- Same test mode, webhook URL, and pass criteria as custom web — the backend is identical. +- Pay inside the SDK's native checkout, on a real device and a simulator/emulator if possible. +- Assert on the **backend callback**, not the SDK's in-app result. + +### Shopify (Paymob apps) + +- **Test mode:** turn on the **test mode** button in the Paymob app's settings in Shopify admin, with test credentials. +- **Run:** place an order on the storefront, choose Paymob at checkout, and pay with the test details from section 2. +- **Passes when:** the order shows as paid in Shopify admin and the transaction appears in the Paymob dashboard (Test mode). +- **Before going live:** turn test mode **off**. Leaving it on means real customers can't pay. + +### WooCommerce and other official plugins (Magento 2, Odoo, OpenCart, PrestaShop, …) + +- **Test mode:** in the Paymob plugin's settings, choose the **Test Mode** state and enter the **Test** API Key, Secret Key, Public Key, and **Test** Integration IDs. (In Paymob's plugins, Test Mode is the unpublished state; "Enabled" / Live uses the live keys and charges real money.) +- **Run:** place an order on the store and pay with the test details from section 2. +- **Passes when:** the order status changes to paid/processing in the store admin and the transaction appears in the Paymob dashboard (Test mode). +- **WooCommerce — run Store Check (optional, recommended):** on `https://wizard.paymob.com/`, open Store Check. A public scan needs only the store's address. For a deeper check of gateway settings and orders, install the **Paymob Wizard Connector** plugin from `https://wizard.paymob.com/store-doctor/downloads/paymob-wizard-connector.zip` (wp-admin → Plugins → Add New → Upload Plugin). The connector is a separate diagnostic helper, **not** the Paymob payment plugin. See `live-resources.md` section 3. +- **Before going live:** switch the plugin to the live state and enter live keys and live Integration IDs. + +### Payment Links (no code) + +- **Test mode:** create the link with the Dashboard in **Test** mode and a Test Integration ID, or use the Integration Wizard's sandbox **Payment Links** creator (`https://wizard.paymob.com/`). +- **Run:** open the link and pay with the test details from section 2. The wizard's **"Pay with test card"** button runs the same check in one step. +- **Passes when:** the link shows as paid and the transaction appears in the Dashboard (Test mode). +- For links created through the API, see the QuickLink APIs in the developer docs (`live-resources.md`), and test the webhook exactly as for custom web. + +## 4. After a passing test + +Switch to live using the step for the integration type above (live keys and Integration IDs, plugin live state, Shopify test mode off). For custom builds nothing else changes — same code, same base URL. Then offer the next steps from **What this skill can help with** in `SKILL.md`. From feda5a8d32802540b394223643749cac117ffbe8 Mon Sep 17 00:00:00 2001 From: MRagabMob Date: Wed, 23 Sep 2026 19:21:08 +0300 Subject: [PATCH 2/3] Add capabilities menu, Payment Links path, webhook and test checkpoints to SKILL.md --- skills/paymob-integration/SKILL.md | 63 +++++++++++++++++++++++++----- 1 file changed, 54 insertions(+), 9 deletions(-) diff --git a/skills/paymob-integration/SKILL.md b/skills/paymob-integration/SKILL.md index bff6c94..fd07542 100644 --- a/skills/paymob-integration/SKILL.md +++ b/skills/paymob-integration/SKILL.md @@ -34,16 +34,38 @@ For a broad integration or audit, delegate only independent, bounded work when t By default, subagents receive no Paymob credentials, cannot call authenticated Paymob tools, and return findings only with file/line references. The primary agent owns all final edits, tests, and live actions. If edit delegation is necessary, assign exclusive non-overlapping paths and merge through the primary agent. Never let multiple agents create intentions, payment links, refunds, voids, captures, or settlements against the same account. +## What this skill can help with + +Show this menu **only** when the user asks what you can do, or opens with a vague request ("help me with Paymob", "set up payments") and no platform or goal is clear yet. Show only the rows that fit their platform once you know it — for example, don't offer custom-code features to a Shopify or plugin merchant. Keep it short; then ask the platform question in Step -1. + +| Area | What the skill does | Fits | +|---|---|---| +| **Get started** | Paymob sign-up and credential collection; picking the right path (Payment Links, Shopify app, official plugin, Unified Checkout, Pixel, mobile SDK) | Everyone | +| **Accept payments** | Cards, mobile wallets, Apple Pay, Google Pay, BNPL, kiosk, bank installments — per market | Everyone (method availability varies by region) | +| **No-code** | Payment Links to share by WhatsApp, social, email, SMS, or QR | Merchants without a website or developer | +| **Plugins & Shopify** | Choose and install the right Paymob app/plugin, configure test mode, run Store Check (WooCommerce) | Shopify, WooCommerce, Magento, Odoo, … | +| **Custom checkout** | Intention API with Unified Checkout (redirect) or Pixel (embedded); native mobile SDKs | Custom web, headless, mobile apps | +| **Webhooks & security** | Callback handling, HMAC-SHA512 verification, idempotent order updates, a public test URL for callbacks | Custom builds | +| **Testing** | Sandbox test details per payment method, a guided test payment, go-live checklist | Everyone | +| **After payment** | Refunds, voids, auth/capture, Transaction Inquiry and reconciliation | Custom builds (plugins handle some of this) | +| **Advanced** | Subscriptions, saved cards (CIT/MIT), split payments, convenience fees | Custom builds | +| **Live account tools** | Paymob MCP server: create payment links/intentions, pull transactions and balances, exports, settlements | Any agent with MCP | +| **Quick commands** | `/paymob-test-cards`, `/paymob-explain-error`, `/paymob-check-hmac` | Claude Code / Cowork plugin | +| **Paymob tools** | Integration Wizard (roadmap, code lab, HMAC checker, Store Check), hooks.paymob.com (webhook inspector) | Everyone | + +After a successful first integration or test payment, end with **one line** of relevant next steps from this table (e.g. "Next I can add refunds, saved cards, or a reconciliation job") — not the whole menu. + ## Step -1 — Check the platform first Before anything else, find out **what the store is built on**. If it's not already obvious from context, ask: -> "Is your store on Shopify or another e-commerce platform (WooCommerce, Magento, Odoo, …), or is this a custom-built site/app?" +> "Is your store on Shopify or another e-commerce platform (WooCommerce, Magento, Odoo, …), is this a custom-built site/app, or do you just want to share payment links without a website?" | Platform | Go to | |---|---| | Shopify | **Shopify path** (below) — skip Step 0 and Phases 1–3 entirely; this is app installation, not custom code | | Other e-commerce platform with an official Paymob plugin (WooCommerce/WordPress, Magento 2, Odoo, OpenCart, PrestaShop, WHMCS, CS-Cart, ZenCart, Joomla, Laravel-Bagisto, osCommerce, Drupal, Staah) | **Prebuilt-plugin path** (below) — install Paymob's official plugin instead of hand-coding | +| No website / no developer — wants to get paid by sharing a link | **Payment Links path** (below) | | Custom-built (Node, Next.js, Django, PHP, mobile app, etc.) | Continue to **Step 0** below | ### Shopify path @@ -54,15 +76,27 @@ Read `references/shopify-apps.md` in full before responding. In short: Paymob sh - **Paymob Accept** (off-site/redirect to Unified Checkout) — all Paymob methods - **Sympl** and **valU** (off-site, Egypt only) — standalone BNPL apps, installed separately -Ask which payment methods the merchant wants, recommend the matching app(s) per the reference file, and hand them the install link(s) directly — each install flow handles Paymob onboarding itself, so the merchant doesn't need the standalone onboarding link below. Do not write Intention API, HMAC, or webhook code for a standard Shopify checkout — the apps handle that. Only fall through to the phases below if the merchant is explicitly building a custom/headless checkout (web or mobile app) that intentionally bypasses Shopify's native checkout and these apps. +Ask which payment methods the merchant wants, recommend the matching app(s) per the reference file, and hand them the install link(s) directly — each install flow handles Paymob onboarding itself, so the merchant doesn't need the standalone onboarding link below. After install, run the **test checkpoint** in `references/testing-guide.md`: the merchant turns on the app's **test mode** button, pays a storefront order with the test details for their methods, then turns test mode off before going live. Do not write Intention API, HMAC, or webhook code for a standard Shopify checkout — the apps handle that. Only fall through to the phases below if the merchant is explicitly building a custom/headless checkout (web or mobile app) that intentionally bypasses Shopify's native checkout and these apps. ### Prebuilt-plugin path (WooCommerce, Magento, Odoo, and other platforms) Paymob maintains official plugins/extensions for **WooCommerce/WordPress, Magento 2, Odoo, OpenCart, PrestaShop, WHMCS, CS-Cart, ZenCart, Joomla, Laravel-Bagisto, osCommerce, Drupal, and Staah**. If the merchant is on one of these, the fastest correct path is to install and configure Paymob's official plugin for that platform — it already handles Intention creation, Unified Checkout, callbacks, and HMAC. Do **not** hand-write Intention API / HMAC / webhook code for a standard checkout on these platforms. - Point the merchant to the plugin for their platform (search "Paymob {platform}" in that platform's marketplace/extension directory, or use the developer docs in `references/live-resources.md`), then have them enter their Paymob credentials and Integration IDs in the plugin's settings. +- Once configured, run the **test checkpoint** in `references/testing-guide.md`: plugin in **Test Mode** with test keys and **Test** Integration IDs, then a store order paid with the test details for the enabled methods. +- **WooCommerce:** also suggest **Store Check** on the Integration Wizard (`https://wizard.paymob.com/`). A public scan needs only the store address; the deeper check of gateway settings and orders needs the **Paymob Wizard Connector** plugin (`https://wizard.paymob.com/store-doctor/downloads/paymob-wizard-connector.zip`). The connector is a diagnostic helper — **not** the Paymob payment plugin. Details in `references/live-resources.md`. - Only fall through to **Step 0** and the phases below if the merchant is building a **custom/headless** checkout that intentionally bypasses the platform's native checkout and its Paymob plugin. +### Payment Links path (no code) + +For merchants who just want to get paid without a website or developer (social selling, invoicing): + +- The merchant creates a link in the Paymob Dashboard: **Create → Quick Link**, set amount, currency, reference and image, choose payment methods and their Integration IDs, then share it by QR, WhatsApp, Facebook, Instagram, SMS, or email. Unpaid links can be cancelled. +- If they have no account yet, send them through **Phase 1** onboarding first (the onboarding links work without any code). +- With the Paymob MCP server connected, the agent can also create links on the merchant's account (`references/mcp-server.md`) — the live-action safety rules above apply. +- To generate links from their own system, use Paymob's QuickLink APIs (see the developer docs via `references/live-resources.md`) and handle the callback as in Phase 2A. +- Test before sharing real links: see the Payment Links section of `references/testing-guide.md`. + --- ## Step 0 — Determine merchant status (custom-built stores only) @@ -147,13 +181,16 @@ Read `references/intention-api.md` for the full request/response spec, field nam | PHP / Laravel | `references/code-php.md` | | .NET / C# / ASP.NET | `references/code-dotnet.md` | | Ruby / Rails | `references/code-ruby.md` | -| Frontend (React / Next.js / Vue / Unified Checkout redirect) | `references/code-frontend.md` | +| Frontend (React / Next.js / Vue / Unified Checkout redirect / Pixel embedded) | `references/code-frontend.md` | Key shape of the flow: 1. **Ask the merchant which payment methods to support** (Cards, Mobile Wallets, Apple/Google Pay, BNPL, Kiosk) if not already specified — each needs its own Integration ID from Phase 1 step 4. 2. **Backend: Create a Payment Intention** — `POST` to the Intention endpoint with amount (in cents), currency, the Integration ID(s), items, billing_data, and your `notification_url` / `redirection_url`. Returns a `client_secret`. Send your own order id as `special_reference` so you can correlate the callback later. -3. **Frontend: Launch checkout** — redirect the customer to Paymob's **Unified Checkout**: `https://{base_url}/unifiedcheckout/?publicKey={PUBLIC_KEY}&clientSecret={client_secret}` (e.g. `https://accept.paymob.com/unifiedcheckout/?publicKey=pk_test_...&clientSecret=csk_test_...` for Egypt). See `references/intention-api.md` for the full breakdown and per-region base URLs. + - **`notification_url` must be a public HTTPS URL** — Paymob can't reach `localhost`. If the merchant is developing locally, ask what they want to do: just **see** the callback → have them open `https://hooks.paymob.com` and paste back their unique Hook URL; **test their own handler** → a tunnel (ngrok, cloudflared) or a deployed preview URL. Never leave either in live config. Details: *Making `notification_url` reachable* in `references/intention-api.md`. +3. **Frontend: Launch checkout** — ask whether the merchant wants a redirect or a form embedded in their page: + - **Unified Checkout (redirect, simplest):** `https://{base_url}/unifiedcheckout/?publicKey={PUBLIC_KEY}&clientSecret={client_secret}` (e.g. `https://accept.paymob.com/unifiedcheckout/?publicKey=pk_test_...&clientSecret=csk_test_...` for Egypt). See `references/intention-api.md` for per-region base URLs. + - **Pixel (embedded):** Paymob's checkout component rendered inside the merchant's page — cards, Google Pay, Apple Pay. See Option B in `references/code-frontend.md`. 4. **Customer pays** — Paymob handles card entry, 3D Secure, wallet OTP, etc. You don't touch raw card data. 5. **Backend: Handle the callback (webhook)** — Paymob POSTs the full transaction result to your `notification_url`. **This callback, not the redirect, is the source of truth for payment status.** Read `references/hmac-verification.md` and implement HMAC verification *before* trusting any callback data — reject/ignore any callback whose computed HMAC doesn't match. 6. **Update order state atomically** after HMAC verification: insert `obj.id` under a unique constraint, compare-and-set the order state, and insert a uniquely keyed transactional outbox record in one database transaction. Use `order.id` / `special_reference` only for correlation; only the committed outbox worker triggers fulfillment. @@ -184,12 +221,14 @@ Set the expectation that Mobile SDK integration takes longer (days–weeks) and ## Phase 3 — Test the integration +**Don't skip this checkpoint.** When the code is done, ask the user **"Ready to run a test payment?"**, then follow `references/testing-guide.md`: confirm test mode, show **only** the test details for the payment methods they enabled (copied from `references/test-credentials.md`, never from memory), and say what a passing test looks like. + Before going live, validate the whole flow in sandbox using Paymob's test credentials: 1. Confirm the merchant is using **Test mode** keys/Integration IDs (status must match between Secret Key and Integration ID, or you'll get a 404). 2. Run through: create intention → checkout → pay with a test card → confirm callback fires → confirm HMAC verifies → confirm order updates. 3. Use the test cards and wallet numbers in `references/test-credentials.md` to simulate success scenarios (decline/error simulation isn't officially documented by Paymob — confirm with the merchant if they need failure-path testing, and note that sandbox test data expires after 30 days). -4. Have the merchant inspect the raw callback payload (log it) the first time, to confirm field names match what the code expects, then verify the HMAC matches manually against `references/hmac-verification.md` if anything looks off. The **Integration Wizard's HMAC validator / webhook tester** (`https://wizard.paymob.com/`) is handy for confirming your HMAC logic in isolation. +4. Have the merchant inspect the raw callback payload (log it) the first time, to confirm field names match what the code expects, then verify the HMAC matches manually against `references/hmac-verification.md` if anything looks off. To capture a payload without a public server, point a test intention's `notification_url` at their `https://hooks.paymob.com` Hook URL (keep the page open — nothing is stored), then paste the payload into the **Integration Wizard's HMAC checker** (`https://wizard.paymob.com/`) to confirm the HMAC logic in isolation. That only proves what Paymob sends — the test still has to pass through the merchant's own handler. 5. Also exercise the Transaction Inquiry fallback (`references/transaction-inquiry.md`) during testing — generate an auth token, then look up the test transaction you just made by transaction ID/order ID, and confirm the merchant system can reconcile correctly if a callback were ever missed. 6. **For Mobile SDK integrations (Phase 2B):** run through the same test cards inside the SDK's native checkout UI, on both a real device and simulator/emulator if possible, and confirm the backend callback (not just the SDK's in-app result) is what your test asserts on. 7. **Kiosk and BNPL can't be tested in sandbox at all — don't block go-live on it.** Sandbox has no test path for them (`references/test-credentials.md`). That doesn't hold up launch: every method uses the same Intention API, the same Unified Checkout, and the same callback + HMAC verification, so a passing card test already validates effectively all of the merchant's own integration code. The merchant enables the remaining methods in the Dashboard and goes live. Four things a card test doesn't cover — check each on the **first real transaction** for each newly enabled method, not before: @@ -197,7 +236,8 @@ Before going live, validate the whole flow in sandbox using Paymob's test creden - **Callback field shape** — `references/hmac-verification.md` notes wallets and cards return slightly different nested shapes, and the HMAC concatenation includes the card-shaped `source_data.pan` / `source_data.sub_type` / `source_data.type`. Log the first real callback per method and confirm the computed HMAC still matches. If it doesn't, the callback is rejected and a genuinely paid order never completes — worth five minutes per method. - **Kiosk settles asynchronously** — the customer pays cash at an outlet, so the callback can arrive hours or days after checkout, or never. Expect long-lived pending orders and rely on Transaction Inquiry (`references/transaction-inquiry.md`) instead of treating pending as failed. - **Refunds** — kiosk and most BNPL don't support them (`references/advanced-features.md`), so don't ship a refund path that assumes they do. -8. Once the card flow passes end to end, the merchant can flip Dashboard to **Live mode** and swap in live keys/Integration IDs (same code, same base URL — only the keys/IDs change). +8. Once the card flow passes end to end, the merchant can flip Dashboard to **Live mode** and swap in live keys/Integration IDs (same code, same base URL — only the keys/IDs change). Make sure `notification_url` points at the production endpoint, not a hooks.paymob.com or tunnel URL. +9. Close with **one line** of relevant next steps from **What this skill can help with** (above). --- @@ -212,6 +252,9 @@ Before going live, validate the whole flow in sandbox using Paymob's test creden | Amount wrong by 100x | Amount must be in cents/piasters (10000 = 100.00 EGP) | | Checkout not rendering | Wrong `publicKey` (must be Public Key, not Secret) or stale/reused `client_secret` (it's single-use) | | Order stuck "pending" | Callback never arrived — use the Transaction Inquiry fallback (`references/transaction-inquiry.md`) | +| Callback never arrives while testing locally | `notification_url` is `localhost` or another private address Paymob can't reach — use a hooks.paymob.com Hook URL to see the callback, or a tunnel / deployed URL to test the handler (`references/intention-api.md`) | +| Nothing shows on hooks.paymob.com | The page was closed or reloaded during the payment (it keeps no history), or the intention used a different Hook URL — reopen, copy the current Hook URL, create a fresh intention | +| Plugin/Shopify test order rejects test cards | Plugin not in Test Mode / Shopify app test mode off, or live keys/Integration IDs entered — see `references/testing-guide.md` | | Need a human / deeper help | Paymob developer community forum (`https://community.paymob.com/`) or `support@paymob.com` — see `references/live-resources.md` | --- @@ -225,6 +268,7 @@ Before going live, validate the whole flow in sandbox using Paymob's test creden - `references/hmac-verification.md` — Callback payload, exact field order for HMAC, SHA-512 calculation, worked example - `references/transaction-inquiry.md` — Pull-based status checks (by order ID, transaction ID, or merchant order ID), reconciliation jobs, auth-token flow - `references/test-credentials.md` — Sandbox test cards, wallet numbers, OTPs +- `references/testing-guide.md` — Test checkpoint, which test details to show per payment method, and how to test each integration type (custom web, Pixel, mobile, Shopify, plugins, Payment Links) **Ready-to-use code (corrected, copy-ready):** - `references/code-nodejs.md` — Node.js / TypeScript / Express / NestJS @@ -232,11 +276,11 @@ Before going live, validate the whole flow in sandbox using Paymob's test creden - `references/code-php.md` — PHP / Laravel - `references/code-dotnet.md` — .NET / C# / ASP.NET - `references/code-ruby.md` — Ruby / Rails -- `references/code-frontend.md` — React / Next.js / Vue / Unified Checkout redirect +- `references/code-frontend.md` — React / Next.js / Vue / Unified Checkout redirect / Pixel (embedded) **Advanced & live resources:** - `references/advanced-features.md` — Subscriptions, saved cards (CIT/MIT), Auth/Capture, refund/void/capture, split payments, convenience fees -- `references/live-resources.md` — Live Paymob developer resources: `llms.txt` doc index, developer docs, Integration Wizard, community forum — and exactly when/how the agent should use each +- `references/live-resources.md` — Live Paymob developer resources: `llms.txt` doc index, developer docs, Integration Wizard (incl. Store Check and the Wizard Connector), community forum, hooks.paymob.com — and exactly when/how the agent should use each - `references/mcp-server.md` — Official Paymob **MCP server**: how to connect (plugin/CLI/`.mcp.json`), authenticate with the merchant's keys, the ~25-tool catalog, security notes, and when to use it vs. the code references --- @@ -247,7 +291,8 @@ When you need authoritative, current details that may have changed since this sk - **`llms.txt` doc index** — `https://developers.paymob.com/paymob-docs/getting-started/overview/llms.txt` — machine-readable map of all Paymob docs. Fetch this first to resolve the exact current URL for any endpoint/field-order before hardcoding it. - **Developer docs** — `https://developers.paymob.com/` — the authoritative API reference. -- **Integration Wizard** — `https://wizard.paymob.com/` — interactive roadmap, runnable code samples, HMAC validator + webhook tester, and an AI assistant ("Mobe"). Point the merchant here for self-serve help and for debugging HMAC/webhooks. +- **Integration Wizard** — `https://wizard.paymob.com/` — personalized roadmap, code lab, sandbox Payment Links and "Pay with test card", HMAC checker, **Store Check** for WooCommerce, and an AI assistant ("Mobe"). Point the merchant here for self-serve help and for debugging HMAC/webhooks. +- **Webhook inspector** — `https://hooks.paymob.com` — a unique Hook URL that shows incoming callbacks live (no retention). Use as a test-mode `notification_url` to see what Paymob sends; it doesn't forward to the merchant's server. - **Community forum** — `https://community.paymob.com/` — Discourse Q&A for troubleshooting and escalation. - **MCP server** — `https://mcp.paymob.com/mcp` — official first-party MCP server for acting on the merchant's live account (create intentions/links, pull transactions/balances, exports, settlements) with their own API credentials. Full setup and tool catalog in `references/mcp-server.md`. From 8534fdfb37e7175f1a5bf1d44fdc25ccb964fb3e Mon Sep 17 00:00:00 2001 From: MRagabMob Date: Wed, 23 Sep 2026 19:22:34 +0300 Subject: [PATCH 3/3] Sync universal-prompt, AGENTS, and README with the new guidance --- AGENTS.md | 2 ++ README.md | 13 +++++++---- universal-prompt.md | 56 +++++++++++++++++++++++++++++---------------- 3 files changed, 47 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6864114..c755a5c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,8 @@ For broad integrations or audits, delegate independent read-only tasks such as c 7. **Prefer a prebuilt integration when one exists.** Shopify → a Paymob app; WooCommerce/Magento/Odoo/OpenCart/PrestaShop/… → Paymob's official plugin. Only hand-code for custom/headless checkouts. 8. **Every live write needs current, specific authorization.** Obtain explicit confirmation for the current account, test/live mode, operation, target, amount, and currency; never reuse blanket approval. Read remote state first and keep a stable operation fingerprint/merchant reference. 9. **Never auto-retry an ambiguous financial write.** After a timeout or unclear response, query Paymob to determine whether it succeeded before retrying. Verify and report the remote result after every write. +10. **`notification_url` must be public HTTPS** (it works for all payment methods). Paymob can't reach `localhost`: to just see callbacks, use a `https://hooks.paymob.com` Hook URL (the user opens the page and pastes it back; no retention, display only); to test the handler, use a tunnel or deployed URL. Never ship either as the live URL. +11. **Always offer a test payment before go-live.** Ask "Ready to run a test payment?", confirm test mode (Shopify app test mode button, plugin Test Mode, or test keys + Test Integration IDs), and show only the test details for the enabled methods from `skills/paymob-integration/references/test-credentials.md`. How to test each integration type: `skills/paymob-integration/references/testing-guide.md`. ## Regional base URLs diff --git a/README.md b/README.md index d0aa82b..bd867a8 100644 --- a/README.md +++ b/README.md @@ -135,13 +135,16 @@ 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). +- **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](https://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. - **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. +- **Live-doc discipline** — points at Paymob's `llms.txt` index, developer docs, Integration Wizard (including Store Check for WooCommerce), 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](#commands-claude-code--cowork). @@ -342,8 +345,9 @@ Paymob-AI-Integration-Skill/ │ ├── 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 -│ ├── live-resources.md # llms.txt, dev docs, Integration Wizard, community — when/how to use +│ ├── live-resources.md # llms.txt, dev docs, Integration Wizard, community, hooks.paymob.com — 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 @@ -398,7 +402,8 @@ Specs embedded here are known-good as of **June 2026**. Paymob changes endpoints ## Support & resources - 📚 Developer docs — https://developers.paymob.com/ -- 🧭 Integration Wizard (roadmap, runnable samples, HMAC/webhook tester) — https://wizard.paymob.com/ +- 🧭 Integration Wizard (roadmap, code lab, HMAC checker, Store Check) — https://wizard.paymob.com/ +- 🪝 Webhook inspector (see callbacks live, test only) — https://hooks.paymob.com - 💬 Community forum — https://community.paymob.com/ - ✉️ Support — support@paymob.com diff --git a/universal-prompt.md b/universal-prompt.md index 9369718..25ef37f 100644 --- a/universal-prompt.md +++ b/universal-prompt.md @@ -23,8 +23,11 @@ For broad integrations or audits, delegate independent read-only work such as co Before writing custom code, check the merchant's platform: - **Shopify** → install a Paymob app (Native Card Checkout for on-site cards; Paymob Accept for all methods; Sympl/valU for BNPL in Egypt). Do not hand-code. - **WooCommerce/WordPress, Magento 2, Odoo, OpenCart, PrestaShop, WHMCS, CS-Cart, ZenCart, Joomla, Laravel-Bagisto, osCommerce, Drupal, Staah** → install Paymob's official plugin for that platform and enter credentials in its settings. Do not hand-code. +- **No website / no developer** → Payment Links: Dashboard → **Create → Quick Link**, choose amount, methods and Integration IDs, share by QR/WhatsApp/social/SMS/email. (QuickLink APIs exist for generating links from a system.) - **Custom / headless web, backend, or mobile app** → use the Intention API flow below. +After installing a Shopify app, turn on its **test mode** button, pay a test order, then turn it off before going live. For plugins, set the plugin to **Test Mode** with test keys and **Test** Integration IDs first. WooCommerce merchants can also run **Store Check** on `https://wizard.paymob.com/` (deeper check via the Paymob Wizard Connector plugin: `https://wizard.paymob.com/store-doctor/downloads/paymob-wizard-connector.zip` — a diagnostic helper, not the payment plugin). + ## REGIONAL BASE URLs | Region | Base URL | @@ -87,35 +90,40 @@ Update an intention (e.g. amount changed) with `PUT {base_url}/v1/intention/{cli {base_url}/unifiedcheckout/?publicKey={public_key}&clientSecret={client_secret} ``` -**Pixel SDK (embedded):** +**Pixel SDK (embedded — card, Google Pay, Apple Pay):** ```html - -
- +
+ ``` -The SDK script URL, init options, and callback names are versioned by Paymob — confirm the current embed snippet in the live docs before shipping. +Source: `developers.paymob.com/paymob-docs/developers/checkout-experiences/pixel-embedded`. Consider pinning a version instead of `@latest` for production, and re-check option names against that page before shipping. **Native Mobile SDKs** (iOS/Android/Flutter/React Native): create the intention on the backend (never in the app — keep the Secret Key off the device), pass `client_secret` to the SDK, and present Normal (Hosted) or Embedded checkout. The SDK result is UX only. +## WEBHOOK URL MUST BE PUBLIC + +`notification_url` works for all payment methods and must be a **public HTTPS URL** — Paymob cannot call `localhost`. While developing: +- To **see** the raw callback: the user opens `https://hooks.paymob.com`, copies the unique Hook URL, and uses it as `notification_url` (it also shows GET redirects). It keeps no data — keep the page open during the test. It only displays requests; it doesn't forward them to the merchant's server. +- To **test the merchant's own handler**: a tunnel (`ngrok http 3000`, `cloudflared tunnel --url http://localhost:3000`) or a deployed preview URL. +- In live: only the merchant's production endpoint. + ## WEBHOOK VALIDATION (HMAC-SHA512) There are **3 HMAC types**. Verify the right one for each callback, or verification silently fails. @@ -235,6 +243,8 @@ POST {base_url}/api/acceptance/payments/pay | Wallet MPIN | `123456` | | Wallet OTP | `123456` | +**Test checkpoint:** when the integration is set up, ask "Ready to run a test payment?", confirm test mode, and show only the rows above for the methods the merchant enabled. Kiosk and BNPL have **no sandbox test path** — a card test covers the shared code; check the Integration ID, callback shape, and HMAC on the first real transaction. Sandbox support for Apple Pay, Google Pay, and bank installments isn't confirmed — ask Paymob support. + Sandbox test data expires after 30 days. Paymob does not publish "decline" test cards — ask Paymob support for decline-simulation guidance if needed. Never use real cards in sandbox; switch to live credentials only after a full successful test run. ## COMMON ERRORS @@ -248,6 +258,7 @@ Sandbox test data expires after 30 days. Paymob does not publish "decline" test | Amount off by 100× | Amount not in cents | `Math.round(amount * 100)` | | Checkout not rendering | Wrong `publicKey` (used Secret Key) or stale/reused single-use `client_secret` | Use the Public Key; create a fresh intention | | Subscription HMAC fails | HMAC is in the body, not the query string | Read `hmac` from the request body | +| Callback never arrives locally | `notification_url` is `localhost`/private | Use a hooks.paymob.com Hook URL to see it, or a tunnel/deployed URL to test the handler | ## LIVE ACCOUNT ACCESS — PAYMOB MCP SERVER (optional) @@ -262,6 +273,11 @@ Use it for interactive testing and reconciliation. It complements — but does * When exact endpoints/field orders/SDK versions may have changed, these win over anything above: - `llms.txt` doc index — `https://developers.paymob.com/paymob-docs/getting-started/overview/llms.txt` - Developer docs — `https://developers.paymob.com/` -- Integration Wizard (roadmap, runnable samples, HMAC/webhook tester) — `https://wizard.paymob.com/` +- Integration Wizard (roadmap, code lab, sandbox links + "Pay with test card", HMAC checker, Store Check) — `https://wizard.paymob.com/` +- Webhook inspector (see callbacks live, no retention, test only) — `https://hooks.paymob.com` - Community forum — `https://community.paymob.com/` - MCP server (live account actions) — `https://mcp.paymob.com/mcp` + +## WHAT YOU CAN OFFER + +If the user asks what you can do, or their request is vague, briefly list what fits their platform: sign-up and credentials; choosing a path (Payment Links, Shopify app, plugin, Unified Checkout, Pixel, mobile SDK); payment methods per market; webhooks and HMAC; guided sandbox testing; refunds/void/capture and reconciliation; subscriptions, saved cards, split payments, convenience fees; the Paymob MCP server for live account actions; the Integration Wizard and hooks.paymob.com. After a successful test, suggest one line of relevant next steps — not the whole list.