@atbas/m-mcp 0.1.0

package/knowledge/docs/mwallet-recurring.md

@@ -0,0 +1,117 @@
+# MWallet Recurring Payments — Linking, Token Payment, Token Inquiry, Token Delete
+
+Source: `MWallet Recurring Payments (2026).pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Recurring mobile-wallet payments in JazzCash are a two-step arrangement. The customer authorises a link once, through a hosted portal, which yields a **payment token**. The merchant then charges that token as often as needed, with no further customer interaction.
+
+## Wallet linking via portal {#wallet-linking-via-portal}
+
+The merchant posts a signed form; the customer enters their MPIN on the JazzCash page; the result is returned to the merchant's Return URL.
+
+Form action, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/WalletLinkingPortal/wallet/LinkWallet
+```
+
+Parameters: `pp_MerchantID`, `pp_Password`, `pp_MSISDN`, `pp_RequestID`, `pp_ReturnURL`, `pp_SecureHash`.
+
+- `pp_RequestID` must be unique for every linking attempt.
+- `pp_ReturnURL` must be pre-registered with JazzCash.
+
+## Shared rules {#shared-rules}
+
+The same payload rules apply as for the MWallet REST APIs: string values in double quotes, unused parameters as `""` rather than `null`, no fields added or removed, constants unmodified, PKR only with amounts in minor units, `YYYYMMDDHHMMSS` timestamps in Pakistan Standard Time, and a freshly generated `pp_SecureHash` per attempt. Status Inquiry and IPN are mandatory; Refund is optional.
+
+## Two defects in the official sample {#sample-defects}
+
+The guide's sample HTML page contains two problems that must not be carried into production.
+
+1. **The form action points at a different host.** The sample posts to `https://pgw.jazzcash.com.pk/WalletLinkingPortal/wallet/LinkWallet`, while the endpoint table and the screenshot in the same document give `https://onlinepayments.jazzcash.com.pk/payment-orchestrator/WalletLinkingPortal/wallet/LinkWallet`. Use the endpoint from the table.
+
+2. **The Integrity Salt is embedded in browser JavaScript.** The sample contains `const INTEGRITY_SALT = "Your Integrity Salt";` and computes the hash client-side with CryptoJS. The Integrity Salt is the HMAC key. Publishing it in page source lets anyone forge a valid `pp_SecureHash` for your merchant account. **Compute the hash on your server** and render only the finished hash into the form.
+
+The sample also selects hash fields with `element.id.startsWith("pp_")`, whereas the official PHP samples include any non-empty field including `ppmpf_*`. This flow declares no `ppmpf_*` fields, so the two rules agree here.
+
+## MWallet Pay via Token {#mwallet-pay-via-token}
+
+Endpoint, identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v4/rest/payments/m-wallet
+```
+
+Sample request:
+
+```json
+{
+  "pp_MerchantID": "{{Your Merchant ID}}",
+  "pp_Password": "{{Your Password}}",
+  "pp_PaymentToken": "{{Payment Token}}",
+  "pp_TxnRefNo": "T20251117153308",
+  "pp_Amount": "100",
+  "pp_TxnCurrency": "PKR",
+  "pp_TxnDateTime": "20251117153308",
+  "pp_BillReference": "B20251117153308",
+  "pp_Description": "MWALLET Payment v4.0",
+  "pp_TxnExpiryDateTime": "20250926003252",
+  "pp_SecureHash": "42D2324F1F3947A5F374A5886D09C15A1B6F567B5F110276AFD6E958304CD57A"
+}
+```
+
+> The sample's `pp_TxnExpiryDateTime` (`20250926003252`) is nearly two months **earlier** than its `pp_TxnDateTime` (`20251117153308`). Ignore the sample values and set the expiry one day after the transaction, as the shared rules require.
+
+Sample response:
+
+```json
+{
+  "pp_ResponseCode": "000",
+  "pp_ResponseMessage": "Thank you for using JazzCash. Your transaction was processed successfully.",
+  "pp_Amount": "100",
+  "pp_RetreivalReferenceNo": "202511171535408897538884",
+  "pp_TxnRefNo": "T20251117153308",
+  "pp_PaymentToken": "{{Payment Token}}",
+  "pp_DiscountedAmount": "",
+  "pp_SecureHash": "A632596C21414A1DB4B4AE799B976..."
+}
+```
+
+## Token Inquiry {#token-inquiry}
+
+Retrieves the payment token currently associated with a customer's mobile number.
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/payment/api/v1/mobile-tokens/inquiry
+```
+
+Request: `pp_RequestID`, `pp_MobileNumber`, `pp_MerchantID`, `pp_Password`, `pp_SecureHash`.
+
+Response carries `pp_PaymentToken` alongside `pp_ResponseCode` `000` and the message "your payment token is active."
+
+- `pp_RequestID` must be unique for every attempt.
+- `pp_MobileNumber` is the number to query.
+
+## Delete Token {#delete-token}
+
+Deletes an existing payment token, removing its association with the customer's account.
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/payment/api/v1/mobile-tokens/delete
+```
+
+Request: `pp_RequestID`, `pp_MerchantID`, `pp_Password`, `pp_PaymentToken`, `pp_SecureHash`.
+
+- `pp_RequestID` must be unique for every attempt.
+- `pp_PaymentToken` is the token to delete.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Linking page not found | Sample's `pgw.jazzcash.com.pk` host used | Use the endpoint from the guide's table |
+| Anyone can forge your hashes | Integrity Salt shipped to the browser | Compute the hash server-side |
+| Duplicate request rejected | `pp_RequestID` reused | Generate a fresh unique value per attempt |
+| Token payment rejected as expired | Expiry copied from the sample | Set the expiry one day after the transaction |
+| Token payment fails after months of working | Customer unlinked the wallet | Call Token Inquiry before charging, and handle an inactive token |

package/knowledge/docs/mwallet-refund.md

@@ -0,0 +1,65 @@
+# Mobile Wallet Refund API v1.1
+
+Source: `Mobile Wallet Refund API (2026).pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Refunds a completed JazzCash mobile wallet transaction, in whole or in part. The Refund API is documented as **optional**, unlike Status Inquiry and IPN, which are mandatory.
+
+The Merchant MPIN must be saved in the merchant portal before a refund will succeed.
+
+## Creating a sandbox account {#create-a-sandbox-account}
+
+Sign up at <https://onlinepayments.jazzcash.com.pk/sandbox-frontend/>, share your Merchant ID with JazzCash, and take your credentials from **Integration → Credentials**, where you also register your Return URL and IPN URL.
+
+## Endpoint {#api-endpoints}
+
+Identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/m-wallet/refund
+```
+
+## Sample request {#sample-request}
+
+```json
+{
+  "pp_MerchantID": "YOUR MERCHANT ID",
+  "pp_Password": "YOUR PASSWORD",
+  "pp_TxnRefNo": "T20251224191536",
+  "pp_Amount": "100",
+  "pp_SecureHash": "928c8fdffd052ef0b940d6bd8661e1c9b78afe3ad17ebdc074a48f36738e2603",
+  "pp_TxnCurrency": "PKR",
+  "pp_MerchantMPIN": "YOUR MERCHANT MPIN"
+}
+```
+
+`pp_TxnRefNo` is the reference of the **original transaction** being refunded, not a new one.
+
+## Sample response {#sample-response}
+
+```json
+{
+  "pp_ResponseCode": "000",
+  "pp_ResponseMessage": "Thank you for using JazzCash. Your transaction was processed successfully.",
+  "pp_RefundAmount": "100",
+  "pp_TotalRefundAmount": "100",
+  "pp_SecureHash": "20B6593DFC995F98A54EC1B397C150085A2CC53DDC6751B72C6B4E927977CB35"
+}
+```
+
+Unlike the card and BNPL refund responses, the mobile wallet refund response **does** use the `pp_` prefix throughout.
+
+## Partial refunds {#partial-refunds}
+
+`pp_RefundAmount` is the amount refunded by this call. `pp_TotalRefundAmount` is the cumulative total refunded against the original transaction. Track the cumulative figure so repeated partial refunds cannot exceed the original amount.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Refund rejected | MPIN not saved in the merchant portal | Save it in the portal, then retry |
+| Transaction not found | A newly generated `pp_TxnRefNo` sent | Send the original transaction's reference |
+| Refund rejected as too large | Cumulative refunds exceed the original | Check `pp_TotalRefundAmount` before refunding again |
+| Amount off by 100× | Refund amount in major units | `pp_Amount` is in minor units |
+| Field not found | Card refund field names assumed | Mobile wallet refunds use `pp_`-prefixed fields |

package/knowledge/docs/mwallet-rest-v1-1.md

@@ -0,0 +1,126 @@
+# MWallet REST API v1.1 (without CNIC)
+
+Source: `MWallet API v1.1 (Without CNIC)_Merchant Guide_(2026).pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Server-to-server debit of a JazzCash mobile account, without CNIC verification. There is no hosted page: your server posts JSON, and the customer approves the transaction on their handset.
+
+## Creating a sandbox account {#create-a-sandbox-account}
+
+1. Sign up at <https://onlinepayments.jazzcash.com.pk/sandbox-frontend/> and share your Merchant ID with JazzCash so the payment option can be enabled.
+2. In **Integration → Credentials**, record the Merchant ID, Password and Integrity Salt, and enter your Return URL and IPN URL.
+
+## Endpoint {#endpoint}
+
+Identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/m-wallet
+```
+
+## Implementation notes {#implementation-notes}
+
+The sections below are the rules JazzCash states for this flow. They are the ones merchants most often break, and each maps directly to a validation check the MCP server performs.
+
+## Request payload rules {#request-payload-rules}
+
+- All parameter values must be passed as strings, enclosed in double quotes.
+- Parameters with no value must remain as empty strings `""`. **Do not replace them with `null` and do not remove them from the request.**
+- Parameter names must not be changed and must exactly match the documentation.
+- No parameters may be added or removed from the request payload.
+- Mandatory constant parameters — `pp_Language`, `pp_TxnCurrency`, `pp_TxnType`, `pp_Version` — must not be modified.
+
+## Mandatory companion integrations {#mandatory-api-integrations}
+
+- **Status Inquiry API — mandatory.**
+- **IPN (Instant Payment Notification) — mandatory.**
+- Refund API — optional.
+
+## Currency and amount handling {#currency-and-amount-handling}
+
+- The gateway processes transactions only in PKR. No currency conversion is performed.
+- `pp_Amount` must be multiplied by 100 before sending: 100.00 is sent as `"10000"`.
+- The last two digits are treated as decimals.
+- When processing the response, divide by 100 to obtain the actual value.
+
+## Transaction references {#transaction-reference-requirements}
+
+- `pp_TxnRefNo` must be unique for every transaction. Recommended format: the first three letters of the merchant's domain name followed by the transaction date and time, e.g. `Goo20230208115409`. The sample annotates the field as 20 alphanumeric characters.
+- `pp_BillReference` is mandatory, may be duplicated across transactions, and must contain only `A–Z`, `a–z` and `0–9`. Spaces and special characters are not allowed.
+
+## Date and time {#date-and-time-parameters}
+
+All values are in Pakistan Standard Time.
+
+- `pp_TxnDateTime` — current transaction date and time, `YYYYMMDDHHMMSS`.
+- `pp_TxnExpiryDateTime` — one day after the transaction date, `YYYYMMDDHHMMSS`.
+
+## Return URL {#return-url-configuration}
+
+`pp_ReturnURL` is mandatory. It must be pre-registered with JazzCash and is part of the merchant authentication profile. The same URL must be used for every request; any change results in request validation failure.
+
+## Secure hash {#secure-hash-generation}
+
+A unique `pp_SecureHash` must be generated for every transaction, for both request submission and response verification, strictly per the JazzCash hashing guidelines.
+
+## Sample request {#sample-request}
+
+```json
+{
+  "pp_Amount": "200",
+  "pp_BillReference": "B20251120115142",
+  "pp_Description": "Test case description",
+  "pp_Language": "EN",
+  "pp_MerchantID": "[Your Merchant ID]",
+  "pp_Password": "[Your Password]",
+  "pp_ReturnURL": "[your return URL]",
+  "pp_SecureHash": "DE2665AA0C04B6E53996CA0D7FEC355D2F4CCEEA04D6EEBC3AAD5DA0A262AA97",
+  "pp_TxnCurrency": "PKR",
+  "pp_TxnDateTime": "20251120115142",
+  "pp_TxnExpiryDateTime": "20251121115142",
+  "pp_TxnRefNo": "T20251120115142",
+  "pp_TxnType": "MWALLET",
+  "pp_Version": "1.1",
+  "ppmpf_1": "[Mobile Wallet Number]",
+  "ppmpf_2": "",
+  "ppmpf_3": "",
+  "ppmpf_4": "",
+  "ppmpf_5": ""
+}
+```
+
+`ppmpf_1` carries the customer's mobile wallet number and is **mandatory in this flow only**. Every other guide instructs you to leave it empty. Because it is non-empty it also participates in the secure hash.
+
+## Sample response {#sample-response}
+
+```json
+{
+  "pp_Amount": "200",
+  "pp_BillReference": "B20251120115142",
+  "pp_Language": "EN",
+  "pp_MerchantID": "XXXXXX",
+  "pp_ResponseCode": "000",
+  "pp_ResponseMessage": "Thank you for Using JazzCash, your transaction was successful.",
+  "pp_RetreivalReferenceNo": "202511201152000464544243",
+  "pp_SecureHash": "78BC9B7231A569C4AB8C4E8ED36D2CA76379D095E629C2EC915BF1357BB4DF7F",
+  "pp_TxnCurrency": "PKR",
+  "pp_TxnDateTime": "20251120115142",
+  "pp_TxnRefNo": "T20251120115142",
+  "pp_TxnType": "MWALLET",
+  "pp_Version": "1.1",
+  "ppmpf_1": "03123456789"
+}
+```
+
+`pp_RetreivalReferenceNo` is spelled with that transposition in the gateway's own response. Match the gateway's spelling when reading it.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Hash mismatch | `ppmpf_1` populated but excluded from the hash | Non-empty `ppmpf_*` fields participate in the hash |
+| Request rejected | A field sent as `null` | Send `""` instead |
+| Request rejected | An extra field added to the payload | Send exactly the documented field set |
+| Customer charged 100× too little | `pp_Amount` sent in major units | Multiply by 100 |
+| Validation failure | `pp_ReturnURL` differs from the registered value | Send the registered URL exactly |

package/knowledge/docs/mwallet-rest-v2-0-cnic.md

@@ -0,0 +1,113 @@
+# MWallet REST API v2.0 (with CNIC)
+
+Source: `MWallet API V.2.0 (With CNIC)_Merchant Guide_(2026).pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Server-to-server debit of a JazzCash mobile account with CNIC verification. Structurally similar to v1.1, but the customer's mobile number and CNIC fragment are first-class parameters rather than being carried in `ppmpf_1`.
+
+## Creating a sandbox account {#create-a-sandbox-account}
+
+Sign up at <https://onlinepayments.jazzcash.com.pk/sandbox-frontend/>, share your Merchant ID with JazzCash to have the option enabled, then take your credentials and register your Return URL and IPN URL under **Integration → Credentials**.
+
+## Endpoint {#endpoint}
+
+Identical for both environments:
+
+```
+https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v2/rest/payments/m-wallet
+```
+
+## Implementation notes {#implementation-notes}
+
+The sections below are the rules JazzCash states for this flow. They are the ones merchants most often break, and each maps directly to a validation check the MCP server performs.
+
+## Request payload rules {#request-payload-rules}
+
+- All values are strings in double quotes.
+- Unused parameters remain `""` — never `null`, never omitted.
+- Parameter names must match the documentation exactly.
+- No parameters may be added or removed.
+- The constants `pp_Language`, `pp_TxnCurrency`, `pp_TxnType` and `pp_Version` must not be modified.
+
+## Mandatory companion integrations {#mandatory-api-integrations}
+
+- **Status Inquiry API — mandatory.**
+- **IPN — mandatory.**
+- Refund API — optional.
+
+## Currency and amount handling {#currency-and-amount-handling}
+
+PKR only, no conversion. `pp_Amount` is multiplied by 100 before sending; the last two digits are decimals; divide by 100 when reading a response.
+
+## Transaction references {#transaction-reference-requirements}
+
+`pp_TxnRefNo` unique per transaction, recommended as a three-letter domain prefix plus `YmdHis`. `pp_BillReference` mandatory, alphanumeric only, may repeat.
+
+## Date and time {#date-and-time-parameters}
+
+`pp_TxnDateTime` and `pp_TxnExpiryDateTime` are `YYYYMMDDHHMMSS` in Pakistan Standard Time, the expiry one day after the transaction.
+
+## Validation checklist {#general-validation-checklist}
+
+Before sending, confirm that every mandatory parameter is present, every empty parameter is `""`, `pp_Amount` has been multiplied by 100, `pp_TxnRefNo` is unique, and `pp_SecureHash` has been freshly generated.
+
+## Sample request {#sample-request}
+
+```json
+{
+  "pp_Amount": "100",
+  "pp_BankID": "",
+  "pp_BillReference": "billRef185",
+  "pp_CNIC": "{{Last 6-digits}}",
+  "pp_Description": "product description",
+  "pp_Language": "EN",
+  "pp_MerchantID": "{{MerchantID}}",
+  "pp_MobileNumber": "{{JazzcashMobileAccount}}",
+  "pp_Password": "{{Password}}",
+  "pp_ProductID": "",
+  "pp_SecureHash": "CD4DA5575F6CC08F9A0B78D414B91657FF0AACFDBE8FF691F8A1F80C6E0C0C4F",
+  "pp_SubMerchantID": "",
+  "pp_TxnCurrency": "PKR",
+  "pp_TxnDateTime": "20250908151702",
+  "pp_TxnExpiryDateTime": "20250910151702",
+  "pp_TxnRefNo": "T20250908151702",
+  "ppmpf_1": "",
+  "ppmpf_2": "",
+  "ppmpf_3": "",
+  "ppmpf_4": "",
+  "ppmpf_5": ""
+}
+```
+
+Two things about this sample are worth noting:
+
+- **`pp_CNIC` is the last six digits of the CNIC**, not the whole number.
+- **The request carries neither `pp_Version` nor `pp_TxnType`**, unlike v1.1. The response echoes both back as empty strings. Send exactly the documented field set: adding either would change the hash and break the "no parameters may be added" rule.
+- The sample's expiry (`20250910151702`) is **two days** after its transaction time, contradicting the same document's "one day after" rule. Follow the rule, not the sample.
+
+## Sample response {#sample-response}
+
+```json
+{
+  "pp_Amount": "100",
+  "pp_AuthCode": "088911015335",
+  "pp_BillReference": "billRef185",
+  "pp_ResponseCode": "000",
+  "pp_ResponseMessage": "Thank you for Using JazzCash, your transaction was successful.",
+  "pp_RetreivalReferenceNo": "202509081757326660695254",
+  "pp_SecureHash": "80609D35A17575E249E99D20AE83B9EA25BDAEAF3EB17FD19B7055502503E2B7",
+  "pp_TxnCurrency": "PKR",
+  "pp_TxnDateTime": "20250908151702",
+  "pp_TxnRefNo": "T20250908151702"
+}
+```
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| CNIC rejected | Full 13-digit CNIC sent | Send only the last six digits |
+| Request rejected | `pp_Version` or `pp_TxnType` added by analogy with v1.1 | v2.0 does not declare them |
+| Hash mismatch | Empty `ppmpf_*` fields included in the hash string | Send them as `""` but exclude them from the hash |
+| Wallet not found | Mobile number in international format | Use the local `03XXXXXXXXX` form |

package/knowledge/docs/portal-guide.md

@@ -0,0 +1,45 @@
+# JazzCash Merchant Portal
+
+Source: `Portal Guide 2026.pdf`, version 2026.
+
+## Logging in {#log-into-merchant-portal}
+
+Portal URL: <https://onlinepayments.jazzcash.com.pk/merchant-frontend/login>
+
+- **Institution ID (Merchant ID) and Username** are provided by the JazzCash team.
+- **Password** arrives by email and must be reset before first use.
+- After clicking Login you receive a one-time password by SMS **and** email. If it does not arrive, use the Resend button.
+
+After logging in, the dashboard shows the functions available to you in the left pane, according to your user rights and transaction permissions.
+
+## Where the integration credentials live {#credentials}
+
+Integration credentials — Merchant ID, Password, Integrity Salt — are under **Integration → Credentials**, along with the fields for your Return URL and IPN URL. The sandbox portal (<https://onlinepayments.jazzcash.com.pk/sandbox-frontend/>) has the same layout.
+
+The Merchant MPIN is also stored here, and must be saved before any refund will succeed.
+
+## Role management {#role-management}
+
+The Role Management tab adds and updates the users who may access the merchant portal.
+
+- **Creating a user** — from Role Management, click Create to add a user, a description and a role.
+- **User management** — update a user's username or email, or delete the user.
+
+## Transaction management {#transaction-management}
+
+Transaction Management shows transaction history and is where reports are extracted.
+
+1. Click the system date and select the desired From–To date and time range.
+2. Click Export. Two options appear: **Export** (the full Transaction Detail Report, or TDR) and **Export Summary**.
+3. A success message confirms the extract has been queued.
+4. Open the **Reports** tab to follow it. The status changes from **Processing** to **Ready** when the TDR is downloadable.
+
+## Common questions {#common-questions}
+
+| Question | Answer |
+| --- | --- |
+| Where is my Integrity Salt? | Integration → Credentials, in the portal for the environment you are calling |
+| Why is my payment method missing? | JazzCash must enable it against your Merchant ID; send them the ID and ask |
+| Why do refunds fail? | The Merchant MPIN must be saved in the portal, not only sent in the request |
+| Where is my transaction report? | Transaction Management → Export, then collect it from the Reports tab once it reads Ready |
+| I did not receive the login OTP | It is sent by both SMS and email; use Resend |

package/knowledge/docs/shopify-guide.md

@@ -0,0 +1,74 @@
+# Shopify Integration
+
+Source: `Shopify Guide.pdf`, version 2026.
+
+## Introduction {#introduction}
+
+Installs the JazzCash Shopify app in a Shopify store. This guide covers migration from the older JazzCash app, which must be deactivated but **not uninstalled** until outstanding transactions are settled.
+
+## Before you begin {#before-you-begin}
+
+- Ensure all pending transactions in the old JazzCash app are captured, settled or refunded.
+- Export any historical transaction reports you need from the old app.
+- Have your **Merchant ID**, **Integrity Salt** and **Password** to hand.
+
+## Step 1 — Deactivate the old payment method {#step-1-deactivate}
+
+1. Shopify Admin → **Settings → Payments**.
+2. Find the existing JazzCash payment method.
+3. Click **Manage**, then **Deactivate**.
+
+**Do not uninstall the old app yet.** Uninstalling before outstanding transactions settle loses access to them.
+
+## Step 2 — Install the new app {#step-2-install}
+
+1. Open the official listing: <https://apps.shopify.com/jazzcash>
+2. Click **Install**.
+3. Approve the requested permissions.
+
+## Step 3 — Onboarding {#step-3-onboarding}
+
+The onboarding screen asks for:
+
+1. Merchant ID
+2. Integrity Salt
+3. Password
+
+Click **Continue / Save**. Enter the credentials carefully: a mistake here surfaces later as payment failures rather than as a setup error.
+
+## Step 4 — Activate the new payment method {#step-4-activate}
+
+Shopify Admin → **Settings → Payments** → find the new JazzCash method → **Activate**.
+
+## Step 5 — Check settings and transaction logs {#step-5-verify}
+
+Click **Open App**, confirm your credentials, and open the **Transactions** tab to see the transaction log.
+
+## Step 6 — Test the integration {#step-6-test}
+
+Before going live:
+
+1. Place a small-value test order.
+2. Confirm the payment redirects correctly.
+3. Confirm the payment status updates in Shopify.
+4. Confirm the order is marked **Paid** after a successful transaction.
+
+## Step 7 — Uninstall the old app {#step-7-uninstall}
+
+Only once all old transactions are settled and the new app is activated and tested: Shopify Admin → **Settings → Apps and Sales Channels** → uninstall the old JazzCash app.
+
+## Step 8 — Refunds {#step-8-refunds}
+
+Refunds are processed from the **order details** page; enter the quantity to refund.
+
+Before attempting a refund, confirm that test transactions have been performed and that **the MPIN is already saved in the merchant portal**. This is the usual cause of a refund failing in Shopify.
+
+## Common failures {#common-failures}
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Both JazzCash methods appear at checkout | Old method still active | Deactivate the old method in Settings → Payments |
+| Payments fail immediately after install | Credentials mistyped during onboarding | Re-check Merchant ID, Integrity Salt and Password in Open App |
+| Refund button does nothing | MPIN not saved in the merchant portal | Save it, then retry |
+| Old transactions inaccessible | Old app uninstalled too early | Contact JazzCash support; export reports before uninstalling in future |
+| Order not marked Paid | Payment succeeded but the status callback did not | Check the app's Transactions tab, then reconcile with Status Inquiry |

package/knowledge/docs/status-inquiry-2025-26.md

@@ -0,0 +1,32 @@
+# Status Inquiry Guide (2025-26 edition — superseded)
+
+Source: `Status Inquiry Guide_Merchants_Latest_2025-26.pdf`.
+
+> **Superseded.** Use [status-inquiry](status-inquiry.md), the 2026 edition. This document is retained only because merchants still hold copies of it and because it contains one contradiction worth being able to explain.
+
+## What differs from the 2026 edition {#differences}
+
+The endpoints, the request payloads and the response shapes are identical. Two things differ in the prose:
+
+1. The 2025-26 edition says only `pp_PaymentResponseCode` is considered when confirming a pending transaction. The 2026 edition adds `pp_Status` alongside it.
+
+2. **The sample response is internally contradictory.** It shows:
+
+   ```
+   pp_PaymentResponseCode: '121'   // documented as "completed"
+   pp_PaymentResponseMessage: 'Sorry! Your transaction was not successful. Please try again later.'
+   pp_Status: 'Completed'
+   ```
+
+   A `121` code with a `Completed` status is a successful transaction. The failure message beside it is a copy-paste error, not a real combination. The 2026 edition corrects it to "Thank you for using JazzCash. Your transaction was processed successfully."
+
+## Guidance {#guidance}
+
+If a merchant quotes the failure message while showing a `121` code, they are reading this edition. Point them at the 2026 guide. Do not build logic that reads `pp_PaymentResponseMessage` to decide an outcome — read the code.
+
+## Endpoints {#endpoints}
+
+Unchanged from the 2026 edition:
+
+- v1.1 — `https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/status/inquiry`
+- v2.0 — `https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v2/rest/payments/status/inquiry`