@payware/mcp-server 1.3.2 → 1.3.3

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

@@ -8,7 +8,7 @@ import { apiErrorResult } from '../../shared/api-errors.js';
  * @param {Object} params - Parameters for set price request
  * @returns {Object} Set price response
  */
-export async function setPOIPrice({ poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams, merchantPartnerId, oauth2Token, useSandbox = true }) {
+export async function setPOIPrice({ poiId, amount, currency, ttlSeconds, merchantPartnerId, oauth2Token, useSandbox = true }) {
   if (!poiId) {
     throw new Error('POI ID is required');
   }
@@ -21,10 +21,6 @@ export async function setPOIPrice({ poiId, amount, currency, reasonL1, reasonL2,
     throw new Error('Currency is required');
   }
 
-  if (!reasonL1) {
-    throw new Error('Reason (reasonL1) is required');
-  }
-
   if (!merchantPartnerId) {
     throw new Error('Merchant Partner ID is required for ISV operations');
   }
@@ -36,17 +32,16 @@ export async function setPOIPrice({ poiId, amount, currency, reasonL1, reasonL2,
   const isvPartnerId = getPartnerIdSafe();
   const privateKey = getPrivateKeySafe(useSandbox);
 
-  // Build request body
+  // amount, currency and ttlSeconds are the only fields the server reads (POIPriceRequest); anything
+  // else is ignored without an error. This used to send reasonL1 (and demand it), reasonL2,
+  // timeToLive, callbackUrl and passbackParams - none of which the server has - so a caller relying
+  // on the per-price callbackUrl got no callbacks at all. The callback URL belongs to the POI.
   const requestBody = {
     amount: String(amount),
-    currency: currency.toUpperCase(),
-    reasonL1
+    currency: currency.toUpperCase()
   };
 
-  if (reasonL2) requestBody.reasonL2 = reasonL2;
-  if (timeToLive) requestBody.timeToLive = timeToLive;
-  if (callbackUrl) requestBody.callbackUrl = callbackUrl;
-  if (passbackParams) requestBody.passbackParams = passbackParams;
+  if (ttlSeconds) requestBody.ttlSeconds = ttlSeconds;
 
   const jwtData = await createJWTForPartner({
     partnerId: isvPartnerId,
@@ -88,13 +83,21 @@ export const setPOIPriceTool = {
 **Endpoint:** PUT /poi/{poiId}/price
 **Use Case:** Set the amount a customer should pay when they scan the POI.
 
-The POI will transition to READY state and wait for a customer scan until the TTL expires.
+The POI moves to READY and waits for a scan until the TTL expires. The scan creates the transaction and
+the POI is BUSY until the sale is final.
+
+**Only amount, currency and ttlSeconds are accepted.** There is no description, callback URL or passback
+field on a price - the callback URL is set on the POI when it is created, and a POI without one sends no
+callbacks.
+
+**Keep the returned sessionToken** until the sale has a final status: pass it to
+payware_poi_get_status to read that sale's transaction and outcome.
 
-**Required:** POI ID, amount, currency, reason, Merchant Partner ID, and OAuth2 token.`,
+**Required:** POI ID, amount, currency, Merchant Partner ID, and OAuth2 token.`,
 
   inputSchema: {
     type: "object",
-    required: ["poiId", "amount", "currency", "reasonL1", "merchantPartnerId", "oauth2Token"],
+    required: ["poiId", "amount", "currency", "merchantPartnerId", "oauth2Token"],
     properties: {
       poiId: {
         type: "string",
@@ -102,31 +105,15 @@ The POI will transition to READY state and wait for a customer scan until the TT
       },
       amount: {
         type: "string",
-        description: "Payment amount (e.g., '25.50')"
+        description: "Payment amount (e.g., '25.50'), positive and no finer than the currency's smallest unit"
       },
       currency: {
         type: "string",
         description: "ISO 4217 currency code (e.g., 'EUR', 'USD', 'GBP')"
       },
-      reasonL1: {
-        type: "string",
-        description: "Payment description (e.g., 'Table 5', 'Order #123')"
-      },
-      reasonL2: {
-        type: "string",
-        description: "Additional description (optional)"
-      },
-      timeToLive: {
+      ttlSeconds: {
         type: "integer",
-        description: "Seconds until price expires (60-600, default: 120)"
-      },
-      callbackUrl: {
-        type: "string",
-        description: "Override callback URL for this payment (optional)"
-      },
-      passbackParams: {
-        type: "string",
-        description: "Data to pass back in callback (optional, max 200 chars)"
+        description: "Seconds until the price expires if nobody scans it (60-600). Defaults to the POI's own ttlSeconds."
       },
       merchantPartnerId: {
         type: "string",
@@ -145,18 +132,16 @@ The POI will transition to READY state and wait for a customer scan until the TT
   },
 
   async handler(args) {
-    const { poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams, merchantPartnerId, oauth2Token, useSandbox = true } = args;
+    const { poiId, amount, currency, ttlSeconds, merchantPartnerId, oauth2Token, useSandbox = true } = args;
 
     if (!poiId) throw new Error("POI ID is required");
     if (!amount) throw new Error("Amount is required");
     if (!currency) throw new Error("Currency is required");
-    if (!reasonL1) throw new Error("Reason (reasonL1) is required");
     if (!merchantPartnerId) throw new Error("Merchant Partner ID is required");
     if (!oauth2Token) throw new Error("OAuth2 token is required");
 
     const result = await setPOIPrice({
-      poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams,
-      merchantPartnerId, oauth2Token, useSandbox
+      poiId, amount, currency, ttlSeconds, merchantPartnerId, oauth2Token, useSandbox
     });
 
     if (result.success) {
@@ -169,19 +154,17 @@ The POI will transition to READY state and wait for a customer scan until the TT
 
 **POI ID:** ${data.poiId || poiId}
 **Status:** 🟡 ${data.status || 'READY'}
-
-**Payment Details:**
-- Amount: **${data.amount || amount} ${data.currency || currency}**
-- Reason: ${reasonL1}${reasonL2 ? ` - ${reasonL2}` : ''}
+**Amount:** ${amount} ${currency.toUpperCase()}
 
 **Session:**
-- Token: ${data.sessionToken || 'N/A'}
-- Expires: ${data.sessionExpiresAt || 'N/A'}
+- Token: ${data.sessionToken || 'N/A'} - keep it until the sale is final
+- Price expires if not scanned: ${data.expiresAt || 'N/A'}
 
 **Next Steps:**
-1. Customer scans the POI (QR code, NFC tag, or barcode)
-2. Customer sees the amount and confirms payment
-3. You receive a callback when payment completes
+1. The customer scans the POI (QR code, NFC tag or BLE); the transaction is created and the POI is BUSY
+2. Outcome by callback, if the POI has a callbackUrl: poi.scanned with the transaction id, then TRANSACTION_FINALIZED with the final status (both carry the poiId)
+3. Or poll payware_poi_get_status every 2-3 seconds with this sessionToken until transactionStatus is final
+4. To cancel, use payware_poi_cancel_price - possible only before the scan
 
 **ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
 **Request ID:** ${result.requestId || 'N/A'}
@@ -202,12 +185,14 @@ The POI will transition to READY state and wait for a customer scan until the TT
 **Status:** ${result.error.status || 'N/A'}
 
 **Common Issues:**
-- INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
-- POI_NOT_FOUND (404): POI doesn't exist or doesn't belong to merchant
-- POI_DISABLED (409): POI is disabled
-- POI_NOT_IDLE (409): POI already has a pending price (cancel it first)
-- INVALID_AMOUNT (400): Check amount format (e.g., '25.50')
-- UNKNOWN_CURRENCY (400): Invalid currency code
+- ERR_INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
+- ERR_POI_NOT_FOUND (404): POI doesn't exist or doesn't belong to the merchant
+- ERR_SHOP_NOT_IN_SCOPE (403): the POI's shop is not assigned to you
+- ERR_POI_DISABLED (409): POI is disabled
+- ERR_POI_ALREADY_HAS_PENDING_PRICE (409): POI already has a pending price (cancel it first)
+- ERR_INVALID_AMOUNT (400): amount finer than the currency's smallest unit
+- ERR_MISSING_CURRENCY (400): currency missing or unknown
+- ERR_VALIDATION_FAILED (400): amount missing or not positive, or ttlSeconds outside 60-600
 
 **Timestamp:** ${result.timestamp}`
         }]

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

@@ -23,10 +23,12 @@ export const simulateCallbackTool = {
 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.
 
-**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.
+**Where the callback goes.** A transaction you create on a merchant's behalf calls back to the
+\`callbackUrl\` you give when creating it; a POI sale calls back to the POI's \`callbackUrl\`. Both are
+signed with your ISV callback key, so verify them with your own payware public key. Give no callbackUrl
+and that transaction sends no callbacks at all - the merchant's default URL is not used. Without a backend, follow the
+transaction with \`payware_operations_get_transaction_status\` while it is ACTIVE and then
+\`payware_operations_get_transaction_history\` once, or a POI sale with \`payware_poi_get_status\`.
 
 Four properties of the real payload that are easy to get wrong:
 
@@ -38,9 +40,11 @@ Four properties of the real payload that are easy to get wrong:
 **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.
 
-**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.
+**4. Deduplicate on \`(transactionId, callbackType)\`.** payware retries up to 15 times, backing off
+from about a second to at most 5 minutes between attempts, until the endpoint answers any 2xx. That
+pair is stable across retries and is the key payware guarantees.
+
+A POI sale's callback also carries \`poiId\`, the POI that created the transaction.
 
 **Not on this payload:** \`deliveryAddress\` (removed 2026-08-07 - fetch it from
 \`payware_operations_get_transaction_history\`), \`producerPartnerId\`, \`transactionType\` and
@@ -99,6 +103,10 @@ guarantees.
         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.'
       },
+      poiId: {
+        type: 'string',
+        description: 'Set to simulate a POI sale: the callback then carries the poiId of the POI that created the transaction'
+      },
       merchantPartnerId: {
         type: 'string',
         description: 'Partner ID of the merchant whose callback this simulates. Used for labelling only - no call is made on their behalf.'
@@ -123,6 +131,7 @@ guarantees.
       feeRate = '0.0150',
       statusMessage,
       paymentMethod,
+      poiId,
       merchantPartnerId
     } = args;
 
@@ -131,7 +140,7 @@ guarantees.
     }
 
     const payload = generateMockCallback(transactionId, status, {
-      amount, currency, fee, feeFixed, feeRate, statusMessage, paymentMethod
+      amount, currency, fee, feeFixed, feeRate, statusMessage, paymentMethod, poiId
     });
 
     const delivery = callbackUrl ? await simulateCallbackDelivery(callbackUrl, payload) : null;
@@ -141,7 +150,7 @@ guarantees.
         type: 'text',
         text: `🔔 **Simulated Callback Payload**${merchantPartnerId ? ` (ISV ${getPartnerIdSafe()} -> Merchant ${merchantPartnerId})` : ''}
 
-This is what payware would POST to the **merchant's** \`callbackUrl\`. No request was made.
+This is what payware would POST to the transaction's (or POI's) \`callbackUrl\`. No request was made.
 
 \`\`\`json
 ${JSON.stringify(payload, null, 2)}
@@ -153,7 +162,7 @@ ${delivery.note}
 ` : '**No callbackUrl given** - payload only.'}
 
 **Building the handler:**
-1. Answer **200** or payware retries - once a second, 15 times.
+1. Answer any **2xx** or payware retries - up to 15 times, backing off from about a second to 5 minutes.
 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.