@payware/mcp-server 1.2.0 → 1.3.0

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

@@ -22,6 +22,11 @@ export async function createTransaction({
   partnerId,
   privateKey,
   passbackParams,
+  // POS terminal producer attribution. Optional, and independent of everything else on the request:
+  // it selects a revenue share out of payware's own fee and never changes what the merchant pays.
+  producerPartnerId,
+  terminalId,
+  terminalManufacturer,
   // QR Options
   qrFormat,
   qrBorder,
@@ -55,7 +60,31 @@ export async function createTransaction({
   if (!partnerId || !privateKey) {
     throw new Error('Partner ID and private key are required for proper JWT creation');
   }
-  
+
+  // Refuse an empty producerPartnerId here rather than letting it reach the server.
+  // The server rejects an unrecognised producer id outright - a misconfigured terminal fails on its
+  // first sale, deliberately, so that an installer sees it - and an empty string is unrecognised.
+  // Sending one turns "no producer arrangement" into a failed transaction, when the correct way to
+  // say that is to omit the field entirely.
+  if (producerPartnerId !== undefined && String(producerPartnerId).trim() === '') {
+    throw new Error(
+      'producerPartnerId must not be empty. Omit the field entirely when there is no POS terminal ' +
+      'producer arrangement - an unrecognised value (including an empty string) is rejected by the ' +
+      'server and fails the transaction.'
+    );
+  }
+
+  for (const [field, value] of [['terminalId', terminalId], ['terminalManufacturer', terminalManufacturer]]) {
+    if (value === undefined || value === null) continue;
+    if (String(value).length > 64) {
+      throw new Error(`${field} cannot exceed 64 characters`);
+    }
+    // The server rejects control characters in both fields; catching it here names the field.
+    if (/[\u0000-\u001F\u007F]/.test(String(value))) {
+      throw new Error(`${field} must not contain control characters`);
+    }
+  }
+
   // Build QR options if applicable
   const qrOptions = {};
   if (type === 'QR') {
@@ -82,9 +111,12 @@ export async function createTransaction({
     ...(friendlyName && { friendlyName }),
     ...(shop && { shop }),
     ...(callbackUrl && { callbackUrl }),
-    ...(passbackParams && { 
-      passbackParams: typeof passbackParams === 'string' ? passbackParams : JSON.stringify(passbackParams) 
+    ...(passbackParams && {
+      passbackParams: typeof passbackParams === 'string' ? passbackParams : JSON.stringify(passbackParams)
     }),
+    ...(producerPartnerId && { producerPartnerId }),
+    ...(terminalId && { terminalId }),
+    ...(terminalManufacturer && { terminalManufacturer }),
     trData: {
       amount: amount !== undefined ? amount.toString() : '0.00',
       currency,
@@ -133,7 +165,7 @@ export async function createTransaction({
     // Provide helpful error message for hash mismatches
     let enhancedMessage = error.response?.data?.message || error.message;
 
-    if (error.response?.data?.code === 'ERR_INVALID_CONTENT_HASH' ||
+    if (error.response?.data?.errorCode === 'ERR_INVALID_CONTENT_HASH' ||
         enhancedMessage?.includes('SHA-256') ||
         enhancedMessage?.includes('contentSha256')) {
       enhancedMessage = `Hash Mismatch Error: The contentSha256 in JWT header doesn't match the request body.
@@ -149,9 +181,9 @@ Original error: ${enhancedMessage}`;
       error: {
         message: enhancedMessage,
         status: error.response?.status,
-        code: error.response?.data?.code,
+        code: error.response?.data?.errorCode,
         details: error.response?.data,
-        helpUrl: error.response?.data?.code === 'ERR_INVALID_CONTENT_HASH' ?
+        helpUrl: error.response?.data?.errorCode === 'ERR_INVALID_CONTENT_HASH' ?
           'https://github.com/payware/mcp-server#sha256-consistency' : undefined
       },
       timestamp: new Date().toISOString()
@@ -168,6 +200,7 @@ export const createTransactionTool = {
 
 📋 **ROOT LEVEL** (Transaction metadata):
 - shop, account, friendlyName, callbackUrl, passbackParams
+- producerPartnerId, terminalId, terminalManufacturer (POS terminal producer attribution - see below)
 
 💰 **TRANSACTION DATA** (trData object):
 - amount, currency, reasonL1, reasonL2
@@ -204,7 +237,33 @@ export const createTransactionTool = {
   },
   "qrOptions": { ... }
 }
-\`\`\``,
+\`\`\`
+
+🏭 **POS TERMINAL PRODUCER ATTRIBUTION** (optional, root level)
+
+Only relevant if the transaction originates on a POS terminal whose producer has a revenue-share
+agreement with payware. Three fields, all optional:
+
+- \`producerPartnerId\` - the 8-character partnerId payware issued to the terminal producer.
+  **An unrecognised value fails the transaction with a 400** (\`ERR_INVALID_PRODUCER_ID\`) - it is
+  deliberately not ignored, so that a terminal configured with the wrong id fails on its first sale
+  where an installer can see it. **Omit the field entirely when there is no producer arrangement;
+  never send an empty string.**
+- \`terminalId\` - the producer's own identifier for the physical terminal. Max 64 chars, no control
+  characters. payware records it and never interprets it: no format, no uniqueness enforcement, and
+  nothing about pricing or attribution depends on it.
+- \`terminalManufacturer\` - device manufacturer as the terminal reports it. Max 64 chars, no control
+  characters. Recorded for provenance; a mismatch is surfaced in settlement review, never blocked.
+
+Two things worth knowing:
+1. **It never changes what the merchant is charged.** The producer's share comes out of payware's own
+   fee, not out of a higher price for the merchant, whose fee always follows the fee hierarchy.
+2. **None of the three is returned.** They do not appear in the create response, in \`get_transaction_status\`,
+   in transaction history, or in any callback. What a producer earned is visible on their own
+   dashboard and settlements - attribution is recorded against the fee, not against the transaction.
+
+If an ISV's software made the call, the ISV is attributed and the producer is not, even when the
+ISV's software is running on that producer's hardware.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -257,9 +316,23 @@ export const createTransactionTool = {
       },
       callbackUrl: {
         type: "string",
-        description: "📋 ROOT LEVEL: HTTPS URL to receive transaction status callbacks (must be https://)",
+        description: "📋 ROOT LEVEL: HTTPS URL to receive transaction status callbacks. Must be https://, must present a publicly-trusted TLS certificate, and must resolve to a public address - internal/private addresses are rejected (ERR_UNRESOLVABLE_CALLBACK_URL).",
         format: "uri"
       },
+      producerPartnerId: {
+        type: "string",
+        description: "🏭 ROOT LEVEL: partnerId of the POS terminal producer whose terminal produced this transaction. Must be a partner registered with payware and flagged as a producer - an unrecognised value REJECTS the transaction (400 ERR_INVALID_PRODUCER_ID) rather than being ignored. Omit entirely when there is no producer arrangement; never send an empty string. Selects the producer's revenue share out of payware's own fee and never changes what the merchant is charged. Not returned in any response or callback."
+      },
+      terminalId: {
+        type: "string",
+        description: "🏭 ROOT LEVEL: Opaque identifier of the physical terminal, scoped to the producer's own estate. payware assumes no format and enforces no uniqueness; it is recorded for provenance and never affects attribution or pricing. Make it unique within your own estate anyway - that is what lets you answer 'which terminal produced this sale' later. Not returned in any response or callback.",
+        maxLength: 64
+      },
+      terminalManufacturer: {
+        type: "string",
+        description: "🏭 ROOT LEVEL: Device manufacturer as reported by the terminal. Recorded for provenance; a mismatch against the expected producer is surfaced in settlement review and never blocks the transaction. Not returned in any response or callback.",
+        maxLength: 64
+      },
       partnerId: {
         type: "string",
         description: "🔐 AUTHENTICATION: Partner ID from payware dashboard (not sent in API request). Uses PAYWARE_PARTNER_ID env var as default."
@@ -355,6 +428,10 @@ export const createTransactionTool = {
       partnerId = getPartnerIdSafe(),
       privateKey = getPrivateKeySafe(args.useSandbox ?? true),
       passbackParams,
+      // POS terminal producer attribution
+      producerPartnerId,
+      terminalId,
+      terminalManufacturer,
       // QR Options
       qrFormat,
       qrBorder,
@@ -396,6 +473,9 @@ export const createTransactionTool = {
       partnerId,
       privateKey,
       passbackParams,
+      producerPartnerId,
+      terminalId,
+      terminalManufacturer,
       // QR Options
       qrFormat,
       qrBorder,

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

@@ -1,6 +1,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';
 
 /**
  * Get transaction status from payware API
@@ -37,16 +38,7 @@ export async function getTransactionStatus({ transactionId, partnerId, privateKe
       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);
   }
 }
 
@@ -79,7 +71,44 @@ export const getTransactionStatusTool = {
 
 **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_transactions_get_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
+top-level \`imageUrl\` is gone. Discriminate a product-originated transaction by the **presence of the
+object**, not by probing individual fields:
+
+\`\`\`json
+{ "transactionId": "pw7e4rCToG", "amount": "57.60", "currency": "EUR",
+  "product": { "productId": "pr7e4rCToG", "type": "ITEM", "name": "Cotton T-shirt, black",
+               "shortDescription": "...", "longDescription": "...",
+               "imageUrl": "https://...", "imageDigest": "9f86d081...", "imageContentType": "image/png",
+               "imageBytes": 20480, "termsUrl": "https://...", "termsText": "...",
+               "regularPrice": "63.36", "shippable": false, "quickPay": true, "shopName": "My shop" } }
+\`\`\`
+
+Three things about that object:
+
+- **\`imageDigest\` is an obligation, not decoration.** It is the SHA-256 payware pinned for the image
+  at \`imageUrl\`. Fetch the image, verify its bytes against this digest before rendering it to a
+  payer, and fall back to a neutral placeholder on mismatch. Present only when \`imageUrl\` is the
+  product's own image.
+- **\`regularPrice\` is display-only, and appears only when there is a genuine saving** - i.e. when it
+  is higher than the transaction \`amount\`. The top-level \`amount\` and \`currency\` are authoritative
+  and are what the payer pays; the object does not repeat them.
+- **Availability follows the merchant's plan.** \`imageUrl\` and \`termsUrl\` are Standard and above;
+  \`termsText\` and the descriptions are universal. A missing field is a plan boundary, not an error.
+
+For a \`pr\`/\`ps\` product identifier the values are resolved live; for the resulting \`pw\` transaction
+they are the snapshot frozen at creation, so the response always reflects what the payer could have
+been shown at scan time.
+
+💰 **Amounts follow the currency, not a fixed two decimals.** \`amount\`, \`fee\`, \`payerAmount\` and
+\`payeeAmount\` are decimal strings at the smallest unit their own currency can be paid in - none for
+JPY, two for EUR, eight for BTC. Parse them with a decimal type; never compare them as strings, and
+never assume two places. \`feeRate\` carries up to six decimals and \`feeFixed\` full stored precision:
+both are informational, and recomputing the fee from them and submitting that at finalize is rejected
+with ERR_FEE_MISMATCH. Echo \`fee\` back unchanged instead.`,
   inputSchema: {
     type: "object",
     properties: {

package/src/merchant/transactions/process-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 { apiErrorResult } from '../../shared/api-errors.js';
 
 /**
  * Process a transaction via payware API (for merchants accepting payments)
@@ -97,16 +98,7 @@ export async function processTransaction({
       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?.errorCode,
-        details: error.response?.data
-      },
-      timestamp: new Date().toISOString()
-    };
+    return apiErrorResult(error);
   }
 }
 

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

@@ -17,10 +17,18 @@ export function generateMockCallback(transactionId, status = 'CONFIRMED', option
     payeeAmount = null,
     paymentMethod = null,
     statusMessage = null,
-    passbackParams = null
+    passbackParams = null,
+    // The fee breakdown the server attaches whenever the transaction has a fee configuration.
+    // Before 2026-08-21 a merchant's FINALIZED callback carried the total fee but not the two
+    // numbers that produced it, so reconciling a charge meant asking payware. It carries both now.
+    feeFixed = '0.1000',
+    feeRate = '0.0150',
+    // Pass fee: null to model the anomaly the server reports by OMITTING the field - a transaction
+    // with no recorded fee. That is deliberately distinguishable from a genuine "0.00".
+    fee: feeOverride = undefined
   } = options;
 
-  // Calculate fee like Java implementation: |payerAmount - amount| or |payeeAmount - amount|
+  // Calculate fee like the server: |payerAmount - amount| or |payeeAmount - amount|.
   const transactionAmount = parseFloat(amount);
   let fee = '0.00';
   if (payerAmount !== null) {
@@ -28,19 +36,29 @@ export function generateMockCallback(transactionId, status = 'CONFIRMED', option
   } else if (payeeAmount !== null) {
     fee = Math.abs(parseFloat(payeeAmount) - transactionAmount).toFixed(2);
   }
+  if (feeOverride !== undefined) {
+    fee = feeOverride;
+  }
 
   const currentTime = Date.now();
+  // Built with the same omission rule the server applies. TransactionCallbackPayload is
+  // @JsonInclude(NON_NULL), so a property with no value is ABSENT from the JSON rather than sent as
+  // null or 0 - and a consumer is entitled to tell those apart. Emitting "passbackParams": null or
+  // "fee": "0.0000" here would have taught an integrator to expect a shape the server never sends.
   const basePayload = {
     callbackType: 'TRANSACTION_FINALIZED',
     transactionId,
-    passbackParams,
+    ...(passbackParams !== null && passbackParams !== undefined && { passbackParams }),
     amount,
-    fee,
+    ...(fee !== null && fee !== undefined && { fee }),
+    ...(feeFixed !== null && feeFixed !== undefined && { feeFixed }),
+    ...(feeRate !== null && feeRate !== undefined && { feeRate }),
     currency,
     status,
-    statusMessage,
+    ...(statusMessage !== null && statusMessage !== undefined && { statusMessage }),
     ...(paymentMethod && { paymentMethod }),
     created: currentTime - 300000, // Created 5 minutes ago (milliseconds)
+    // Absent on EXPIRED: the expiry sweep transitions status in bulk and sets no finalized moment.
     ...(status !== 'EXPIRED' && { finalized: currentTime })
   };
   
@@ -116,7 +134,32 @@ export async function simulateCallbackDelivery(callbackUrl, payload) {
  */
 export const simulateCallbackTool = {
   name: "payware_operations_simulate_callback",
-  description: "Simulate callback scenarios for testing webhook handling",
+  description: `Simulate callback scenarios for testing webhook handling.
+
+Generates the payload a merchant's \`callbackUrl\` actually receives, so a handler can be built and
+tested against the real shape. Four properties of that shape are easy to get wrong:
+
+**1. Absent means absent, not zero.** The payload omits properties with no value rather than sending
+\`null\` or \`0\`. \`statusMessage\`, \`passbackParams\`, \`fee\`, \`feeFixed\` and \`feeRate\` are all simply
+missing when they do not apply. A missing \`fee\` means the fee is *unknown* for that transaction - it
+does not mean the transaction was free. Do not write a handler that reads \`payload.fee\` as a number
+without checking it is there.
+
+**2. \`finalized\` is absent on EXPIRED.** An expired transaction is closed by the platform's expiry
+sweep, which sets no finalization moment. Every other status carries one.
+
+**3. \`EXPIRED\` is a non-payment, not a failure.** The payer never paid within \`timeToLive\`. Release
+the order or the stock, as you would for a cancellation - do not treat it as an error to retry.
+
+**4. Deduplicate on \`(transactionId, callbackType)\`.** payware retries a callback once a second, up
+to 15 times, until the endpoint answers 200. That pair is stable across every retry of the same
+event, and it is the key payware guarantees. A handler that does not deduplicate will eventually
+process one payment twice.
+
+**Not on this payload:** \`deliveryAddress\` (removed 2026-08-07 - fetch it from
+\`payware_operations_get_transaction_history\`, which is authenticated and tenant-scoped),
+\`producerPartnerId\`, \`transactionType\` and \`initiatedBy\` (the last two are carried on
+TRANSACTION_PROCESSED, which merchants do not receive).`,
   inputSchema: {
     type: "object", 
     properties: {
@@ -148,8 +191,17 @@ export const simulateCallbackTool = {
       },
       fee: {
         type: "string",
-        description: "Fee amount charged by payment institution (e.g., '0.00' for no fee)",
-        default: "0.00"
+        description: "The payware fee on this transaction, at the currency's smallest payable unit (e.g. '0.29'). Not always two decimals - it follows the currency. Pass null to model the anomaly case, where a transaction has no recorded fee and the server OMITS the property entirely; that is deliberately distinguishable from a genuine '0.00'."
+      },
+      feeFixed: {
+        type: "string",
+        description: "Fixed fee component of the applicable fee configuration, e.g. '0.1000'. Informational, for reconciliation. Present on FINALIZED callbacks since 2026-08-21 - before that a merchant got the total fee but not the breakdown that produced it. Pass null to model a transaction with no fee configuration, where it is omitted.",
+        default: "0.1000"
+      },
+      feeRate: {
+        type: "string",
+        description: "Variable rate of the applicable fee configuration, e.g. '0.0150' = 1.5%. Informational, same as feeFixed. Pass null to model a transaction with no fee configuration.",
+        default: "0.0150"
       },
       statusMessage: {
         type: "string",
@@ -172,7 +224,12 @@ export const simulateCallbackTool = {
       callbackUrl,
       amount = '57.60',
       currency = 'EUR',
-      fee = '0.00',
+      // No default: an omitted fee falls through to generateMockCallback's own derivation.
+      // Defaulting it to '0.00' here made every simulated callback assert a zero fee, which is the
+      // one value the real payload never sends for "no fee" - it omits the property instead.
+      fee,
+      feeFixed = '0.1000',
+      feeRate = '0.0150',
       statusMessage,
       paymentMethod
     } = args;
@@ -186,6 +243,8 @@ export const simulateCallbackTool = {
       amount,
       currency,
       fee,
+      feeFixed,
+      feeRate,
       statusMessage,
       paymentMethod
     });