@payware/mcp-server 1.1.1 → 1.3.0

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

@@ -1,15 +1,66 @@
 import axios from 'axios';
 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';
 
 /**
- * Process (finalize) a transaction via payware API as an ISV
+ * Process a PEER transaction as an ISV on behalf of a merchant.
+ *
+ * **This used to send `PATCH /transactions/{id}` with `{action: "CONFIRMED"|"DECLINED"}`, which is
+ * wrong three times over.**
+ *
+ *  1. Wrong verb and operation. `PATCH` is *finalize*, not process. Processing is
+ *     `POST /transactions/{transactionId}` with a full transaction request - which is what the
+ *     merchant tool has always done.
+ *  2. Wrong field. Finalize consumes `TransactionStatusUpdateRequest` - `status`, `statusMessage`,
+ *     `currency`, `amount`, `fee`. There is no `action` field anywhere on the payware API, so the
+ *     body deserialized to an empty request.
+ *  3. Wrong actor. Even with the right field name, a merchant or an ISV acting for one may only
+ *     send `status: CANCELLED`: `MerchantValidationService` throws `InvalidStatusException` for
+ *     anything else, because confirming or declining a payment is the financial institution's
+ *     decision and merchants never reach that path.
+ *
+ * To cancel, use `payware_operations_cancel_transaction`. To confirm or decline, you are looking for
+ * the financial-institution role's `payware_operations_finalize_transaction`, which an ISV is not.
  */
-export async function processTransaction({ transactionId, merchantPartnerId, oauth2Token, action = 'CONFIRMED', useSandbox = true }) {
+export async function processTransaction({
+  transactionId,
+  amount,
+  currency,
+  reasonL1,
+  reasonL2,
+  account,
+  friendlyName,
+  shop,
+  callbackUrl,
+  passbackParams,
+  timeToLive = 120,
+  paymentMethod,
+  merchantPartnerId,
+  oauth2Token,
+  useSandbox = true
+}) {
   if (!transactionId) {
     throw new Error('Transaction ID is required');
   }
 
+  if (!amount) {
+    throw new Error('Amount is required for processing');
+  }
+
+  if (typeof amount !== 'string' && typeof amount !== 'number') {
+    throw new Error('Amount must be a string or number representing currency value (e.g., "25.50" or 25.50)');
+  }
+
+  if (parseFloat(amount) <= 0) {
+    throw new Error('Amount must be positive for processing');
+  }
+
+  if (!reasonL1) {
+    throw new Error('reasonL1 is required (transaction grounds description)');
+  }
+
   if (!merchantPartnerId) {
     throw new Error('Merchant Partner ID is required for ISV operations');
   }
@@ -18,14 +69,27 @@ export async function processTransaction({ transactionId, merchantPartnerId, oau
     throw new Error('OAuth2 token is required for ISV operations');
   }
 
-  if (!['CONFIRMED', 'DECLINED'].includes(action)) {
-    throw new Error('Action must be either CONFIRMED or DECLINED');
-  }
-
   const isvPartnerId = getPartnerIdSafe();
   const privateKey = getPrivateKeySafe(useSandbox);
 
-  const requestBody = { action };
+  // Same body the merchant tool builds - the on-behalf claims live in the JWT, not in the payload.
+  const requestBody = {
+    ...(account && { account }),
+    ...(friendlyName && { friendlyName }),
+    ...(shop && { shop }),
+    ...(callbackUrl && { callbackUrl }),
+    ...(passbackParams && { passbackParams }),
+    ...(paymentMethod && { paymentMethod }),
+    trData: {
+      amount: amount.toString(),
+      currency,
+      reasonL1,
+      ...(reasonL2 && { reasonL2 })
+    },
+    trOptions: {
+      timeToLive
+    }
+  };
 
   const jwtData = await createJWTForPartner({
     partnerId: isvPartnerId,
@@ -35,14 +99,12 @@ export async function processTransaction({ transactionId, merchantPartnerId, oau
     oauth2Token
   });
 
-  // Use the same JSON serialization method as the JWT factory for MD5 calculation
-  const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
+  // The EXACT string the JWT hashed must be the body; anything else is ERR_INVALID_CONTENT_HASH.
   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.patch(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
+    const response = await axios.post(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,
         'Content-Type': 'application/json',
@@ -54,42 +116,102 @@ export async function processTransaction({ transactionId, merchantPartnerId, oau
 
     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');
   }
 }
 
 export const processTransactionTool = {
   name: 'payware_operations_process_transaction',
-  description: `Process (finalize) a transaction as an ISV on behalf of a merchant.
+  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}
+
+The customer presents a transaction they created; the merchant (through you) processes it with the
+amount to collect. Only ACTIVE transactions can be processed - one already processed answers **409
+\`ERR_ALREADY_PROCESSED\`**, which means "already done", not "bad request".
+
+⚠️ **This does not confirm or decline a payment.** Processing hands the transaction to the payer's
+financial institution, which decides. An ISV cannot send CONFIRMED or DECLINED - the server rejects
+any status other than CANCELLED from a merchant or its ISV. To cancel, use
+\`payware_operations_cancel_transaction\`.
+
+⚠️ **The MERCHANT's plan governs, not the ISV's.** An on-behalf call inherits the acting merchant's
+plan, so this answers **403** when that merchant is on **Basic**. Naming a shop outside the scope the
+merchant assigned you answers **403 \`ERR_SHOP_NOT_IN_SCOPE\`**.
 
-Allows confirming or declining a transaction. Only ACTIVE transactions can be processed.
-Requires ISV authentication with merchant partner ID and OAuth2 token.`,
+💰 **\`amount\` is a decimal string at the currency's own scale** - not always two decimals. The fee
+payware returns on the response is the value to echo back at finalize, unchanged.`,
 
   inputSchema: {
     type: 'object',
-    required: ['transactionId', 'merchantPartnerId', 'oauth2Token'],
+    required: ['transactionId', 'amount', 'currency', 'reasonL1', 'merchantPartnerId', 'oauth2Token'],
     properties: {
       transactionId: {
         type: 'string',
-        description: 'Transaction ID to process'
+        description: "The customer's transaction to process, e.g. \"pw7e4rCToG\""
+      },
+      amount: {
+        type: 'string',
+        description: 'Amount to collect, as a decimal string at the currency\'s own scale (e.g. "25.50"). Must be positive.'
+      },
+      currency: {
+        type: 'string',
+        pattern: '^[A-Z]{3}$',
+        description: 'ISO 4217 currency code. Must match the transaction currency - changing it answers ERR_SPECIFYING_CURRENCY_NOT_ALLOWED.'
+      },
+      reasonL1: {
+        type: 'string',
+        description: 'Transaction grounds description (required)',
+        maxLength: 100
+      },
+      reasonL2: {
+        type: 'string',
+        description: 'Transaction grounds description continuation (optional)',
+        maxLength: 100
+      },
+      account: {
+        type: 'string',
+        description: 'Merchant account identifier. If omitted, determined from the merchant profile.',
+        maxLength: 36
+      },
+      friendlyName: {
+        type: 'string',
+        description: 'Account holder recognizable name. If omitted, the merchant alias is used.',
+        maxLength: 100
+      },
+      shop: {
+        type: 'string',
+        description: 'Shop code. If omitted, the merchant default shop is used - which may be outside your assigned scope. Find valid codes with payware_shops_list.',
+        maxLength: 10
+      },
+      callbackUrl: {
+        type: 'string',
+        description: 'HTTPS URL for the status callback. Must present a publicly-trusted TLS certificate and resolve to a public address.',
+        format: 'uri'
+      },
+      passbackParams: {
+        type: 'string',
+        description: 'Opaque string passed back unmodified on responses and callbacks.',
+        maxLength: 200
+      },
+      timeToLive: {
+        type: 'number',
+        description: 'Processing window in seconds.',
+        default: 120
+      },
+      paymentMethod: {
+        type: 'string',
+        enum: ['A2A', 'CARD_FUNDED', 'BNPL', 'INSTANT_CREDIT'],
+        description: 'Payment method. A2A = direct transfer. CARD_FUNDED = card-linked account. BNPL = buy now pay later. INSTANT_CREDIT = credit line.'
       },
       merchantPartnerId: {
         type: 'string',
-        description: 'Partner ID of the target merchant'
+        description: 'Partner ID of the target merchant (8 alphanumeric characters)'
       },
       oauth2Token: {
         type: 'string',
         description: 'OAuth2 access token obtained from the merchant'
       },
-      action: {
-        type: 'string',
-        enum: ['CONFIRMED', 'DECLINED'],
-        default: 'CONFIRMED',
-        description: 'Action to perform on the transaction'
-      },
       useSandbox: {
         type: 'boolean',
         description: 'Use sandbox environment for testing',
@@ -102,19 +224,19 @@ Requires ISV authentication with merchant partner ID and OAuth2 token.`,
     try {
       const result = await processTransaction(params);
 
-      const actionEmoji = params.action === 'CONFIRMED' ? '✅' : '❌';
-
       return {
         content: [{
           type: 'text',
-          text: `${actionEmoji} Transaction ${params.action} Successfully (ISV -> Merchant: ${params.merchantPartnerId})
+          text: `✅ **Transaction Processed** (ISV -> Merchant: ${params.merchantPartnerId})
 
-📋 **Processing Details:**
-- **Transaction ID**: ${params.transactionId}
-- **Action**: ${params.action}
-- **New Status**: ${result.status || params.action}
-- **ISV Partner**: ${getPartnerIdSafe()}
-- **Target Merchant**: ${params.merchantPartnerId}
+- Transaction ID: ${result.transactionId || params.transactionId}
+- Status: ${result.status || 'N/A'}
+- Amount: ${result.amount ?? params.amount} ${result.currency ?? params.currency}
+- Fee: ${result.fee ?? '(not reported)'}${result.fee ? ' - echo this back unchanged at finalize' : ''}
+- ISV Partner: ${getPartnerIdSafe()}
+
+**Next:** the payer's financial institution now confirms or declines. Watch for the callback, or poll
+\`payware_operations_get_transaction_status\` while it is ACTIVE.
 
 **Raw Response:**
 \`\`\`json
@@ -132,14 +254,10 @@ ${JSON.stringify(result, null, 2)}
 
 **Processing Attempt:**
 - Transaction ID: ${params.transactionId}
-- Action: ${params.action}
-- Merchant: ${params.merchantPartnerId}
-
-**ISV Authentication:**
-- OAuth2 Token: ${params.oauth2Token ? 'Provided' : 'Missing'}
+- Merchant Partner ID: ${params.merchantPartnerId}
 - ISV Partner ID: ${getPartnerIdSafe()}`
         }]
       };
     }
   }
-};
+};

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

@@ -1,146 +1,165 @@
-import axios from 'axios';
-import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
-import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { getPartnerIdSafe } from '../../config/env.js';
+import { generateMockCallback, simulateCallbackDelivery } from '../../merchant/transactions/simulate-callback.js';
 
 /**
- * Simulate a transaction callback via payware API as an ISV
+ * Simulate the callback a merchant's endpoint receives, for an ISV building that handler.
+ *
+ * **This used to POST `/transactions/{id}/simulate-callback` with `{action: "CONFIRMED"}`.** There is
+ * no such endpoint - a whole-tree search of the server finds no `simulate-callback` route in any
+ * controller, in any profile - so every call 404'd, and the `action` field it sent is not a field on
+ * any payware request. payware has no "trigger a callback for me" API at all.
+ *
+ * Simulation is therefore local, exactly as the merchant tool has always done it: build the payload
+ * payware would send and hand it back, so a handler can be written and tested against the real
+ * shape without a live transaction. The generator is imported from the merchant tool rather than
+ * copied - one definition of the payload, so a contract change cannot fix one role and miss the
+ * other, which is how the two drifted apart in the first place.
  */
-export async function simulateCallback({ transactionId, merchantPartnerId, oauth2Token, action = 'CONFIRMED', useSandbox = true }) {
-  if (!transactionId) {
-    throw new Error('Transaction ID is required');
-  }
+export const simulateCallbackTool = {
+  name: 'payware_operations_simulate_callback',
+  description: `Simulate the callback payload payware sends to a merchant's callbackUrl, for building and testing a webhook handler as an ISV.
 
-  if (!merchantPartnerId) {
-    throw new Error('Merchant Partner ID is required for ISV operations');
-  }
+**Local only - this makes no API call.** payware has no endpoint that triggers a callback on demand,
+so nothing here reaches the network. What you get back is the exact payload shape a real
+TRANSACTION_FINALIZED callback carries, which is what a handler needs in order to be written.
 
-  if (!oauth2Token) {
-    throw new Error('OAuth2 token is required for ISV operations');
-  }
+**Callbacks go to the MERCHANT's callbackUrl, not to yours.** An ISV that needs to know a transaction
+finished either has the merchant forward it, or polls
+\`payware_operations_get_transaction_history\` for the ids it created. Simulating the payload here
+tells you what the merchant's endpoint will receive; it does not route anything to you.
 
-  if (!['CONFIRMED', 'DECLINED'].includes(action)) {
-    throw new Error('Action must be either CONFIRMED or DECLINED');
-  }
+Four properties of the real payload that are easy to get wrong:
 
-  const isvPartnerId = getPartnerIdSafe();
-  const privateKey = getPrivateKeySafe(useSandbox);
-
-  const requestBody = { action };
-
-  const jwtData = await createJWTForPartner({
-    partnerId: isvPartnerId,
-    privateKey,
-    requestBody,
-    merchantId: merchantPartnerId,
-    oauth2Token
-  });
-
-  // Use the same JSON serialization method as the JWT factory for MD5 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.post(`${baseUrl}/transactions/${transactionId}/simulate-callback`, minimizedBodyString, {
-      headers: {
-        'Authorization': `Bearer ${jwtData.token}`,
-        'Content-Type': 'application/json',
-        'Api-Version': '1'
-      },
-      // Tell axios to send the string as-is, don't serialize it again
-      transformRequest: [(data) => data]
-    });
+**1. Absent means absent, not zero.** Properties with no value are omitted, not sent as \`null\` or
+\`0\`. A missing \`fee\` means the fee is *unknown* for that transaction - not that it was free.
 
-    return response.data;
-  } catch (error) {
-    if (error.response) {
-      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
-    }
-    throw error;
-  }
-}
+**2. \`finalized\` is absent on EXPIRED** - the expiry sweep sets no finalization moment.
 
-export const simulateCallbackTool = {
-  name: 'payware_operations_simulate_callback',
-  description: `Simulate a transaction callback as an ISV on behalf of a merchant.
+**3. \`EXPIRED\` is a non-payment, not a failure.** The payer never paid within \`timeToLive\`. Release
+the order or the stock; do not treat it as an error to retry.
 
-Triggers a callback to test webhook integration in sandbox environment.
-Requires ISV authentication with merchant partner ID and OAuth2 token.`,
+**4. Deduplicate on \`(transactionId, callbackType)\`.** payware retries once a second, up to 15
+times, until the endpoint answers 200. That pair is stable across retries and is the key payware
+guarantees.
+
+**Not on this payload:** \`deliveryAddress\` (removed 2026-08-07 - fetch it from
+\`payware_operations_get_transaction_history\`), \`producerPartnerId\`, \`transactionType\` and
+\`initiatedBy\`.`,
 
   inputSchema: {
     type: 'object',
-    required: ['transactionId', 'merchantPartnerId', 'oauth2Token'],
+    required: ['transactionId'],
     properties: {
       transactionId: {
         type: 'string',
-        description: 'Transaction ID to simulate callback for'
+        description: 'Transaction ID to build the callback payload for'
       },
-      merchantPartnerId: {
+      status: {
+        type: 'string',
+        enum: ['CONFIRMED', 'DECLINED', 'FAILED', 'EXPIRED', 'CANCELLED'],
+        description: 'Final status to simulate',
+        default: 'CONFIRMED'
+      },
+      callbackUrl: {
         type: 'string',
-        description: 'Partner ID of the target merchant'
+        description: 'URL the callback would be delivered to. Recorded in the output for reference; no request is sent.',
+        format: 'uri'
       },
-      oauth2Token: {
+      amount: {
         type: 'string',
-        description: 'OAuth2 access token obtained from the merchant'
+        description: "Transaction amount as a decimal string at the currency's own scale (e.g. '57.60')",
+        default: '57.60'
       },
-      action: {
+      currency: {
         type: 'string',
-        enum: ['CONFIRMED', 'DECLINED'],
-        default: 'CONFIRMED',
-        description: 'Action to simulate in the callback'
+        enum: ['EUR', 'USD', 'GBP'],
+        description: 'Transaction currency',
+        default: 'EUR'
+      },
+      fee: {
+        type: 'string',
+        description: "The payware fee, at the currency's smallest payable unit (e.g. '0.29'). Pass null to model the anomaly case where a transaction has no recorded fee and the server OMITS the property - deliberately distinguishable from a genuine '0.00'."
+      },
+      feeFixed: {
+        type: 'string',
+        description: 'Fixed fee component of the applicable fee configuration. Informational, for reconciliation. Present on FINALIZED callbacks since 2026-08-21.',
+        default: '0.1000'
+      },
+      feeRate: {
+        type: 'string',
+        description: "Variable rate of the applicable fee configuration, e.g. '0.0150' = 1.5%. Informational, same as feeFixed.",
+        default: '0.0150'
+      },
+      statusMessage: {
+        type: 'string',
+        description: 'Custom status message. DECLINED, FAILED and CANCELLED transactions always carry one.'
+      },
+      paymentMethod: {
+        type: 'string',
+        enum: ['A2A', 'CARD_FUNDED', 'BNPL', 'INSTANT_CREDIT'],
+        description: 'Payment method chosen by the customer. A2A = direct transfer. CARD_FUNDED = card-linked account. BNPL = buy now pay later. INSTANT_CREDIT = credit line.'
+      },
+      merchantPartnerId: {
+        type: 'string',
+        description: 'Partner ID of the merchant whose callback this simulates. Used for labelling only - no call is made on their behalf.'
       },
       useSandbox: {
         type: 'boolean',
-        description: 'Use sandbox environment for testing',
+        description: 'Retained for consistency with the other tools; simulation is local and ignores it.',
         default: true
       }
     }
   },
 
-  async handler(params) {
-    try {
-      const result = await simulateCallback(params);
+  async handler(args) {
+    const {
+      transactionId,
+      status = 'CONFIRMED',
+      callbackUrl,
+      amount = '57.60',
+      currency = 'EUR',
+      fee,
+      feeFixed = '0.1000',
+      feeRate = '0.0150',
+      statusMessage,
+      paymentMethod,
+      merchantPartnerId
+    } = args;
+
+    if (!transactionId) {
+      throw new Error('Transaction ID is required');
+    }
 
-      const actionEmoji = params.action === 'CONFIRMED' ? '✅' : '❌';
+    const payload = generateMockCallback(transactionId, status, {
+      amount, currency, fee, feeFixed, feeRate, statusMessage, paymentMethod
+    });
 
-      return {
-        content: [{
-          type: 'text',
-          text: `🔔 Callback Simulated Successfully (ISV -> Merchant: ${params.merchantPartnerId})
+    const delivery = callbackUrl ? await simulateCallbackDelivery(callbackUrl, payload) : null;
 
-**Callback Details:**
-- **Transaction ID**: ${params.transactionId}
-- **Simulated Action**: ${actionEmoji} ${params.action}
-- **ISV Partner**: ${getPartnerIdSafe()}
-- **Target Merchant**: ${params.merchantPartnerId}
+    return {
+      content: [{
+        type: 'text',
+        text: `🔔 **Simulated Callback Payload**${merchantPartnerId ? ` (ISV ${getPartnerIdSafe()} -> Merchant ${merchantPartnerId})` : ''}
 
-**Use Case**: Testing webhook integration in sandbox environment
+This is what payware would POST to the **merchant's** \`callbackUrl\`. No request was made.
 
-**Raw Response:**
 \`\`\`json
-${JSON.stringify(result, null, 2)}
-\`\`\``
-        }]
-      };
-    } catch (error) {
-      return {
-        content: [{
-          type: 'text',
-          text: `❌ Callback Simulation Failed
-
-**Error**: ${error.message}
-
-**Simulation Attempt:**
-- Transaction ID: ${params.transactionId}
-- Action: ${params.action}
-- Merchant: ${params.merchantPartnerId}
-
-**ISV Authentication:**
-- OAuth2 Token: ${params.oauth2Token ? 'Provided' : 'Missing'}
-- ISV Partner ID: ${getPartnerIdSafe()}`
-        }]
-      };
-    }
+${JSON.stringify(payload, null, 2)}
+\`\`\`
+${delivery ? `
+**Would be delivered to:** ${delivery.url}
+**Headers:** ${JSON.stringify(delivery.headers, null, 2)}
+${delivery.note}
+` : '**No callbackUrl given** - payload only.'}
+
+**Building the handler:**
+1. Answer **200** or payware retries - once a second, 15 times.
+2. Deduplicate on \`(transactionId, callbackType)\`; retries repeat the same pair.
+3. Read properties defensively: absent means absent, never zero.
+4. Treat \`EXPIRED\` as a non-payment, not an error to retry.
+5. Need the delivery address for a SHIPPABLE order? It is not here - call
+   \`payware_operations_get_transaction_history\`.`
+      }]
+    };
   }
-};
+};