@payware/mcp-server 1.4.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payware/mcp-server",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "mcpName": "io.github.payware/mcp-server",
   "description": "Official MCP server for payware payment API integration",
   "main": "src/index.js",

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

@@ -37,6 +37,7 @@ export async function createTransaction({
   barBarHeight,
   barFontSize,
   barHumanReadableLocation,
+  idempotencyKey,
   useSandbox = true
 }) {
   // ISV-specific validation
@@ -132,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');
   }
@@ -166,11 +171,13 @@ now returns 403, check the merchant's plan first.
 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.
+ℹ️ **Producer attribution does not apply here.** 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, and the
+producer earns nothing from it. This tool therefore does not send \`producerPartnerId\` /
+\`terminalId\` / \`terminalManufacturer\`. The server does accept them on an ISV call - it checks
+them (an unrecognised producer is a 400) and records them for provenance - but they never move the
+sale to the producer. 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
@@ -200,6 +207,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/process-transaction.js

@@ -40,6 +40,7 @@ export async function processTransaction({
   paymentMethod,
   merchantPartnerId,
   oauth2Token,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!transactionId) {
@@ -109,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');
   }
@@ -148,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/merchant/transactions/cancel-transaction.js

@@ -214,7 +214,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction not found. **ERR_TRANSACTION_EXPIRED** (also 404): its time to live has run out and it is already closed as unpaid
 2. **ERR_ALREADY_PROCESSED**: Transaction already processed, cannot cancel
 3. **ERR_UNAUTHORIZED_OPERATION**: Only transaction creator can cancel
 4. **ERR_INVALID_STATUS_MESSAGE**: Status message invalid or too long

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

@@ -40,6 +40,7 @@ export async function createTransaction({
   barBarHeight,
   barFontSize,
   barHumanReadableLocation,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!reasonL1) {
@@ -142,7 +143,8 @@ export async function createTransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1' // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
   
   try {
@@ -160,6 +162,7 @@ export async function createTransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -255,7 +258,9 @@ agreement with payware. Three fields, all optional:
   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.
+  characters. Recorded for provenance. payware's internal attribution review counts each producer's
+  sales by reported manufacturer, so a build running on another vendor's hardware stands out; it is
+  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
@@ -269,6 +274,11 @@ ISV's software is running on that producer's hardware.`,
   inputSchema: {
     type: "object",
     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}$"
+      },
       type: {
         type: "string",
         enum: ["PLAIN", "QR", "BARCODE"],
@@ -446,6 +456,7 @@ ISV's software is running on that producer's hardware.`,
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox = true
     } = args;
     
@@ -490,6 +501,7 @@ ISV's software is running on that producer's hardware.`,
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox
     });
     

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

@@ -25,6 +25,7 @@ export async function processTransaction({
   paymentMethod,
   partnerId,
   privateKey,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!transactionId) {
@@ -80,7 +81,8 @@ export async function processTransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1'  // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
 
   try {
@@ -96,6 +98,7 @@ export async function processTransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -138,6 +141,11 @@ export const processTransactionTool = {
     type: "object",
     additionalProperties: false,
     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: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
@@ -236,6 +244,7 @@ export const processTransactionTool = {
       paymentMethod,
       partnerId = getPartnerIdSafe(),
       privateKey = getPrivateKeySafe(args.useSandbox ?? true),
+      idempotencyKey,
       useSandbox = true
     } = args;
     
@@ -274,6 +283,7 @@ export const processTransactionTool = {
       paymentMethod,
       partnerId,
       privateKey,
+      idempotencyKey,
       useSandbox
     });
     
@@ -334,7 +344,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found. **ERR_TRANSACTION_EXPIRED** (also 404): its time to live has run out and it is closed as unpaid
 2. **ERR_UNKNOWN_ROLE**: Transaction generated by payee (can't process own transaction)
 3. **ERR_ALREADY_PROCESSED**: Transaction already processed
 4. **ERR_SPECIFYING_AMOUNT_NOT_ALLOWED**: Amount exceeds transaction limit

package/src/payment-institution/transactions/create-pi-transaction.js

@@ -37,6 +37,7 @@ export async function createPITransaction({
   barBarHeight,
   barFontSize,
   barHumanReadableLocation,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!role || !['SRC', 'DST'].includes(role)) {
@@ -122,7 +123,8 @@ export async function createPITransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1' // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
 
   try {
@@ -139,6 +141,7 @@ export async function createPITransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -185,6 +188,11 @@ export const createPITransactionTool = {
   inputSchema: {
     type: "object",
     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}$"
+      },
       role: {
         type: "string",
         enum: ["SRC", "DST"],
@@ -348,6 +356,7 @@ export const createPITransactionTool = {
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox = true
     } = args;
 
@@ -397,6 +406,7 @@ export const createPITransactionTool = {
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox
     });
 

package/src/payment-institution/transactions/finalize-transaction.js

@@ -313,7 +313,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Finalization Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found. **ERR_TRANSACTION_EXPIRED** (also 404): the time to live ran out before the finalize arrived, and the transaction is closed as unpaid
 2. **ERR_TRANSACTION_NOT_PROCESSED**: Transaction hasn't been processed yet
 3. **ERR_ALREADY_PROCESSED**: Transaction already finalized
 4. **ERR_INVALID_STATUS**: Invalid status value provided

package/src/payment-institution/transactions/process-pi-transaction.js

@@ -28,6 +28,7 @@ export async function processPITransaction({
   deliveryAddress,
   // Payment method for POI transactions (Payment Choice Architecture)
   paymentMethod,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!transactionId) {
@@ -85,7 +86,8 @@ export async function processPITransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1'  // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
 
   try {
@@ -101,6 +103,7 @@ export async function processPITransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -148,6 +151,11 @@ export const processPITransactionTool = {
   inputSchema: {
     type: "object",
     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: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
@@ -294,6 +302,7 @@ export const processPITransactionTool = {
       privateKey = getPrivateKeySafe(args.useSandbox ?? true),
       paymentMethod,
       deliveryAddress,
+      idempotencyKey,
       useSandbox = true
     } = args;
 
@@ -340,6 +349,7 @@ export const processPITransactionTool = {
       privateKey,
       paymentMethod,
       deliveryAddress,
+      idempotencyKey,
       useSandbox
     });
 
@@ -404,7 +414,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Payment Institution Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found. **ERR_TRANSACTION_EXPIRED** (also 404): its time to live has run out and it is closed as unpaid
 2. **ERR_ALREADY_PROCESSED**: Transaction already processed
 3. **ERR_MISSING_PARTNER_ACCOUNT**: Account parameter missing or empty
 4. **ERR_MISSING_FRIENDLY_NAME**: Friendly name parameter missing