@payware/mcp-server 1.1.1 → 1.2.0

package/README.md

@@ -10,10 +10,11 @@ Official MCP (Model Context Protocol) server for payware payment API integration
 - **ISVs (Independent Software Vendors)** - Build multi-merchant platforms with OAuth2 token management
 - **Payment Institutions** - Process A2A transfers, handle Payment Choice Architecture with multiple payment methods
 
-## What's New in v1.1.0
+## What's New in v1.2.0
 
-- **Point of Interaction (POI)** - Full POI management: set prices, get status, generate QR codes, list and manage POIs
-- **Payment Choice Architecture** - Support for `paymentMethod` field (A2A, CARD_FUNDED, BNPL, INSTANT_CREDIT) in transaction processing
+- **SHA-256 Authentication** - Upgraded from MD5 to SHA-256 for JWT content hashing (`contentSha256` header)
+- **Updated Error Codes** - New error codes: `ERR_INVALID_CONTENT_HASH`, `ERR_MISSING_CONTENT_HASH`
+- **Backward Compatibility** - Deprecated MD5 functions retained for legacy support
 
 ## Features
 
@@ -375,7 +376,7 @@ Generate comprehensive API documentation with code examples.
 - `outputFormat` (optional): markdown, html, json (default: markdown)
 
 #### `payware_utils_format_request`
-Format and validate API requests with deterministic JSON serialization for MD5 consistency.
+Format and validate API requests with deterministic JSON serialization for SHA-256 consistency.
 
 **Parameters:**
 - `type` (required): transaction, headers, or curl
@@ -386,7 +387,7 @@ Format and validate API requests with deterministic JSON serialization for MD5 c
 - `method` (optional): HTTP method (default: POST)
 
 #### `payware_utils_format_json_deterministic`
-Format JSON with deterministic property ordering for consistent MD5 calculation.
+Format JSON with deterministic property ordering for consistent SHA-256 calculation.
 
 **Parameters:**
 - `data` (required): Object to serialize
@@ -395,7 +396,7 @@ Format JSON with deterministic property ordering for consistent MD5 calculation.
 #### `payware_utils_server_info`
 Get MCP server information and configuration.
 
-**Note:** All transaction data is serialized using consistent property ordering to prevent MD5 mismatch errors.
+**Note:** All transaction data is serialized using consistent property ordering to prevent content hash mismatch errors.
 
 ## Dependencies
 
@@ -435,12 +436,12 @@ Get MCP server information and configuration.
 - Validate all input parameters
 - Implement rate limiting and monitoring
 
-### JSON Serialization & MD5 Consistency
-⚠️ **CRITICAL**: payware API requires deterministic JSON serialization for MD5 calculation
+### JSON Serialization & SHA-256 Consistency
+⚠️ **CRITICAL**: payware API requires deterministic JSON serialization for SHA-256 calculation
 
 - **Property Order**: JSON objects must have consistent property ordering
 - **Minimized Format**: No whitespace or formatting in request bodies
-- **MD5 Calculation**: Must be calculated from the exact same JSON string sent to API
+- **SHA-256 Calculation**: Must be calculated from the exact same JSON string sent to API
 - **Implementation**: This server uses deterministic JSON serialization to ensure consistency
 
 **Example of correct JSON format:**
@@ -449,9 +450,9 @@ Get MCP server information and configuration.
 ```
 
 **Why this matters:**
-- Different property orders produce different MD5 hashes
-- MD5 mismatch results in `ContentMd5 mismatch` errors
-- Server validates that JWT contentMd5 matches request body MD5
+- Different property orders produce different SHA-256 hashes
+- Hash mismatch results in `ERR_INVALID_CONTENT_HASH` errors
+- Server validates that JWT `contentSha256` matches request body SHA-256
 
 ## Troubleshooting
 
@@ -463,11 +464,11 @@ Get MCP server information and configuration.
    - **Verification**: Use `openssl rsa -in privateKey.pem -pubout` to extract public key from private key
    - **Status**: ✅ Resolved - Keys must be properly registered on payware partner portal
 
-2. **ContentMd5 Mismatch Error**
+2. **Content Hash Mismatch Error (ERR_INVALID_CONTENT_HASH)**
    - **Root Cause**: Inconsistent JSON property ordering
    - **Solution**: Use deterministic JSON serialization (implemented in this server)
-   - **Symptoms**: Server logs show different expected vs actual MD5 hashes
-   - **Prevention**: Always use `createMinimizedJSON()` from `/src/utils/json-serializer.js`
+   - **Symptoms**: Server logs show different expected vs actual SHA-256 hashes
+   - **Prevention**: Always use `createMinimizedJSON()` from `/src/core/utils/json-serializer.js`
    - **Status**: ✅ Fixed - Deterministic JSON serialization implemented
 
 3. **Transaction Creation Failed**
@@ -500,7 +501,7 @@ Get MCP server information and configuration.
 - JWT token creation with RS256 algorithm
 - Transaction creation (POST /api/transactions)
 - Transaction cancellation (PATCH /api/transactions/{id})
-- Deterministic JSON serialization for MD5 consistency
+- Deterministic JSON serialization for SHA-256 consistency
 - Public/private key pair validation
 
 **🧪 Test Results:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payware/mcp-server",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Official MCP server for payware payment API integration",
   "main": "src/index.js",
   "type": "module",

package/src/auth/sandbox-setup.js

@@ -155,13 +155,13 @@ ${JSON.stringify(config, null, 2)}
 
 **Required Headers (All Requests):**
 ${Object.entries(config.headers).map(([key, value]) => `- ${key}: ${value}`).join('\n')}
-- Authorization: Bearer {JWT_TOKEN} (with contentMd5 for POST/PATCH)
+- Authorization: Bearer {JWT_TOKEN} (with contentSha256 for POST/PATCH)
 
 **JWT Requirements:**
 - Algorithm: RS256
 - Issuer (iss): Your Partner ID
 - Audience (aud): https://payware.eu
-- Content-MD5: Required in JWT header for POST/PATCH requests
+- Content-SHA256: Required in JWT header for POST/PATCH requests
 - Private Key: RSA 2048-bit minimum
 
 **Required Fields for Transaction Creation:**

package/src/core/auth/jwt-factory.js

@@ -99,7 +99,7 @@ async function createISVJWT({ isvPartnerId, merchantPartnerId, oauth2Token, priv
  * Create JWT token with custom payload (for ISV use case)
  * @param {Object} payload - Custom JWT payload
  * @param {string} privateKey - Private key for signing
- * @param {Object} requestBody - Request body for content MD5
+ * @param {Object} requestBody - Request body for content SHA-256
  * @returns {Object} JWT token data
  */
 async function createJWTTokenWithCustomPayload(payload, privateKey, requestBody) {
@@ -116,11 +116,11 @@ async function createJWTTokenWithCustomPayload(payload, privateKey, requestBody)
     typ: 'JWT'
   };
 
-  // Add contentMd5 to header if request body exists
+  // Add contentSha256 to header if request body exists (SHA-256 is preferred over MD5)
   if (requestBody) {
     const { createMinimizedJSON } = await import('../utils/json-serializer.js');
     const bodyString = createMinimizedJSON(requestBody);
-    header.contentMd5 = crypto.default.createHash('md5').update(bodyString, 'utf8').digest('base64');
+    header.contentSha256 = crypto.default.createHash('sha256').update(bodyString, 'utf8').digest('base64');
   }
 
   const token = jwt.default.sign(payload, normalizedKey, {
@@ -134,7 +134,7 @@ async function createJWTTokenWithCustomPayload(payload, privateKey, requestBody)
     audience: payload.aud,
     subject: payload.sub,
     issuedAt: new Date(payload.iat * 1000).toISOString(),
-    contentMd5: header.contentMd5 || null,
+    contentSha256: header.contentSha256 || null,
     hasBody: !!requestBody,
     isISV: true
   };

package/src/core/auth/jwt-token.js

@@ -5,14 +5,36 @@ import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { createDeterministicJSON } from '../utils/json-serializer.js';
 
 /**
- * Generate MD5 hash for JWT contentMd5 header
+ * Generate SHA-256 hash for JWT contentSha256 header (PREFERRED)
  *
- * PAYWARE REQUIREMENT: The MD5 hash must be calculated from the EXACT same
+ * PAYWARE REQUIREMENT: The SHA-256 hash must be calculated from the EXACT same
  * compact JSON string that will be sent as the HTTP request body.
  *
  * CRITICAL: Any difference in whitespace, property order, or formatting
- * between the string used for MD5 and the HTTP body will cause authentication
- * failures with ERR_INVALID_MD5 errors.
+ * between the string used for hash and the HTTP body will cause authentication
+ * failures with ERR_INVALID_CONTENT_HASH errors.
+ *
+ * @param {Object|string} body - Request body (object will be consistently serialized)
+ * @returns {string} Base64 encoded SHA-256 hash for JWT contentSha256 header
+ */
+export function generateContentSha256(body) {
+  if (!body) return null;
+
+  // CRITICAL: Use deterministic JSON serialization with sorted keys
+  // This ensures consistent hashes regardless of property order
+  const bodyString = typeof body === 'string' ? body : createDeterministicJSON(body);
+
+  // Generate SHA-256 hash as raw binary and encode in base64
+  const hash = crypto.createHash('sha256');
+  hash.update(bodyString, 'utf8');
+  return hash.digest('base64');
+}
+
+/**
+ * Generate MD5 hash for JWT contentMd5 header (DEPRECATED - use generateContentSha256)
+ *
+ * @deprecated Use generateContentSha256 instead. MD5 is still supported by the server
+ * for backwards compatibility but is deprecated.
  *
  * @param {Object|string} body - Request body (object will be consistently serialized)
  * @returns {string} Base64 encoded MD5 hash for JWT contentMd5 header
@@ -20,8 +42,6 @@ import { createDeterministicJSON } from '../utils/json-serializer.js';
 export function generateContentMd5(body) {
   if (!body) return null;
 
-  // CRITICAL: Use deterministic JSON serialization with sorted keys
-  // This ensures consistent MD5 hashes regardless of property order
   const bodyString = typeof body === 'string' ? body : createDeterministicJSON(body);
 
   // Generate MD5 hash as raw binary and encode in base64
@@ -31,17 +51,17 @@ export function generateContentMd5(body) {
 }
 
 /**
- * Generate the exact JSON string for both JWT MD5 and HTTP request body
+ * Generate the exact JSON string for both JWT content hash and HTTP request body
  *
  * PAYWARE REQUIREMENT: The same compact JSON string must be used for:
- * 1. JWT contentMd5 calculation (passed to generateContentMd5)
+ * 1. JWT contentSha256 calculation (passed to generateContentSha256)
  * 2. HTTP request body (sent to payware API)
  *
  * This function guarantees consistency by using deterministic serialization.
  * Any mismatch between these two uses will result in authentication failure.
  *
  * @param {Object} payload - Request payload object
- * @returns {string} Compact JSON string for both MD5 and HTTP body
+ * @returns {string} Compact JSON string for both hash calculation and HTTP body
  */
 export function serializePayload(payload) {
   if (!payload) return null;
@@ -71,11 +91,11 @@ export function createJWTToken(partnerId, privateKey, requestBody = null) {
     typ: 'JWT'
   };
   
-  // Add contentMd5 to header if request body exists (for POST/PUT/PATCH)
+  // Add contentSha256 to header if request body exists (for POST/PUT/PATCH)
   // CRITICAL: The requestBody here must be the EXACT same string that will
-  // be sent as the HTTP request body, otherwise MD5 will not match
+  // be sent as the HTTP request body, otherwise hash will not match
   if (requestBody) {
-    header.contentMd5 = generateContentMd5(requestBody);
+    header.contentSha256 = generateContentSha256(requestBody);
   }
   
   // JWT Payload (as per documentation)
@@ -95,7 +115,7 @@ export function createJWTToken(partnerId, privateKey, requestBody = null) {
     partnerId,
     audience: 'https://payware.eu',
     issuedAt: new Date(now * 1000).toISOString(),
-    contentMd5: header.contentMd5 || null,
+    contentSha256: header.contentSha256 || null,
     hasBody: !!requestBody
   };
 }
@@ -125,7 +145,7 @@ export function createRequestSignature(method, path, body, privateKey) {
  */
 export const validateJWTTokenTool = {
   name: "payware_authentication_validate_jwt",
-  description: "Validate and debug JWT token structure, decode payload/headers, verify MD5 calculation, and check RS256 signature format for payware API compliance",
+  description: "Validate and debug JWT token structure, decode payload/headers, verify content hash (SHA-256/MD5) calculation, and check RS256 signature format for payware API compliance",
   inputSchema: {
     type: "object",
     properties: {
@@ -135,7 +155,7 @@ export const validateJWTTokenTool = {
       },
       expectedPayload: {
         type: "object",
-        description: "Expected request body (optional - for MD5 validation)"
+        description: "Expected request body (optional - for content hash validation)"
       }
     },
     required: ["jwtToken"],
@@ -159,6 +179,11 @@ export const validateJWTTokenTool = {
 
       const { header, payload } = decoded;
 
+      // Determine which hash type is used
+      const hasContentSha256 = !!header.contentSha256;
+      const hasContentMd5 = !!header.contentMd5;
+      const hasContentHash = hasContentSha256 || hasContentMd5;
+
       // Validation results
       const validation = {
         structure: true,
@@ -167,19 +192,31 @@ export const validateJWTTokenTool = {
         audience: payload.aud === 'https://payware.eu',
         issuer: !!payload.iss,
         issuedAt: !!payload.iat,
-        contentMd5: header.contentMd5 ? true : false
+        contentHash: hasContentHash
       };
 
-      // MD5 validation if expected payload provided
-      let md5Validation = null;
-      if (expectedPayload && header.contentMd5) {
-        const calculatedMd5 = generateContentMd5(expectedPayload);
-        md5Validation = {
-          provided: header.contentMd5,
-          calculated: calculatedMd5,
-          matches: header.contentMd5 === calculatedMd5,
-          deterministicJson: createDeterministicJSON(expectedPayload)
-        };
+      // Content hash validation if expected payload provided
+      let hashValidation = null;
+      if (expectedPayload && hasContentHash) {
+        if (hasContentSha256) {
+          const calculatedSha256 = generateContentSha256(expectedPayload);
+          hashValidation = {
+            type: 'SHA-256 (preferred)',
+            provided: header.contentSha256,
+            calculated: calculatedSha256,
+            matches: header.contentSha256 === calculatedSha256,
+            deterministicJson: createDeterministicJSON(expectedPayload)
+          };
+        } else if (hasContentMd5) {
+          const calculatedMd5 = generateContentMd5(expectedPayload);
+          hashValidation = {
+            type: 'MD5 (deprecated)',
+            provided: header.contentMd5,
+            calculated: calculatedMd5,
+            matches: header.contentMd5 === calculatedMd5,
+            deterministicJson: createDeterministicJSON(expectedPayload)
+          };
+        }
       }
 
       // Check for common issues
@@ -189,11 +226,14 @@ export const validateJWTTokenTool = {
       if (!validation.audience) issues.push("Audience should be 'https://payware.eu'");
       if (!validation.issuer) issues.push("Missing issuer (iss) claim");
       if (!validation.issuedAt) issues.push("Missing issued at (iat) claim");
-      if (md5Validation && !md5Validation.matches) {
-        issues.push("MD5 hash mismatch - ensure deterministic JSON serialization with sorted keys");
+      if (hasContentMd5 && !hasContentSha256) {
+        issues.push("Using deprecated MD5 hash - consider upgrading to SHA-256 (contentSha256)");
+      }
+      if (hashValidation && !hashValidation.matches) {
+        issues.push("Content hash mismatch - ensure deterministic JSON serialization with sorted keys");
       }
 
-      const overallValid = Object.values(validation).every(v => v) && (!md5Validation || md5Validation.matches);
+      const overallValid = Object.values(validation).every(v => v) && (!hashValidation || hashValidation.matches);
 
       return {
         content: [{
@@ -222,26 +262,26 @@ ${validation.type ? '✅' : '❌'} **Type**: JWT ${validation.type ? '(correct)'
 ${validation.audience ? '✅' : '❌'} **Audience**: https://payware.eu ${validation.audience ? '(correct)' : `(found: ${payload.aud})`}
 ${validation.issuer ? '✅' : '❌'} **Issuer**: ${payload.iss || 'Missing'}
 ${validation.issuedAt ? '✅' : '❌'} **Issued At**: ${payload.iat ? new Date(payload.iat * 1000).toISOString() : 'Missing'}
-${validation.contentMd5 ? '✅' : 'ℹ️'} **Content MD5**: ${header.contentMd5 || 'Not present (OK for GET requests)'}
+${validation.contentHash ? '✅' : 'ℹ️'} **Content Hash**: ${header.contentSha256 ? `SHA-256: ${header.contentSha256}` : header.contentMd5 ? `MD5 (deprecated): ${header.contentMd5}` : 'Not present (OK for GET requests)'}
 
-${md5Validation ? `## MD5 Hash Validation
+${hashValidation ? `## Content Hash Validation
 
-${md5Validation.matches ? '✅' : '❌'} **MD5 Match**: ${md5Validation.matches ? 'Correct' : 'Mismatch detected'}
-**Provided**: \`${md5Validation.provided}\`
-**Calculated**: \`${md5Validation.calculated}\`
+${hashValidation.matches ? '✅' : '❌'} **${hashValidation.type} Match**: ${hashValidation.matches ? 'Correct' : 'Mismatch detected'}
+**Provided**: \`${hashValidation.provided}\`
+**Calculated**: \`${hashValidation.calculated}\`
 
 **Deterministic JSON Used**:
 \`\`\`json
-${md5Validation.deterministicJson}
+${hashValidation.deterministicJson}
 \`\`\`
 
-${!md5Validation.matches ? `
-⚠️ **MD5 Mismatch Debugging**:
+${!hashValidation.matches ? `
+⚠️ **Hash Mismatch Debugging**:
 
-PAYWARE REQUIREMENT: The EXACT same compact JSON string must be used for both JWT contentMd5 and HTTP body.
+PAYWARE REQUIREMENT: The EXACT same compact JSON string must be used for both JWT content hash and HTTP body.
 
 **Common Causes**:
-1. Different JSON strings used for JWT MD5 vs HTTP body
+1. Different JSON strings used for JWT hash vs HTTP body
 2. Extra whitespace or formatting differences
 3. Property order variations between serializations
 
@@ -268,7 +308,7 @@ ${issues.includes("Type should be 'JWT'") ? '- Set JWT type to "JWT"\n' : ''}
 ${issues.includes("Audience should be 'https://payware.eu'") ? '- Set audience to "https://payware.eu" (not just "payware")\n' : ''}
 ${issues.includes("Missing issuer (iss) claim") ? '- Add your partner ID as the issuer claim\n' : ''}
 ${issues.includes("Missing issued at (iat) claim") ? '- Add current Unix timestamp as issued at claim\n' : ''}
-${issues.some(i => i.includes('MD5 hash mismatch')) ? '- Use deterministic JSON serialization with sorted keys\n- Ensure same JSON string for MD5 and HTTP body\n' : ''}
+${issues.some(i => i.includes('hash mismatch')) ? '- Use deterministic JSON serialization with sorted keys\n- Ensure same JSON string for hash calculation and HTTP body\n' : ''}
 ` : '## ✅ No Issues Found\n\nYour JWT token is properly formatted for payware API usage.'}
 
 ## Technical Details
@@ -324,7 +364,7 @@ ${issues.some(i => i.includes('MD5 hash mismatch')) ? '- Use deterministic JSON
  */
 export const testJWTTokenTool = {
   name: "payware_authentication_test_jwt",
-  description: "Test JWT token creation process with detailed step-by-step breakdown, showing deterministic JSON serialization, MD5 calculation, and final JWT structure",
+  description: "Test JWT token creation process with detailed step-by-step breakdown, showing deterministic JSON serialization, SHA-256 hash calculation, and final JWT structure",
   inputSchema: {
     type: "object",
     properties: {
@@ -334,7 +374,7 @@ export const testJWTTokenTool = {
       },
       requestPayload: {
         type: "object",
-        description: "Sample request payload to demonstrate MD5 calculation"
+        description: "Sample request payload to demonstrate SHA-256 hash calculation"
       },
       showPrivateKey: {
         type: "boolean",
@@ -387,27 +427,27 @@ ${deterministicJson}
 
 **Key Sorting**: [${sortedKeys.join(', ')}]`);
 
-      // Step 2: MD5 Calculation
-      const md5Hash = generateContentMd5(requestPayload);
+      // Step 2: SHA-256 Calculation
+      const sha256Hash = generateContentSha256(requestPayload);
 
-      steps.push(`**Step 2: MD5 Hash Calculation**
+      steps.push(`**Step 2: SHA-256 Hash Calculation**
 Using deterministic JSON string:
 \`\`\`
 ${deterministicJson}
 \`\`\`
 
-MD5 hash (Base64): \`${md5Hash}\`
+SHA-256 hash (Base64): \`${sha256Hash}\`
 
 **Process**:
-1. Create MD5 hash from UTF-8 bytes of deterministic JSON
+1. Create SHA-256 hash from UTF-8 bytes of deterministic JSON
 2. Encode hash as Base64
-3. Include in JWT header as \`contentMd5\``);
+3. Include in JWT header as \`contentSha256\``);
 
       // Step 3: JWT Header Construction
       const jwtHeader = {
         alg: 'RS256',
         typ: 'JWT',
-        contentMd5: md5Hash
+        contentSha256: sha256Hash
       };
 
       steps.push(`**Step 3: JWT Header Construction**
@@ -418,7 +458,7 @@ ${JSON.stringify(jwtHeader, null, 2)}
 **Requirements**:
 - Algorithm: RS256 (RSA with SHA-256)
 - Type: JWT
-- Content MD5: ${md5Hash}`);
+- Content SHA-256: ${sha256Hash}`);
 
       // Step 4: JWT Payload Construction
       const now = Math.floor(Date.now() / 1000);
@@ -498,18 +538,19 @@ ${deterministicJson}
 ## 🔑 **Key Insights**
 
 1. **Deterministic JSON is Critical**: Property order MUST be sorted
-2. **MD5 Consistency**: Same JSON string for both MD5 and HTTP body
+2. **Hash Consistency**: Same JSON string for both SHA-256 hash and HTTP body
 3. **Audience Requirement**: Must be "https://payware.eu" (include https://)
 4. **RS256 Algorithm**: RSA with SHA-256 signature
-5. **Content MD5 in Header**: Not in payload, but in JWT header
+5. **Content Hash in Header**: Not in payload, but in JWT header (use contentSha256)
 
 ## 🐛 **Common Mistakes to Avoid**
 
 ❌ Using \`JSON.stringify()\` without sorted keys
-❌ Different JSON for MD5 vs HTTP request
+❌ Different JSON for hash calculation vs HTTP request
 ❌ Setting audience to "payware" instead of "https://payware.eu"
-❌ Putting contentMd5 in payload instead of header
+❌ Putting contentSha256 in payload instead of header
 ❌ Using wrong algorithm (HS256 instead of RS256)
+❌ Using deprecated contentMd5 instead of contentSha256
 
 ---
 **Execution Info:**
@@ -567,7 +608,7 @@ export const createJWTTokenTool = {
       },
       requestBody: {
         type: "object",
-        description: "Request body (for POST/PUT/PATCH requests that need contentMd5)"
+        description: "Request body (for POST/PUT/PATCH requests that need contentSha256)"
       }
     },
     additionalProperties: false
@@ -619,14 +660,14 @@ ${tokenData.token}
 - Issued At (iat): ${tokenData.issuedAt}
 - Algorithm: RS256
 - Type: JWT
-${tokenData.contentMd5 ? `- Content MD5: ${tokenData.contentMd5}` : '- Content MD5: Not included (no request body)'}
+${tokenData.contentSha256 ? `- Content SHA-256: ${tokenData.contentSha256}` : '- Content SHA-256: Not included (no request body)'}
 
 **JWT Structure (Decoded):**
 **Header:**
 \`\`\`json
 {
   "alg": "RS256",
-  "typ": "JWT"${tokenData.contentMd5 ? `,\n  "contentMd5": "${tokenData.contentMd5}"` : ''}
+  "typ": "JWT"${tokenData.contentSha256 ? `,\n  "contentSha256": "${tokenData.contentSha256}"` : ''}
 }
 \`\`\`
 
@@ -653,7 +694,7 @@ Content-Type: application/json
 - ✅ Issuer: Your Partner ID
 - ✅ Audience: https://payware.eu
 - ✅ Issued At: Unix timestamp
-${tokenData.contentMd5 ? '- ✅ Content MD5: Included for request body' : '- ℹ️ Content MD5: Not needed for GET requests'}
+${tokenData.contentSha256 ? '- ✅ Content SHA-256: Included for request body' : '- ℹ️ Content SHA-256: Not needed for GET requests'}
 
 **📝 Private Key Formats Supported:**
 - ✅ Full PEM format with headers/footers
@@ -663,9 +704,9 @@ ${tokenData.contentMd5 ? '- ✅ Content MD5: Included for request body' : '- ℹ
 ## ⚠️ **CRITICAL AUTHENTICATION REQUIREMENTS**
 
 ### JSON Body Consistency Rule
-${tokenData.contentMd5 ? `**Your contentMd5 (${tokenData.contentMd5}) MUST match the exact bytes sent in HTTP request.**
+${tokenData.contentSha256 ? `**Your contentSha256 (${tokenData.contentSha256}) MUST match the exact bytes sent in HTTP request.**
 
-❌ **Common Error Causing ERR_INVALID_MD5:**
+❌ **Common Error Causing ERR_INVALID_CONTENT_HASH:**
 \`\`\`python
 # Wrong - different serialization formats!
 jwt_token = create_jwt(json.dumps(payload))  # One format
@@ -674,18 +715,18 @@ requests.post(url, json=payload)            # Different format!
 
 ✅ **Correct Implementation:**
 \`\`\`python
-# Same serialization for both MD5 and HTTP body
+# Same serialization for both hash and HTTP body
 json_body = json.dumps(payload, separators=(',', ':'))  # Compact format
 jwt_token = create_jwt(json_body)
 requests.post(url, data=json_body, headers=headers)
 \`\`\`
-` : '**No request body - No MD5 consistency concerns for GET requests.**'}
+` : '**No request body - No hash consistency concerns for GET requests.**'}
 
 ### Troubleshooting Authentication Errors
 
-**ERR_INVALID_MD5** - MD5 hash mismatch:
-- Cause: JWT contentMd5 doesn't match HTTP request body bytes
-- Fix: Use identical JSON serialization for both MD5 calculation and HTTP request
+**ERR_INVALID_CONTENT_HASH** - Content hash mismatch:
+- Cause: JWT contentSha256 doesn't match HTTP request body bytes
+- Fix: Use identical JSON serialization for both hash calculation and HTTP request
 - Common issue: \`requests.post(json=data)\` vs \`requests.post(data=json_string)\`
 
 **ERR_INVALID_SIGNATURE** - JWT signature validation failed:
@@ -718,7 +759,7 @@ const response = await axios.post(url, jsonBody, {headers: {'Authorization': \`B
 - Do not share or log this token
 - Generate new token for each request with different body
 - Ensure your public key is registered with payware
-- **Critical:** Always use matching JSON serialization for MD5 and HTTP body`
+- **Critical:** Always use matching JSON serialization for SHA-256 hash and HTTP body`
       }]
     };
     } catch (error) {

package/src/core/utils/json-serializer.js

@@ -2,7 +2,7 @@
  * JSON Consistency Utilities for payware API
  *
  * CORE REQUIREMENT: The exact same compact JSON string must be used for
- * both JWT contentMd5 calculation and HTTP request body to prevent MD5 mismatches.
+ * both JWT contentSha256 calculation and HTTP request body to prevent hash mismatches.
  *
  * SOLUTION: We use deterministic serialization (sorted keys) to guarantee
  * consistent JSON output regardless of object property insertion order.
@@ -15,10 +15,10 @@
  * Create consistent compact JSON string for payware API requests
  *
  * CORE REQUIREMENT: payware API requires that the exact same compact JSON string
- * is used for both JWT contentMd5 calculation and the HTTP request body.
+ * is used for both JWT contentSha256 calculation and the HTTP request body.
  *
  * SOLUTION: This function uses deterministic serialization with sorted keys
- * to guarantee the same output every time, preventing MD5 mismatch errors.
+ * to guarantee the same output every time, preventing hash mismatch errors.
  *
  * @param {Object} obj - Object to serialize
  * @returns {string} Compact JSON string with sorted keys (no whitespace)
@@ -72,7 +72,7 @@ function sortObjectKeys(obj) {
  *
  * payware REQUIRES:
  * 1. JSON must be compact (no extra whitespace)
- * 2. The EXACT same string must be used for JWT contentMd5 and HTTP body
+ * 2. The EXACT same string must be used for JWT contentSha256 and HTTP body
  *
  * This function ensures both requirements by using deterministic serialization.
  *
@@ -86,7 +86,7 @@ export function createMinimizedJSON(requestBody) {
 /**
  * Validate that two objects produce the same JSON string
  *
- * This is crucial for payware API because the JWT contentMd5 and HTTP body
+ * This is crucial for payware API because the JWT contentSha256 and HTTP body
  * must use the exact same string. This function helps test that requirement.
  *
  * @param {Object} obj1 - First object