@payware/mcp-server 1.1.1 → 1.3.0

package/src/isv/reference/index.js

@@ -0,0 +1,249 @@
+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';
+
+/**
+ * Reference data - the enumerations a merchant registration form has to be filled in with.
+ *
+ * These are the values an assistant otherwise guesses at, and guessing is expensive here: a legal
+ * form is jurisdiction-specific ("OOD" exists in Bulgaria and not in Spain), a business activity is
+ * a numeric id rather than free text, and a currency the platform does not carry is a rejected
+ * transaction rather than a rejected form. One GET each and there is nothing to guess.
+ *
+ * **Authenticated as the ISV itself, not on behalf of a merchant.** These are consumed while
+ * building the form that creates a merchant, so there is no merchant to act for yet - the request
+ * carries a plain ISV JWT with no `aud`/`sub` on-behalf claims.
+ */
+
+/** The five datasets, and what each one's query parameters mean. */
+const DATASETS = {
+  'legal-forms': {
+    path: '/isv/reference/legal-forms',
+    requires: 'jurisdictionCode',
+    summary: 'Legal forms (company types) available in one jurisdiction',
+    note:
+      'jurisdictionCode is REQUIRED - an ISO 3166-1 alpha-2 country code such as BG, DE, ES. ' +
+      'An unknown code is not an error: the server falls back to a generic jurisdiction and returns ' +
+      'its list, so a typo comes back looking like a valid but oddly generic answer. Check that the ' +
+      'result matches the country you meant.'
+  },
+  'business-activities': {
+    path: '/isv/reference/business-activities',
+    optional: 'languageCode',
+    summary: 'Business activity categories, translated',
+    note:
+      'languageCode is an ISO 639-1 code (en, bg, es) and defaults to English. Only the LABELS are ' +
+      'translated - the ids are stable across languages, so store the id and re-fetch labels rather ' +
+      'than storing the text.'
+  },
+  currencies: {
+    path: '/isv/reference/currencies',
+    summary: 'Every currency payware supports',
+    note:
+      'Use this to validate a currency before sending it on a transaction or product. Note that the ' +
+      'number of decimal places a currency uses is a property OF THE CURRENCY - two for EUR, none ' +
+      'for JPY, more for others - and every amount on the API is formatted to it. Do not assume two.'
+  },
+  languages: {
+    path: '/isv/reference/languages',
+    summary: 'Languages payware supports for merchant-facing content',
+    note: 'The set that languageCode accepts on the other datasets, and that a merchant can be registered in.'
+  },
+  jurisdictions: {
+    path: '/isv/reference/jurisdictions',
+    optional: 'languageCode',
+    summary: 'Countries/jurisdictions where payware operates, translated',
+    note:
+      'Fetch this before legal-forms: it gives you the valid jurisdictionCode values, which is the ' +
+      'one parameter legal-forms will silently fall back on rather than reject.'
+  }
+};
+
+/**
+ * Fetch one reference dataset.
+ *
+ * @param {Object} params
+ * @param {string} params.dataset one of the keys of DATASETS
+ * @param {string} [params.jurisdictionCode] required for legal-forms
+ * @param {string} [params.languageCode] optional for business-activities and jurisdictions
+ */
+export async function getReferenceData({
+  dataset,
+  jurisdictionCode,
+  languageCode,
+  partnerId,
+  privateKey,
+  useSandbox = true
+}) {
+  const spec = DATASETS[dataset];
+  if (!spec) {
+    throw new Error(
+      `Unknown dataset "${dataset}". Valid datasets: ${Object.keys(DATASETS).join(', ')}`
+    );
+  }
+  if (spec.requires === 'jurisdictionCode' && !jurisdictionCode) {
+    throw new Error(
+      'jurisdictionCode is required for the legal-forms dataset. Use the jurisdictions dataset to ' +
+      'find valid codes - an unknown code is NOT rejected, it silently falls back to a generic list.'
+    );
+  }
+
+  const query = new URLSearchParams();
+  if (spec.requires === 'jurisdictionCode' || jurisdictionCode) {
+    if (jurisdictionCode) query.set('jurisdictionCode', jurisdictionCode.toUpperCase());
+  }
+  if (spec.optional === 'languageCode' && languageCode) {
+    query.set('languageCode', languageCode);
+  }
+
+  // GET, so no body and no content hash.
+  const tokenData = createJWTToken(partnerId, privateKey);
+  const headers = {
+    'Authorization': `Bearer ${tokenData.token}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1'
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const qs = query.toString();
+    const response = await axios.get(`${baseUrl}${spec.path}${qs ? `?${qs}` : ''}`, { headers });
+
+    return {
+      success: true,
+      dataset,
+      items: response.data,
+      count: Array.isArray(response.data) ? response.data.length : 0,
+      requestId: response.headers['x-request-id'],
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    return apiErrorResult(error);
+  }
+}
+
+const DATASET_DOCS = Object.entries(DATASETS)
+  .map(([key, spec]) => `- **\`${key}\`** - ${spec.summary}.\n  ${spec.note}`)
+  .join('\n');
+
+export const referenceDataTool = {
+  name: 'payware_reference_lookup',
+  description: `Look up payware reference data - the enumerations a merchant registration form needs.
+
+**Endpoints:** GET /isv/reference/{legal-forms, business-activities, currencies, languages, jurisdictions}
+
+One tool with a \`dataset\` parameter rather than five near-identical tools. All five are cheap,
+read-only lookups, and they are used together when building a registration flow.
+
+**Datasets**
+
+${DATASET_DOCS}
+
+**Authentication:** as the ISV itself. These are consumed while building the form that CREATES a
+merchant, so there is no merchant to act on behalf of yet - no \`merchantPartnerId\` or
+\`oauth2Token\` is involved.
+
+**Typical order when registering a merchant:** \`jurisdictions\` -> \`legal-forms\` (with the chosen
+jurisdictionCode) -> \`business-activities\` -> \`currencies\`. Store the **ids** these return, not the
+translated labels; the labels change with \`languageCode\` and the ids do not.`,
+
+  inputSchema: {
+    type: 'object',
+    required: ['dataset'],
+    properties: {
+      dataset: {
+        type: 'string',
+        enum: Object.keys(DATASETS),
+        description: 'Which reference dataset to fetch.'
+      },
+      jurisdictionCode: {
+        type: 'string',
+        description: "ISO 3166-1 alpha-2 country code (BG, DE, ES). REQUIRED for dataset='legal-forms'. An unknown code is not rejected - the server falls back to a generic jurisdiction - so verify the result matches the country you meant.",
+        pattern: '^[A-Za-z]{2}$'
+      },
+      languageCode: {
+        type: 'string',
+        description: "ISO 639-1 language code (en, bg, es) for translated labels. Applies to dataset='business-activities' and dataset='jurisdictions'; ignored otherwise. Defaults to English.",
+        pattern: '^[A-Za-z]{2}$'
+      },
+      partnerId: {
+        type: 'string',
+        description: 'ISV partner ID. Uses PAYWARE_PARTNER_ID env var as default.'
+      },
+      privateKey: {
+        type: 'string',
+        description: 'RSA private key for JWT signing. Uses the environment-specific key as default.'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler(args) {
+    const {
+      dataset,
+      jurisdictionCode,
+      languageCode,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe(args.useSandbox ?? true),
+      useSandbox = true
+    } = args;
+
+    if (!partnerId) {
+      throw new Error("Partner ID is required. Provide 'partnerId' or set PAYWARE_PARTNER_ID.");
+    }
+    if (!privateKey) {
+      throw new Error("Private key is required. Provide 'privateKey' or set PAYWARE_PRIVATE_KEY.");
+    }
+
+    const result = await getReferenceData({
+      dataset, jurisdictionCode, languageCode, partnerId, privateKey, useSandbox
+    });
+
+    if (!result.success) {
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ **Reference Lookup Failed** (${dataset})
+
+- Message: ${result.error.message}
+- Status: ${result.error.status || 'N/A'}
+- Code: ${result.error.errorCode || 'N/A'}
+${result.error.correlationId ? `- Correlation ID: ${result.error.correlationId}` : ''}
+${result.error.guidance ? `\n${result.error.guidance}` : ''}
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+
+    const items = Array.isArray(result.items) ? result.items : [];
+    // Reference rows have no single shape, so render whatever identity-ish and label-ish fields
+    // each one actually has rather than assuming a schema that differs per dataset.
+    const rendered = items.map(item => {
+      const id = item.id ?? item.code ?? item.isoCode ?? item.currencyCode ?? item.iso31661Alpha2;
+      const label = item.name ?? item.description ?? item.label ?? item.translation;
+      return `- ${id !== undefined ? `\`${id}\`` : ''}${label ? ` ${label}` : ''}`.trim();
+    }).join('\n');
+
+    return {
+      content: [{
+        type: 'text',
+        text: `📚 **${dataset}** - ${result.count} item(s)${jurisdictionCode ? ` for ${jurisdictionCode.toUpperCase()}` : ''}${languageCode ? ` in ${languageCode}` : ''}
+
+${rendered || 'No items returned.'}
+
+${DATASETS[dataset].note}
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+      }]
+    };
+  }
+};
+
+export const isvReferenceTools = [referenceDataTool];

package/src/isv/shops/index.js

@@ -0,0 +1,22 @@
+import { buildListShopsTool } from '../../shared/shops/shops-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Shop tools for the ISV role.
+ *
+ * Signed as an on-behalf call, so the server answers with the shops this merchant assigned to this
+ * ISV's scope - not every shop the merchant owns. Anything outside that scope is a 403
+ * ERR_SHOP_NOT_IN_SCOPE on the write paths, which is why listing matters more here than it does for
+ * a merchant acting on its own estate.
+ */
+export const listShopsTool = buildListShopsTool({
+  partnerType: 'isv',
+  resolveAuth: (args) => ({
+    isvPartnerId: getPartnerIdSafe(),
+    privateKey: getPrivateKeySafe(args.useSandbox ?? true),
+    merchantPartnerId: args.merchantPartnerId,
+    oauth2Token: args.oauth2Token
+  })
+});
+
+export const isvShopTools = [listShopsTool];

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

@@ -1,15 +1,26 @@
 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';
 
 /**
  * Cancel a transaction via payware API as an ISV
  */
-export async function cancelTransaction({ transactionId, merchantPartnerId, oauth2Token, useSandbox = true }) {
+export async function cancelTransaction({ transactionId, statusMessage, merchantPartnerId, oauth2Token, useSandbox = true }) {
   if (!transactionId) {
     throw new Error('Transaction ID is required');
   }
 
+  // Required by the server, not optional politeness: MerchantValidationService throws
+  // MissingStatusMessageException when an ACTIVE transaction is cancelled without one, and that
+  // path is the ISV path too - it explicitly resolves the acting merchant through the on-behalf ISV.
+  if (!statusMessage) {
+    throw new Error('statusMessage is required when cancelling (server: ERR_MISSING_STATUS_MESSAGE)');
+  }
+  if (statusMessage.length > 100) {
+    throw new Error('statusMessage cannot exceed 100 characters');
+  }
+
   if (!merchantPartnerId) {
     throw new Error('Merchant Partner ID is required for ISV operations');
   }
@@ -21,7 +32,17 @@ export async function cancelTransaction({ transactionId, merchantPartnerId, oaut
   const isvPartnerId = getPartnerIdSafe();
   const privateKey = getPrivateKeySafe(useSandbox);
 
-  const requestBody = {}; // Empty body for cancel
+  // PATCH with a status body, matching the merchant tool and the server.
+  //
+  // This used to be `axios.delete` against `/transactions/{id}` with an empty body. There is no
+  // DELETE /transactions/{id} on the server - TransactionController has DELETE only on
+  // /{transactionId}/link - so the call could never have succeeded, and the empty body carried
+  // neither the CANCELLED status nor the status message the validator demands. Three separate
+  // reasons it could not work, which is why it is a rewrite rather than a patch.
+  const requestBody = {
+    status: 'CANCELLED',
+    statusMessage
+  };
 
   const jwtData = await createJWTForPartner({
     partnerId: isvPartnerId,
@@ -31,30 +52,26 @@ export async function cancelTransaction({ transactionId, merchantPartnerId, oaut
     oauth2Token
   });
 
-  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  // Use the same JSON serialization method as the JWT factory for SHA-256 calculation
   const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
-    const response = await axios.delete(`${baseUrl}/transactions/${transactionId}`, {
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
+    const response = await axios.patch(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,
         'Content-Type': 'application/json',
         'Api-Version': '1'
       },
-      data: minimizedBodyString,
       // Tell axios to send the string as-is, don't serialize it again
       transformRequest: [(data) => data]
     });
 
     return response.data;
   } catch (error) {
-    if (error.response) {
-      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
-    }
-    throw error;
+    throw describeApiError(error, 'call the payware API');
   }
 }
 
@@ -62,17 +79,31 @@ export const cancelTransactionTool = {
   name: 'payware_operations_cancel_transaction',
   description: `Cancel an active transaction as an ISV on behalf of a merchant.
 
+**Endpoint:** PATCH /transactions/{transactionId} with \`{"status":"CANCELLED","statusMessage":"..."}\`
+
 Requires ISV authentication with merchant partner ID and OAuth2 token.
-Only ACTIVE transactions can be cancelled.`,
+Only ACTIVE transactions can be cancelled - one already processed answers 409 ERR_ALREADY_PROCESSED.
+
+**\`statusMessage\` is mandatory.** The server rejects a cancellation without one
+(ERR_MISSING_STATUS_MESSAGE); it is the reason shown to the merchant and recorded against the
+transaction. Max 100 characters.
+
+**You can cancel only what you initiated.** An ISV's own transactions include those it created on
+behalf of this merchant; anything else answers 403 ERR_UNAUTHORIZED_OPERATION.`,
 
   inputSchema: {
     type: 'object',
-    required: ['transactionId', 'merchantPartnerId', 'oauth2Token'],
+    required: ['transactionId', 'statusMessage', 'merchantPartnerId', 'oauth2Token'],
     properties: {
       transactionId: {
         type: 'string',
         description: 'Transaction ID to cancel'
       },
+      statusMessage: {
+        type: 'string',
+        description: 'Reason for the cancellation. REQUIRED - the server rejects a cancellation without one (ERR_MISSING_STATUS_MESSAGE). Max 100 characters.',
+        maxLength: 100
+      },
       merchantPartnerId: {
         type: 'string',
         description: 'Partner ID of the target merchant'

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

@@ -1,6 +1,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';
 
 /**
  * Create a transaction via payware API on behalf of a merchant (ISV)
@@ -119,13 +120,13 @@ export async function createTransaction({
     oauth2Token
   });
 
-  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  // Use the same JSON serialization method as the JWT factory for SHA-256 calculation
   const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
   const minimizedBodyString = createMinimizedJSON(requestBody);
 
   try {
     const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
-    // Send the exact minimized JSON string that was used for MD5 calculation
+    // Send the exact minimized JSON string that was used for SHA-256 calculation
     const response = await axios.post(`${baseUrl}/transactions`, minimizedBodyString, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,
@@ -138,10 +139,7 @@ export async function createTransaction({
 
     return response.data;
   } catch (error) {
-    if (error.response) {
-      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
-    }
-    throw error;
+    throw describeApiError(error, 'call the payware API');
   }
 }
 
@@ -154,6 +152,24 @@ Requires valid OAuth2 token obtained from the merchant.
 
 **Authentication**: Uses ISV JWT with merchant partner ID in 'aud' claim and OAuth2 token in 'sub' claim.
 
+⚠️ **The MERCHANT's plan governs, not the ISV's.** An on-behalf call inherits the plan of the merchant
+it acts for, so this endpoint answers **403** (\`ERR_METHOD_NOT_ALLOWED_FOR_CURRENT_USER_PLAN\`) when
+that merchant is on **Basic**. Acting on behalf is no longer sufficient on its own - before
+2026-08-21 it was, and an ISV serving a Basic merchant could reach the transaction, product, shop and
+report APIs regardless of that merchant's plan. The same applies to
+\`payware_products_*\`, \`payware_deep_links_*\` and \`payware_data_*\`. If a call that used to work
+now returns 403, check the merchant's plan first.
+
+⚠️ **Shop scope.** An ISV reaches only the shops the merchant assigned it. Naming any other shop
+answers **403 ERR_SHOP_NOT_IN_SCOPE**, and \`payware_shops_list\` returns only the in-scope ones.
+Omitting \`shop\` uses the merchant's default shop, which may itself be out of scope.
+
+ℹ️ **Producer attribution does not apply here.** \`producerPartnerId\` / \`terminalId\` /
+\`terminalManufacturer\` are accepted on direct merchant calls only. Whoever made the API call owns the
+sale, so an ISV call is an ISV sale even when the ISV's software is running on a hardware producer's
+terminal. Do not try to pass them through - use \`payware_operations_create_transaction\` from the
+merchant role if the terminal producer is meant to be attributed.
+
 **Transaction Types:**
 - PLAIN: Basic transaction without visual codes
 - QR: Transaction with QR code for mobile payments

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

@@ -1,6 +1,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';
 
 /**
  * Get transaction status from payware API as an ISV
@@ -51,16 +52,7 @@ export async function getTransactionStatus({ transactionId, merchantPartnerId, o
       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()
-    };
+    return apiErrorResult(error);
   }
 }
 
@@ -96,7 +88,22 @@ export const getTransactionStatusTool = {
 **Use Case:** Check status of ACTIVE transactions only. This endpoint only returns transactions with ACTIVE status.
 **Note:** For transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED), use 'payware_transactions_get_history' instead.
 
-**Required:** Merchant Partner ID and OAuth2 token for ISV authentication.`,
+**Required:** Merchant Partner ID and OAuth2 token for ISV authentication.
+
+🛍️ **Product-originated transactions carry a nested \`product\` object** (productId, type, name,
+descriptions, imageUrl, imageDigest, imageContentType, imageBytes, termsUrl, termsText, regularPrice,
+shippable, quickPay, shopName). Since 2026-07-22 these are grouped under \`product\` instead of sitting
+flat - the old top-level \`imageUrl\` is gone. Discriminate by the presence of the object. Verify
+\`imageDigest\` (SHA-256, pinned by payware) before rendering the image to a payer; \`regularPrice\` is
+display-only and appears only when higher than \`amount\`. The top-level \`amount\` and \`currency\` are
+authoritative and are not repeated inside the object.
+
+⚠️ **The MERCHANT's plan governs.** An on-behalf call inherits the acting merchant's plan, so this
+answers **403** for a **Basic** merchant. Which presentation fields come back also follows that plan:
+\`imageUrl\` and \`termsUrl\` are Standard and above.
+
+💰 **Amounts follow the currency, not a fixed two decimals.** Parse them with a decimal type and never
+compare them as strings.`,
 
   inputSchema: {
     type: "object",