@atbas/m-mcp 0.1.0

package/knowledge/flows/bnpl-page-redirection-v1.1.json

@@ -0,0 +1,211 @@
+{
+  "id": "bnpl-page-redirection-v1.1",
+  "title": "Buy Now Pay Later (BNPL) — Page Redirection v1.1",
+  "provider": "jazzcash",
+  "product": "bnpl",
+  "version": "1.1",
+  "transport": "form-post",
+  "summary": "Hosted BNPL checkout. Identical in shape to card page redirection, with pp_TxnType set to BNPL.",
+  "useWhen": "You want to offer Buy Now Pay Later at checkout.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/CustomerPortal/transactionmanagement/merchantform",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/CustomerPortal/transactionmanagement/merchantform"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "payment",
+  "constants": {
+    "pp_Version": "1.1",
+    "pp_TxnType": "BNPL",
+    "pp_Language": "EN",
+    "pp_TxnCurrency": "PKR"
+  },
+  "parameters": [
+    {
+      "name": "pp_Version",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "Constant. Must not be modified.",
+      "constantValue": "1.1"
+    },
+    {
+      "name": "pp_TxnType",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "BNPL selects the Buy Now Pay Later flow.",
+      "constantValue": "BNPL"
+    },
+    {
+      "name": "pp_Language",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "Constant. Must not be modified.",
+      "constantValue": "EN"
+    },
+    {
+      "name": "pp_MerchantID",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "From Integration > Credentials in the merchant portal."
+    },
+    {
+      "name": "pp_Password",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "From Integration > Credentials. Never render this into client-side code.",
+      "sensitive": true
+    },
+    {
+      "name": "pp_TxnRefNo",
+      "requirement": "mandatory",
+      "valueType": "txn-ref",
+      "notes": "Unique for every transaction. Recommended shape: three-letter merchant prefix followed by YYYYMMDDHHMMSS.",
+      "maxLength": 20
+    },
+    {
+      "name": "pp_Amount",
+      "requirement": "mandatory",
+      "valueType": "minor-units",
+      "notes": "Minor units. Multiply the order total by 100: PKR 100.00 is sent as \"10000\"."
+    },
+    {
+      "name": "pp_TxnCurrency",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "The gateway processes PKR only and performs no conversion.",
+      "constantValue": "PKR"
+    },
+    {
+      "name": "pp_TxnDateTime",
+      "requirement": "mandatory",
+      "valueType": "pkt-datetime",
+      "notes": "YYYYMMDDHHMMSS in Pakistan Standard Time."
+    },
+    {
+      "name": "pp_BillReference",
+      "requirement": "mandatory",
+      "valueType": "bill-reference",
+      "notes": "Alphanumeric only. May repeat across transactions."
+    },
+    {
+      "name": "pp_Description",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "Product or order description."
+    },
+    {
+      "name": "pp_TxnExpiryDateTime",
+      "requirement": "mandatory",
+      "valueType": "pkt-expiry",
+      "notes": "YYYYMMDDHHMMSS in Pakistan Standard Time, one day after pp_TxnDateTime."
+    },
+    {
+      "name": "pp_ReturnURL",
+      "requirement": "mandatory",
+      "valueType": "url",
+      "notes": "Must exactly match the URL registered against the merchant profile. It is part of merchant authentication; any difference fails validation."
+    },
+    {
+      "name": "pp_SubMerchantID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\". Do not use null and do not omit it."
+    },
+    {
+      "name": "pp_BankID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\". Do not use null and do not omit it."
+    },
+    {
+      "name": "pp_ProductID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\". Do not use null and do not omit it."
+    },
+    {
+      "name": "ppmpf_1",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "ppmpf_2",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "ppmpf_3",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "ppmpf_4",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "ppmpf_5",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "pp_SecureHash",
+      "requirement": "mandatory",
+      "valueType": "secure-hash",
+      "notes": "HMAC-SHA256 over the sorted non-empty values, prefixed by the Integrity Salt. Excluded from its own input."
+    }
+  ],
+  "hash": {
+    "algorithm": "hmac-sha256",
+    "includeFieldPrefixes": ["pp_", "ppmpf_"],
+    "excludeFields": ["pp_SecureHash", "SecureHash"],
+    "outputEncoding": "hex-lowercase",
+    "comparison": "case-insensitive"
+  },
+  "response": {
+    "hashField": "pp_SecureHash",
+    "hashFieldPrefixes": [],
+    "successField": "pp_ResponseCode",
+    "successValue": "000",
+    "messageField": "pp_ResponseMessage",
+    "hashVerification": "assumed-all-non-empty",
+    "notableFields": ["pp_ResponseCode", "pp_ResponseMessage", "pp_TxnRefNo"]
+  },
+  "companionFlows": ["status-inquiry-v1.1", "refund-bnpl"],
+  "docRefs": [
+    {
+      "docId": "bnpl-guide",
+      "sectionId": "introduction",
+      "label": "JazzCash Buy Now Pay Later (BNPL) Guide, 2026"
+    },
+    {
+      "docId": "hmac-sha256-calculation",
+      "sectionId": "how-is-hmac-sha256-calculated"
+    }
+  ],
+  "knownIssues": [
+    {
+      "id": "bnpl-production-credentials-for-testing",
+      "summary": "BNPL testing uses production credentials",
+      "detail": "The BNPL guide states \"Use Production Credentials for BNPL Testing\", unlike every other flow, which is tested in sandbox.",
+      "guidance": "Treat every BNPL test as a live transaction: use the smallest possible amount, expect a real debit, and refund it afterwards."
+    },
+    {
+      "id": "php-sample-loose-comparison",
+      "summary": "The official PHP sample drops a value of integer 0 from the hash",
+      "detail": "The sample filters with `$value != null && $value != \"\"`, which is false for integer 0 in PHP, silently removing that field from the hash string.",
+      "guidance": "Filter with a strict string comparison instead: `$value !== null && (string)$value !== ''`."
+    },
+    {
+      "id": "php-sample-ksort-mode",
+      "summary": "The official PHP sample sorts with ksort() in SORT_REGULAR mode",
+      "detail": "The specification requires ascending ASCII order of parameter names. SORT_REGULAR is not guaranteed to be a plain string comparison.",
+      "guidance": "Use `ksort($params, SORT_STRING);` so the ordering is deterministic and matches the specification."
+    }
+  ]
+}

package/knowledge/flows/card-page-redirection-v1.1.json

@@ -0,0 +1,211 @@
+{
+  "id": "card-page-redirection-v1.1",
+  "title": "Card Payment — Page Redirection / Checkout v1.1",
+  "provider": "jazzcash",
+  "product": "card",
+  "version": "1.1",
+  "transport": "form-post",
+  "summary": "Hosted checkout. The merchant posts a signed HTML form to JazzCash, the customer completes payment on the JazzCash landing page, and the result is posted back to the registered Return URL.",
+  "useWhen": "You want card payments without handling card data yourself. The same landing page also offers mobile account and voucher payment.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/CustomerPortal/transactionmanagement/merchantform",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/CustomerPortal/transactionmanagement/merchantform"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "payment",
+  "constants": {
+    "pp_Version": "1.1",
+    "pp_TxnType": "MPAY",
+    "pp_Language": "EN",
+    "pp_TxnCurrency": "PKR"
+  },
+  "parameters": [
+    {
+      "name": "pp_Version",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "constantValue": "1.1",
+      "notes": "Constant. Must not be modified."
+    },
+    {
+      "name": "pp_TxnType",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "constantValue": "MPAY",
+      "notes": "MPAY selects the card checkout page."
+    },
+    {
+      "name": "pp_Language",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "constantValue": "EN",
+      "notes": "Constant. Must not be modified."
+    },
+    {
+      "name": "pp_MerchantID",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "From Integration > Credentials in the merchant portal."
+    },
+    {
+      "name": "pp_Password",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "sensitive": true,
+      "notes": "From Integration > Credentials. Never render this into client-side code."
+    },
+    {
+      "name": "pp_TxnRefNo",
+      "requirement": "mandatory",
+      "valueType": "txn-ref",
+      "maxLength": 20,
+      "notes": "Unique for every transaction. Recommended shape: three-letter merchant prefix followed by YYYYMMDDHHMMSS."
+    },
+    {
+      "name": "pp_Amount",
+      "requirement": "mandatory",
+      "valueType": "minor-units",
+      "notes": "Minor units. Multiply the order total by 100: PKR 2.00 is sent as \"200\"."
+    },
+    {
+      "name": "pp_TxnCurrency",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "constantValue": "PKR",
+      "notes": "The gateway processes PKR only and performs no conversion."
+    },
+    {
+      "name": "pp_TxnDateTime",
+      "requirement": "mandatory",
+      "valueType": "pkt-datetime",
+      "notes": "YYYYMMDDHHMMSS in Pakistan Standard Time."
+    },
+    {
+      "name": "pp_BillReference",
+      "requirement": "mandatory",
+      "valueType": "bill-reference",
+      "notes": "Alphanumeric only. May repeat across transactions."
+    },
+    {
+      "name": "pp_Description",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "Shown to the customer on the payment page."
+    },
+    {
+      "name": "pp_TxnExpiryDateTime",
+      "requirement": "mandatory",
+      "valueType": "pkt-expiry",
+      "notes": "YYYYMMDDHHMMSS in Pakistan Standard Time, one day after pp_TxnDateTime."
+    },
+    {
+      "name": "pp_ReturnURL",
+      "requirement": "mandatory",
+      "valueType": "url",
+      "notes": "Must exactly match the URL registered against the merchant profile. It is part of merchant authentication; any difference fails validation."
+    },
+    {
+      "name": "pp_SubMerchantID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\". Do not use null and do not omit it."
+    },
+    {
+      "name": "pp_BankID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\"."
+    },
+    {
+      "name": "pp_ProductID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\"."
+    },
+    {
+      "name": "ppmpf_1",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty for card checkout."
+    },
+    {
+      "name": "ppmpf_2",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty for card checkout."
+    },
+    {
+      "name": "ppmpf_3",
+      "requirement": "optional",
+      "valueType": "string",
+      "notes": "Optional merchant-defined field. When non-empty it participates in the secure hash."
+    },
+    {
+      "name": "ppmpf_4",
+      "requirement": "optional",
+      "valueType": "string",
+      "notes": "Optional merchant-defined field. When non-empty it participates in the secure hash."
+    },
+    {
+      "name": "ppmpf_5",
+      "requirement": "optional",
+      "valueType": "string",
+      "notes": "Optional merchant-defined field. When non-empty it participates in the secure hash."
+    },
+    {
+      "name": "pp_SecureHash",
+      "requirement": "mandatory",
+      "valueType": "secure-hash",
+      "notes": "HMAC-SHA256 over the sorted non-empty values, prefixed by the Integrity Salt. Excluded from its own input."
+    }
+  ],
+  "hash": {
+    "algorithm": "hmac-sha256",
+    "includeFieldPrefixes": ["pp_", "ppmpf_"],
+    "excludeFields": ["pp_SecureHash", "SecureHash"],
+    "outputEncoding": "hex-lowercase",
+    "comparison": "case-insensitive"
+  },
+  "response": {
+    "hashField": "pp_SecureHash",
+    "hashFieldPrefixes": [],
+    "successField": "pp_ResponseCode",
+    "successValue": "000",
+    "messageField": "pp_ResponseMessage",
+    "hashVerification": "assumed-all-non-empty",
+    "notableFields": ["pp_ResponseCode", "pp_ResponseMessage", "pp_TxnRefNo", "pp_RetreivalReferenceNo", "pp_AuthCode"]
+  },
+  "companionFlows": ["status-inquiry-v1.1"],
+  "docRefs": [
+    {
+      "docId": "card-page-redirection",
+      "sectionId": "introduction",
+      "label": "Card Payment — Page Redirection/Checkout (v1.1), 2026"
+    },
+    {
+      "docId": "hmac-sha256-calculation",
+      "sectionId": "how-is-hmac-sha256-calculated"
+    }
+  ],
+  "knownIssues": [
+    {
+      "id": "php-sample-loose-comparison",
+      "summary": "The official PHP sample drops a value of integer 0 from the hash",
+      "detail": "The sample filters with `$value != null && $value != \"\"`, which is false for integer 0 in PHP, silently removing that field from the hash string.",
+      "guidance": "Filter with a strict string comparison instead: `$value !== null && (string)$value !== ''`."
+    },
+    {
+      "id": "php-sample-ksort-mode",
+      "summary": "The official PHP sample sorts with ksort() in SORT_REGULAR mode",
+      "detail": "The specification requires ascending ASCII order of parameter names. SORT_REGULAR is not guaranteed to be a plain string comparison.",
+      "guidance": "Use `ksort($params, SORT_STRING);` so the ordering is deterministic and matches the specification."
+    },
+    {
+      "id": "browser-rendered-values",
+      "summary": "Form values are rendered into HTML without escaping in the official sample",
+      "detail": "Values are echoed directly into hidden inputs, so a quote in pp_Description breaks the form and can alter what is submitted.",
+      "guidance": "Escape every rendered value, e.g. `htmlspecialchars($value, ENT_QUOTES, 'UTF-8')`."
+    }
+  ]
+}

package/knowledge/flows/mwallet-rest-v1.1.json

@@ -0,0 +1,187 @@
+{
+  "id": "mwallet-rest-v1.1",
+  "title": "MWallet REST API v1.1 (without CNIC)",
+  "provider": "jazzcash",
+  "product": "mwallet",
+  "version": "1.1",
+  "transport": "rest",
+  "summary": "Server-to-server mobile account debit. The customer approves the transaction on their handset.",
+  "useWhen": "You want to charge a JazzCash mobile wallet directly, without CNIC verification and without a hosted page.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/m-wallet",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/m-wallet"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "payment",
+  "constants": {
+    "pp_Version": "1.1",
+    "pp_TxnType": "MWALLET",
+    "pp_Language": "EN",
+    "pp_TxnCurrency": "PKR"
+  },
+  "parameters": [
+    {
+      "name": "pp_Amount",
+      "requirement": "mandatory",
+      "valueType": "minor-units",
+      "notes": "Minor units. Multiply the order total by 100: PKR 100.00 is sent as \"10000\"."
+    },
+    {
+      "name": "pp_BillReference",
+      "requirement": "mandatory",
+      "valueType": "bill-reference",
+      "notes": "Alphanumeric only. May repeat across transactions."
+    },
+    {
+      "name": "pp_Description",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "Product or order description."
+    },
+    {
+      "name": "pp_Language",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "Constant. Must not be modified.",
+      "constantValue": "EN"
+    },
+    {
+      "name": "pp_MerchantID",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "From Integration > Credentials in the merchant portal."
+    },
+    {
+      "name": "pp_Password",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "From Integration > Credentials. Never render this into client-side code.",
+      "sensitive": true
+    },
+    {
+      "name": "pp_ReturnURL",
+      "requirement": "mandatory",
+      "valueType": "url",
+      "notes": "Must exactly match the URL registered against the merchant profile. It is part of merchant authentication; any difference fails validation."
+    },
+    {
+      "name": "pp_SecureHash",
+      "requirement": "mandatory",
+      "valueType": "secure-hash",
+      "notes": "HMAC-SHA256 over the sorted non-empty values, prefixed by the Integrity Salt. Excluded from its own input."
+    },
+    {
+      "name": "pp_TxnCurrency",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "The gateway processes PKR only and performs no conversion.",
+      "constantValue": "PKR"
+    },
+    {
+      "name": "pp_TxnDateTime",
+      "requirement": "mandatory",
+      "valueType": "pkt-datetime",
+      "notes": "YYYYMMDDHHMMSS in Pakistan Standard Time."
+    },
+    {
+      "name": "pp_TxnExpiryDateTime",
+      "requirement": "mandatory",
+      "valueType": "pkt-expiry",
+      "notes": "YYYYMMDDHHMMSS in Pakistan Standard Time, one day after pp_TxnDateTime."
+    },
+    {
+      "name": "pp_TxnRefNo",
+      "requirement": "mandatory",
+      "valueType": "txn-ref",
+      "notes": "Unique for every transaction. Recommended shape: three-letter merchant prefix followed by YYYYMMDDHHMMSS.",
+      "maxLength": 20
+    },
+    {
+      "name": "pp_TxnType",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "Constant. Must not be modified.",
+      "constantValue": "MWALLET"
+    },
+    {
+      "name": "pp_Version",
+      "requirement": "mandatory",
+      "valueType": "constant",
+      "notes": "Constant. Must not be modified.",
+      "constantValue": "1.1"
+    },
+    {
+      "name": "ppmpf_1",
+      "requirement": "mandatory",
+      "valueType": "msisdn",
+      "notes": "Mobile wallet number. Mandatory for this flow, unlike every other, where ppmpf_1 is left empty."
+    },
+    {
+      "name": "ppmpf_2",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "ppmpf_3",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "ppmpf_4",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    },
+    {
+      "name": "ppmpf_5",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Leave empty."
+    }
+  ],
+  "hash": {
+    "algorithm": "hmac-sha256",
+    "includeFieldPrefixes": ["pp_", "ppmpf_"],
+    "excludeFields": ["pp_SecureHash", "SecureHash"],
+    "outputEncoding": "hex-lowercase",
+    "comparison": "case-insensitive"
+  },
+  "response": {
+    "hashField": "pp_SecureHash",
+    "hashFieldPrefixes": [],
+    "successField": "pp_ResponseCode",
+    "successValue": "000",
+    "messageField": "pp_ResponseMessage",
+    "hashVerification": "assumed-all-non-empty",
+    "notableFields": ["pp_ResponseCode", "pp_ResponseMessage", "pp_RetreivalReferenceNo", "pp_TxnRefNo"]
+  },
+  "companionFlows": ["status-inquiry-v1.1", "refund-mwallet-v1.1"],
+  "docRefs": [
+    {
+      "docId": "mwallet-rest-v1-1",
+      "sectionId": "implementation-notes",
+      "label": "MWallet REST API v1.1 (Without CNIC) Merchant Guide, 2026"
+    },
+    {
+      "docId": "hmac-sha256-calculation",
+      "sectionId": "how-is-hmac-sha256-calculated"
+    }
+  ],
+  "knownIssues": [
+    {
+      "id": "identical-sandbox-and-production-endpoint",
+      "summary": "Sandbox and production use the same URL",
+      "detail": "The guide lists an identical endpoint for both environments, so the URL carries no information about which environment a request reaches. The environment is determined entirely by the credentials.",
+      "guidance": "Declare the environment explicitly on every call and cross-check it against the credential profile in use. Never infer it from the endpoint."
+    },
+    {
+      "id": "ppmpf1-carries-the-wallet-number",
+      "summary": "ppmpf_1 is a mandatory business field in this flow",
+      "detail": "Every other guide instructs merchants to leave ppmpf_1 empty. In MWallet REST v1.1 it carries the customer's mobile wallet number and is mandatory.",
+      "guidance": "Populate ppmpf_1 with the wallet MSISDN. Because it is non-empty it also participates in the secure hash."
+    }
+  ]
+}