@atbas/m-mcp 0.1.0

package/knowledge/flows/mwallet-rest-v2.0-cnic.json

@@ -0,0 +1,197 @@
+{
+  "id": "mwallet-rest-v2.0-cnic",
+  "title": "MWallet REST API v2.0 (with CNIC)",
+  "provider": "jazzcash",
+  "product": "mwallet",
+  "version": "2.0",
+  "transport": "rest",
+  "summary": "Server-to-server mobile account debit with CNIC verification.",
+  "useWhen": "You want to charge a JazzCash mobile wallet and your account is enabled for CNIC verification.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v2/rest/payments/m-wallet",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v2/rest/payments/m-wallet"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "payment",
+  "constants": {
+    "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_BankID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\". Do not use null and do not omit it."
+    },
+    {
+      "name": "pp_BillReference",
+      "requirement": "mandatory",
+      "valueType": "bill-reference",
+      "notes": "Alphanumeric only. May repeat across transactions."
+    },
+    {
+      "name": "pp_CNIC",
+      "requirement": "mandatory",
+      "valueType": "cnic",
+      "notes": "Last six digits of the customer's CNIC.",
+      "sensitive": true
+    },
+    {
+      "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_MobileNumber",
+      "requirement": "mandatory",
+      "valueType": "msisdn",
+      "notes": "The customer's JazzCash mobile account number.",
+      "sensitive": true
+    },
+    {
+      "name": "pp_Password",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "From Integration > Credentials. Never render this into client-side code.",
+      "sensitive": true
+    },
+    {
+      "name": "pp_ProductID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\". Do not use null and do not omit it."
+    },
+    {
+      "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_SubMerchantID",
+      "requirement": "must-be-empty",
+      "valueType": "string",
+      "notes": "Send as \"\". Do not use null and do not omit it."
+    },
+    {
+      "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": "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."
+    }
+  ],
+  "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_AuthCode", "pp_RetreivalReferenceNo"]
+  },
+  "companionFlows": ["status-inquiry-v2.0", "refund-mwallet-v1.1"],
+  "docRefs": [
+    {
+      "docId": "mwallet-rest-v2-0-cnic",
+      "sectionId": "implementation-notes",
+      "label": "MWallet API v2.0 (With 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": "v2-request-omits-version-and-txntype",
+      "summary": "The v2.0 request sample carries neither pp_Version nor pp_TxnType",
+      "detail": "Unlike v1.1, the documented v2.0 request payload omits both fields; the response echoes them back as empty strings.",
+      "guidance": "Send exactly the documented field set. Adding pp_Version or pp_TxnType would change the hash and breaks the guide's rule that no parameters may be added."
+    }
+  ]
+}

package/knowledge/flows/mwallet-token-pay-v4.0.json

@@ -0,0 +1,130 @@
+{
+  "id": "mwallet-token-pay-v4.0",
+  "title": "MWallet Pay via Token v4.0",
+  "provider": "jazzcash",
+  "product": "mwallet",
+  "version": "4.0",
+  "transport": "rest",
+  "summary": "Charge a previously linked mobile wallet using its payment token, without customer interaction.",
+  "useWhen": "You have linked a wallet through the Wallet Linking Portal and want to take a recurring payment.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v4/rest/payments/m-wallet",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v4/rest/payments/m-wallet"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "payment",
+  "constants": {
+    "pp_TxnCurrency": "PKR"
+  },
+  "parameters": [
+    {
+      "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_PaymentToken",
+      "requirement": "mandatory",
+      "valueType": "payment-token",
+      "notes": "Token returned by wallet linking or by the Token Inquiry API.",
+      "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_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_RetreivalReferenceNo", "pp_DiscountedAmount"]
+  },
+  "companionFlows": ["status-inquiry-v1.1", "token-inquiry-v1"],
+  "docRefs": [
+    {
+      "docId": "mwallet-recurring",
+      "sectionId": "mwallet-pay-via-token",
+      "label": "MWallet Recurring Payments (Linking & Payment), 2026"
+    }
+  ],
+  "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": "sample-expiry-precedes-transaction",
+      "summary": "The guide's sample has an expiry earlier than its transaction time",
+      "detail": "The sample request pairs pp_TxnDateTime 20251117153308 with pp_TxnExpiryDateTime 20250926003252, which is nearly two months earlier.",
+      "guidance": "Ignore the sample values. Set the expiry one day after the transaction time, as the shared rules require."
+    }
+  ]
+}

package/knowledge/flows/refund-bnpl.json

@@ -0,0 +1,105 @@
+{
+  "id": "refund-bnpl",
+  "title": "BNPL Refund API",
+  "provider": "jazzcash",
+  "product": "refund",
+  "version": "1.1",
+  "transport": "rest",
+  "summary": "Refund a completed BNPL transaction. Shares an endpoint with Card Refund v1.1 but documents a different payload.",
+  "useWhen": "A customer returns an order paid with Buy Now Pay Later.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/authorize/refund",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/authorize/refund"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "refund",
+  "constants": {
+    "pp_TxnCurrency": "PKR"
+  },
+  "parameters": [
+    {
+      "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_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_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_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"
+    }
+  ],
+  "hash": {
+    "algorithm": "hmac-sha256",
+    "includeFieldPrefixes": ["pp_", "ppmpf_"],
+    "excludeFields": ["pp_SecureHash", "SecureHash"],
+    "outputEncoding": "hex-lowercase",
+    "comparison": "case-insensitive"
+  },
+  "response": {
+    "hashField": "SecureHash",
+    "hashFieldPrefixes": [],
+    "successField": "ResponseCode",
+    "successValue": "000",
+    "messageField": "ResponseMessage",
+    "hashVerification": "assumed-all-non-empty",
+    "notableFields": ["ResponseCode", "ResponseMessage", "RefundAmount", "TotalRefundAmount"]
+  },
+  "companionFlows": ["status-inquiry-v1.1"],
+  "docRefs": [
+    {
+      "docId": "bnpl-guide",
+      "sectionId": "bnpl-refund-api",
+      "label": "JazzCash Buy Now Pay Later (BNPL) Guide, 2026"
+    }
+  ],
+  "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": "shares-endpoint-with-card-refund-v1-1",
+      "summary": "Identical endpoint to Card Refund v1.1, different documented payload",
+      "detail": "Both guides give /api/v1/rest/payments/mpgs/authorize/refund, but the BNPL sample omits pp_MerchantMPIN, which the card refund sample marks mandatory.",
+      "guidance": "Send the payload from the BNPL guide for a BNPL transaction. If the gateway rejects it, add pp_MerchantMPIN and report the documentation conflict to JazzCash."
+    },
+    {
+      "id": "response-uses-bare-securehash",
+      "summary": "The response returns SecureHash, not pp_SecureHash",
+      "detail": "BNPL refund responses use unprefixed ResponseCode, ResponseMessage and SecureHash.",
+      "guidance": "Read the bare field names when verifying a BNPL refund response."
+    }
+  ]
+}

package/knowledge/flows/refund-card-v1.1.json

@@ -0,0 +1,112 @@
+{
+  "id": "refund-card-v1.1",
+  "title": "Card Refund API v1.1",
+  "provider": "jazzcash",
+  "product": "refund",
+  "version": "1.1",
+  "transport": "rest",
+  "summary": "Refund a completed card transaction, in whole or in part.",
+  "useWhen": "A customer returns an order paid by card.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/authorize/refund",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/authorize/refund"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "refund",
+  "constants": {
+    "pp_TxnCurrency": "PKR"
+  },
+  "parameters": [
+    {
+      "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_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_MerchantMPIN",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "Merchant MPIN, saved in the merchant portal. Refunds fail until it is set.",
+      "sensitive": true
+    },
+    {
+      "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": "SecureHash",
+    "hashFieldPrefixes": [],
+    "successField": "ResponseCode",
+    "successValue": "000",
+    "messageField": "ResponseMessage",
+    "hashVerification": "assumed-all-non-empty",
+    "notableFields": ["ResponseCode", "ResponseMessage", "RefundAmount", "TotalRefundAmount"]
+  },
+  "companionFlows": ["status-inquiry-v1.1"],
+  "docRefs": [
+    {
+      "docId": "card-refund",
+      "sectionId": "rest-based-card-refund-api-v1-1",
+      "label": "Card Refund API, 2026"
+    }
+  ],
+  "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": "response-uses-bare-securehash",
+      "summary": "The response returns SecureHash, not pp_SecureHash",
+      "detail": "Card refund responses use unprefixed ResponseCode, ResponseMessage and SecureHash, unlike every other documented response.",
+      "guidance": "Read the bare field names when verifying a card refund response, or verification will be silently skipped."
+    },
+    {
+      "id": "mpin-must-be-saved-in-portal",
+      "summary": "Refunds fail until the MPIN is saved in the merchant portal",
+      "detail": "The Shopify guide notes that refunds require the MPIN to already be stored in the merchant portal, in addition to being sent in the request.",
+      "guidance": "Save the MPIN in the portal before the first refund attempt."
+    }
+  ]
+}

package/knowledge/flows/refund-card-v2.0.json

@@ -0,0 +1,121 @@
+{
+  "id": "refund-card-v2.0",
+  "title": "Card Refund API v2.0",
+  "provider": "jazzcash",
+  "product": "refund",
+  "version": "2.0",
+  "transport": "rest",
+  "summary": "Refund a completed card transaction, in whole or in part.",
+  "useWhen": "A customer returns an order paid by card.",
+  "endpoints": {
+    "sandbox": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/v2.0/authorize/refund",
+    "production": "https://onlinepayments.jazzcash.com.pk/payment-orchestrator/api/v1/rest/payments/mpgs/v2.0/authorize/refund"
+  },
+  "sameEndpointForBothEnvironments": true,
+  "movesMoney": true,
+  "responseContext": "refund",
+  "constants": {
+    "pp_TxnCurrency": "PKR"
+  },
+  "parameters": [
+    {
+      "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_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_MerchantMPIN",
+      "requirement": "mandatory",
+      "valueType": "string",
+      "notes": "Merchant MPIN, saved in the merchant portal. Refunds fail until it is set.",
+      "sensitive": true
+    },
+    {
+      "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": "SecureHash",
+    "hashFieldPrefixes": [],
+    "successField": "ResponseCode",
+    "successValue": "000",
+    "messageField": "ResponseMessage",
+    "hashVerification": "assumed-all-non-empty",
+    "notableFields": [
+      "ResponseCode",
+      "ResponseMessage",
+      "RefundAmount",
+      "TotalRefundAmount",
+      "RetrievalReferenceNo",
+      "Stan",
+      "Receipt",
+      "Terminal"
+    ]
+  },
+  "companionFlows": ["status-inquiry-v1.1"],
+  "docRefs": [
+    {
+      "docId": "card-refund",
+      "sectionId": "rest-based-card-refund-api-v2-0",
+      "label": "Card Refund API, 2026"
+    }
+  ],
+  "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": "response-uses-bare-securehash",
+      "summary": "The response returns SecureHash, not pp_SecureHash",
+      "detail": "Card refund responses use unprefixed ResponseCode, ResponseMessage and SecureHash, unlike every other documented response.",
+      "guidance": "Read the bare field names when verifying a card refund response, or verification will be silently skipped."
+    },
+    {
+      "id": "mpin-must-be-saved-in-portal",
+      "summary": "Refunds fail until the MPIN is saved in the merchant portal",
+      "detail": "The Shopify guide notes that refunds require the MPIN to already be stored in the merchant portal, in addition to being sent in the request.",
+      "guidance": "Save the MPIN in the portal before the first refund attempt."
+    }
+  ]
+}