@payware/mcp-server 1.2.0 → 1.3.0

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

@@ -1,341 +1,334 @@
-import axios from 'axios';
-import { createJWTToken } from '../../core/auth/jwt-token.js';
-import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
-import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
-
-/**
- * Finalize a transaction as a payment institution via payware API
- * Payment institutions can update transaction status after execution in their network
- * @param {Object} params - Transaction finalization parameters
- * @returns {Object} Transaction finalization response
- */
-export async function finalizeTransaction({
-  transactionId,
-  status,
-  statusMessage,
-  amount,
-  fee,
-  currency,
-  partnerId,
-  privateKey,
-  useSandbox = true
-}) {
-  if (!transactionId) {
-    throw new Error('Transaction ID is required');
-  }
-
-  if (!status || !['CONFIRMED', 'CANCELLED', 'DECLINED', 'FAILED'].includes(status)) {
-    throw new Error('status is required and must be one of: CONFIRMED, CANCELLED, DECLINED, FAILED');
-  }
-
-  if (['CANCELLED', 'DECLINED', 'FAILED'].includes(status) && !statusMessage) {
-    throw new Error(`statusMessage is required for status: ${status}`);
-  }
-
-  if (status === 'CONFIRMED') {
-    if (!amount) {
-      throw new Error('amount is required for CONFIRMED transactions');
-    }
-    if (!currency) {
-      throw new Error('currency is required for CONFIRMED transactions');
-    }
-    if (fee === undefined) {
-      throw new Error('fee is required for CONFIRMED transactions (use 0 for no fee)');
-    }
-  }
-
-  if (!partnerId || !privateKey) {
-    throw new Error('Partner ID and private key are required for proper JWT creation');
-  }
-
-  // Build request body according to payment institution API documentation
-  const requestBody = {
-    status,
-    ...(statusMessage && { statusMessage }),
-    ...(status === 'CONFIRMED' && {
-      amount: amount.toString(),
-      fee: fee.toString(),
-      currency
-    })
-  };
-
-  // Convert to deterministic minimized JSON for SHA-256 calculation
-  const minimizedBodyString = createMinimizedJSON(requestBody);
-
-  // 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 {
-    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // 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
-      transformRequest: [(data) => data]
-    });
-
-    return {
-      success: true,
-      transaction: response.data,
-      requestId: response.headers['x-request-id'],
-      timestamp: new Date().toISOString()
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: {
-        message: error.response?.data?.message || error.message,
-        status: error.response?.status,
-        code: error.response?.data?.code,
-        details: error.response?.data
-      },
-      timestamp: new Date().toISOString()
-    };
-  }
-}
-
-/**
- * Finalize transaction tool implementation
- */
-export const finalizeTransactionTool = {
-  name: "payware_operations_finalize_transaction",
-  description: `Finalize a transaction as a payment institution. This updates the transaction status after execution in your payment network.
-
-**Payment Institution Finalization:**
-- **CONFIRMED**: Transaction executed successfully (requires amount, fee, currency)
-- **CANCELLED**: Transaction cancelled by creator
-- **DECLINED**: Transaction declined by payment institution (requires statusMessage)
-- **FAILED**: Transaction failed during execution (requires statusMessage)
-
-**Requirements:**
-- Only payment institutions can finalize transactions
-- Currency must match the processing currency of the transaction
-- Amount/fee required for CONFIRMED status
-- StatusMessage required for CANCELLED/DECLINED/FAILED status
-
-**API Request Structure:**
-\`\`\`json
-{
-  "status": "CONFIRMED",
-  "amount": "57.60",
-  "fee": "0.29",
-  "currency": "EUR"
-}
-\`\`\``,
-  inputSchema: {
-    type: "object",
-    properties: {
-      transactionId: {
-        type: "string",
-        description: "Transaction ID to finalize. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
-        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
-      },
-      status: {
-        type: "string",
-        enum: ["CONFIRMED", "CANCELLED", "DECLINED", "FAILED"],
-        description: "Final transaction status"
-      },
-      statusMessage: {
-        type: "string",
-        description: "Transaction failure/cancellation reason (required for CANCELLED, DECLINED, FAILED)",
-        maxLength: 100
-      },
-      amount: {
-        type: ["number", "string"],
-        description: "Final transaction amount (required for CONFIRMED status)",
-        minimum: 0.01,
-        maximum: 9999999999999.99
-      },
-      fee: {
-        type: ["number", "string"],
-        description: "Fee amount collected by payment institution (required for CONFIRMED status, use 0 for no fee)",
-        minimum: 0,
-        maximum: 9999999999999.99
-      },
-      currency: {
-        type: "string",
-        pattern: "^[A-Z]{3}$",
-        description: "Transaction currency (required for CONFIRMED status, must match processing currency)"
-      },
-      partnerId: {
-        type: "string",
-        description: "Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
-        default: getPartnerIdSafe()
-      },
-      privateKey: {
-        type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
-      },
-      useSandbox: {
-        type: "boolean",
-        description: "Use sandbox environment for testing",
-        default: true
-      }
-    },
-    required: ["transactionId", "status"]
-  },
-
-  async handler(args) {
-    const {
-      transactionId,
-      status,
-      statusMessage,
-      amount,
-      fee,
-      currency,
-      partnerId = getPartnerIdSafe(),
-      privateKey = getPrivateKeySafe(args.useSandbox ?? true),
-      useSandbox = true
-    } = args;
-
-    if (!transactionId) {
-      throw new Error("Transaction ID is required");
-    }
-
-    if (!status) {
-      throw new Error("status is required and must be one of: CONFIRMED, CANCELLED, DECLINED, FAILED");
-    }
-
-    // Validate status-specific requirements
-    if (['CANCELLED', 'DECLINED', 'FAILED'].includes(status) && !statusMessage) {
-      throw new Error(`statusMessage is required for status: ${status}`);
-    }
-
-    if (status === 'CONFIRMED') {
-      if (!amount) {
-        throw new Error("amount is required for CONFIRMED transactions");
-      }
-      if (!currency) {
-        throw new Error("currency is required for CONFIRMED transactions");
-      }
-      if (fee === undefined) {
-        throw new Error("fee is required for CONFIRMED transactions (use 0 for no fee)");
-      }
-    }
-
-    if (!partnerId) {
-      throw new Error("Partner ID is required. Provide via 'partnerId' parameter or set PAYWARE_PARTNER_ID environment variable.");
-    }
-
-    if (!privateKey) {
-      throw new Error("Private key is required. Provide via 'privateKey' parameter or set PAYWARE_PRIVATE_KEY environment variable.");
-    }
-
-    const result = await finalizeTransaction({
-      transactionId,
-      status,
-      statusMessage,
-      amount,
-      fee,
-      currency,
-      partnerId,
-      privateKey,
-      useSandbox
-    });
-
-    if (result.success) {
-      const statusEmojis = {
-        CONFIRMED: '✅',
-        CANCELLED: '🚫',
-        DECLINED: '❌',
-        FAILED: '💥'
-      };
-
-      const statusEmoji = statusEmojis[status] || '📄';
-
-      return {
-        content: [{
-          type: "text",
-          text: `${statusEmoji} **Transaction Finalized Successfully**
-
-**Transaction ID:** ${transactionId}
-**Final Status:** ${status}
-
-**Finalization Details:**
-${statusMessage ? `- Status Message: ${statusMessage}` : ''}
-${amount ? `- Final Amount: ${amount} ${currency}` : ''}
-${fee !== undefined ? `- Fee Collected: ${fee} ${currency}` : ''}
-${result.transaction.paymentMethod ? `- Payment Method: ${result.transaction.paymentMethod}` : ''}
-
-**Transaction Response:**
-\`\`\`json
-${JSON.stringify(result.transaction, null, 2)}
-\`\`\`
-
-**API Call Details:**
-- Endpoint: PATCH ${baseUrl}/transactions/${transactionId}
-- Request ID: ${result.requestId || 'N/A'}
-- Timestamp: ${result.timestamp}
-
-**Callbacks Triggered:**
-- **TRANSACTION_FINALIZED** callback sent to all parties
-- Transaction moved to historical records
-- Final status permanently recorded
-
-**Next Steps:**
-${status === 'CONFIRMED' ?
-  `1. ✅ Payment completed successfully
-2. Transaction funds should be processed in your network
-3. Use \`payware_pi_get_transaction_history\` to retrieve details later` :
-  `1. ⚠️ Payment not completed due to: ${statusMessage || status}
-2. Transaction marked as ${status} in payware system
-3. All parties notified via callbacks`
-}
-
-**⚠️ Important:**
-- Transaction finalization is **permanent** and cannot be reversed
-- This transaction is now complete in the payware system`
-        }]
-      };
-    } else {
-      return {
-        content: [{
-          type: "text",
-          text: `❌ **Transaction Finalization Failed**
-
-**Transaction ID:** ${transactionId}
-**Attempted Status:** ${status}
-
-**Error Details:**
-- Message: ${result.error.message}
-- Status: ${result.error.status || 'N/A'}
-- Code: ${result.error.code || 'N/A'}
-
-**Full Error Response:**
-\`\`\`json
-${JSON.stringify(result.error.details || result.error, null, 2)}
-\`\`\`
-
-**Timestamp:** ${result.timestamp}
-
-**Common Finalization Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
-2. **ERR_TRANSACTION_NOT_PROCESSED**: Transaction hasn't been processed yet
-3. **ERR_ALREADY_PROCESSED**: Transaction already finalized
-4. **ERR_INVALID_STATUS**: Invalid status value provided
-5. **ERR_MISSING_STATUS_MESSAGE**: Status message required for failed/declined/cancelled
-6. **ERR_SPECIFYING_CURRENCY_NOT_ALLOWED**: Currency doesn't match transaction currency
-7. **ERR_INVALID_AMOUNT**: Amount validation failed
-8. **ERR_UNAUTHORIZED_OPERATION**: Not authorized to finalize this transaction
-
-**Troubleshooting:**
-1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
-2. Ensure transaction has been processed first
-3. Check status is one of: CONFIRMED, CANCELLED, DECLINED, FAILED
-4. Provide statusMessage for non-CONFIRMED statuses
-5. Include amount, fee, currency for CONFIRMED status
-6. Verify you are authorized to finalize this transaction
-7. Ensure currency matches the original transaction currency`
-        }]
-      };
-    }
-  }
+import axios from 'axios';
+import { createJWTToken } from '../../core/auth/jwt-token.js';
+import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { apiErrorResult } from '../../shared/api-errors.js';
+
+/**
+ * Finalize a transaction as a payment institution via payware API
+ * Payment institutions can update transaction status after execution in their network
+ * @param {Object} params - Transaction finalization parameters
+ * @returns {Object} Transaction finalization response
+ */
+export async function finalizeTransaction({
+  transactionId,
+  status,
+  statusMessage,
+  amount,
+  fee,
+  currency,
+  partnerId,
+  privateKey,
+  useSandbox = true
+}) {
+  if (!transactionId) {
+    throw new Error('Transaction ID is required');
+  }
+
+  if (!status || !['CONFIRMED', 'CANCELLED', 'DECLINED', 'FAILED'].includes(status)) {
+    throw new Error('status is required and must be one of: CONFIRMED, CANCELLED, DECLINED, FAILED');
+  }
+
+  if (['CANCELLED', 'DECLINED', 'FAILED'].includes(status) && !statusMessage) {
+    throw new Error(`statusMessage is required for status: ${status}`);
+  }
+
+  if (status === 'CONFIRMED') {
+    if (!amount) {
+      throw new Error('amount is required for CONFIRMED transactions');
+    }
+    if (!currency) {
+      throw new Error('currency is required for CONFIRMED transactions');
+    }
+    if (fee === undefined) {
+      throw new Error('fee is required for CONFIRMED transactions (use 0 for no fee)');
+    }
+  }
+
+  if (!partnerId || !privateKey) {
+    throw new Error('Partner ID and private key are required for proper JWT creation');
+  }
+
+  // Build request body according to payment institution API documentation
+  const requestBody = {
+    status,
+    ...(statusMessage && { statusMessage }),
+    ...(status === 'CONFIRMED' && {
+      amount: amount.toString(),
+      fee: fee.toString(),
+      currency
+    })
+  };
+
+  // Convert to deterministic minimized JSON for SHA-256 calculation
+  const minimizedBodyString = createMinimizedJSON(requestBody);
+
+  // 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 {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    // 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
+      transformRequest: [(data) => data]
+    });
+
+    return {
+      success: true,
+      transaction: response.data,
+      requestId: response.headers['x-request-id'],
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    return apiErrorResult(error);
+  }
+}
+
+/**
+ * Finalize transaction tool implementation
+ */
+export const finalizeTransactionTool = {
+  name: "payware_operations_finalize_transaction",
+  description: `Finalize a transaction as a payment institution. This updates the transaction status after execution in your payment network.
+
+**Payment Institution Finalization:**
+- **CONFIRMED**: Transaction executed successfully (requires amount, fee, currency)
+- **CANCELLED**: Transaction cancelled by creator
+- **DECLINED**: Transaction declined by payment institution (requires statusMessage)
+- **FAILED**: Transaction failed during execution (requires statusMessage)
+
+**Requirements:**
+- Only payment institutions can finalize transactions
+- Currency must match the processing currency of the transaction
+- Amount/fee required for CONFIRMED status
+- StatusMessage required for CANCELLED/DECLINED/FAILED status
+- **fee**: payware calculates it, the institution executes it. Echo the \`fee\` from the process response verbatim - do not recompute it from \`feeFixed\`/\`feeRate\` and do not re-round it, or the call is rejected with ERR_FEE_MISMATCH.
+
+**API Request Structure:**
+\`\`\`json
+{
+  "status": "CONFIRMED",
+  "amount": "57.60",
+  "fee": "0.29",
+  "currency": "EUR"
+}
+\`\`\``,
+  inputSchema: {
+    type: "object",
+    properties: {
+      transactionId: {
+        type: "string",
+        description: "Transaction ID to finalize. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
+        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+      },
+      status: {
+        type: "string",
+        enum: ["CONFIRMED", "CANCELLED", "DECLINED", "FAILED"],
+        description: "Final transaction status"
+      },
+      statusMessage: {
+        type: "string",
+        description: "Transaction failure/cancellation reason (required for CANCELLED, DECLINED, FAILED)",
+        maxLength: 100
+      },
+      amount: {
+        type: ["number", "string"],
+        description: "Final transaction amount (required for CONFIRMED status)",
+        minimum: 0.01,
+        maximum: 9999999999999.99
+      },
+      fee: {
+        type: ["number", "string"],
+        description: "The payware transaction fee. Echo back the `fee` value from the process/get response EXACTLY - payware calculates the fee and the institution executes it. Do not recompute it from feeFixed/feeRate and do not re-round it; it already carries the currency's smallest payable unit (2 decimals for EUR/USD, 0 for JPY, 3 for KWD). A recomputed value is rejected with ERR_FEE_MISMATCH. Required for CONFIRMED status; use 0 when no fee applies.",
+        minimum: 0,
+        maximum: 9999999999999.99
+      },
+      currency: {
+        type: "string",
+        pattern: "^[A-Z]{3}$",
+        description: "Transaction currency (required for CONFIRMED status, must match processing currency)"
+      },
+      partnerId: {
+        type: "string",
+        description: "Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment for testing",
+        default: true
+      }
+    },
+    required: ["transactionId", "status"]
+  },
+
+  async handler(args) {
+    const {
+      transactionId,
+      status,
+      statusMessage,
+      amount,
+      fee,
+      currency,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe(args.useSandbox ?? true),
+      useSandbox = true
+    } = args;
+
+    if (!transactionId) {
+      throw new Error("Transaction ID is required");
+    }
+
+    if (!status) {
+      throw new Error("status is required and must be one of: CONFIRMED, CANCELLED, DECLINED, FAILED");
+    }
+
+    // Validate status-specific requirements
+    if (['CANCELLED', 'DECLINED', 'FAILED'].includes(status) && !statusMessage) {
+      throw new Error(`statusMessage is required for status: ${status}`);
+    }
+
+    if (status === 'CONFIRMED') {
+      if (!amount) {
+        throw new Error("amount is required for CONFIRMED transactions");
+      }
+      if (!currency) {
+        throw new Error("currency is required for CONFIRMED transactions");
+      }
+      if (fee === undefined) {
+        throw new Error("fee is required for CONFIRMED transactions (use 0 for no fee)");
+      }
+    }
+
+    if (!partnerId) {
+      throw new Error("Partner ID is required. Provide via 'partnerId' parameter or set PAYWARE_PARTNER_ID environment variable.");
+    }
+
+    if (!privateKey) {
+      throw new Error("Private key is required. Provide via 'privateKey' parameter or set PAYWARE_PRIVATE_KEY environment variable.");
+    }
+
+    const result = await finalizeTransaction({
+      transactionId,
+      status,
+      statusMessage,
+      amount,
+      fee,
+      currency,
+      partnerId,
+      privateKey,
+      useSandbox
+    });
+
+    if (result.success) {
+      const statusEmojis = {
+        CONFIRMED: '✅',
+        CANCELLED: '🚫',
+        DECLINED: '❌',
+        FAILED: '💥'
+      };
+
+      const statusEmoji = statusEmojis[status] || '📄';
+
+      return {
+        content: [{
+          type: "text",
+          text: `${statusEmoji} **Transaction Finalized Successfully**
+
+**Transaction ID:** ${transactionId}
+**Final Status:** ${status}
+
+**Finalization Details:**
+${statusMessage ? `- Status Message: ${statusMessage}` : ''}
+${amount ? `- Final Amount: ${amount} ${currency}` : ''}
+${fee !== undefined ? `- Fee Collected: ${fee} ${currency}` : ''}
+${result.transaction.paymentMethod ? `- Payment Method: ${result.transaction.paymentMethod}` : ''}
+
+**Transaction Response:**
+\`\`\`json
+${JSON.stringify(result.transaction, null, 2)}
+\`\`\`
+
+**API Call Details:**
+- Endpoint: PATCH ${baseUrl}/transactions/${transactionId}
+- Request ID: ${result.requestId || 'N/A'}
+- Timestamp: ${result.timestamp}
+
+**Callbacks Triggered:**
+- **TRANSACTION_FINALIZED** callback sent to all parties
+- Transaction moved to historical records
+- Final status permanently recorded
+
+**Next Steps:**
+${status === 'CONFIRMED' ?
+  `1. ✅ Payment completed successfully
+2. Transaction funds should be processed in your network
+3. Use \`payware_pi_get_transaction_history\` to retrieve details later` :
+  `1. ⚠️ Payment not completed due to: ${statusMessage || status}
+2. Transaction marked as ${status} in payware system
+3. All parties notified via callbacks`
+}
+
+**⚠️ Important:**
+- Transaction finalization is **permanent** and cannot be reversed
+- This transaction is now complete in the payware system`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Transaction Finalization Failed**
+
+**Transaction ID:** ${transactionId}
+**Attempted Status:** ${status}
+
+**Error Details:**
+- Message: ${result.error.message}
+- Status: ${result.error.status || 'N/A'}
+- Code: ${result.error.code || 'N/A'}
+
+**Full Error Response:**
+\`\`\`json
+${JSON.stringify(result.error.details || result.error, null, 2)}
+\`\`\`
+
+**Timestamp:** ${result.timestamp}
+
+**Common Finalization Issues:**
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
+2. **ERR_TRANSACTION_NOT_PROCESSED**: Transaction hasn't been processed yet
+3. **ERR_ALREADY_PROCESSED**: Transaction already finalized
+4. **ERR_INVALID_STATUS**: Invalid status value provided
+5. **ERR_MISSING_STATUS_MESSAGE**: Status message required for failed/declined/cancelled
+6. **ERR_SPECIFYING_CURRENCY_NOT_ALLOWED**: Currency doesn't match transaction currency
+7. **ERR_INVALID_AMOUNT**: Amount validation failed
+8. **ERR_UNAUTHORIZED_OPERATION**: Not authorized to finalize this transaction
+
+**Troubleshooting:**
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+2. Ensure transaction has been processed first
+3. Check status is one of: CONFIRMED, CANCELLED, DECLINED, FAILED
+4. Provide statusMessage for non-CONFIRMED statuses
+5. Include amount, fee, currency for CONFIRMED status
+6. Verify you are authorized to finalize this transaction
+7. Ensure currency matches the original transaction currency`
+        }]
+      };
+    }
+  }
 };