@atbas/m-mcp 0.1.0

package/knowledge/docs/status-inquiry.md

@@ -0,0 +1,111 @@
+# Status Inquiry API
+
+Source: `Status Inquiry Guide (2026).pdf`, version 2026.
+
+## Introduction {#introduction}
+
+The Status Inquiry API obtains the final status of pending or missing transactions. It is a **mandatory** integration for every JazzCash payment flow.
+
+**Call it no sooner than ten minutes after the transaction was initiated.**
+
+Only `pp_PaymentResponseCode` and `pp_Status` confirm the state of a pending transaction. `pp_ResponseCode` describes the enquiry itself, not the payment.
+
+```
+pp_ResponseCode: '000'            // the Status Inquiry call succeeded
+pp_ResponseMessage: 'Thank you for Using JazzCash, your operation successfully completed.'
+pp_PaymentResponseCode: '121'     // the transaction completed and the amount was debited
+pp_PaymentResponseMessage: 'Thank you for using JazzCash. Your transaction was processed successfully.'
+pp_Status: 'Completed'
+```
+
+## API version 1.1 {#api-version-1-1}
+
+Endpoint, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/status/inquiry
+```
+
+Request:
+
+```json
+{
+  "pp_TxnRefNo": "T20251124131402",
+  "pp_MerchantID": "{{Your Merchant ID}}",
+  "pp_Password": "{{Your Password}}",
+  "pp_SecureHash": "18494EE9B220CA4ADBE3ED5B597CCBF26E8C6F8BA205A9199A2EC8B87A2C0673"
+}
+```
+
+Response:
+
+```json
+{
+  "pp_ResponseCode": "000",
+  "pp_ResponseMessage": "Thank you for using JazzCash. Your operation was processed successfully.",
+  "pp_PaymentResponseCode": "121",
+  "pp_PaymentResponseMessage": "Thank you for using JazzCash. Your transaction was processed successfully.",
+  "pp_Status": "Completed",
+  "pp_RetrievalReferenceNo": "202511241314312807581909",
+  "pp_SettlementDate": "",
+  "pp_SettlementExpiry": "",
+  "pp_AuthCode": "095469672235",
+  "pp_BankID": "",
+  "pp_ProductID": "",
+  "pp_SecureHash": "EC906098D8C778B0043F33102698929F39DC32D7D560D6204377E0B390CE17E4"
+}
+```
+
+## API version 2.0 {#api-version-2-0}
+
+Endpoint, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v2/rest/payments/status/inquiry
+```
+
+The request is identical to v1.1. The response adds the original transaction details, which makes reconciliation possible without a separate lookup:
+
+```json
+{
+  "pp_ResponseCode": "000",
+  "pp_ResponseMessage": "Thank you for using JazzCash. Your operation was processed successfully.",
+  "pp_PaymentResponseCode": "121",
+  "pp_PaymentResponseMessage": "Thank you for using JazzCash. Your transaction was processed successfully.",
+  "pp_Status": "Completed",
+  "pp_MerchantID": "{{Your Merchant ID}}",
+  "pp_RetrievalReferenceNo": "202511241314312807581909",
+  "pp_TxnRefNo": "T20251124131402",
+  "pp_TxnType": "MWALLET",
+  "pp_Amount": "100",
+  "pp_TxnDateTime": "20251124131402",
+  "pp_BillReference": "B20251124131402",
+  "pp_SettlementDate": "",
+  "pp_AuthCode": "095469672235",
+  "pp_SecureHash": "F1CE61CD416F75860009839091607127279C179531B6DE0F1806A742AFD62096"
+}
+```
+
+Prefer v2.0 for new integrations: the extra fields let you verify that the transaction you are reading is the one you sent.
+
+## Reading the codes {#reading-the-codes}
+
+| Field | Value | Meaning |
+| --- | --- | --- |
+| `pp_ResponseCode` | `000` | The enquiry itself succeeded |
+| `pp_PaymentResponseCode` | `121` | The transaction completed and the amount was debited |
+| `pp_PaymentResponseCode` | `199`, `999`, others | The transaction failed |
+| `pp_Status` | `Completed` | Terminal success |
+
+An undocumented code is not a failure. Treat it as unresolved, read `pp_PaymentResponseMessage`, and confirm the meaning with JazzCash before releasing goods or refunding.
+
+Note the spelling difference between flows: Status Inquiry returns `pp_RetrievalReferenceNo`, while the MWallet payment APIs return `pp_RetreivalReferenceNo`.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Order marked paid but no money arrives | `pp_ResponseCode` `000` treated as proof of payment | Read `pp_PaymentResponseCode` |
+| Enquiry always returns pending | Called too soon | Wait at least ten minutes after initiation |
+| Field not found when reading the reference | Spelling copied from the MWallet payment response | Status Inquiry uses `pp_RetrievalReferenceNo` |
+| Hash mismatch on the request | Only three fields participate | Hash `pp_MerchantID`, `pp_Password` and `pp_TxnRefNo`, prefixed by the salt |

package/knowledge/docs/wordpress-guide.md

@@ -0,0 +1,49 @@
+# WordPress / WooCommerce Integration
+
+Source: `WordPress Integration Guide (2026).pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Adds JazzCash as a payment method to a WordPress site. **WooCommerce must already be installed.**
+
+## Plugin installation {#plugin-installation}
+
+The plugin is distributed as a `.zip` from a Google Drive link supplied by JazzCash:
+<https://drive.google.com/file/d/1mVVl8fdwlX384HjYyezFknN23rJFr68u/view?usp=sharing>
+
+Download it, upload the `.zip` in the Plugins upload section, and activate it.
+
+Because the plugin is distributed outside the WordPress plugin directory, it receives no automatic updates. Ask JazzCash for the current version when troubleshooting.
+
+## Credentials configuration {#credentials-configuration}
+
+Go to **WooCommerce → Settings → Payments** and click **Manage** on the JazzCash method to enter your transaction credentials. Save the changes.
+
+## Return and IPN URLs {#return-and-ipn-urls}
+
+Register these in the **Credentials** tab of your sandbox (or production) portal:
+
+- Return URL: `{yourbaseURL}/wc-api/result/`
+- IPN URL: `{yourbaseURL}/jazzcash_ipn_v2`
+
+Both must match exactly, including the trailing slash on the Return URL. The Return URL is part of merchant authentication, so a mismatch fails validation with an unhelpful error.
+
+## Test products {#test-products}
+
+Add two test products — one at **PKR 10** and one at **PKR 1** — for card and wallet testing respectively, and perform test transactions using the sandbox testing numbers.
+
+> The sandbox testing numbers are not listed in the guide. Request them from JazzCash during onboarding.
+
+## Refunds {#refunds}
+
+Process a refund from the **JazzCash Transaction** tab using the **Refund** button. As elsewhere, the Merchant MPIN must be saved in the merchant portal first.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Payment method not offered at checkout | WooCommerce missing, or the method not enabled | Install WooCommerce, then enable JazzCash under Settings → Payments |
+| Validation failure on every payment | Return URL missing its trailing slash | Register and send exactly `{base}/wc-api/result/` |
+| Orders never leave "pending payment" | IPN URL not registered, or not reachable | Register `{base}/jazzcash_ipn_v2` and confirm it is publicly reachable |
+| Refund button fails | MPIN not saved in the merchant portal | Save it, then retry |
+| Plugin behaves differently from the documentation | An older `.zip` is installed | Ask JazzCash for the current build |

package/knowledge/flow.schema.json

@@ -0,0 +1,390 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://m-mcp.local/flow.schema.json",
+  "title": "JazzCash integration flow specification",
+  "description": "Editor tooling aid. The authoritative contract is the zod schema in src/catalogue/types.ts; tests/catalogue/schema-parity.test.ts asserts the two stay in step.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "title",
+    "provider",
+    "product",
+    "version",
+    "transport",
+    "summary",
+    "useWhen",
+    "endpoints",
+    "sameEndpointForBothEnvironments",
+    "movesMoney",
+    "responseContext",
+    "parameters",
+    "hash",
+    "response",
+    "docRefs"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Must equal the file name without its extension."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "provider": {
+      "type": "string",
+      "enum": ["jazzcash"],
+      "description": "The gateway this flow belongs to. Required rather than defaulted: a second provider's file that omitted it would load as a JazzCash flow, and would then be signed the JazzCash way and checked against JazzCash endpoints."
+    },
+    "product": {
+      "type": "string",
+      "enum": ["card", "bnpl", "mwallet", "wallet-linking", "token", "status-inquiry", "refund"]
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "transport": {
+      "type": "string",
+      "enum": ["rest", "form-post"],
+      "description": "How the flow is performed. Called rest, a form-post flow would be sent server-side to an endpoint that expects a customer's browser; called form-post, a REST flow would redirect a customer straight at an endpoint that expects a signed server-side payload."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "useWhen": {
+      "type": "string",
+      "minLength": 1
+    },
+    "endpoints": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sandbox", "production"],
+      "properties": {
+        "sandbox": {
+          "type": "string",
+          "format": "uri"
+        },
+        "production": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    },
+    "sameEndpointForBothEnvironments": {
+      "type": "boolean"
+    },
+    "movesMoney": {
+      "type": "boolean",
+      "description": "True when a successful call debits, refunds or links. Drives the production dual opt-in guard."
+    },
+    "responseContext": {
+      "type": "string",
+      "enum": ["payment", "inquiry", "refund", "ipn", "token"]
+    },
+    "constants": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "parameters": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "requirement", "valueType", "notes"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "requirement": {
+            "type": "string",
+            "enum": ["mandatory", "optional", "must-be-empty"]
+          },
+          "valueType": {
+            "type": "string",
+            "enum": [
+              "constant",
+              "string",
+              "minor-units",
+              "pkt-datetime",
+              "pkt-expiry",
+              "url",
+              "txn-ref",
+              "bill-reference",
+              "request-id",
+              "msisdn",
+              "cnic",
+              "payment-token",
+              "secure-hash"
+            ]
+          },
+          "constantValue": {
+            "type": "string"
+          },
+          "maxLength": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "pattern": {
+            "type": "string"
+          },
+          "sensitive": {
+            "type": "boolean",
+            "default": false,
+            "description": "True for credentials and personal data; excluded from logs and echoes."
+          },
+          "neverAcceptAsToolArgument": {
+            "type": "boolean",
+            "default": false,
+            "description": "True for a value that must never cross the MCP boundary as a tool argument, such as a PAN, expiry or CVV. A tool argument is written to the transcript before any server code runs, so no later redaction can recall it."
+          },
+          "notes": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "hash": {
+      "description": "How the flow signs its requests. One construction ships today; it stays a oneOf rather than being inlined because a second construction differs in more than a digest name — which fields are selected, whether the secret is a key or a component, whether a separator exists — and a flat object would let a flow declare two selection rules at once with nothing to say which wins.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The JazzCash construction: sort the selected non-empty parameters by name, join their values, prepend the Integrity Salt and HMAC the result with it.",
+          "required": ["algorithm", "includeFieldPrefixes", "excludeFields", "outputEncoding", "comparison"],
+          "properties": {
+            "algorithm": {
+              "const": "hmac-sha256"
+            },
+            "includeFieldPrefixes": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string"
+              },
+              "description": "Assumption A1: the PHP samples include ppmpf_*, the JavaScript linking sample does not."
+            },
+            "excludeFields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "outputEncoding": {
+              "type": "string",
+              "enum": ["hex-lowercase", "base64"]
+            },
+            "comparison": {
+              "type": "string",
+              "enum": ["case-insensitive", "case-sensitive"]
+            }
+          }
+        }
+      ]
+    },
+    "response": {
+      "description": "How the response reports its outcome, and whether it carries a signature to verify.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Assumption A2: response hash coverage is undocumented, so a mismatch reports 'unverified', never 'failed'.",
+          "required": ["successField", "successValue", "hashVerification", "hashField"],
+          "properties": {
+            "hashVerification": {
+              "const": "assumed-all-non-empty"
+            },
+            "hashField": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+              "description": "The field carrying the response signature. JazzCash card and BNPL refunds return a bare SecureHash; every other JazzCash response returns pp_SecureHash."
+            },
+            "successField": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+              "description": "The field carrying the service-level outcome."
+            },
+            "successValue": {
+              "type": "string",
+              "minLength": 1
+            },
+            "messageField": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+              "description": "The field carrying the gateway's own explanation of the outcome. Optional: a provider that sends no message has none to name, and the generator then emits no lookup for it."
+            },
+            "settlement": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "The bank level of a two-level success rule. Checking only the service-level code classifies a DECLINED card as a successful payment.",
+              "required": ["field", "successValue"],
+              "properties": {
+                "field": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 64,
+                  "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
+                },
+                "successValue": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            "hashFieldPrefixes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Prefixes selecting which RESPONSE fields feed the response hash. Empty means no filtering, which is correct for every documented flow: card and BNPL refund responses use unprefixed field names."
+            },
+            "notableFields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "A response the server does not verify a signature on. hashField is optional here: a provider whose responses are unsigned must not be made to name a field that does not exist.",
+          "required": ["successField", "successValue", "hashVerification"],
+          "properties": {
+            "hashVerification": {
+              "const": "not-applicable"
+            },
+            "hashField": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+              "description": "Optional here: a gateway may return a digest it does not document how to reproduce, and absent means there is nothing to read."
+            },
+            "successField": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+              "description": "The field carrying the service-level outcome."
+            },
+            "successValue": {
+              "type": "string",
+              "minLength": 1
+            },
+            "messageField": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+              "description": "The field carrying the gateway's own explanation of the outcome. Optional: a provider that sends no message has none to name, and the generator then emits no lookup for it."
+            },
+            "settlement": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "The bank level of a two-level success rule. Checking only the service-level code classifies a DECLINED card as a successful payment.",
+              "required": ["field", "successValue"],
+              "properties": {
+                "field": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 64,
+                  "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
+                },
+                "successValue": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            "hashFieldPrefixes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Prefixes selecting which RESPONSE fields feed the response hash. Empty means no filtering, which is correct for every documented flow: card and BNPL refund responses use unprefixed field names."
+            },
+            "notableFields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "companionFlows": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "docRefs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["docId"],
+        "properties": {
+          "docId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sectionId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "knownIssues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "summary", "detail", "guidance"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "detail": {
+            "type": "string",
+            "minLength": 1
+          },
+          "guidance": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}