@payware/mcp-server 1.3.2 → 1.4.0

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

@@ -1,16 +1,18 @@
 import { getProductDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { ADDS } from '../../shared/tool-annotations.js';
 
 /**
  * Get deep link for a merchant product
  */
 export const getProductLinkTool = {
   name: "payware_deep_links_get_product_link",
-  description: `Get an active deep link for a product. Returns a clickable URL that redirects to the payware mobile app.
+  annotations: ADDS,
+  description: `Get an active deep link for a product. Returns a clickable URL that redirects to the payware mobile app. For a link whose payments are attributed to one placement of the product (a poster, an ad, a mailing), use payware_products_get_placement_link instead.
 
 **Deep Link Format:**
 - Web URL: https://go.payware.eu/{productId}
-- Mobile Redirect: payware://{productId}
+- Mobile Redirect: payware:/{productId} (one slash: the identifier is case-sensitive, so it must not sit in the URI host, which redirect services lowercase)
 
 **Use Cases:**
 - Mobile-only e-commerce product references
@@ -19,6 +21,7 @@ export const getProductLinkTool = {
 
 **Important Notes:**
 - Deep links are only supported in production environment
+- Apps that open payware links must accept \`payware:\` followed by one, two or three slashes (QR codes and NFC tags carry \`payware://{id}\`): read the identifier after the scheme and any slashes, up to \`/\`, \`?\` or \`#\`, and keep its case
 - Link expiration is synchronized with the referenced product
 - Traditional deep links that route to app content when app is installed`,
 
@@ -37,8 +40,7 @@ export const getProductLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["productId"]
@@ -82,7 +84,7 @@ export const getProductLinkTool = {
 **Deep Link Details:**
 - Product ID: ${productId}
 - Web URL: ${linkUrl}
-- Mobile Redirect: payware://${productId}
+- Mobile Redirect: payware:/${productId}
 
 **Link Information:**
 - Status: Active
@@ -101,7 +103,7 @@ ${JSON.stringify(result.data, null, 2)}
 
 **Usage:**
 1. Share the web URL: \`${linkUrl}\`
-2. On mobile devices, it will redirect to: \`payware://${productId}\`
+2. On mobile devices, it will redirect to: \`payware:/${productId}\`
 3. Link expires when the product expires
 4. Recreate if product is updated`
         }]

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

@@ -1,16 +1,18 @@
 import { getTransactionDeepLink } from '../../shared/deep-links/api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { ADDS } from '../../shared/tool-annotations.js';
 
 /**
  * Get deep link for a merchant transaction
  */
 export const getTransactionLinkTool = {
   name: "payware_deep_links_get_transaction_link",
+  annotations: ADDS,
   description: `Get an active deep link for a transaction. Returns a clickable URL that redirects to the payware mobile app.
 
 **Deep Link Format:**
 - Web URL: https://go.payware.eu/{transactionId}
-- Mobile Redirect: payware://{transactionId}
+- Mobile Redirect: payware:/{transactionId} (one slash: the identifier is case-sensitive, so it must not sit in the URI host, which redirect services lowercase)
 
 **Use Cases:**
 - P2P payments via messaging services
@@ -19,6 +21,7 @@ export const getTransactionLinkTool = {
 
 **Important Notes:**
 - Deep links are only supported in production environment
+- Apps that open payware links must accept \`payware:\` followed by one, two or three slashes (QR codes and NFC tags carry \`payware://{id}\`): read the identifier after the scheme and any slashes, up to \`/\`, \`?\` or \`#\`, and keep its case
 - Link expiration is synchronized with the referenced transaction
 - Traditional deep links that route to app content when app is installed`,
 
@@ -37,8 +40,7 @@ export const getTransactionLinkTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       }
     },
     required: ["transactionId"]
@@ -82,7 +84,7 @@ export const getTransactionLinkTool = {
 **Deep Link Details:**
 - Transaction ID: ${transactionId}
 - Web URL: ${linkUrl}
-- Mobile Redirect: payware://${transactionId}
+- Mobile Redirect: payware:/${transactionId}
 
 **Link Information:**
 - Status: Active
@@ -101,7 +103,7 @@ ${JSON.stringify(result.data, null, 2)}
 
 **Usage:**
 1. Share the web URL: \`${linkUrl}\`
-2. On mobile devices, it will redirect to: \`payware://${transactionId}\`
+2. On mobile devices, it will redirect to: \`payware:/${transactionId}\`
 3. Link expires when the transaction expires
 4. Recreate if transaction is extended`
         }]
@@ -123,7 +125,7 @@ ${JSON.stringify(result.data, null, 2)}
 4. **Invalid transaction ID**: Ensure transaction ID format is correct
 
 **Troubleshooting:**
-1. Verify transaction exists using \`payware_transactions_get_transaction_status\`
+1. Verify transaction exists using \`payware_operations_get_transaction_status\`
 2. Check if running in production environment
 3. Ensure JWT authentication is working
 4. Confirm transaction is not expired`

package/src/merchant/index.js

@@ -26,6 +26,9 @@ import { merchantLogsTools } from './logs/index.js';
 // Shop tools - needed before any call that takes a shop / shopCode
 import { merchantShopTools } from './shops/index.js';
 
+// Campaigns, placements and airings - one definition shared by merchants and ISVs
+import { placementTools } from '../shared/placements/tools.js';
+
 // Shared utility tools
 import { getServerInfoTool } from '../utils/server-info.js';
 
@@ -60,7 +63,10 @@ export const merchantTools = [
   ...merchantLogsTools,
 
   // Shop lookup
-  ...merchantShopTools
+  ...merchantShopTools,
+
+  // Campaigns, placements and airings
+  ...placementTools('merchant')
 ];
 
 /**

package/src/merchant/logs/index.js

@@ -12,12 +12,14 @@ import {
   LOG_LEVELS
 } from '../../shared/logs/logs-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { LOCAL, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Query logs tool for merchants
  */
 export const queryLogsTool = {
   name: "payware_logs_query",
+  annotations: READS,
   description: "Query application logs with filters. Premium plan required. Returns paginated JSON log entries for debugging and monitoring your integration.",
   inputSchema: {
     type: "object",
@@ -174,6 +176,7 @@ Use cursor \`${nextCursor}\` to fetch the next page of results.` : ''}
  */
 export const getLogStatusTool = {
   name: "payware_logs_status",
+  annotations: READS,
   description: "Get log availability and storage information. Premium plan required. Shows if logs are available, total size, and file count.",
   inputSchema: {
     type: "object",
@@ -262,6 +265,7 @@ ${data.logsAvailable ? `
  */
 export const getLogDownloadUrlTool = {
   name: "payware_logs_download_url",
+  annotations: LOCAL,
   description: "Get download URL for logs archive. Premium plan required. Returns URL for downloading logs as gzipped JSON file.",
   inputSchema: {
     type: "object",

package/src/merchant/products/audios.js

@@ -6,15 +6,17 @@ import {
   deleteAudio
 } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Register audio tool implementation for merchants
  */
 export const registerAudioTool = {
   name: "payware_products_register_audio",
+  annotations: CREATES,
   description: `Register an audio file (soundbite) for a product to enable audio-based payment initiation.
 
-**Supported formats:** Most audio/video formats (up to 200MB)
+**Supported formats:** MP3, WAV, OGG, M4A, FLAC, AAC, WMA, MP4, MOV, up to 100 MB, holding 2 to 120 seconds of audio
 **Note:** For video files, only the audio channel is registered`,
 
   inputSchema: {
@@ -36,8 +38,7 @@ export const registerAudioTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -126,8 +127,8 @@ ${audio.status === '1' ? '✅ Audio is ready for use in soundbite transactions'
 
 **Troubleshooting:**
 1. Verify the audio file path exists and is accessible
-2. Check file size (max 200MB)
-3. Ensure supported audio/video format
+2. Check file size (max 100 MB) and length (2 to 120 seconds of audio)
+3. Ensure the format is MP3, WAV, OGG, M4A, FLAC, AAC, WMA, MP4 or MOV
 4. Verify the product ID exists and belongs to your account
 5. Check available storage space`
         }]
@@ -141,6 +142,7 @@ ${audio.status === '1' ? '✅ Audio is ready for use in soundbite transactions'
  */
 export const getAudiosTool = {
   name: "payware_products_get_audios",
+  annotations: READS,
   description: "Get all registered audio files for a product",
 
   inputSchema: {
@@ -158,8 +160,7 @@ export const getAudiosTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -253,6 +254,7 @@ ${audiosList}
  */
 export const getAudioTool = {
   name: "payware_products_get_audio",
+  annotations: READS,
   description: "Get detailed information about a specific audio file",
 
   inputSchema: {
@@ -274,8 +276,7 @@ export const getAudioTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -367,6 +368,7 @@ ${audio.status === '1' ? '✅ **Ready:** Audio is processed and ready for soundb
  */
 export const updateAudioTool = {
   name: "payware_products_update_audio",
+  annotations: CHANGES,
   description: "Update audio information (title) or reassign audio to another product",
 
   inputSchema: {
@@ -388,7 +390,7 @@ export const updateAudioTool = {
       },
       newProductId: {
         type: "string",
-        description: "New product ID to reassign audio to (starts with 'pr')",
+        description: "Product to move the audio to (starts with 'pr'). Sent as a transfer, which keeps the fingerprint; the target must be in the same shop",
         pattern: "^pr[a-zA-Z0-9]+$"
       },
       partnerId: {
@@ -398,8 +400,7 @@ export const updateAudioTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -501,6 +502,7 @@ ${JSON.stringify(audio, null, 2)}
  */
 export const deleteAudioTool = {
   name: "payware_products_delete_audio",
+  annotations: CHANGES,
   description: "Delete an audio file from a product. This action cannot be undone.",
 
   inputSchema: {
@@ -522,8 +524,7 @@ export const deleteAudioTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

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

@@ -1,12 +1,14 @@
 import { createProduct } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { PRODUCT_TYPES, OVERLAP_PRIORITY } from '../../shared/products/products-api.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create product tool implementation for merchants
  */
 export const createProductTool = {
   name: "payware_products_create_product",
+  annotations: CREATES,
   description: `Create a new product for inventory management and payment processing.
 
 **Product Structure:**
@@ -134,8 +136,7 @@ export const createProductTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe(true)
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/delete-product.js

@@ -1,11 +1,13 @@
 import { deleteProduct } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Delete product tool implementation for merchants
  */
 export const deleteProductTool = {
   name: "payware_products_delete_product",
+  annotations: CHANGES,
   description: "Delete a product from the merchant account. This action cannot be undone.",
 
   inputSchema: {
@@ -23,8 +25,7 @@ export const deleteProductTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/get-product-image.js

@@ -1,12 +1,14 @@
 import { getProductImage } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { IMAGE_TYPES, IMAGE_FORMATS, QR_ERROR_CORRECTION, BARCODE_LOCATIONS } from '../../shared/products/products-api.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get product image tool implementation for merchants
  */
 export const getProductImageTool = {
   name: "payware_products_get_product_image",
+  annotations: READS,
   description: `Generate a QR code or barcode image for a product.
 
 **QR Code Options:** Format, border, error correction, scale, version
@@ -102,8 +104,7 @@ export const getProductImageTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/get-product.js

@@ -1,11 +1,13 @@
 import { getProduct } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get product tool implementation for merchants
  */
 export const getProductTool = {
   name: "payware_products_get_product",
+  annotations: READS,
   description: "Get detailed information about a specific product by ID",
 
   inputSchema: {
@@ -23,8 +25,7 @@ export const getProductTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/list-products.js

@@ -1,11 +1,13 @@
 import { getProducts } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * List products tool implementation for merchants
  */
 export const listProductsTool = {
   name: "payware_products_list_products",
+  annotations: READS,
   description: "Get a list of all products for the merchant account",
 
   inputSchema: {
@@ -18,8 +20,7 @@ export const listProductsTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/schedules.js

@@ -7,12 +7,14 @@ import {
 } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { PRICE_CORRECTION_TYPES, CORRECTION_TYPES } from '../../shared/products/products-api.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Create price schedule tool implementation for merchants
  */
 export const createScheduleTool = {
   name: "payware_products_create_schedule",
+  annotations: CREATES,
   description: "Create a price schedule for a product to manage time-based pricing",
 
   inputSchema: {
@@ -62,8 +64,7 @@ export const createScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -174,6 +175,7 @@ ${JSON.stringify(schedule, null, 2)}
  */
 export const getSchedulesTool = {
   name: "payware_products_get_schedules",
+  annotations: READS,
   description: "Get all price schedules for a product",
 
   inputSchema: {
@@ -191,8 +193,7 @@ export const getSchedulesTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -286,6 +287,7 @@ ${schedulesList}
  */
 export const getScheduleTool = {
   name: "payware_products_get_schedule",
+  annotations: READS,
   description: "Get detailed information about a specific price schedule",
 
   inputSchema: {
@@ -307,8 +309,7 @@ export const getScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -399,6 +400,7 @@ ${JSON.stringify(schedule, null, 2)}
  */
 export const updateScheduleTool = {
   name: "payware_products_update_schedule",
+  annotations: CHANGES,
   description: "Update an existing price schedule. Only provide fields you want to change.",
 
   inputSchema: {
@@ -449,8 +451,7 @@ export const updateScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",
@@ -547,6 +548,7 @@ ${JSON.stringify(schedule, null, 2)}
  */
 export const deleteScheduleTool = {
   name: "payware_products_delete_schedule",
+  annotations: CHANGES,
   description: "Delete a price schedule. This action cannot be undone.",
 
   inputSchema: {
@@ -568,8 +570,7 @@ export const deleteScheduleTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/products/update-product.js

@@ -1,12 +1,14 @@
 import { updateProduct } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { PRODUCT_TYPES, OVERLAP_PRIORITY } from '../../shared/products/products-api.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Update product tool implementation for merchants
  */
 export const updateProductTool = {
   name: "payware_products_update_product",
+  annotations: CHANGES,
   description: `Update an existing product. Only provide the fields you want to change.
 
 **Product Structure:**
@@ -128,8 +130,7 @@ export const updateProductTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication (uses environment-specific private key as default)",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication (uses environment-specific private key as default)"
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/transactions/cancel-transaction.js

@@ -3,6 +3,7 @@ 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';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Cancel a transaction via payware API
@@ -76,6 +77,7 @@ export async function cancelTransaction({
  */
 export const cancelTransactionTool = {
   name: "payware_operations_cancel_transaction",
+  annotations: CHANGES,
   description: "Cancel an ACTIVE transaction created by this merchant. Only the merchant who created the transaction can cancel it, and only before it has been processed.",
   inputSchema: {
     type: "object",
@@ -104,8 +106,7 @@ export const cancelTransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default."
       },
       useSandbox: {
         type: "boolean",

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

@@ -2,6 +2,7 @@ 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 { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create a transaction via payware API
@@ -196,6 +197,7 @@ Original error: ${enhancedMessage}`;
  */
 export const createTransactionTool = {
   name: "payware_operations_create_transaction",
+  annotations: CREATES,
   description: `Create a new payware transaction. Parameters map to the following API structure:
 
 📋 **ROOT LEVEL** (Transaction metadata):
@@ -524,7 +526,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 
 **Next Steps:**
 1. Save the transaction ID: \`${result.transaction.transactionId || 'N/A'}\`
-2. Use \`payware_transactions_get_transaction_status\` to check status
+2. Use \`payware_operations_get_transaction_status\` to check status
 3. Wait for callback notification (if callback URL provided)
 4. Process payment through payware interface`
         }]

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

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction status from payware API
@@ -67,11 +68,12 @@ function formatTransactionStatus(transaction) {
  */
 export const getTransactionStatusTool = {
   name: "payware_operations_get_transaction_status", 
+  annotations: READS,
   description: `Get status of an ACTIVE transaction by ID (for completed/expired transactions use transaction history tool).
 
 **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.
+**Note:** For transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use 'payware_operations_get_transaction_history' instead.
 
 🛍️ **Product-originated transactions carry a nested \`product\` object.** Since 2026-07-22 the
 presentation fields are grouped under \`product\` rather than sitting flat on the response - the old
@@ -123,8 +125,7 @@ with ERR_FEE_MISMATCH. Echo \`fee\` back unchanged instead.`,
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default."
       },
       useSandbox: {
         type: "boolean",

package/src/merchant/transactions/process-transaction.js

@@ -3,6 +3,7 @@ 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';
+import { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Process a transaction via payware API (for merchants accepting payments)
@@ -107,6 +108,7 @@ export async function processTransaction({
  */
 export const processTransactionTool = {
   name: "payware_operations_process_transaction",
+  annotations: COMMITS,
   description: `Process a PEER transaction (for merchants accepting payments by scanning customer QR/barcode).
 
 **Use Case:** Merchant scans customer's payware QR code or barcode to accept payment.
@@ -138,8 +140,8 @@ export const processTransactionTool = {
     properties: {
       transactionId: {
         type: "string",
-        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
-        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
+        pattern: "^(pw|pr|pl|ps)[0-9A-Za-z]{8}$"
       },
       amount: {
         type: ["number", "string"], 
@@ -207,8 +209,7 @@ export const processTransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default."
       },
       useSandbox: {
         type: "boolean",