@payware/mcp-server 1.0.0

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

@@ -0,0 +1,361 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Create a transaction via payware API on behalf of a merchant (ISV)
+ * @param {Object} params - Transaction parameters including ISV authentication
+ * @returns {Object} Transaction response
+ */
+export async function createTransaction({
+  // ISV Authentication
+  merchantPartnerId,
+  oauth2Token,
+  // Transaction parameters
+  type = 'PLAIN',
+  amount,
+  currency = 'EUR',
+  reasonL1,
+  reasonL2,
+  callbackUrl,
+  account,
+  friendlyName,
+  shop,
+  timeToLive = 120,
+  passbackParams,
+  // QR Options
+  qrFormat,
+  qrBorder,
+  qrErrorCorrection,
+  qrScale,
+  qrVersion,
+  // Barcode Options
+  barFormat,
+  barModuleWidth,
+  barBarHeight,
+  barFontSize,
+  barHumanReadableLocation,
+  useSandbox = true
+}) {
+  // ISV-specific validation
+  if (!merchantPartnerId) {
+    throw new Error('Merchant Partner ID is required for ISV operations');
+  }
+
+  if (!oauth2Token) {
+    throw new Error('OAuth2 token is required for ISV operations');
+  }
+
+  // Standard validation
+  if (!reasonL1) {
+    throw new Error('reasonL1 is required (transaction grounds description)');
+  }
+
+  if (amount !== undefined && (typeof amount !== 'string' && typeof amount !== 'number')) {
+    throw new Error('Amount must be a string or number representing currency value (e.g., "25.50" or 25.50)');
+  }
+
+  if (amount !== undefined && parseFloat(amount) < 0) {
+    throw new Error('Amount must be non-negative');
+  }
+
+  if (!['PLAIN', 'QR', 'BARCODE'].includes(type)) {
+    throw new Error('Transaction type must be PLAIN, QR, or BARCODE');
+  }
+
+  // Build QR options if applicable
+  const qrOptions = {};
+  if (type === 'QR') {
+    if (qrFormat) qrOptions.qrFormat = qrFormat;
+    if (qrBorder !== undefined) qrOptions.qrBorder = qrBorder;
+    if (qrErrorCorrection) qrOptions.qrErrorCorrection = qrErrorCorrection;
+    if (qrScale) qrOptions.qrScale = qrScale;
+    if (qrVersion) qrOptions.qrVersion = qrVersion;
+  }
+
+  // Build barcode options if applicable
+  const barOptions = {};
+  if (type === 'BARCODE') {
+    if (barFormat) barOptions.barFormat = barFormat;
+    if (barModuleWidth) barOptions.barModuleWidth = barModuleWidth;
+    if (barBarHeight) barOptions.barBarHeight = barBarHeight;
+    if (barFontSize) barOptions.barFontSize = barFontSize;
+    if (barHumanReadableLocation) barOptions.barHumanReadableLocation = barHumanReadableLocation;
+  }
+
+  // Build request body according to documentation structure
+  const requestBody = {
+    ...(account && { account }),
+    ...(friendlyName && { friendlyName }),
+    ...(shop && { shop }),
+    ...(callbackUrl && { callbackUrl }),
+    ...(passbackParams && {
+      passbackParams: typeof passbackParams === 'string' ? passbackParams : JSON.stringify(passbackParams)
+    }),
+    trData: {
+      amount: amount !== undefined ? amount.toString() : '0.00',
+      currency,
+      reasonL1,
+      ...(reasonL2 && { reasonL2 })
+    },
+    trOptions: {
+      type,
+      timeToLive
+    },
+    ...(type === 'QR' && Object.keys(qrOptions).length > 0 && { qrOptions }),
+    ...(type === 'BARCODE' && Object.keys(barOptions).length > 0 && { barOptions })
+  };
+
+  // Get ISV credentials
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  // Create ISV JWT token
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  // Use the same JSON serialization method as the JWT factory for MD5 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
+    const response = await axios.post(`${baseUrl}/transactions`, minimizedBodyString, {
+      headers: {
+        'Authorization': `Bearer ${jwtData.token}`,
+        'Content-Type': 'application/json',
+        'Api-Version': '1'
+      },
+      // Tell axios to send the string as-is, don't serialize it again
+      transformRequest: [(data) => data]
+    });
+
+    return response.data;
+  } catch (error) {
+    if (error.response) {
+      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+    }
+    throw error;
+  }
+}
+
+export const createTransactionTool = {
+  name: 'payware_operations_create_transaction',
+  description: `Create a new transaction through payware as an ISV on behalf of a merchant.
+
+ISV partners can create transactions for merchants they have authorization for via OAuth2.
+Requires valid OAuth2 token obtained from the merchant.
+
+**Authentication**: Uses ISV JWT with merchant partner ID in 'aud' claim and OAuth2 token in 'sub' claim.
+
+**Transaction Types:**
+- PLAIN: Basic transaction without visual codes
+- QR: Transaction with QR code for mobile payments
+- BARCODE: Transaction with barcode for scanning
+
+**Required for all transactions:**
+- Merchant Partner ID and OAuth2 token (ISV authentication)
+- reasonL1 (transaction description)
+- amount (transaction value)
+
+**QR Code Options** (when type='QR'):
+- qrFormat: PNG, SVG (default: PNG)
+- qrBorder: Border width in modules (0-10, default: 4)
+- qrErrorCorrection: L, M, Q, H (default: M)
+- qrScale: Scale factor (1-10, default: 4)
+- qrVersion: QR version (1-40, auto if not specified)
+
+**Barcode Options** (when type='BARCODE'):
+- barFormat: CODE128, EAN13, etc.
+- barModuleWidth: Width of bars in pixels
+- barBarHeight: Height of bars in pixels
+- barFontSize: Font size for human readable text
+- barHumanReadableLocation: TOP, BOTTOM, NONE`,
+
+  inputSchema: {
+    type: 'object',
+    required: ['merchantPartnerId', 'oauth2Token', 'reasonL1'],
+    properties: {
+      // ISV Authentication
+      merchantPartnerId: {
+        type: 'string',
+        description: 'Partner ID of the target merchant (8 alphanumeric characters, e.g., "PZAYNMVE")'
+      },
+      oauth2Token: {
+        type: 'string',
+        description: 'OAuth2 access token obtained from the merchant'
+      },
+
+      // Core transaction data
+      type: {
+        type: 'string',
+        enum: ['PLAIN', 'QR', 'BARCODE'],
+        default: 'PLAIN',
+        description: 'Transaction type'
+      },
+      amount: {
+        type: ['string', 'number'],
+        description: 'Transaction amount (e.g., "25.50" or 25.50)'
+      },
+      currency: {
+        type: 'string',
+        default: 'EUR',
+        description: 'Currency code (ISO 4217, e.g., EUR, USD, GBP)'
+      },
+      reasonL1: {
+        type: 'string',
+        description: 'Primary transaction reason/description (required)'
+      },
+      reasonL2: {
+        type: 'string',
+        description: 'Secondary transaction reason/description (optional)'
+      },
+
+      // Optional transaction metadata
+      callbackUrl: {
+        type: 'string',
+        description: 'URL to receive transaction status updates'
+      },
+      account: {
+        type: 'string',
+        description: 'Account identifier'
+      },
+      friendlyName: {
+        type: 'string',
+        description: 'Human-readable transaction identifier'
+      },
+      shop: {
+        type: 'string',
+        description: 'Shop/location identifier'
+      },
+      timeToLive: {
+        type: 'number',
+        default: 120,
+        description: 'Transaction validity in minutes'
+      },
+      passbackParams: {
+        type: ['string', 'object'],
+        description: 'Additional parameters to pass back in callbacks'
+      },
+
+      // QR Code options (when type='QR')
+      qrFormat: {
+        type: 'string',
+        enum: ['PNG', 'SVG'],
+        description: 'QR code image format'
+      },
+      qrBorder: {
+        type: 'number',
+        minimum: 0,
+        maximum: 10,
+        description: 'QR code border width in modules'
+      },
+      qrErrorCorrection: {
+        type: 'string',
+        enum: ['L', 'M', 'Q', 'H'],
+        description: 'QR error correction level'
+      },
+      qrScale: {
+        type: 'number',
+        minimum: 1,
+        maximum: 10,
+        description: 'QR code scale factor'
+      },
+      qrVersion: {
+        type: 'number',
+        minimum: 1,
+        maximum: 40,
+        description: 'QR code version (size)'
+      },
+
+      // Barcode options (when type='BARCODE')
+      barFormat: {
+        type: 'string',
+        description: 'Barcode format (e.g., CODE128, EAN13)'
+      },
+      barModuleWidth: {
+        type: 'number',
+        description: 'Barcode module width in pixels'
+      },
+      barBarHeight: {
+        type: 'number',
+        description: 'Barcode height in pixels'
+      },
+      barFontSize: {
+        type: 'number',
+        description: 'Font size for human readable text'
+      },
+      barHumanReadableLocation: {
+        type: 'string',
+        enum: ['TOP', 'BOTTOM', 'NONE'],
+        description: 'Location of human readable text'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler(params) {
+    try {
+      const result = await createTransaction(params);
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ Transaction Created Successfully (ISV -> Merchant: ${params.merchantPartnerId})
+
+📋 **Transaction Details:**
+- **Transaction ID**: ${result.transactionId || 'N/A'}
+- **Status**: ${result.status || 'CREATED'}
+- **Type**: ${params.type}
+- **Amount**: ${params.amount || 'N/A'} ${params.currency || 'EUR'}
+- **Reason**: ${params.reasonL1}
+- **TTL**: ${params.timeToLive || 120} minutes
+
+🔗 **Integration Details:**
+- **ISV Partner**: ${getPartnerIdSafe()}
+- **Target Merchant**: ${params.merchantPartnerId}
+- **OAuth2 Token**: ${params.oauth2Token.substring(0, 8)}...
+
+${result.qrCodeUrl ? `🔲 **QR Code**: ${result.qrCodeUrl}` : ''}
+${result.barcodeUrl ? `📊 **Barcode**: ${result.barcodeUrl}` : ''}
+${result.paymentUrl ? `💳 **Payment URL**: ${result.paymentUrl}` : ''}
+
+**Raw Response:**
+\`\`\`json
+${JSON.stringify(result, null, 2)}
+\`\`\``
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ Transaction Creation Failed
+
+**Error**: ${error.message}
+
+**ISV Authentication Check:**
+- Merchant Partner ID: ${params.merchantPartnerId || 'Missing'}
+- OAuth2 Token: ${params.oauth2Token ? 'Provided' : 'Missing'}
+- ISV Partner ID: ${getPartnerIdSafe()}
+
+**Troubleshooting:**
+- Verify OAuth2 token is valid and granted
+- Ensure merchant partner ID is correct (8 characters)
+- Check transaction parameters meet payware requirements
+- Confirm ISV has authorization to act on behalf of merchant`
+        }]
+      };
+    }
+  }
+};

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

@@ -0,0 +1,217 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get transaction status from payware API as an ISV
+ * @param {Object} params - Parameters for status request
+ * @returns {Object} Transaction status response
+ */
+export async function getTransactionStatus({ transactionId, merchantPartnerId, oauth2Token, useSandbox = true }) {
+  if (!transactionId) {
+    throw new Error('Transaction ID is required');
+  }
+
+  if (!merchantPartnerId) {
+    throw new Error('Merchant Partner ID is required for ISV operations');
+  }
+
+  if (!oauth2Token) {
+    throw new Error('OAuth2 token is required for ISV operations');
+  }
+
+  // Get ISV credentials
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  // Create ISV JWT token (GET request - no body)
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody: null,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  // Required headers as per payware API documentation
+  const headers = {
+    'Authorization': `Bearer ${jwtData.token}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1'  // Required: current API version
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.get(`${baseUrl}/transactions/${transactionId}`, { headers });
+
+    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()
+    };
+  }
+}
+
+/**
+ * Format transaction status for display
+ */
+function formatTransactionStatus(transaction) {
+  const statusEmojis = {
+    'ACTIVE': '⏳'
+  };
+
+  // If a transaction is returned from GET /transactions/{id}, it's always ACTIVE
+  // (transactions with final statuses are only available via /transactions-history)
+  const status = transaction.status || 'ACTIVE';
+  const emoji = statusEmojis[status] || '⏳';
+
+  return {
+    emoji,
+    status,
+    formatted: `${emoji} ${status}`
+  };
+}
+
+/**
+ * Get transaction status tool implementation for ISV
+ */
+export const getTransactionStatusTool = {
+  name: "payware_operations_get_transaction_status",
+  description: `Get status of an ACTIVE transaction by ID as an ISV on behalf of a merchant.
+
+**ISV Authentication:** Uses ISV JWT with merchant partner ID in 'aud' claim and OAuth2 token in 'sub' claim.
+**Endpoint:** GET /transactions/{transactionId}
+**Use Case:** Check status of ACTIVE transactions only. This endpoint only returns transactions with ACTIVE status.
+**Note:** For transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use 'payware_transactions_get_history' instead.
+
+**Required:** Merchant Partner ID and OAuth2 token for ISV authentication.`,
+
+  inputSchema: {
+    type: "object",
+    required: ["transactionId", "merchantPartnerId", "oauth2Token"],
+    properties: {
+      transactionId: {
+        type: "string",
+        description: "Transaction ID to check status for"
+      },
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the target merchant (8 alphanumeric characters, e.g., 'PZAYNMVE')"
+      },
+      oauth2Token: {
+        type: "string",
+        description: "OAuth2 access token obtained from the merchant"
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment for testing",
+        default: true
+      }
+    }
+  },
+
+  async handler(args) {
+    const { transactionId, merchantPartnerId, oauth2Token, useSandbox = true } = args;
+
+    if (!transactionId) {
+      throw new Error("Transaction ID is required");
+    }
+
+    if (!merchantPartnerId) {
+      throw new Error("Merchant Partner ID is required for ISV operations");
+    }
+
+    if (!oauth2Token) {
+      throw new Error("OAuth2 token is required for ISV operations");
+    }
+
+    const result = await getTransactionStatus({ transactionId, merchantPartnerId, oauth2Token, useSandbox });
+
+    if (result.success) {
+      const statusInfo = formatTransactionStatus(result.transaction);
+
+      return {
+        content: [{
+          type: "text",
+          text: `📊 **Transaction Status Retrieved (ISV -> Merchant: ${merchantPartnerId})**
+
+**Transaction:** ${transactionId}
+**Status:** ${statusInfo.formatted}
+
+**ISV Integration:**
+- ISV Partner: ${getPartnerIdSafe()}
+- Target Merchant: ${merchantPartnerId}
+- OAuth2 Token: ${oauth2Token.substring(0, 8)}...
+
+**Transaction Details:**
+- ID: ${result.transaction.id || 'N/A'}
+- Type: ${result.transaction.type || 'N/A'}
+- Amount: ${result.transaction.trData ? `${result.transaction.trData.amount} ${result.transaction.trData.currency}` : 'N/A'}
+- Description: ${result.transaction.description || 'N/A'}
+- Created: ${result.transaction.createdAt || 'N/A'}
+- Updated: ${result.transaction.updatedAt || 'N/A'}
+
+**Full Response:**
+\`\`\`json
+${JSON.stringify(result.transaction, null, 2)}
+\`\`\`
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}
+
+**Status Meanings:**
+- ⏳ ACTIVE: Active transaction pending processing or finalizing
+
+**Note:** Only ACTIVE transactions are returned by this endpoint. For final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use the transaction history tool.`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Get Transaction Status**
+
+**Transaction ID:** ${transactionId}
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
+
+**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}
+
+**ISV-Specific Troubleshooting:**
+1. Verify OAuth2 token is valid and granted for merchant
+2. Ensure merchant partner ID is correct (8 characters)
+3. Check if ISV has authorization to access merchant transactions
+4. Verify transaction belongs to the specified merchant
+5. Confirm JWT token is properly signed for ISV requests
+
+**General Troubleshooting:**
+1. Verify the transaction ID is correct
+2. Check if transaction exists and is accessible
+3. Ensure transaction is still ACTIVE (not finalized)
+4. Try using transaction history tool for completed transactions`
+        }]
+      };
+    }
+  }
+};