@payware/mcp-server 1.0.0 → 1.1.1

package/README.md

@@ -1,18 +1,41 @@
 # payware MCP Server
 
-Minimal MCP server for payware API integration. Enables quick merchant integration with payware APIs in sandbox environment.
+[![npm version](https://badge.fury.io/js/%40payware%2Fmcp-server.svg)](https://www.npmjs.com/package/@payware/mcp-server)
+
+Official MCP (Model Context Protocol) server for payware payment API integration. This server enables AI assistants to interact with payware APIs, automating integration workflows for all partner types.
+
+## Who Is This For?
+
+- **Merchants** - Accept payments, manage products, generate transaction reports
+- **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
+
+- **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
 
 ## Features
 
 ### 🔐 Authentication Tools
 - **RSA Key Generation**: Generate secure 2048-bit RSA key pairs
-- **JWT Token Creation**: Create properly formatted JWT tokens  
+- **JWT Token Creation**: Create properly formatted JWT tokens
 - **Sandbox Setup**: Configure sandbox authentication
 
 ### 💳 Transaction Tools
 - **Create Transaction**: Support PLAIN, QR, and BARCODE transactions
+- **Process Transaction**: Process transactions with Payment Choice Architecture support
 - **Transaction Status**: Check transaction status by ID
-- **Callback Simulation**: Test callback scenarios
+- **Transaction History**: Get finalized transaction details
+- **Callback Simulation**: Test callback scenarios for merchants and payment institutions
+
+### 📍 Point of Interaction (POI) Tools
+- **Set Price**: Configure POI with amount, currency, and payment details
+- **Cancel Price**: Clear active price from POI
+- **Get POI**: Retrieve POI details and current state
+- **Get Status**: Check POI transaction status
+- **Get QR Code**: Generate QR code for POI payments
+- **List POIs**: List all POIs for a merchant
 
 ### 🛠️ Utility Tools
 - **Advanced Code Generation**: Generate complete integration code across 8 languages (Python, Node.js, PHP, Java, C#, Go, Ruby, cURL) with 16+ framework support
@@ -25,8 +48,15 @@ Minimal MCP server for payware API integration. Enables quick merchant integrati
 
 ### 1. Installation
 
+**From npm (recommended):**
 ```bash
-cd payware/mcp
+npm install -g @payware/mcp-server
+```
+
+**From source:**
+```bash
+git clone https://github.com/payware/mcp-server.git
+cd mcp-server
 npm install
 ```
 
@@ -309,6 +339,14 @@ Generate production-ready code examples for any payware operation.
 - `get_product` - Get product details
 - `list_products` - List all products
 
+**POI Operations (isv):**
+- `set_price` - Set price on a Point of Interaction device
+- `cancel_price` - Cancel active price on POI
+- `get_poi` - Get POI details
+- `get_poi_status` - Get POI transaction status
+- `get_poi_qrcode` - Generate QR code for POI
+- `list_pois` - List all POIs for a merchant
+
 **OAuth2 Operations (isv only):**
 - `obtain_token` - Obtain OAuth2 access token
 - `get_token_info` - Get OAuth2 token information

package/package.json

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

package/src/isv/data/index.js

@@ -11,6 +11,9 @@ import {
   downloadExport,
   cancelReport,
   cancelExport,
+  listReports,
+  getReportRequests,
+  getExportList,
   REPORT_TYPES,
   EXPORT_FORMATS,
   LOCALES
@@ -229,6 +232,23 @@ This feature requires proper OAuth2 authorization from the merchant and is only
 };
 
 // Create all other ISV data tools
+export const listReportsTool = createISVDataTool('list_reports', listReports, 'List All Available Reports', {});
+
+export const getReportRequestsTool = createISVDataTool('get_report_requests', getReportRequests, 'Get Report Request History', {
+  reportId: {
+    type: "string",
+    description: "The report unit ID (path) to get execution history for (e.g., '/processedTransactions')",
+    enum: Object.values(REPORT_TYPES)
+  }
+});
+
+export const getExportListTool = createISVDataTool('get_export_list', getExportList, 'Get Export List for Request', {
+  requestId: {
+    type: "string",
+    description: "The request ID (UUID) to get exports for"
+  }
+});
+
 export const getReportStatusTool = createISVDataTool('get_report_status', getReportStatus, 'Get Report Status', {
   requestId: {
     type: "string",
@@ -281,9 +301,12 @@ export const cancelExportTool = createISVDataTool('cancel_export', cancelExport,
  * All ISV data tools
  */
 export const isvDataTools = [
+  listReportsTool,
   generateReportTool,
+  getReportRequestsTool,
   getReportStatusTool,
   exportReportTool,
+  getExportListTool,
   getExportStatusTool,
   downloadExportTool,
   cancelReportTool,

package/src/isv/deep-links/delete-product-link.js

@@ -100,7 +100,7 @@ export const deleteProductLinkTool = {
 - Product ID: ${productId}
 - Merchant: ${merchantPartnerId}
 - Status: Successfully deleted
-- Link URL: https://url.payware.eu/${productId} (now inactive)
+- Link URL: https://go.payware.eu/${productId} (now inactive)
 
 **ISV Authentication:**
 - ISV Partner ID: ${isvPartnerId}

package/src/isv/deep-links/delete-transaction-link.js

@@ -100,7 +100,7 @@ export const deleteTransactionLinkTool = {
 - Transaction ID: ${transactionId}
 - Merchant: ${merchantPartnerId}
 - Status: Successfully deleted
-- Link URL: https://url.payware.eu/${transactionId} (now inactive)
+- Link URL: https://go.payware.eu/${transactionId} (now inactive)
 
 **ISV Authentication:**
 - ISV Partner ID: ${isvPartnerId}

package/src/isv/deep-links/get-product-link.js

@@ -13,7 +13,7 @@ export const getProductLinkTool = {
 - Requires OAuth2 token in 'sub' claim
 
 **Deep Link Format:**
-- Web URL: https://url.payware.eu/{productId}
+- Web URL: https://go.payware.eu/{productId}
 - Mobile Redirect: payware://{productId}
 
 **Use Cases:**

package/src/isv/deep-links/get-transaction-link.js

@@ -13,7 +13,7 @@ export const getTransactionLinkTool = {
 - Requires OAuth2 token in 'sub' claim
 
 **Deep Link Format:**
-- Web URL: https://url.payware.eu/{transactionId}
+- Web URL: https://go.payware.eu/{transactionId}
 - Mobile Redirect: payware://{transactionId}
 
 **Use Cases:**

package/src/isv/index.js

@@ -25,6 +25,9 @@ import { isvProductTools } from './products/index.js';
 // Deep links tools
 import { isvDeepLinksTools } from './deep-links/index.js';
 
+// POI tools
+import { isvPOITools } from './poi/index.js';
+
 // Import shared tools
 import { sharedTools } from '../shared/index.js';
 
@@ -55,7 +58,10 @@ export const isvTools = [
   ...isvProductTools,
 
   // Deep links management
-  ...isvDeepLinksTools
+  ...isvDeepLinksTools,
+
+  // POI management
+  ...isvPOITools
 ];
 
 /**
@@ -94,6 +100,10 @@ export function getISVTools() {
     else if (tool.name.startsWith('payware_deep_links_')) {
       newName = tool.name; // Keep deep_links grouping
     }
+    // POI tools keep their poi grouping
+    else if (tool.name.startsWith('payware_poi_')) {
+      newName = tool.name; // Keep poi grouping
+    }
 
     return {
       ...tool,

package/src/isv/poi/cancel-price.js

@@ -0,0 +1,149 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Cancel pending price on a POI via ISV authentication
+ * @param {Object} params - Parameters for cancel request
+ * @returns {Object} Cancel response
+ */
+export async function cancelPOIPrice({ poiId, merchantPartnerId, oauth2Token, useSandbox = true }) {
+  if (!poiId) {
+    throw new Error('POI 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 isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody: null,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  const headers = {
+    'Authorization': `Bearer ${jwtData.token}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1'
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.delete(`${baseUrl}/poi/${poiId}/price`, { headers });
+
+    return {
+      success: true,
+      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()
+    };
+  }
+}
+
+/**
+ * Cancel POI price tool implementation for ISV
+ */
+export const cancelPOIPriceTool = {
+  name: "payware_poi_cancel_price",
+  description: `Cancel a pending price on a POI, resetting it to IDLE state.
+
+**ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
+**Endpoint:** DELETE /poi/{poiId}/price
+**Use Case:** Cancel a price that was set but customer didn't pay (e.g., order cancelled).
+
+The POI will return to IDLE state and be ready for a new price.
+
+**Required:** POI ID, Merchant Partner ID, and OAuth2 token.`,
+
+  inputSchema: {
+    type: "object",
+    required: ["poiId", "merchantPartnerId", "oauth2Token"],
+    properties: {
+      poiId: {
+        type: "string",
+        description: "The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)"
+      },
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the target merchant (8 alphanumeric characters)"
+      },
+      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 { poiId, merchantPartnerId, oauth2Token, useSandbox = true } = args;
+
+    if (!poiId) throw new Error("POI ID is required");
+    if (!merchantPartnerId) throw new Error("Merchant Partner ID is required");
+    if (!oauth2Token) throw new Error("OAuth2 token is required");
+
+    const result = await cancelPOIPrice({ poiId, merchantPartnerId, oauth2Token, useSandbox });
+
+    if (result.success) {
+      return {
+        content: [{
+          type: "text",
+          text: `✅ **Price Cancelled Successfully**
+
+**POI ID:** ${poiId}
+**Status:** 🟢 IDLE (ready for new price)
+
+The POI is now ready to accept a new price.
+
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Cancel Price**
+
+**POI ID:** ${poiId}
+
+**Error:** ${result.error.message}
+**Code:** ${result.error.code || 'N/A'}
+**Status:** ${result.error.status || 'N/A'}
+
+**Common Issues:**
+- INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
+- POI_NOT_FOUND (404): POI doesn't exist or doesn't belong to merchant
+- POI_NO_PENDING_PAYMENT (409): No pending price to cancel (POI already IDLE)
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/poi/get-poi.js

@@ -0,0 +1,190 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get POI details via ISV authentication
+ * @param {Object} params - Parameters for get request
+ * @returns {Object} POI details response
+ */
+export async function getPOI({ poiId, merchantPartnerId, oauth2Token, useSandbox = true }) {
+  if (!poiId) {
+    throw new Error('POI 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'
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.get(`${baseUrl}/poi/${poiId}`, { headers });
+
+    return {
+      success: true,
+      poi: 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()
+    };
+  }
+}
+
+/**
+ * Get POI details tool implementation for ISV
+ */
+export const getPOITool = {
+  name: "payware_poi_get",
+  description: `Get details of a specific POI (Point of Interaction).
+
+**ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
+**Endpoint:** GET /poi/{poiId}
+**Use Case:** Retrieve full details of a physical payment point including configuration and current state.
+
+**Required:** POI ID, Merchant Partner ID, and OAuth2 token.`,
+
+  inputSchema: {
+    type: "object",
+    required: ["poiId", "merchantPartnerId", "oauth2Token"],
+    properties: {
+      poiId: {
+        type: "string",
+        description: "The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)"
+      },
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the target merchant (8 alphanumeric characters)"
+      },
+      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 { poiId, merchantPartnerId, oauth2Token, useSandbox = true } = args;
+
+    if (!poiId) {
+      throw new Error("POI 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 getPOI({ poiId, merchantPartnerId, oauth2Token, useSandbox });
+
+    if (result.success) {
+      const poi = result.poi;
+      const statusEmoji = {
+        'IDLE': '🟢',
+        'READY': '🟡',
+        'BUSY': '🔴',
+        'DISABLED': '⚫'
+      }[poi.status] || '⚪';
+
+      return {
+        content: [{
+          type: "text",
+          text: `📍 **POI Details Retrieved (ISV -> Merchant: ${merchantPartnerId})**
+
+**POI:** ${poi.name} (${poi.poiId})
+**Status:** ${statusEmoji} ${poi.status}
+**Active:** ${poi.isActive ? '✅ Yes' : '❌ No'}
+
+**Location:**
+- Shop: ${poi.shopName || 'N/A'} (${poi.shopCode || 'N/A'})
+
+**Configuration:**
+- Default TTL: ${poi.ttlSeconds || 120} seconds
+- Callback URL: ${poi.callbackUrl || 'Not configured'}
+- Linked vPOS: ${poi.linkedVposCount || 0} terminals
+
+**Current Session:**
+${poi.status !== 'IDLE' && poi.pendingAmount ? `- Amount: ${poi.pendingAmount} ${poi.pendingCurrency}
+- Expires: ${poi.sessionExpiresAt || 'N/A'}
+- Token: ${poi.sessionToken || 'N/A'}` : '- No active session'}
+
+**Timestamps:**
+- Created: ${poi.createdAt || 'N/A'}
+- Updated: ${poi.updatedAt || 'N/A'}
+
+**Full Response:**
+\`\`\`json
+${JSON.stringify(poi, null, 2)}
+\`\`\`
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Get POI Details**
+
+**POI ID:** ${poiId}
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
+
+**Error Details:**
+- Message: ${result.error.message}
+- Status: ${result.error.status || 'N/A'}
+- Code: ${result.error.code || 'N/A'}
+
+**Troubleshooting:**
+1. Verify POI ID format (must be pi + 8 alphanumeric chars, e.g., piABC12345)
+2. If 400 error: POI ID format is invalid (ERR_INVALID_POI_ID)
+3. If 404 error: POI not found or doesn't belong to merchant
+4. Check OAuth2 token validity
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/poi/get-qrcode.js

@@ -0,0 +1,151 @@
+import axios from 'axios';
+import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+
+/**
+ * Get POI QR code image
+ * Note: This endpoint is public and doesn't require authentication
+ * @param {Object} params - Parameters for QR code request
+ * @returns {Object} QR code response
+ */
+export async function getPOIQRCode({ poiId, format = 'PNG', useSandbox = true }) {
+  if (!poiId) {
+    throw new Error('POI ID is required');
+  }
+
+  const headers = {
+    'Api-Version': '1'
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.get(`${baseUrl}/poi/${poiId}/image`, {
+      headers,
+      params: { format },
+      responseType: 'arraybuffer'
+    });
+
+    const contentType = response.headers['content-type'];
+    const base64Image = Buffer.from(response.data).toString('base64');
+
+    return {
+      success: true,
+      image: {
+        base64: base64Image,
+        contentType,
+        format,
+        size: response.data.length
+      },
+      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()
+    };
+  }
+}
+
+/**
+ * Get POI QR code tool implementation
+ */
+export const getPOIQRCodeTool = {
+  name: "payware_poi_get_qrcode",
+  description: `Generate a QR code image for a POI that customers can scan.
+
+**Endpoint:** GET /poi/{poiId}/image
+**Authentication:** Public endpoint (no auth required)
+**Use Case:** Generate QR codes for printing or displaying on screens.
+
+**Formats:** PNG (default), SVG, JPG
+
+Returns base64-encoded image data that can be saved or displayed.
+
+**Required:** POI ID only.`,
+
+  inputSchema: {
+    type: "object",
+    required: ["poiId"],
+    properties: {
+      poiId: {
+        type: "string",
+        description: "The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)"
+      },
+      format: {
+        type: "string",
+        enum: ["PNG", "SVG", "JPG"],
+        description: "Image format (default: PNG)",
+        default: "PNG"
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment for testing",
+        default: true
+      }
+    }
+  },
+
+  async handler(args) {
+    const { poiId, format = 'PNG', useSandbox = true } = args;
+
+    if (!poiId) throw new Error("POI ID is required");
+
+    const result = await getPOIQRCode({ poiId, format, useSandbox });
+
+    if (result.success) {
+      const img = result.image;
+      const sizeKB = (img.size / 1024).toFixed(2);
+
+      return {
+        content: [{
+          type: "text",
+          text: `📱 **POI QR Code Generated**
+
+**POI ID:** ${poiId}
+**Format:** ${img.format}
+**Size:** ${sizeKB} KB
+**Content-Type:** ${img.contentType}
+
+**Base64 Image Data:**
+\`\`\`
+${img.base64.substring(0, 100)}...
+\`\`\`
+
+**Usage:**
+- Save as file: decode base64 and write to ${poiId}.${format.toLowerCase()}
+- Display in HTML: \`<img src="data:${img.contentType};base64,${img.base64.substring(0, 20)}...">\`
+- Print for physical placement at point of sale
+
+**Full base64 length:** ${img.base64.length} characters
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Generate QR Code**
+
+**POI ID:** ${poiId}
+
+**Error:** ${result.error.message}
+**Status:** ${result.error.status || 'N/A'}
+
+**Common Issues:**
+- INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
+- POI_NOT_FOUND (404): POI doesn't exist
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  }
+};