@atbas/m-mcp 0.1.0

package/knowledge/docs/bnpl-guide.md

@@ -0,0 +1,77 @@
+# Buy Now Pay Later (BNPL)
+
+Source: `Page Redirection v1.1 template for (BNPL)_2026.pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Integrates JazzCash Buy Now Pay Later into a website or mobile application using BNPL page redirection. The request is structurally identical to card page redirection; only `pp_TxnType` differs.
+
+> **Use production credentials for BNPL testing.** This is stated explicitly in the guide and is unlike every other flow, which is tested in sandbox. Treat every BNPL test as a live transaction: use the smallest possible amount, expect a real debit, and refund it afterwards.
+
+## Endpoint {#endpoint}
+
+Form action, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/CustomerPortal/transactionmanagement/merchantform
+```
+
+## Request parameters {#request-parameters}
+
+Identical to card page redirection, except:
+
+- `pp_TxnType` is `BNPL` rather than `MPAY`.
+- `ppmpf_1` through `ppmpf_5` are all marked "leave it empty"; the card guide marks `ppmpf_3`–`ppmpf_5` as optional.
+
+`pp_Version` `1.1`, `pp_TxnType` `BNPL`, `pp_Language` `EN`, `pp_MerchantID`, `pp_Password`, `pp_TxnRefNo`, `pp_Amount`, `pp_TxnCurrency` `PKR`, `pp_TxnDateTime`, `pp_BillReference`, `pp_Description`, `pp_TxnExpiryDateTime`, `pp_ReturnURL`, `pp_SubMerchantID` `""`, `pp_BankID` `""`, `pp_ProductID` `""`, `ppmpf_1`–`ppmpf_5` `""`, plus `pp_SecureHash`.
+
+## Important notes {#important-notes}
+
+- `pp_TxnRefNo` must be unique for every transaction.
+- `pp_Amount` is in minor units: multiply by 100.
+- `pp_TxnDateTime` and `pp_TxnExpiryDateTime` are `YYYYMMDDHHMMSS` in Pakistan Standard Time, the expiry being one day later.
+- `pp_ReturnURL` must match the registered value exactly; it is part of merchant authentication.
+- All empty fields must remain as `""`.
+
+## BNPL Refund API {#bnpl-refund-api}
+
+Endpoint, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/authorize/refund
+```
+
+This is the same URL as Card Refund v1.1, but the documented payload differs: the BNPL sample omits `pp_MerchantMPIN`, which the card refund guide marks mandatory.
+
+Sample request:
+
+```json
+{
+  "pp_TxnRefNo": "T20260114153733",
+  "pp_MerchantID": "{Merchant ID}",
+  "pp_Password": "{Password}",
+  "pp_SecureHash": "fde479ead7b9fdf231f4c992a62ac4413914f05a61cabf3f33dd0c90fcb52030",
+  "pp_Amount": "100",
+  "pp_TxnCurrency": "PKR"
+}
+```
+
+Sample response — note the **unprefixed** field names:
+
+```json
+{
+  "ResponseCode": "000",
+  "ResponseMessage": "Thank you for using JazzCash. Your transaction was processed successfully.",
+  "RefundAmount": "100",
+  "TotalRefundAmount": "100",
+  "SecureHash": "20B6593DFC995F98A54EC1B397C150085A2CC53DDC6751B72C6B4E927977CB35"
+}
+```
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Sandbox credentials rejected | BNPL is tested with production credentials | Use production credentials and the smallest possible amount |
+| Response hash never verifies | Code looks for `pp_SecureHash` | BNPL refund responses return a bare `SecureHash` |
+| Refund rejected as missing a field | Card refund payload assumed | The BNPL sample omits `pp_MerchantMPIN`; add it only if the gateway demands it, and report the conflict |

package/knowledge/docs/card-page-redirection.md

@@ -0,0 +1,67 @@
+# Card Payment — Page Redirection / Checkout v1.1
+
+Source: `Page Redirection v1.1 template for (Card Payments)_2026.pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Integrates JazzCash card payments into a website or mobile application using hosted checkout. The merchant renders a signed HTML form; the customer completes payment on the JazzCash landing page; the result is posted back to the registered Return URL. For a mobile application, the same redirection code is used inside a web view.
+
+The landing page also offers mobile account and voucher payment, so a single integration covers three payment methods.
+
+## Creating a sandbox account {#create-a-sandbox-account}
+
+1. Sign up at <https://onlinepayments.jazzcash.com.pk/sandbox-frontend/>.
+2. Share your Merchant ID with JazzCash so the team can enable the payment options for you. Until they do, the payment method will not appear.
+3. In the sandbox portal, go to **Integration → Credentials** and record the Merchant ID, Password and Integrity Salt.
+4. Enter your **Return URL / Callback URL** in the same screen.
+5. If you are using instant payment notifications, enter your **IPN URL** as well.
+
+## Endpoint {#endpoint}
+
+Form action, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/CustomerPortal/transactionmanagement/merchantform
+```
+
+Because the URL does not distinguish sandbox from production, the environment is determined entirely by which credentials you post with.
+
+## Request parameters {#request-parameters}
+
+`pp_Version` `1.1`, `pp_TxnType` `MPAY`, `pp_Language` `EN`, `pp_MerchantID`, `pp_Password`, `pp_TxnRefNo`, `pp_Amount`, `pp_TxnCurrency` `PKR`, `pp_TxnDateTime`, `pp_BillReference`, `pp_Description`, `pp_TxnExpiryDateTime`, `pp_ReturnURL`, `pp_SubMerchantID` `""`, `pp_BankID` `""`, `pp_ProductID` `""`, `ppmpf_1` `""`, `ppmpf_2` `""`, `ppmpf_3`–`ppmpf_5` optional, plus `pp_SecureHash`.
+
+`pp_TxnType` is the only difference from the BNPL flow, which uses `BNPL`.
+
+## Important notes {#important-notes}
+
+- **`pp_TxnRefNo`** is a unique identifier and must be a unique value for every transaction.
+- **`pp_Amount`** is mandatory. The last two digits are treated as decimals, so multiply the product amount by 100 (2 × 100 = 200).
+- **`pp_TxnDateTime`** is `YYYYMMDDHHMMSS` in Pakistan Standard Time.
+- **`pp_TxnExpiryDateTime`** is `YYYYMMDDHHMMSS` in Pakistan Standard Time, one day after the current date.
+- **`pp_ReturnURL`** is mandatory and must be shared with JazzCash before use, because it becomes part of your merchant profile. It must be identical in every request: it is part of merchant authentication, and any difference fails validation.
+- Keep all mandatory parameters in every request.
+- All empty fields must remain as `""`.
+- Generate `pp_SecureHash` per the JazzCash hashing guidelines before sending the request.
+
+## Testing evidence required {#testing}
+
+Perform test transactions and capture screenshots for each payment method — mobile account, voucher payment, and credit/debit card. For each method, supply screenshots of:
+
+- the merchant checkout page;
+- the JazzCash landing page;
+- payment method selection;
+- the payment step;
+- the payment response received on the merchant Callback URL;
+- the order status in the merchant admin panel.
+
+Paste the screenshots into the supplied template document and reply on the same email thread.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Validation failure with correct-looking data | `pp_ReturnURL` differs from the registered value, even by a trailing slash | Send the registered URL byte for byte |
+| Payment method missing from the landing page | JazzCash has not enabled it for your Merchant ID | Send your Merchant ID to JazzCash and ask for the method to be enabled |
+| Duplicate transaction rejected | `pp_TxnRefNo` reused | Append a timestamp with millisecond precision |
+| Customer charged the wrong amount | `pp_Amount` sent in major units | Multiply by 100 |
+| Form submits but the hash is rejected | Values HTML-escaped after hashing, or not escaped at all | Escape when rendering, hash the unescaped values you intend to send |

package/knowledge/docs/card-refund.md

@@ -0,0 +1,91 @@
+# Card Refund API
+
+Source: `Card Refund API (2026).pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Refunds a completed card transaction, in whole or in part. Two versions are documented; both are live.
+
+The Merchant MPIN must already be **saved in the merchant portal** before a refund will succeed, in addition to being sent in the request.
+
+## REST-based Card Refund API v1.1 {#rest-based-card-refund-api-v1-1}
+
+Endpoint, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/authorize/refund
+```
+
+This is the same URL used by the BNPL refund, which documents a different payload.
+
+Request:
+
+```json
+{
+  "pp_TxnRefNo": "T20251224170612",
+  "pp_Amount": "100",
+  "pp_TxnCurrency": "PKR",
+  "pp_MerchantID": "YOUR MERCHANT ID",
+  "pp_Password": "YOUR PASSWORD",
+  "pp_MerchantMPIN": "YOUR MERCHANT MPIN",
+  "pp_SecureHash": "c2537a63bb3314b53232603a6f56c394f96f7ce8e28c62ec8c6ab9da83367db0"
+}
+```
+
+Response:
+
+```json
+{
+  "ResponseCode": "000",
+  "ResponseMessage": "Thank you for using JazzCash. Your transaction was processed successfully.",
+  "RefundAmount": "100",
+  "TotalRefundAmount": "100",
+  "SecureHash": "20B6593DFC995F98A54EC1B397C150085A2CC53DDC6751B72C6B4E927977CB35"
+}
+```
+
+## REST-based Card Refund API v2.0 {#rest-based-card-refund-api-v2-0}
+
+Endpoint, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/v2.0/authorize/refund
+```
+
+Note that the version marker is in the path segment `v2.0`, while the API prefix stays `api/v1`.
+
+The request is identical to v1.1. The response adds acquirer detail useful for reconciliation:
+
+```json
+{
+  "ResponseCode": "000",
+  "ResponseMessage": "Thank you for using JazzCash. Your transaction was processed successfully.",
+  "RefundAmount": "100",
+  "TotalRefundAmount": "100",
+  "TxnRefNo": "T20251224174341",
+  "MerchantID": "YOUR MERCHANT ID",
+  "RetrievalReferenceNo": "202512241751151549494723",
+  "Stan": "203190",
+  "Receipt": "535812203190",
+  "Terminal": "80520144",
+  "SecureHash": "E3F8DD09E8E6E6CAF348E27AC42BCF1A2FFE884DB86C588675F541425B9FB79F7"
+}
+```
+
+Prefer v2.0: `TotalRefundAmount` plus the acquirer references let you reconcile partial refunds without a separate lookup.
+
+## Unprefixed response fields {#unprefixed-response-fields}
+
+Card refund responses use **`ResponseCode`, `ResponseMessage` and `SecureHash`** — with no `pp_` prefix. Every other documented JazzCash response prefixes them. Code that looks only for `pp_SecureHash` will silently skip verification of a refund response.
+
+`RefundAmount` is the amount refunded by this call; `TotalRefundAmount` is the cumulative total refunded against the original transaction. Compare the latter against the original amount to know whether a transaction is fully refunded.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Refund rejected | MPIN not saved in the merchant portal | Save it in the portal, then retry |
+| Response hash never verifies | Reading `pp_SecureHash` | Read the bare `SecureHash` |
+| Refund appears to succeed but nothing returns | Refunding an incomplete transaction | Confirm the original completed with Status Inquiry first |
+| Over-refund accepted then reversed | Not tracking `TotalRefundAmount` | Compare the cumulative total against the original amount before refunding |
+| Amount mismatch | Refund amount sent in major units | `pp_Amount` is in minor units here too |

package/knowledge/docs/hmac-sha256-calculation.md

@@ -0,0 +1,72 @@
+# HMAC-SHA256 (pp_SecureHash) Calculation
+
+Source: `How is HMAC-SHA256 calculated (2026).pdf`, version 2026.
+
+## The algorithm {#how-is-hmac-sha256-calculated}
+
+The secure hash is computed the same way for every JazzCash flow.
+
+1. Take **all non-empty fields** from the request.
+2. Sort by **parameter name**, ascending alphabetical (ASCII) order.
+3. Concatenate the **values** — not the names — joining them with `&`.
+4. **Prepend** the Integrity Salt (also called the Hash Key), separated by `&`.
+5. Hash the result with **HMAC-SHA256**, using the Integrity Salt itself as the secret key.
+
+The salt therefore appears twice: once as the first element of the message, and once as the HMAC key.
+
+## Worked example {#sorted-hash-array}
+
+With Integrity Salt `3vv9wu3a18` and these parameters:
+
+```json
+{
+  "pp_Amount": "25000",
+  "pp_MerchantID": "MC25041",
+  "pp_MerchantMPIN": "1234",
+  "pp_Password": "sz1v4agvyf",
+  "pp_TxnCurrency": "PKR",
+  "pp_TxnRefNo": "T20220518150213"
+}
+```
+
+Sorted by name and joined by `&`, the values are:
+
+```
+25000&MC25041&1234&sz1v4agvyf&PKR&T20220518150213
+```
+
+After prepending the Integrity Salt:
+
+```
+3vv9wu3a18&25000&MC25041&1234&sz1v4agvyf&PKR&T20220518150213
+```
+
+That string is then hashed with HMAC-SHA256 using the key `3vv9wu3a18`.
+
+## Rules that are easy to miss {#rules-that-are-easy-to-miss}
+
+- **Empty fields are sent but not hashed.** A parameter you are told to "leave empty" must still appear in the request as `""`. It simply does not contribute a value to the hash string.
+- **`pp_SecureHash` is never part of its own input.** Remove it from the parameter set before hashing.
+- **Sorting is by name; concatenation is of values.** The names never appear in the hash string.
+- **Case of the output does not matter.** PHP's `hash_hmac` returns lowercase hex; JazzCash response samples show uppercase. Compare case-insensitively.
+- **Uppercase letters sort before lowercase** in ASCII, and `_` (0x5F) sorts before `m` (0x6D), so every `pp_*` field precedes every `ppmpf_*` field.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Hash mismatch on every request | Salt appended instead of prepended | Build `salt & v1 & v2 …` |
+| Hash mismatch on every request | Salt used only as the HMAC key | Prepend it to the message as well |
+| Hash mismatch when some fields are blank | Empty fields included in the hash string | Skip empty values when hashing, but still send them |
+| Hash mismatch on retries only | A stale `pp_SecureHash` left in the payload and hashed | Exclude `pp_SecureHash` before hashing |
+| Works in one language, fails in another | Locale-sensitive sorting | Sort by raw ASCII, never with a locale-aware comparator |
+| Intermittent mismatch | Payload mutated after the hash was computed | Hash last, from the exact map you transmit |
+| Mismatch only when an amount is zero-like | PHP's loose `$value != ""` drops integer `0` | Compare with `(string)$value !== ''` |
+
+## Divergences from the official PHP sample {#php-sample-divergences}
+
+The sample published in the redirection guides has two defects worth correcting in your own code:
+
+- `if ($value != null && $value != "")` evaluates false for integer `0`, silently dropping that field.
+  Use `if ($value !== null && (string)$value !== '')`.
+- `ksort($Params)` uses `SORT_REGULAR`. Use `ksort($Params, SORT_STRING)` so ordering is a plain string comparison, as the specification requires.

package/knowledge/docs/index.json

@@ -0,0 +1,189 @@
+{
+  "corpusVersion": "2026",
+  "note": "Document-level metadata. Sections are derived from the '## Title {#anchor}' headings in each markdown file, so the two cannot drift.",
+  "documents": [
+    {
+      "docId": "hmac-sha256-calculation",
+      "title": "HMAC-SHA256 (pp_SecureHash) Calculation",
+      "sourcePdf": "docs/integration_documents/How is HMAC-SHA256 calculated (2026).pdf",
+      "version": "2026",
+      "flowIds": [],
+      "keywords": [
+        "hash",
+        "secure hash",
+        "pp_SecureHash",
+        "hmac",
+        "sha256",
+        "integrity salt",
+        "hash key",
+        "mismatch",
+        "sorting",
+        "signature"
+      ]
+    },
+    {
+      "docId": "card-page-redirection",
+      "title": "Card Payment — Page Redirection / Checkout v1.1",
+      "sourcePdf": "docs/integration_documents/Page Redirection v1.1 template for (Card Payments)_2026.pdf",
+      "version": "2026",
+      "flowIds": ["card-page-redirection-v1.1"],
+      "keywords": [
+        "card",
+        "checkout",
+        "hosted page",
+        "redirection",
+        "MPAY",
+        "landing page",
+        "return url",
+        "voucher",
+        "credit",
+        "debit"
+      ]
+    },
+    {
+      "docId": "bnpl-guide",
+      "title": "Buy Now Pay Later (BNPL)",
+      "sourcePdf": "docs/integration_documents/Page Redirection v1.1 template for (BNPL)_2026.pdf",
+      "version": "2026",
+      "flowIds": ["bnpl-page-redirection-v1.1", "refund-bnpl"],
+      "keywords": ["bnpl", "buy now pay later", "instalments", "credit", "redirection", "refund"]
+    },
+    {
+      "docId": "mwallet-rest-v1-1",
+      "title": "MWallet REST API v1.1 (without CNIC)",
+      "sourcePdf": "docs/integration_documents/MWallet API v1.1 (Without CNIC)_Merchant Guide_(2026).pdf",
+      "version": "2026",
+      "flowIds": ["mwallet-rest-v1.1"],
+      "keywords": [
+        "mwallet",
+        "mobile wallet",
+        "mobile account",
+        "rest",
+        "v1.1",
+        "ppmpf_1",
+        "without cnic",
+        "direct debit"
+      ]
+    },
+    {
+      "docId": "mwallet-rest-v2-0-cnic",
+      "title": "MWallet REST API v2.0 (with CNIC)",
+      "sourcePdf": "docs/integration_documents/MWallet API V.2.0 (With CNIC)_Merchant Guide_(2026).pdf",
+      "version": "2026",
+      "flowIds": ["mwallet-rest-v2.0-cnic"],
+      "keywords": ["mwallet", "mobile wallet", "cnic", "rest", "v2.0", "pp_MobileNumber", "identity"]
+    },
+    {
+      "docId": "mwallet-recurring",
+      "title": "MWallet Recurring Payments — Linking, Token Payment, Token Inquiry, Token Delete",
+      "sourcePdf": "docs/integration_documents/MWallet Recurring Payments (2026).pdf",
+      "version": "2026",
+      "flowIds": ["wallet-linking-portal", "mwallet-token-pay-v4.0", "token-inquiry-v1", "token-delete-v1"],
+      "keywords": [
+        "recurring",
+        "subscription",
+        "wallet linking",
+        "payment token",
+        "token",
+        "mpin",
+        "v4.0",
+        "pp_RequestID",
+        "unlink"
+      ]
+    },
+    {
+      "docId": "status-inquiry",
+      "title": "Status Inquiry API",
+      "sourcePdf": "docs/integration_documents/Status Inquiry Guide (2026).pdf",
+      "version": "2026",
+      "flowIds": ["status-inquiry-v1.1", "status-inquiry-v2.0"],
+      "keywords": [
+        "status",
+        "inquiry",
+        "enquiry",
+        "pending",
+        "reconciliation",
+        "121",
+        "pp_PaymentResponseCode",
+        "missing transaction"
+      ]
+    },
+    {
+      "docId": "status-inquiry-2025-26",
+      "title": "Status Inquiry Guide (2025-26 edition — superseded)",
+      "sourcePdf": "docs/integration_documents/Status Inquiry Guide_Merchants_Latest_2025-26.pdf",
+      "version": "2025-26",
+      "flowIds": ["status-inquiry-v1.1", "status-inquiry-v2.0"],
+      "keywords": ["status", "inquiry", "superseded", "older edition", "contradiction", "copy-paste"]
+    },
+    {
+      "docId": "ipn-implementation",
+      "title": "IPN (Instant Payment Notification) Implementation",
+      "sourcePdf": "docs/integration_documents/IPN Guide for Merchants (REST API)_2026.pdf",
+      "version": "2026",
+      "flowIds": [],
+      "keywords": [
+        "ipn",
+        "instant payment notification",
+        "webhook",
+        "callback",
+        "notification",
+        "retry",
+        "idempotent",
+        "listener",
+        "60 seconds"
+      ]
+    },
+    {
+      "docId": "card-refund",
+      "title": "Card Refund API",
+      "sourcePdf": "docs/integration_documents/Card Refund API (2026).pdf",
+      "version": "2026",
+      "flowIds": ["refund-card-v1.1", "refund-card-v2.0"],
+      "keywords": ["refund", "card", "reversal", "mpin", "partial refund", "TotalRefundAmount", "mpgs"]
+    },
+    {
+      "docId": "mwallet-refund",
+      "title": "Mobile Wallet Refund API v1.1",
+      "sourcePdf": "docs/integration_documents/Mobile Wallet Refund API (2026).pdf",
+      "version": "2026",
+      "flowIds": ["refund-mwallet-v1.1"],
+      "keywords": ["refund", "mwallet", "mobile wallet", "reversal", "mpin", "partial refund"]
+    },
+    {
+      "docId": "portal-guide",
+      "title": "JazzCash Merchant Portal",
+      "sourcePdf": "docs/integration_documents/Portal Guide 2026.pdf",
+      "version": "2026",
+      "flowIds": [],
+      "keywords": [
+        "portal",
+        "dashboard",
+        "credentials",
+        "integrity salt",
+        "login",
+        "otp",
+        "role management",
+        "transaction detail report",
+        "tdr",
+        "reports"
+      ]
+    },
+    {
+      "docId": "shopify-guide",
+      "title": "Shopify Integration",
+      "sourcePdf": "docs/integration_documents/Shopify Guide.pdf",
+      "version": "2026",
+      "flowIds": [],
+      "keywords": ["shopify", "app", "plugin", "ecommerce", "migration", "old app", "storefront"]
+    },
+    {
+      "docId": "wordpress-guide",
+      "title": "WordPress / WooCommerce Integration",
+      "sourcePdf": "docs/integration_documents/WordPress Integration Guide (2026).pdf",
+      "version": "2026",
+      "flowIds": [],
+      "keywords": ["wordpress", "woocommerce", "plugin", "wp", "ecommerce", "wc-api", "jazzcash_ipn_v2"]
+    }
+  ]
+}

package/knowledge/docs/ipn-implementation.md

@@ -0,0 +1,89 @@
+# IPN (Instant Payment Notification) Implementation
+
+Source: `IPN Guide for Merchants (REST API)_2026.pdf`, version 2026.
+
+## Overview {#overview}
+
+JazzCash notifies merchants when a payment completes. After a transaction, the payment gateway posts the transaction status to a REST endpoint the merchant exposes.
+
+IPN is a **mandatory** integration for the MWallet REST and recurring flows.
+
+## Retry behaviour {#retry-behaviour}
+
+If the merchant returns a failed response, or if no response is received **within 60 seconds**, JazzCash retries **two more times**, with a short delay between attempts.
+
+Two consequences for your handler:
+
+- It must respond well inside 60 seconds. Acknowledge first, then do the slow work asynchronously.
+- It must be **idempotent**. The same notification can legitimately arrive three times, and reprocessing it must not fulfil an order twice or double-count revenue.
+
+## Expected response from the merchant {#expected-ipn-response}
+
+```json
+{
+  "pp_ResponseCode": "000",
+  "pp_ResponseMessage": "IPN received successfully",
+  "pp_SecureHash": "{{Your Generated Secure Hash}}"
+}
+```
+
+`000` here means "I received this notification", not "the payment succeeded".
+
+## Response codes inside the notification {#response-codes}
+
+| Code | Meaning |
+| --- | --- |
+| `121` | Successful transaction |
+| `199`, `999`, others | Failed transaction |
+
+Note that in an **inbound IPN** the payment outcome arrives in `pp_ResponseCode`, whereas in a Status Inquiry response it arrives in `pp_PaymentResponseCode`. The same field name carries a different meaning depending on which direction the message travels.
+
+## Sample notification {#sample-notification}
+
+```json
+{
+  "pp_Version": "2.0",
+  "pp_TxnType": "MWALLET",
+  "pp_BankID": "",
+  "pp_ProductID": null,
+  "pp_Password": "0123456789",
+  "pp_TxnRefNo": "T20240418145702",
+  "pp_TxnDateTime": "20240418145702",
+  "pp_ResponseCode": "121",
+  "pp_ResponseMessage": "Transaction has been marked confirmed by Merchant.",
+  "pp_AuthCode": "060935465981",
+  "pp_SettlementExpiry": null,
+  "pp_RetreivalReferenceNo": "240418718258",
+  "pp_SecureHash": "2B47BCF7825FA27FC8B522292BC8D226213FCCDA685FC68A67EC20B10836E5B7"
+}
+```
+
+The sample endpoint given in the guide is a `beeceptor.com` test URL. Register your own URL under **Integration → Credentials**.
+
+## Verifying the notification {#verifying-the-notification}
+
+An IPN endpoint is a publicly reachable URL that marks orders as paid. Anyone can post to it.
+
+**Always verify `pp_SecureHash` before acting on a notification.** Recompute it from the received fields using your Integrity Salt and compare case-insensitively. Reject anything that does not match.
+
+Note that the notification contains `null` values (`pp_ProductID`, `pp_SettlementExpiry`) even though merchants are told never to send `null` in requests. Treat a `null` as empty when recomputing the hash.
+
+## Handler checklist {#handler-checklist}
+
+- [ ] Verify `pp_SecureHash` before anything else.
+- [ ] Look up the order by `pp_TxnRefNo`.
+- [ ] Check the amount matches the order you recorded.
+- [ ] If the order is already marked paid, return `000` and stop — the notification is a retry.
+- [ ] Interpret `pp_ResponseCode`: `121` succeeded, `199`/`999` failed, anything else is unresolved.
+- [ ] Respond with `000` within 60 seconds.
+- [ ] Reconcile against the Status Inquiry API for any transaction where no IPN arrived.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Orders fulfilled twice | Handler is not idempotent and JazzCash retried | Key on `pp_TxnRefNo` and ignore repeats |
+| JazzCash reports IPN failures | Handler does slow work before responding | Acknowledge first, process asynchronously |
+| Fraudulent "paid" orders | `pp_SecureHash` not verified | Verify before acting |
+| No IPN ever arrives | IPN URL not registered, or unreachable from the internet | Register it under Integration → Credentials and confirm it is publicly reachable |
+| Hash never matches | `null` values not normalised to empty | Treat `null` as `""` when recomputing |