@payware/mcp-server 1.1.0 → 1.2.0

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

package/src/isv/transactions/cancel-transaction.js

@@ -31,13 +31,13 @@ export async function cancelTransaction({ transactionId, merchantPartnerId, oaut
     oauth2Token
   });
 
-  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  // Use the same JSON serialization method as the JWT factory for SHA-256 calculation
   const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.delete(`${baseUrl}/transactions/${transactionId}`, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,

package/src/isv/transactions/create-transaction.js

@@ -119,13 +119,13 @@ export async function createTransaction({
     oauth2Token
   });
 
-  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  // Use the same JSON serialization method as the JWT factory for SHA-256 calculation
   const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.post(`${baseUrl}/transactions`, minimizedBodyString, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,

package/src/isv/transactions/process-transaction.js

@@ -35,13 +35,13 @@ export async function processTransaction({ transactionId, merchantPartnerId, oau
     oauth2Token
   });
 
-  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  // Use the same JSON serialization method as the JWT factory for SHA-256 calculation
   const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.patch(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,

package/src/isv/transactions/simulate-callback.js

@@ -35,13 +35,13 @@ export async function simulateCallback({ transactionId, merchantPartnerId, oauth
     oauth2Token
   });
 
-  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  // Use the same JSON serialization method as the JWT factory for SHA-256 calculation
   const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.post(`${baseUrl}/transactions/${transactionId}/simulate-callback`, minimizedBodyString, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,

package/src/isv/utils/auth.js

@@ -80,11 +80,11 @@ async function createOAuth2JWT({ isvPartnerId, privateKey, requestBody, audience
     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) {
     // Use standard JSON.stringify to match axios serialization (preserves property order)
     const bodyString = JSON.stringify(requestBody);
-    header.contentMd5 = crypto.default.createHash('md5').update(bodyString, 'utf8').digest('base64');
+    header.contentSha256 = crypto.default.createHash('sha256').update(bodyString, 'utf8').digest('base64');
   }
 
   // JWT Payload for OAuth2 requests

package/src/merchant/transactions/cancel-transaction.js

@@ -37,21 +37,21 @@ export async function cancelTransaction({
     statusMessage
   };
   
-  // Convert to deterministic minimized JSON for MD5 calculation
+  // Convert to deterministic minimized JSON for SHA-256 calculation
   const minimizedBodyString = createMinimizedJSON(requestBody);
-  
-  // Create JWT token with contentMd5 for the request body (PATCH requires contentMd5)
+
+  // Create JWT token with contentSha256 for the request body (PATCH requires contentSha256)
   const tokenData = createJWTToken(partnerId, privateKey, minimizedBodyString);
-  
+
   // Required headers as per payware API documentation
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
     'Api-Version': '1' // Required: current API version
   };
-  
+
   try {
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
     const response = await axios.patch(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
       headers,

package/src/merchant/transactions/create-transaction.js

@@ -99,10 +99,10 @@ export async function createTransaction({
     ...(type === 'BARCODE' && Object.keys(barOptions).length > 0 && { barOptions })
   };
   
-  // Convert to deterministic minimized JSON as required by payware API for MD5 calculation
+  // Convert to deterministic minimized JSON as required by payware API for SHA-256 calculation
   const minimizedBodyString = createMinimizedJSON(requestBody);
-  
-  // Create JWT token with contentMd5 for the request body (POST requires contentMd5)
+
+  // Create JWT token with contentSha256 for the request body (POST requires contentSha256)
   const tokenData = createJWTToken(partnerId, privateKey, minimizedBodyString);
   
   // Required headers as per payware API documentation
@@ -114,8 +114,8 @@ export async function createTransaction({
   
   try {
     
-    // Send the exact minimized JSON string that was used for MD5 calculation
-    // This ensures the server calculates the same MD5 hash
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
+    // This ensures the server calculates the same SHA-256 hash
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
     const response = await axios.post(`${baseUrl}/transactions`, minimizedBodyString, {
       headers,
@@ -130,15 +130,15 @@ export async function createTransaction({
       timestamp: new Date().toISOString()
     };
   } catch (error) {
-    // Provide helpful error message for MD5 mismatches
+    // Provide helpful error message for hash mismatches
     let enhancedMessage = error.response?.data?.message || error.message;
 
-    if (error.response?.data?.code === 'ERR_INVALID_MD5' ||
-        enhancedMessage?.includes('MD5') ||
-        enhancedMessage?.includes('contentMd5')) {
-      enhancedMessage = `MD5 Mismatch Error: The contentMd5 in JWT header doesn't match the request body.
+    if (error.response?.data?.code === 'ERR_INVALID_CONTENT_HASH' ||
+        enhancedMessage?.includes('SHA-256') ||
+        enhancedMessage?.includes('contentSha256')) {
+      enhancedMessage = `Hash Mismatch Error: The contentSha256 in JWT header doesn't match the request body.
 
-Cause: Different JSON strings were used for JWT contentMd5 calculation and HTTP body.
+Cause: Different JSON strings were used for JWT contentSha256 calculation and HTTP body.
 Solution: Ensure the EXACT same compact JSON string is used for both purposes.
 
 Original error: ${enhancedMessage}`;
@@ -151,8 +151,8 @@ Original error: ${enhancedMessage}`;
         status: error.response?.status,
         code: error.response?.data?.code,
         details: error.response?.data,
-        helpUrl: error.response?.data?.code === 'ERR_INVALID_MD5' ?
-          'https://github.com/payware/mcp-server#md5-consistency' : undefined
+        helpUrl: error.response?.data?.code === 'ERR_INVALID_CONTENT_HASH' ?
+          'https://github.com/payware/mcp-server#sha256-consistency' : undefined
       },
       timestamp: new Date().toISOString()
     };

package/src/merchant/transactions/get-status.js

@@ -16,7 +16,7 @@ export async function getTransactionStatus({ transactionId, partnerId, privateKe
     throw new Error('Partner ID and private key are required for proper JWT creation');
   }
   
-  // Create JWT token without body (GET request - no contentMd5 required)
+  // Create JWT token without body (GET request - no contentSha256 required)
   const tokenData = createJWTToken(partnerId, privateKey, null);
   
   // Required headers as per payware API documentation

package/src/merchant/transactions/process-transaction.js

@@ -68,22 +68,22 @@ export async function processTransaction({
     }
   };
   
-  // Convert to deterministic minimized JSON for MD5 calculation
+  // Convert to deterministic minimized JSON for SHA-256 calculation
   const minimizedBodyString = createMinimizedJSON(requestBody);
-  
-  // Create JWT token with contentMd5 for the request body (POST requires contentMd5)
+
+  // Create JWT token with contentSha256 for the request body (POST requires contentSha256)
   const tokenData = createJWTToken(partnerId, privateKey, minimizedBodyString);
-  
+
   // Required headers as per payware API documentation
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
     'Api-Version': '1'  // Required: current API version
   };
-  
+
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.post(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
       headers,
       // Tell axios to send the string as-is, don't serialize it again

package/src/merchant/transactions/transaction-history.js

@@ -16,7 +16,7 @@ export async function getTransactionHistory({ transactionId, partnerId, privateK
     throw new Error('Partner ID and private key are required for proper JWT creation');
   }
   
-  // Create JWT token without body (GET request - no contentMd5 required)
+  // Create JWT token without body (GET request - no contentSha256 required)
   const tokenData = createJWTToken(partnerId, privateKey, null);
   
   // Required headers as per payware API documentation

package/src/payment-institution/transactions/create-pi-transaction.js

@@ -110,10 +110,10 @@ export async function createPITransaction({
     ...(type === 'BARCODE' && Object.keys(barOptions).length > 0 && { barOptions })
   };
 
-  // Convert to deterministic minimized JSON as required by payware API for MD5 calculation
+  // Convert to deterministic minimized JSON as required by payware API for SHA-256 calculation
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
-  // Create JWT token with contentMd5 for the request body (POST requires contentMd5)
+  // Create JWT token with contentSha256 for the request body (POST requires contentSha256)
   const tokenData = createJWTToken(partnerId, privateKey, minimizedBodyString);
 
   // Required headers as per payware API documentation
@@ -125,8 +125,8 @@ export async function createPITransaction({
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
-    // This ensures the server calculates the same MD5 hash
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
+    // This ensures the server calculates the same SHA-256 hash
     const response = await axios.post(`${baseUrl}/transactions`, minimizedBodyString, {
       headers,
       // Tell axios to send the string as-is, don't serialize it again

package/src/payment-institution/transactions/finalize-transaction.js

@@ -59,10 +59,10 @@ export async function finalizeTransaction({
     })
   };
 
-  // Convert to deterministic minimized JSON for MD5 calculation
+  // Convert to deterministic minimized JSON for SHA-256 calculation
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
-  // Create JWT token with contentMd5 for the request body (PATCH requires contentMd5)
+  // Create JWT token with contentSha256 for the request body (PATCH requires contentSha256)
   const tokenData = createJWTToken(partnerId, privateKey, minimizedBodyString);
 
   // Required headers as per payware API documentation
@@ -74,7 +74,7 @@ export async function finalizeTransaction({
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.patch(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
       headers,
       // Tell axios to send the string as-is, don't serialize it again

package/src/payment-institution/transactions/get-transaction-history.js

@@ -21,7 +21,7 @@ export async function getPITransactionHistory({
     throw new Error('Partner ID and private key are required for proper JWT creation');
   }
 
-  // Create JWT token for GET request (no contentMd5 needed for GET)
+  // Create JWT token for GET request (no contentSha256 needed for GET)
   const tokenData = createJWTToken(partnerId, privateKey, null);
 
   // Required headers as per payware API documentation

package/src/payment-institution/transactions/get-transaction-status.js

@@ -21,7 +21,7 @@ export async function getPITransactionStatus({
     throw new Error('Partner ID and private key are required for proper JWT creation');
   }
 
-  // Create JWT token for GET request (no contentMd5 needed for GET)
+  // Create JWT token for GET request (no contentSha256 needed for GET)
   const tokenData = createJWTToken(partnerId, privateKey, null);
 
   // Required headers as per payware API documentation

package/src/payment-institution/transactions/process-pi-transaction.js

@@ -73,10 +73,10 @@ export async function processPITransaction({
     ...(deliveryAddress && { deliveryAddress })
   };
 
-  // Convert to deterministic minimized JSON for MD5 calculation
+  // Convert to deterministic minimized JSON for SHA-256 calculation
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
-  // Create JWT token with contentMd5 for the request body (POST requires contentMd5)
+  // Create JWT token with contentSha256 for the request body (POST requires contentSha256)
   const tokenData = createJWTToken(partnerId, privateKey, minimizedBodyString);
 
   // Required headers as per payware API documentation
@@ -88,7 +88,7 @@ export async function processPITransaction({
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.post(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
       headers,
       // Tell axios to send the string as-is, don't serialize it again

package/src/payment-institution/transactions/soundbite-transaction.js

@@ -37,8 +37,8 @@ export async function getSoundbiteTransaction({
     contentType: 'application/octet-stream'
   });
 
-  // For multipart/form-data requests, we don't calculate contentMd5 the same way
-  // The JWT token is created without content MD5 for multipart uploads
+  // For multipart/form-data requests, we don't calculate contentSha256 the same way
+  // The JWT token is created without content SHA-256 for multipart uploads
   const tokenData = createJWTToken(partnerId, privateKey, null);
 
   // Required headers as per payware API documentation
@@ -98,7 +98,7 @@ export const soundbiteTransactionTool = {
 **API Request:**
 - Uses multipart/form-data content type
 - File uploaded as form field named 'file'
-- JWT authentication without contentMd5 (multipart upload)`,
+- JWT authentication without contentSha256 (multipart upload)`,
   inputSchema: {
     type: "object",
     properties: {