@payware/mcp-server 1.3.1 → 1.3.3

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

@@ -1,168 +1,194 @@
-import axios from 'axios';
-import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
-import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
-import { apiErrorResult } from '../../shared/api-errors.js';
-
-/**
- * Get POI status via ISV authentication
- * @param {Object} params - Parameters for status request
- * @returns {Object} POI status response
- */
-export async function getPOIStatus({ 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.get(`${baseUrl}/poi/${poiId}/status`, { headers });
-
-    return {
-      success: true,
-      status: response.data,
-      requestId: response.headers['x-request-id'],
-      timestamp: new Date().toISOString()
-    };
-  } catch (error) {
-    return apiErrorResult(error);
-  }
-}
-
-/**
- * Get POI status tool implementation for ISV
- */
-export const getPOIStatusTool = {
-  name: "payware_poi_get_status",
-  description: `Get current status of a POI including any pending payment.
-
-**ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
-**Endpoint:** GET /poi/{poiId}/status
-**Use Case:** Check if a POI is idle, has a pending price, or is busy with a payment.
-
-**POI States:**
-- IDLE: Ready for new payment
-- READY: Price set, waiting for customer scan
-- BUSY: Payment in progress
-- DISABLED: Not accepting payments
-
-**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 getPOIStatus({ poiId, merchantPartnerId, oauth2Token, useSandbox });
-
-    if (result.success) {
-      const status = result.status;
-      const statusEmoji = {
-        'IDLE': '🟢',
-        'READY': '🟡',
-        'BUSY': '🔴',
-        'DISABLED': '⚫'
-      }[status.status] || '⚪';
-
-      let pendingInfo = '';
-      if (status.status === 'READY' || status.status === 'BUSY') {
-        pendingInfo = `
-**Pending Payment:**
-- Amount: ${status.pendingAmount} ${status.pendingCurrency}
-- Expires: ${status.sessionExpiresAt || 'N/A'}${status.transactionId ? `\n- Transaction: ${status.transactionId}` : ''}`;
-      }
-
-      return {
-        content: [{
-          type: "text",
-          text: `${statusEmoji} **POI Status: ${status.status}**
-
-**POI ID:** ${status.poiId}
-**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
-${pendingInfo}
-
-**Status Meaning:**
-${status.status === 'IDLE' ? '✅ POI is ready to accept a new price' : ''}${status.status === 'READY' ? '⏳ Price set, waiting for customer to scan' : ''}${status.status === 'BUSY' ? '🔄 Customer scanned, payment in progress' : ''}${status.status === 'DISABLED' ? '🚫 POI is disabled and cannot accept payments' : ''}
-
-**Request ID:** ${result.requestId || 'N/A'}
-**Timestamp:** ${result.timestamp}`
-        }]
-      };
-    } else {
-      return {
-        content: [{
-          type: "text",
-          text: `❌ **Failed to Get POI Status**
-
-**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}`
-        }]
-      };
-    }
-  }
-};
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { apiErrorResult } from '../../shared/api-errors.js';
+
+/**
+ * Get POI status via ISV authentication
+ * @param {Object} params - Parameters for status request
+ * @returns {Object} POI status response
+ */
+export async function getPOIStatus({ poiId, sessionToken, 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();
+    // The session token pins one sale: with it the response also carries that session's
+    // transactionId and transactionStatus. A GET is signed without a body, so the query string is free.
+    const query = sessionToken ? `?sessionToken=${encodeURIComponent(sessionToken)}` : '';
+    const response = await axios.get(`${baseUrl}/poi/${poiId}/status${query}`, { headers });
+
+    return {
+      success: true,
+      status: response.data,
+      requestId: response.headers['x-request-id'],
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    return apiErrorResult(error);
+  }
+}
+
+/**
+ * Get POI status tool implementation for ISV
+ */
+export const getPOIStatusTool = {
+  name: "payware_poi_get_status",
+  description: `Get the current status of a POI and the outcome of its sales.
+
+**ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
+**Endpoint:** GET /poi/{poiId}/status[?sessionToken=...]
+**Use Case:** Follow a sale to its outcome - the backup to callbacks, and on Basic (no transaction
+endpoints) the only way when a callback is lost or there is no backend.
+
+**POI States:**
+- IDLE: no pending price and no sale running
+- READY: price set, waiting for a scan (wins over BUSY: the POI can take the next price while a sale runs)
+- BUSY: a customer scanned and the sale is running
+
+**Every response** carries lastTransactionId / lastTransactionStatus - the POI's most recent sale, running
+(ACTIVE) or finished (CONFIRMED, DECLINED, FAILED, CANCELLED, EXPIRED). Once the POI is back to IDLE,
+lastTransactionStatus is how the last sale ended.
+
+**With sessionToken** (from payware_poi_set_price) the response also carries transactionId /
+transactionStatus for exactly that sale - use it when the POI may be re-armed before the previous sale
+finishes. Poll every 2-3 seconds and stop at a final status; the read is rate limited.
+
+**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)"
+      },
+      sessionToken: {
+        type: "string",
+        description: "Optional. The sessionToken returned by payware_poi_set_price; returns that sale's transaction and status"
+      },
+      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, sessionToken, 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 getPOIStatus({ poiId, sessionToken, merchantPartnerId, oauth2Token, useSandbox });
+
+    if (result.success) {
+      const status = result.status;
+      const statusEmoji = {
+        'IDLE': '🟢',
+        'READY': '🟡',
+        'BUSY': '🔴'
+      }[status.status] || '⚪';
+      const meaning = {
+        'IDLE': status.lastTransactionId
+          ? `No sale running. The last sale ended ${status.lastTransactionStatus}.`
+          : 'No sale running, and the POI has not had a sale yet.',
+        'READY': 'Price set, waiting for a customer to scan.',
+        'BUSY': 'A customer scanned and the sale is running.'
+      }[status.status] || '';
+
+      const pendingInfo = status.status === 'READY' ? `
+**Pending Price:**
+- Amount: ${status.pendingAmount} ${status.pendingCurrency}
+- Session expires: ${status.sessionExpiresAt || 'N/A'}` : '';
+
+      const lastSale = status.lastTransactionId ? `
+**Last Sale:** ${status.lastTransactionId} - ${status.lastTransactionStatus}` : '';
+
+      const pinnedSale = sessionToken ? `
+**Sale for this session token:** ${status.transactionId
+          ? `${status.transactionId} - ${status.transactionStatus}`
+          : 'not scanned yet (or the token does not belong to this POI)'}` : '';
+
+      return {
+        content: [{
+          type: "text",
+          text: `${statusEmoji} **POI Status: ${status.status}**
+
+**POI ID:** ${status.poiId}
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
+${pendingInfo}${lastSale}${pinnedSale}
+
+**Meaning:** ${meaning}
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Get POI Status**
+
+**POI ID:** ${poiId}
+**Error:** ${result.error.message}
+**Status:** ${result.error.status || 'N/A'}
+
+**Common Issues:**
+- ERR_INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
+- ERR_POI_NOT_FOUND (404): POI doesn't exist, or is disabled
+- ERR_SHOP_NOT_IN_SCOPE (403): the POI's shop is not assigned to you
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/poi/list-pois.js

@@ -64,7 +64,7 @@ export const listPOIsTool = {
 **Endpoint:** GET /poi
 **Use Case:** Retrieve all physical payment points configured for a merchant.
 
-POI states: IDLE (ready), READY (price set), BUSY (payment in progress), DISABLED.
+POI states: IDLE (no price, no sale running), READY (price set, waiting for a scan), BUSY (scanned, sale running). A disabled POI is not a state: it shows isActive false.
 
 **Required:** Merchant Partner ID and OAuth2 token for ISV authentication.`,
 
@@ -106,13 +106,12 @@ POI states: IDLE (ready), READY (price set), BUSY (payment in progress), DISABLE
         const statusEmoji = {
           'IDLE': '🟢',
           'READY': '🟡',
-          'BUSY': '🔴',
-          'DISABLED': '⚫'
+          'BUSY': '🔴'
         }[poi.status] || '⚪';
 
         return `${statusEmoji} **${poi.name}** (${poi.poiId})
    Shop: ${poi.shopName || poi.shopCode}
-   Status: ${poi.status}${poi.pendingAmount && poi.pendingAmount !== '0.00' ? ` | Pending: ${poi.pendingAmount} ${poi.pendingCurrency}` : ''}`;
+   Status: ${poi.status}${poi.isActive === false ? ' (disabled)' : ''}${poi.pendingAmount && poi.pendingAmount !== '0.00' ? ` | Pending: ${poi.pendingAmount} ${poi.pendingCurrency}` : ''}`;
       }).join('\n\n');
 
       return {
@@ -127,8 +126,7 @@ ${poisList || 'No POIs found for this merchant.'}
 **Status Legend:**
 🟢 IDLE - Ready for new payment
 🟡 READY - Price set, waiting for customer
-🔴 BUSY - Payment in progress
-⚫ DISABLED - Not accepting payments
+🔴 BUSY - Scanned, sale running (payware_poi_get_status shows its outcome)
 
 **Request ID:** ${result.requestId || 'N/A'}
 **Timestamp:** ${result.timestamp}`

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

@@ -8,7 +8,7 @@ import { apiErrorResult } from '../../shared/api-errors.js';
  * @param {Object} params - Parameters for set price request
  * @returns {Object} Set price response
  */
-export async function setPOIPrice({ poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams, merchantPartnerId, oauth2Token, useSandbox = true }) {
+export async function setPOIPrice({ poiId, amount, currency, ttlSeconds, merchantPartnerId, oauth2Token, useSandbox = true }) {
   if (!poiId) {
     throw new Error('POI ID is required');
   }
@@ -21,10 +21,6 @@ export async function setPOIPrice({ poiId, amount, currency, reasonL1, reasonL2,
     throw new Error('Currency is required');
   }
 
-  if (!reasonL1) {
-    throw new Error('Reason (reasonL1) is required');
-  }
-
   if (!merchantPartnerId) {
     throw new Error('Merchant Partner ID is required for ISV operations');
   }
@@ -36,17 +32,16 @@ export async function setPOIPrice({ poiId, amount, currency, reasonL1, reasonL2,
   const isvPartnerId = getPartnerIdSafe();
   const privateKey = getPrivateKeySafe(useSandbox);
 
-  // Build request body
+  // amount, currency and ttlSeconds are the only fields the server reads (POIPriceRequest); anything
+  // else is ignored without an error. This used to send reasonL1 (and demand it), reasonL2,
+  // timeToLive, callbackUrl and passbackParams - none of which the server has - so a caller relying
+  // on the per-price callbackUrl got no callbacks at all. The callback URL belongs to the POI.
   const requestBody = {
     amount: String(amount),
-    currency: currency.toUpperCase(),
-    reasonL1
+    currency: currency.toUpperCase()
   };
 
-  if (reasonL2) requestBody.reasonL2 = reasonL2;
-  if (timeToLive) requestBody.timeToLive = timeToLive;
-  if (callbackUrl) requestBody.callbackUrl = callbackUrl;
-  if (passbackParams) requestBody.passbackParams = passbackParams;
+  if (ttlSeconds) requestBody.ttlSeconds = ttlSeconds;
 
   const jwtData = await createJWTForPartner({
     partnerId: isvPartnerId,
@@ -88,13 +83,21 @@ export const setPOIPriceTool = {
 **Endpoint:** PUT /poi/{poiId}/price
 **Use Case:** Set the amount a customer should pay when they scan the POI.
 
-The POI will transition to READY state and wait for a customer scan until the TTL expires.
+The POI moves to READY and waits for a scan until the TTL expires. The scan creates the transaction and
+the POI is BUSY until the sale is final.
+
+**Only amount, currency and ttlSeconds are accepted.** There is no description, callback URL or passback
+field on a price - the callback URL is set on the POI when it is created, and a POI without one sends no
+callbacks.
+
+**Keep the returned sessionToken** until the sale has a final status: pass it to
+payware_poi_get_status to read that sale's transaction and outcome.
 
-**Required:** POI ID, amount, currency, reason, Merchant Partner ID, and OAuth2 token.`,
+**Required:** POI ID, amount, currency, Merchant Partner ID, and OAuth2 token.`,
 
   inputSchema: {
     type: "object",
-    required: ["poiId", "amount", "currency", "reasonL1", "merchantPartnerId", "oauth2Token"],
+    required: ["poiId", "amount", "currency", "merchantPartnerId", "oauth2Token"],
     properties: {
       poiId: {
         type: "string",
@@ -102,31 +105,15 @@ The POI will transition to READY state and wait for a customer scan until the TT
       },
       amount: {
         type: "string",
-        description: "Payment amount (e.g., '25.50')"
+        description: "Payment amount (e.g., '25.50'), positive and no finer than the currency's smallest unit"
       },
       currency: {
         type: "string",
         description: "ISO 4217 currency code (e.g., 'EUR', 'USD', 'GBP')"
       },
-      reasonL1: {
-        type: "string",
-        description: "Payment description (e.g., 'Table 5', 'Order #123')"
-      },
-      reasonL2: {
-        type: "string",
-        description: "Additional description (optional)"
-      },
-      timeToLive: {
+      ttlSeconds: {
         type: "integer",
-        description: "Seconds until price expires (60-600, default: 120)"
-      },
-      callbackUrl: {
-        type: "string",
-        description: "Override callback URL for this payment (optional)"
-      },
-      passbackParams: {
-        type: "string",
-        description: "Data to pass back in callback (optional, max 200 chars)"
+        description: "Seconds until the price expires if nobody scans it (60-600). Defaults to the POI's own ttlSeconds."
       },
       merchantPartnerId: {
         type: "string",
@@ -145,18 +132,16 @@ The POI will transition to READY state and wait for a customer scan until the TT
   },
 
   async handler(args) {
-    const { poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams, merchantPartnerId, oauth2Token, useSandbox = true } = args;
+    const { poiId, amount, currency, ttlSeconds, merchantPartnerId, oauth2Token, useSandbox = true } = args;
 
     if (!poiId) throw new Error("POI ID is required");
     if (!amount) throw new Error("Amount is required");
     if (!currency) throw new Error("Currency is required");
-    if (!reasonL1) throw new Error("Reason (reasonL1) is required");
     if (!merchantPartnerId) throw new Error("Merchant Partner ID is required");
     if (!oauth2Token) throw new Error("OAuth2 token is required");
 
     const result = await setPOIPrice({
-      poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams,
-      merchantPartnerId, oauth2Token, useSandbox
+      poiId, amount, currency, ttlSeconds, merchantPartnerId, oauth2Token, useSandbox
     });
 
     if (result.success) {
@@ -169,19 +154,17 @@ The POI will transition to READY state and wait for a customer scan until the TT
 
 **POI ID:** ${data.poiId || poiId}
 **Status:** 🟡 ${data.status || 'READY'}
-
-**Payment Details:**
-- Amount: **${data.amount || amount} ${data.currency || currency}**
-- Reason: ${reasonL1}${reasonL2 ? ` - ${reasonL2}` : ''}
+**Amount:** ${amount} ${currency.toUpperCase()}
 
 **Session:**
-- Token: ${data.sessionToken || 'N/A'}
-- Expires: ${data.sessionExpiresAt || 'N/A'}
+- Token: ${data.sessionToken || 'N/A'} - keep it until the sale is final
+- Price expires if not scanned: ${data.expiresAt || 'N/A'}
 
 **Next Steps:**
-1. Customer scans the POI (QR code, NFC tag, or barcode)
-2. Customer sees the amount and confirms payment
-3. You receive a callback when payment completes
+1. The customer scans the POI (QR code, NFC tag or BLE); the transaction is created and the POI is BUSY
+2. Outcome by callback, if the POI has a callbackUrl: poi.scanned with the transaction id, then TRANSACTION_FINALIZED with the final status (both carry the poiId)
+3. Or poll payware_poi_get_status every 2-3 seconds with this sessionToken until transactionStatus is final
+4. To cancel, use payware_poi_cancel_price - possible only before the scan
 
 **ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
 **Request ID:** ${result.requestId || 'N/A'}
@@ -202,12 +185,14 @@ The POI will transition to READY state and wait for a customer scan until the TT
 **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_DISABLED (409): POI is disabled
-- POI_NOT_IDLE (409): POI already has a pending price (cancel it first)
-- INVALID_AMOUNT (400): Check amount format (e.g., '25.50')
-- UNKNOWN_CURRENCY (400): Invalid currency code
+- ERR_INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
+- ERR_POI_NOT_FOUND (404): POI doesn't exist or doesn't belong to the merchant
+- ERR_SHOP_NOT_IN_SCOPE (403): the POI's shop is not assigned to you
+- ERR_POI_DISABLED (409): POI is disabled
+- ERR_POI_ALREADY_HAS_PENDING_PRICE (409): POI already has a pending price (cancel it first)
+- ERR_INVALID_AMOUNT (400): amount finer than the currency's smallest unit
+- ERR_MISSING_CURRENCY (400): currency missing or unknown
+- ERR_VALIDATION_FAILED (400): amount missing or not positive, or ttlSeconds outside 60-600
 
 **Timestamp:** ${result.timestamp}`
         }]

package/src/isv/products/create-product.js

@@ -70,7 +70,7 @@ export const createProductTool = {
       },
       shop: {
         type: "string",
-        description: "Shop code (if not supplied, default shop is used)",
+        description: "Shop code. If omitted, the merchant's default shop is used - which may be outside your assigned scope (403 ERR_SHOP_NOT_IN_SCOPE). Find valid codes with payware_shops_list.",
         maxLength: 10
       },
       // Product Data Properties