@payware/mcp-server 1.0.0

package/src/payment-institution/transactions/simulate-pi-callback.js

@@ -0,0 +1,326 @@
+/**
+ * Simulate payment institution callback scenarios for testing
+ * Payment institutions receive TRANSACTION_PROCESSED and TRANSACTION_FINALIZED callbacks
+ */
+
+/**
+ * Generate mock payment institution callback payload
+ * @param {string} transactionId - Transaction ID
+ * @param {string} callbackType - Callback type (TRANSACTION_PROCESSED, TRANSACTION_FINALIZED)
+ * @param {Object} options - Additional options
+ * @returns {Object} Mock callback payload
+ */
+export function generateMockPICallback(transactionId, callbackType = 'TRANSACTION_PROCESSED', options = {}) {
+  const {
+    amount = '57.00',
+    currency = 'EUR',
+    payerAmount = null,
+    payeeAmount = null,
+    payeeBIC = 'SBBICID1',
+    payeeAccount = 'M-1W-1account2',
+    payeeFriendlyName = 'payware',
+    payerBIC = 'SBBICID1',
+    payerAccount = 'payerAccount',
+    payerFriendlyName = 'Demo Financial Institution',
+    reasonL1 = '57',
+    reasonL2 = null,
+    timeToLive = 600,
+    initiatedBy = 'PEER',
+    transactionType = 'DEFAULT',
+    status = 'CONFIRMED',
+    statusMessage = null,
+    passbackParams = null
+  } = options;
+
+  // Calculate fee like Java implementation: |payerAmount - amount| or |payeeAmount - amount|
+  const transactionAmount = parseFloat(amount);
+  let fee = '0.60'; // Default fee
+  if (payerAmount !== null) {
+    fee = Math.abs(parseFloat(payerAmount) - transactionAmount).toFixed(2);
+  } else if (payeeAmount !== null) {
+    fee = Math.abs(parseFloat(payeeAmount) - transactionAmount).toFixed(2);
+  }
+
+  // Build payload based on callback type (matching Java implementation exactly)
+  if (callbackType === 'TRANSACTION_PROCESSED') {
+    return {
+      callbackType,
+      transactionId,
+      passbackParams,
+      amount,
+      fee,
+      currency,
+      payeeBIC,
+      payeeAccount,
+      payeeFriendlyName,
+      payerBIC,
+      payerAccount,
+      payerFriendlyName,
+      reasonL1,
+      ...(reasonL2 && { reasonL2 }),
+      timeToLive,
+      transactionType,
+      initiatedBy
+    };
+  } else {
+    // TRANSACTION_FINALIZED
+    return {
+      callbackType,
+      transactionId,
+      passbackParams,
+      amount,
+      fee,
+      currency,
+      status,
+      ...(statusMessage && { statusMessage }),
+      created: Date.now() - 300000, // Created 5 minutes ago (milliseconds)
+      finalized: Date.now()
+    };
+  }
+}
+
+/**
+ * Simulate callback delivery for payment institutions
+ * @param {string} callbackUrl - URL to send callback to
+ * @param {Object} payload - Callback payload
+ * @returns {Object} Simulation result
+ */
+export async function simulatePICallbackDelivery(callbackUrl, payload) {
+  if (!callbackUrl || !callbackUrl.startsWith('http')) {
+    return {
+      success: false,
+      error: 'Invalid callback URL provided'
+    };
+  }
+
+  // In a real implementation, this would actually send HTTP POST
+  // For simulation, we just return what would be sent
+  return {
+    success: true,
+    url: callbackUrl,
+    payload,
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer mock-jwt-token-' + Date.now()
+    },
+    simulatedAt: new Date().toISOString(),
+    note: 'This is a simulation - no actual HTTP request was made. Real payware callbacks use JWT tokens in Authorization header.'
+  };
+}
+
+/**
+ * Payment Institution callback simulation tool implementation
+ */
+export const simulatePICallbackTool = {
+  name: "payware_operations_simulate_callback",
+  description: "Simulate payment institution callback scenarios for testing webhook handling. Payment institutions receive TRANSACTION_PROCESSED when merchant processes their transaction, and TRANSACTION_FINALIZED when transaction is completed.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      transactionId: {
+        type: "string",
+        description: "Transaction ID to simulate callback for"
+      },
+      callbackType: {
+        type: "string",
+        enum: ["TRANSACTION_PROCESSED", "TRANSACTION_FINALIZED"],
+        description: "Type of callback to simulate",
+        default: "TRANSACTION_PROCESSED"
+      },
+      callbackUrl: {
+        type: "string",
+        description: "URL where callback would be sent (for simulation only)",
+        format: "uri"
+      },
+      amount: {
+        type: "string",
+        description: "Transaction amount (e.g., '57.00')",
+        default: "57.00"
+      },
+      currency: {
+        type: "string",
+        enum: ["EUR", "USD", "GBP"],
+        description: "Transaction currency",
+        default: "EUR"
+      },
+      fee: {
+        type: "string",
+        description: "Fee amount charged by payment institution (e.g., '0.60')",
+        default: "0.60"
+      },
+      payeeBIC: {
+        type: "string",
+        description: "Payee's BIC code",
+        default: "SBBICID1"
+      },
+      payeeAccount: {
+        type: "string",
+        description: "Payee account identifier",
+        default: "M-1W-1account2"
+      },
+      payeeFriendlyName: {
+        type: "string",
+        description: "Payee friendly name",
+        default: "payware"
+      },
+      payerBIC: {
+        type: "string",
+        description: "Payer's BIC code",
+        default: "SBBICID1"
+      },
+      payerAccount: {
+        type: "string",
+        description: "Payer account identifier",
+        default: "payerAccount"
+      },
+      payerFriendlyName: {
+        type: "string",
+        description: "Payer friendly name",
+        default: "Demo Financial Institution"
+      },
+      reasonL1: {
+        type: "string",
+        description: "Transaction reason line 1",
+        default: "57"
+      },
+      reasonL2: {
+        type: "string",
+        description: "Transaction reason line 2 (optional)"
+      },
+      timeToLive: {
+        type: "number",
+        description: "Remaining time to live in seconds",
+        default: 600
+      },
+      status: {
+        type: "string",
+        enum: ["CONFIRMED", "DECLINED", "FAILED", "CANCELLED"],
+        description: "Transaction status (only for TRANSACTION_FINALIZED callbacks)",
+        default: "CONFIRMED"
+      },
+      statusMessage: {
+        type: "string",
+        description: "Status message (only for TRANSACTION_FINALIZED callbacks)"
+      }
+    },
+    required: ["transactionId"]
+  },
+
+  async handler(args) {
+    const {
+      transactionId,
+      callbackType = 'TRANSACTION_PROCESSED',
+      callbackUrl,
+      amount = '57.00',
+      currency = 'EUR',
+      fee = '0.60',
+      payeeBIC = 'SBBICID1',
+      payeeAccount = 'M-1W-1account2',
+      payeeFriendlyName = 'payware',
+      payerBIC = 'SBBICID1',
+      payerAccount = 'payerAccount',
+      payerFriendlyName = 'Demo Financial Institution',
+      reasonL1 = '57',
+      reasonL2,
+      timeToLive = 600,
+      status = 'CONFIRMED',
+      statusMessage
+    } = args;
+
+    if (!transactionId) {
+      throw new Error("Transaction ID is required");
+    }
+
+    // Generate mock callback payload
+    const payload = generateMockPICallback(transactionId, callbackType, {
+      amount,
+      currency,
+      fee,
+      payeeBIC,
+      payeeAccount,
+      payeeFriendlyName,
+      payerBIC,
+      payerAccount,
+      payerFriendlyName,
+      reasonL1,
+      reasonL2,
+      timeToLive,
+      initiatedBy: 'PEER',
+      transactionType: 'DEFAULT',
+      status,
+      statusMessage
+    });
+
+    // Simulate callback delivery if URL provided
+    let deliveryResult = null;
+    if (callbackUrl) {
+      deliveryResult = await simulatePICallbackDelivery(callbackUrl, payload);
+    }
+
+    const callbackEmojis = {
+      'TRANSACTION_PROCESSED': '🔄',
+      'TRANSACTION_FINALIZED': '✅'
+    };
+
+    const statusEmojis = {
+      'CONFIRMED': '✅',
+      'DECLINED': '❌',
+      'FAILED': '💥',
+      'CANCELLED': '🚫'
+    };
+
+    const callbackEmoji = callbackEmojis[callbackType] || '📨';
+    const statusEmoji = statusEmojis[status] || '❓';
+
+    return {
+      content: [{
+        type: "text",
+        text: `${callbackEmoji} **Payment Institution Callback Simulation Complete**
+
+**Transaction:** ${transactionId}
+**Callback Type:** ${callbackType}
+${callbackType === 'TRANSACTION_FINALIZED' ? `**Status:** ${statusEmoji} ${status}` : ''}
+
+**Mock Callback Payload:**
+\`\`\`json
+${JSON.stringify(payload, null, 2)}
+\`\`\`
+
+${deliveryResult ? `
+**Callback Delivery Simulation:**
+${deliveryResult.success ? '✅ Callback would be delivered successfully' : '❌ Callback delivery would fail'}
+
+**Delivery Details:**
+- URL: ${deliveryResult.url || 'N/A'}
+- Headers: ${JSON.stringify(deliveryResult.headers || {}, null, 2)}
+- Simulated At: ${deliveryResult.simulatedAt || 'N/A'}
+
+**Note:** ${deliveryResult.note || 'No actual HTTP request was made'}
+` : '**No callback URL provided** - only payload generated'}
+
+**Payment Institution Callback Types:**
+- 🔄 **TRANSACTION_PROCESSED**: Merchant has processed your transaction (ready for finalization)
+- ✅ **TRANSACTION_FINALIZED**: Transaction completed with final status
+
+**Transaction Flow:**
+1. Payment Institution creates transaction as SRC (payer) or DST (payee)
+2. Transaction can be processed by merchant OR payment institution → **TRANSACTION_PROCESSED** callback to PI
+3. Transaction can be finalized ONLY by payment institution → **TRANSACTION_FINALIZED** callback to PI
+4. Transaction can be cancelled ONLY by its issuer (creator)
+
+**Integration Testing:**
+1. Use this payload to test your payment institution callback handler
+2. Verify handling of both TRANSACTION_PROCESSED and TRANSACTION_FINALIZED
+3. Test different status scenarios for finalized transactions
+4. Ensure proper BIC and account information processing
+
+**Next Steps:**
+1. Implement callback endpoint to receive this payload structure
+2. Test with both callback types
+3. Add signature verification in production
+4. Set up proper error handling and retry logic`
+      }]
+    };
+  }
+};

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

@@ -0,0 +1,269 @@
+import axios from 'axios';
+import FormData from 'form-data';
+import { createJWTToken } from '../../core/auth/jwt-token.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { readFileSync } from 'fs';
+
+/**
+ * Get transaction information using Soundbite file via payware API
+ * @param {Object} params - Soundbite transaction parameters
+ * @returns {Object} Transaction response
+ */
+export async function getSoundbiteTransaction({
+  filePath,
+  partnerId,
+  privateKey,
+  useSandbox = true
+}) {
+  if (!filePath) {
+    throw new Error('filePath is required for soundbite transaction');
+  }
+
+  if (!partnerId || !privateKey) {
+    throw new Error('Partner ID and private key are required for proper JWT creation');
+  }
+
+  let fileBuffer;
+  try {
+    fileBuffer = readFileSync(filePath);
+  } catch (error) {
+    throw new Error(`Failed to read soundbite file: ${error.message}`);
+  }
+
+  // Create form data
+  const formData = new FormData();
+  formData.append('file', fileBuffer, {
+    filename: filePath.split('/').pop() || 'soundbite.lo',
+    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
+  const tokenData = createJWTToken(partnerId, privateKey, null);
+
+  // Required headers as per payware API documentation
+  const headers = {
+    'Authorization': `Bearer ${tokenData.token}`,
+    'Api-Version': '1',  // Required: current API version
+    ...formData.getHeaders()
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.post(`${baseUrl}/transactions`, formData, {
+      headers,
+      maxContentLength: Infinity,
+      maxBodyLength: Infinity
+    });
+
+    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()
+    };
+  }
+}
+
+/**
+ * Soundbite transaction tool implementation
+ */
+export const soundbiteTransactionTool = {
+  name: "payware_operations_soundbite_transaction",
+  description: `Get transaction information using a Soundbite SDK output file. This allows payment institutions to process transactions using audio-based identifiers.
+
+**Soundbite Integration:**
+- Upload Soundbite SDK output file (.lo extension)
+- File contains audio-encoded transaction identifier
+- Alternative to QR/barcode scanning for accessibility
+- Returns same transaction information as regular transaction lookup
+
+**File Requirements:**
+- File must be output from Soundbite SDK
+- Supported file format: .lo (Soundbite format)
+- File must contain valid transaction identifier
+- Maximum file size limits apply
+
+**API Request:**
+- Uses multipart/form-data content type
+- File uploaded as form field named 'file'
+- JWT authentication without contentMd5 (multipart upload)`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      filePath: {
+        type: "string",
+        description: "Absolute path to the Soundbite SDK output file (typically with .lo extension)"
+      },
+      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: ["filePath"]
+  },
+
+  async handler(args) {
+    const {
+      filePath,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe(args.useSandbox ?? true),
+      useSandbox = true
+    } = args;
+
+    if (!filePath) {
+      throw new Error("filePath is required for soundbite transaction");
+    }
+
+    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 getSoundbiteTransaction({
+      filePath,
+      partnerId,
+      privateKey,
+      useSandbox
+    });
+
+    if (result.success) {
+      const tx = result.transaction;
+      const createdDate = tx.created ? new Date(tx.created * 1000).toISOString() : 'N/A';
+      const typeDisplay = tx.transactionType || 'DEFAULT';
+      const initiatorDisplay = tx.initiatedBy || 'UNKNOWN';
+
+      return {
+        content: [{
+          type: "text",
+          text: `🔊 **Soundbite Transaction Retrieved Successfully**
+
+**Transaction Information:**
+- ID: ${tx.transactionId || 'N/A'}
+- Type: ${typeDisplay}
+- Initiated By: ${initiatorDisplay}
+- Status: ⏳ ACTIVE
+- Created: ${createdDate}
+- Remaining TTL: ${tx.timeToLive || 'N/A'} seconds
+
+**Transaction Details:**
+- Amount: ${tx.amount || 'N/A'} ${tx.currency || 'N/A'}
+- Reason L1: ${tx.reasonL1 || 'N/A'}
+${tx.reasonL2 ? `- Reason L2: ${tx.reasonL2}` : ''}
+
+**Payee Information:**
+- Account: ${tx.payeeAccount || 'N/A'}
+- Friendly Name: ${tx.payeeFriendlyName || 'N/A'}
+- BIC: ${tx.payeeBIC || 'N/A'}
+
+**Payer Information:**
+- Account: ${tx.payerAccount || 'N/A'}
+- Friendly Name: ${tx.payerFriendlyName || 'N/A'}
+- BIC: ${tx.payerBIC || 'N/A'}
+
+**Soundbite Details:**
+- File Path: ${filePath}
+- File Name: ${filePath.split('/').pop()}
+- Processing Method: Audio-based transaction identifier
+
+**Full API Response:**
+\`\`\`json
+${JSON.stringify(result.transaction, null, 2)}
+\`\`\`
+
+**API Call Details:**
+- Endpoint: POST ${baseUrl}/transactions (multipart/form-data)
+- Request ID: ${result.requestId || 'N/A'}
+- Timestamp: ${result.timestamp}
+
+**Next Steps:**
+1. Transaction successfully identified from soundbite file
+2. Use transaction ID: \`${tx.transactionId || 'N/A'}\` for further operations
+3. ${!tx.payerAccount ? 'Process this transaction if you are the payer' : 'Transaction ready for finalization'}
+4. Use \`payware_pi_process_transaction\` to process payment
+5. Use \`payware_pi_finalize_transaction\` to confirm/decline
+
+**♿ Accessibility Note:**
+- Soundbite provides audio-based alternative to QR/barcode scanning
+- Enables accessible payment processing for visually impaired users
+- Same functionality as visual transaction identifiers`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Soundbite Transaction Processing Failed**
+
+**File Path:** ${filePath}
+
+**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 Soundbite Issues:**
+1. **File Not Found**: Verify the file path is correct and accessible
+2. **Invalid File Format**: Ensure file is a valid Soundbite SDK output (.lo format)
+3. **Corrupted Audio Data**: File may be corrupted or invalid
+4. **Transaction Not Found**: Audio may not contain valid transaction identifier
+5. **File Size Limits**: File may exceed maximum upload size
+6. **Authentication Issues**: Verify JWT token and partner credentials
+
+**Troubleshooting:**
+1. **File Path**: Ensure file path is absolute and file exists
+2. **File Format**: Verify file is output from Soundbite SDK (usually .lo extension)
+3. **File Integrity**: Check file is not corrupted or modified
+4. **Audio Quality**: Ensure soundbite was captured with sufficient quality
+5. **Transaction Validity**: Verify the original transaction hasn't expired
+6. **Permissions**: Check file read permissions
+
+**File Requirements:**
+- ✅ Valid Soundbite SDK output file
+- ✅ Readable file permissions
+- ✅ File size within limits
+- ✅ Contains valid transaction identifier
+- ✅ Transaction still active/valid
+
+**Alternative Actions:**
+- Try capturing soundbite again if audio quality was poor
+- Use QR/barcode scanning as alternative
+- Verify original transaction is still active
+- Check Soundbite SDK integration and file generation`
+        }]
+      };
+    }
+  }
+};