@payware/mcp-server 1.3.3 → 1.5.0

package/src/isv/invitations/index.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Merchant invitations - how an ISV onboards a merchant onto payware.
@@ -181,6 +182,7 @@ ${result.error.guidance ? `\n${result.error.guidance}` : ''}
 
 export const createInvitationTool = {
   name: 'payware_isv_create_invitation',
+  annotations: CREATES,
   description: `Invite a merchant to join payware through this ISV. **This is the start of the ISV onboarding flow.**
 
 **Endpoint:** POST /isv/invitations -> 201 Created
@@ -300,6 +302,7 @@ to start acting on their behalf.
 
 export const listInvitationsTool = {
   name: 'payware_isv_list_invitations',
+  annotations: READS,
   description: `List the merchant invitations this ISV has created, newest first.
 
 **Endpoint:** GET /isv/invitations - paginated
@@ -362,6 +365,7 @@ to was deleted.
 
 export const getInvitationTool = {
   name: 'payware_isv_get_invitation',
+  annotations: READS,
   description: `Get full details of one invitation, including its link and the merchant data it pre-fills.
 
 **Endpoint:** GET /isv/invitations/{invitationId}
@@ -416,6 +420,7 @@ ${inv.invitationLink}
 
 export const cancelInvitationTool = {
   name: 'payware_isv_cancel_invitation',
+  annotations: CHANGES,
   description: `Cancel a PENDING invitation. **The link stops working immediately.**
 
 **Endpoint:** DELETE /isv/invitations/{invitationId} -> 204 No Content

package/src/isv/oauth2/get-token-info.js

@@ -5,8 +5,11 @@
  * Use this to check token status and present information in POS software UI.
  */
 
+import { READS } from '../../shared/tool-annotations.js';
+
 export const getTokenInfoTool = {
   name: 'payware_authorization_oauth2_get_token_info',
+  annotations: READS,
   description: `Get information about an OAuth2 access token.
 
 This endpoint exposes information about access tokens, including their status.

package/src/isv/oauth2/obtain-token.js

@@ -5,8 +5,11 @@
  * This is the first step in the ISV authorization flow.
  */
 
+import { CREATES } from '../../shared/tool-annotations.js';
+
 export const obtainTokenTool = {
   name: 'payware_authorization_oauth2_obtain_token',
+  annotations: CREATES,
   description: `Obtain an OAuth2 access token for a merchant.
 
 ISVs must be authorized by payware registered merchants to make requests on their behalf.

package/src/isv/oauth2/token-helper.js

@@ -5,12 +5,14 @@
 
 import { obtainTokenTool } from './obtain-token.js';
 import { getTokenInfoTool } from './get-token-info.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Helper tool to create or find OAuth2 tokens with clear output
  */
 export const tokenHelperTool = {
   name: 'payware_authorization_oauth2_token_helper',
+  annotations: CREATES,
   description: `OAuth2 Token Helper - Create or manage tokens with clear output.
 
 This tool helps you:

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

@@ -2,6 +2,7 @@ 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';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Cancel pending price on a POI via ISV authentication
@@ -57,6 +58,7 @@ export async function cancelPOIPrice({ poiId, merchantPartnerId, oauth2Token, us
  */
 export const cancelPOIPriceTool = {
   name: "payware_poi_cancel_price",
+  annotations: CHANGES,
   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.

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

@@ -2,6 +2,7 @@ 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';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get POI details via ISV authentication
@@ -61,6 +62,7 @@ export async function getPOI({ poiId, merchantPartnerId, oauth2Token, useSandbox
  */
 export const getPOITool = {
   name: "payware_poi_get",
+  annotations: READS,
   description: `Get details of a specific POI (Point of Interaction).
 
 **ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.

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

@@ -1,19 +1,41 @@
 import axios from 'axios';
-import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.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 POI QR code image
- * Note: This endpoint is public and doesn't require authentication
+ * Get POI QR code image via ISV authentication
+ *
+ * Not a public endpoint: the server resolves the merchant from the token and only answers for that
+ * merchant's own POIs (ApiPOIController.getQRCode, V-05), so an unauthenticated request was refused.
  * @param {Object} params - Parameters for QR code request
  * @returns {Object} QR code response
  */
-export async function getPOIQRCode({ poiId, format = 'PNG', useSandbox = true }) {
+export async function getPOIQRCode({ poiId, format = 'PNG', 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');
+  }
+
+  // Create ISV JWT token (GET request - no body)
+  const jwtData = await createJWTForPartner({
+    partnerId: getPartnerIdSafe(),
+    privateKey: getPrivateKeySafe(useSandbox),
+    requestBody: null,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
   const headers = {
+    'Authorization': `Bearer ${jwtData.token}`,
     'Api-Version': '1'
   };
 
@@ -49,26 +71,35 @@ export async function getPOIQRCode({ poiId, format = 'PNG', useSandbox = true })
  */
 export const getPOIQRCodeTool = {
   name: "payware_poi_get_qrcode",
+  annotations: READS,
   description: `Generate a QR code image for a POI that customers can scan.
 
 **Endpoint:** GET /poi/{poiId}/image
-**Authentication:** Public endpoint (no auth required)
+**Authentication:** On behalf of the merchant that owns the POI
 **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.`,
+**Required:** POI ID, and the merchant partner ID and OAuth2 token to act on its behalf.`,
 
   inputSchema: {
     type: "object",
-    required: ["poiId"],
+    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"
+      },
       format: {
         type: "string",
         enum: ["PNG", "SVG", "JPG"],
@@ -84,11 +115,11 @@ Returns base64-encoded image data that can be saved or displayed.
   },
 
   async handler(args) {
-    const { poiId, format = 'PNG', useSandbox = true } = args;
+    const { poiId, format = 'PNG', merchantPartnerId, oauth2Token, useSandbox = true } = args;
 
     if (!poiId) throw new Error("POI ID is required");
 
-    const result = await getPOIQRCode({ poiId, format, useSandbox });
+    const result = await getPOIQRCode({ poiId, format, merchantPartnerId, oauth2Token, useSandbox });
 
     if (result.success) {
       const img = result.image;

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

@@ -2,6 +2,7 @@ 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';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get POI status via ISV authentication
@@ -61,6 +62,7 @@ export async function getPOIStatus({ poiId, sessionToken, merchantPartnerId, oau
  */
 export const getPOIStatusTool = {
   name: "payware_poi_get_status",
+  annotations: READS,
   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.

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

@@ -2,6 +2,7 @@ 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';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * List all POIs for a merchant via ISV authentication
@@ -58,6 +59,7 @@ export async function listPOIs({ merchantPartnerId, oauth2Token, useSandbox = tr
  */
 export const listPOIsTool = {
   name: "payware_poi_list",
+  annotations: READS,
   description: `List all POIs (Points of Interaction) for a merchant.
 
 **ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.

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

@@ -2,6 +2,7 @@ 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';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Set price on a POI via ISV authentication
@@ -77,6 +78,7 @@ export async function setPOIPrice({ poiId, amount, currency, ttlSeconds, merchan
  */
 export const setPOIPriceTool = {
   name: "payware_poi_set_price",
+  annotations: CHANGES,
   description: `Set a pending price on a POI for customer payment.
 
 **ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.

package/src/isv/products/audios.js

@@ -6,6 +6,7 @@ import {
   deleteAudio
 } from '../../shared/products/products-api.js';
 import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 // Common ISV authentication properties
 const ISV_AUTH_PROPS = {
@@ -46,9 +47,10 @@ function validateISVAuth(args) {
  */
 export const registerAudioTool = {
   name: "payware_products_register_audio",
+  annotations: CREATES,
   description: `Register an audio file (soundbite) for a merchant's product (ISV operation).
 
-**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: {
@@ -139,6 +141,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 merchant's product (ISV operation)",
 
   inputSchema: {
@@ -225,6 +228,7 @@ ${audiosList}`
  */
 export const getAudioTool = {
   name: "payware_products_get_audio",
+  annotations: READS,
   description: "Get detailed information about a specific audio file (ISV operation)",
 
   inputSchema: {
@@ -305,6 +309,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 (ISV operation)",
 
   inputSchema: {
@@ -327,7 +332,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]+$"
       },
       useSandbox: {
@@ -400,6 +405,7 @@ ${newProductId ? `- Reassigned from product ${productId} to ${newProductId}` : '
  */
 export const deleteAudioTool = {
   name: "payware_products_delete_audio",
+  annotations: CHANGES,
   description: "Delete an audio file from a merchant's product (ISV operation). This action cannot be undone.",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const createProductTool = {
   name: "payware_products_create_product",
+  annotations: CREATES,
   description: `Create a new product for inventory management and payment processing on behalf of a merchant (ISV operation).
 
 **ISV Authentication**: Requires ISV credentials and OAuth2 token from target merchant.

package/src/isv/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 ISVs
  */
 export const deleteProductTool = {
   name: "payware_products_delete_product",
+  annotations: CHANGES,
   description: "Delete a product from a merchant account (ISV operation). This action cannot be undone.",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const getProductImageTool = {
   name: "payware_products_get_product_image",
+  annotations: READS,
   description: `Generate a QR code or barcode image for a merchant's product (ISV operation).`,
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const getProductTool = {
   name: "payware_products_get_product",
+  annotations: READS,
   description: "Get detailed information about a specific product by ID (ISV operation)",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const listProductsTool = {
   name: "payware_products_list_products",
+  annotations: READS,
   description: "Get a list of all products for a merchant account (ISV operation)",
 
   inputSchema: {

package/src/isv/products/schedules.js

@@ -7,6 +7,7 @@ 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';
 
 // Common ISV authentication properties
 const ISV_AUTH_PROPS = {
@@ -47,6 +48,7 @@ function validateISVAuth(args) {
  */
 export const createScheduleTool = {
   name: "payware_products_create_schedule",
+  annotations: CREATES,
   description: "Create a price schedule for a merchant's product (ISV operation)",
 
   inputSchema: {
@@ -172,6 +174,7 @@ export const createScheduleTool = {
  */
 export const getSchedulesTool = {
   name: "payware_products_get_schedules",
+  annotations: READS,
   description: "Get all price schedules for a merchant's product (ISV operation)",
 
   inputSchema: {
@@ -258,6 +261,7 @@ ${schedulesList}`
  */
 export const getScheduleTool = {
   name: "payware_products_get_schedule",
+  annotations: READS,
   description: "Get detailed information about a specific price schedule (ISV operation)",
 
   inputSchema: {
@@ -341,6 +345,7 @@ export const getScheduleTool = {
  */
 export const updateScheduleTool = {
   name: "payware_products_update_schedule",
+  annotations: CHANGES,
   description: "Update an existing price schedule (ISV operation)",
 
   inputSchema: {
@@ -452,6 +457,7 @@ export const updateScheduleTool = {
  */
 export const deleteScheduleTool = {
   name: "payware_products_delete_schedule",
+  annotations: CHANGES,
   description: "Delete a price schedule (ISV operation). This action cannot be undone.",
 
   inputSchema: {

package/src/isv/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 ISVs
  */
 export const updateProductTool = {
   name: "payware_products_update_product",
+  annotations: CHANGES,
   description: `Update an existing product on behalf of a merchant (ISV operation). Only provide the fields you want to change.`,
 
   inputSchema: {

package/src/isv/reference/index.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Reference data - the enumerations a merchant registration form has to be filled in with.
@@ -129,6 +130,7 @@ const DATASET_DOCS = Object.entries(DATASETS)
 
 export const referenceDataTool = {
   name: 'payware_reference_lookup',
+  annotations: READS,
   description: `Look up payware reference data - the enumerations a merchant registration form needs.
 
 **Endpoints:** GET /isv/reference/{legal-forms, business-activities, currencies, languages, jurisdictions}

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

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { describeApiError } from '../../shared/api-errors.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Cancel a transaction via payware API as an ISV
@@ -77,6 +78,7 @@ export async function cancelTransaction({ transactionId, statusMessage, merchant
 
 export const cancelTransactionTool = {
   name: 'payware_operations_cancel_transaction',
+  annotations: CHANGES,
   description: `Cancel an active transaction as an ISV on behalf of a merchant.
 
 **Endpoint:** PATCH /transactions/{transactionId} with \`{"status":"CANCELLED","statusMessage":"..."}\`

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

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { describeApiError } from '../../shared/api-errors.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create a transaction via payware API on behalf of a merchant (ISV)
@@ -36,6 +37,7 @@ export async function createTransaction({
   barBarHeight,
   barFontSize,
   barHumanReadableLocation,
+  idempotencyKey,
   useSandbox = true
 }) {
   // ISV-specific validation
@@ -131,13 +133,17 @@ export async function createTransaction({
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,
         'Content-Type': 'application/json',
-        'Api-Version': '1'
+        'Api-Version': '1',
+        ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
       },
       // Tell axios to send the string as-is, don't serialize it again
       transformRequest: [(data) => data]
     });
 
-    return response.data;
+    // A retry answered from the first call (Idempotency-Key) says so in a header, not in the body.
+    return response.headers?.['idempotent-replayed'] === 'true'
+      ? { ...response.data, replayed: true }
+      : response.data;
   } catch (error) {
     throw describeApiError(error, 'call the payware API');
   }
@@ -145,6 +151,7 @@ export async function createTransaction({
 
 export const createTransactionTool = {
   name: 'payware_operations_create_transaction',
+  annotations: CREATES,
   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.
@@ -198,6 +205,11 @@ merchant role if the terminal producer is meant to be attributed.
     type: 'object',
     required: ['merchantPartnerId', 'oauth2Token', 'reasonL1'],
     properties: {
+      idempotencyKey: {
+        type: "string",
+        description: "Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the transaction the first call created instead of a new one, and the result reports replayed: true. The same key with a different body is refused (422 ERR_IDEMPOTENCY_KEY_REUSED); a retry while the first call still runs gets 409 ERR_IDEMPOTENCY_KEY_IN_PROGRESS.",
+        pattern: "^[\\x21-\\x7E]{1,255}$"
+      },
       // ISV Authentication
       merchantPartnerId: {
         type: 'string',

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

@@ -2,6 +2,7 @@ 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';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction status from payware API as an ISV
@@ -81,12 +82,13 @@ function formatTransactionStatus(transaction) {
  */
 export const getTransactionStatusTool = {
   name: "payware_operations_get_transaction_status",
+  annotations: READS,
   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.
+**Note:** For transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use 'payware_operations_get_transaction_history' instead.
 
 **Required:** Merchant Partner ID and OAuth2 token for ISV authentication.
 

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

@@ -3,6 +3,7 @@ import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { describeApiError } from '../../shared/api-errors.js';
+import { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Process a PEER transaction as an ISV on behalf of a merchant.
@@ -39,6 +40,7 @@ export async function processTransaction({
   paymentMethod,
   merchantPartnerId,
   oauth2Token,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!transactionId) {
@@ -108,13 +110,17 @@ export async function processTransaction({
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,
         'Content-Type': 'application/json',
-        'Api-Version': '1'
+        'Api-Version': '1',
+        ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
       },
       // Tell axios to send the string as-is, don't serialize it again
       transformRequest: [(data) => data]
     });
 
-    return response.data;
+    // A retry answered from the first call (Idempotency-Key) says so in a header, not in the body.
+    return response.headers?.['idempotent-replayed'] === 'true'
+      ? { ...response.data, replayed: true }
+      : response.data;
   } catch (error) {
     throw describeApiError(error, 'call the payware API');
   }
@@ -122,6 +128,7 @@ export async function processTransaction({
 
 export const processTransactionTool = {
   name: 'payware_operations_process_transaction',
+  annotations: COMMITS,
   description: `Process a PEER transaction as an ISV on behalf of a merchant - the merchant scanning a customer's QR or barcode to collect payment.
 
 **Endpoint:** POST /transactions/{transactionId}
@@ -146,6 +153,11 @@ payware returns on the response is the value to echo back at finalize, unchanged
     type: 'object',
     required: ['transactionId', 'amount', 'currency', 'reasonL1', 'merchantPartnerId', 'oauth2Token'],
     properties: {
+      idempotencyKey: {
+        type: "string",
+        description: "Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the transaction the first call created instead of a new one, and the result reports replayed: true. The same key with a different body is refused (422 ERR_IDEMPOTENCY_KEY_REUSED); a retry while the first call still runs gets 409 ERR_IDEMPOTENCY_KEY_IN_PROGRESS.",
+        pattern: "^[\\x21-\\x7E]{1,255}$"
+      },
       transactionId: {
         type: 'string',
         description: "The customer's transaction to process, e.g. \"pw7e4rCToG\""

package/src/isv/transactions/simulate-callback.js

@@ -1,5 +1,6 @@
 import { getPartnerIdSafe } from '../../config/env.js';
 import { generateMockCallback, simulateCallbackDelivery } from '../../merchant/transactions/simulate-callback.js';
+import { LOCAL } from '../../shared/tool-annotations.js';
 
 /**
  * Simulate the callback a merchant's endpoint receives, for an ISV building that handler.
@@ -17,6 +18,7 @@ import { generateMockCallback, simulateCallbackDelivery } from '../../merchant/t
  */
 export const simulateCallbackTool = {
   name: 'payware_operations_simulate_callback',
+  annotations: LOCAL,
   description: `Simulate the callback payload payware sends to a merchant's callbackUrl, for building and testing a webhook handler as an ISV.
 
 **Local only - this makes no API call.** payware has no endpoint that triggers a callback on demand,