strapi-plugin-payone-provider 5.6.9 → 5.6.10

package/README.md

@@ -1566,3 +1566,135 @@ For wallet payments (PayPal, Google Pay, Apple Pay), you can specify:
 
 - `capturemode: "full"`: Capture the entire preauthorized amount
 - `capturemode: "partial"`: Capture less than the preauthorized amount
+
+---
+
+## 📢 TransactionStatus Notifications
+
+The Payone platform provides an asynchronous way of notifying your system of changes to a transaction. These notifications are called "TransactionStatus" and are automatically handled by this plugin.
+
+### What are TransactionStatus Notifications?
+
+TransactionStatus notifications are POST requests sent from Payone's servers to your endpoint when transaction status changes occur. This is especially important for:
+
+- **Redirect Payment Methods**: Verifying that payments were actually completed (prevents fraud)
+- **Chargeback Processes**: Being notified when customers initiate chargebacks
+- **Real-time Tracking**: Keeping your system updated with the latest transaction status
+
+### How It Works
+
+1. **Payone sends notification** → Your Strapi endpoint receives POST request
+2. **Plugin verifies request** → Checks IP address, User-Agent, and hash signature
+3. **Plugin processes notification** → Updates transaction history automatically
+4. **Plugin responds** → Returns `TSOK` to confirm receipt
+
+### Endpoint Configuration
+
+The plugin automatically provides the TransactionStatus endpoint at:
+
+**URL**: `POST /api/strapi-plugin-payone-provider/transaction-status`
+
+**No authentication required** - The endpoint is secured by:
+
+- IP address verification (only Payone IPs allowed)
+- User-Agent verification (must be "PAYONE FinanceGate")
+- Hash signature verification (MD5 hash of transaction data)
+
+### PMI Configuration
+
+You need to configure this endpoint in your Payone Merchant Interface (PMI):
+
+1. Log into your Payone Merchant Interface (PMI)
+2. Navigate to **Configuration** → **Payment Portals** → **[Your Portal]**
+3. Find the **TransactionStatus Endpoint** setting
+4. Enter your endpoint URL: `https://yourdomain.com/api/strapi-plugin-payone-provider/transaction-status`
+5. Save the configuration
+
+> ⚠️ **Important**: The endpoint must be accessible via HTTPS. Payone will not send notifications to HTTP endpoints.
+
+### Security Features
+
+The plugin automatically verifies:
+
+1. **IP Address**: Only accepts requests from Payone's IP ranges:
+
+   - `185.60.20.0/24`
+   - `54.246.203.105`
+
+2. **User-Agent**: Must be exactly `"PAYONE FinanceGate"`
+
+3. **Hash Signature**: Verifies MD5 hash using your Portal Key:
+
+   ```
+   MD5(portalid + aid + txid + sequencenumber + price + currency + mode + key)
+   ```
+
+4. **Credentials**: Verifies that `portalid` and `aid` match your configured settings
+
+### Notification Parameters
+
+Payone sends the following parameters (among others):
+
+- `txaction`: Transaction action (appointed, paid, cancelation, etc.)
+- `txid`: Transaction ID
+- `reference`: Your reference number
+- `sequencenumber`: Sequence number for this transaction
+- `transaction_status`: Current transaction status
+- `price`: Transaction amount
+- `balance`: Current balance
+- `receivable`: Receivable amount
+- `currency`: Currency code
+- `key`: MD5 hash for verification
+
+### Response Requirements
+
+The endpoint **must** respond with exactly `TSOK` (4 characters, no HTML):
+
+- Response time: Must be within 10 seconds
+- Response format: Plain text `TSOK`
+- No other characters allowed
+
+> ℹ️ **Note**: Even if processing fails, the endpoint must return `TSOK` to prevent Payone from retrying. The plugin handles this automatically.
+
+### Retry Mechanism
+
+If Payone doesn't receive `TSOK` within 10 seconds:
+
+- Payone will retry up to **12 times**
+- Retries occur over **48 hours**
+- First retry after ~1 hour
+- Retry intervals increase over time
+
+### Transaction Updates
+
+When a TransactionStatus notification is received:
+
+1. The plugin finds the transaction in history by `txid`
+2. Updates the transaction with new status information
+3. Stores the full notification data for reference
+4. Updates `balance`, `receivable`, and `sequencenumber` fields
+
+If the transaction is not found in history, a new entry is created.
+
+### Example Notification Flow
+
+**Scenario**: Customer completes PayPal payment
+
+1. Customer redirected to PayPal → Completes payment
+2. Payone sends TransactionStatus: `txaction=appointed`, `transaction_status=completed`
+3. Plugin receives notification → Verifies and updates transaction
+4. Plugin responds: `TSOK`
+5. Customer redirected back to your `successurl`
+6. Later, Payone sends: `txaction=paid` (payment confirmed)
+7. Plugin updates transaction status to "paid"
+
+### Testing
+
+To test TransactionStatus notifications:
+
+1. Configure the endpoint in PMI
+2. Make a test payment
+3. Check your Strapi logs for notification processing
+4. Verify transaction history is updated correctly
+
+> 📖 **Reference**: For more details, see [Payone TransactionStatus Notification Documentation](https://docs.payone.com/integration/response-handling/transactionstatus-notification)

package/admin/src/pages/utils/paymentUtils.js

@@ -89,7 +89,6 @@ export const getBaseParams = (options = {}) => {
     currency: currency.toUpperCase(),
     reference: reference || `REF-${Date.now()}`,
     customerid: finalCustomerId,
-
     firstname,
     lastname,
     street,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strapi-plugin-payone-provider",
-  "version": "5.6.9",
+  "version": "5.6.10",
   "description": "Strapi plugin for Payone payment gateway integration",
   "license": "MIT",
   "maintainers": [

package/server/controllers/payone.js

@@ -295,5 +295,23 @@ module.exports = ({ strapi }) => ({
         }
       };
     }
+  },
+
+  async handleTransactionStatus(ctx) {
+    try {
+      const notificationData = ctx.request.body || {};
+      await getPayoneService(strapi).processTransactionStatus(notificationData);
+
+      ctx.status = 200;
+      ctx.body = "TSOK";
+      ctx.type = "text/plain";
+      console.log(`[Payone TransactionStatus] Responded TSOK`);
+    } catch (error) {
+      console.log("[Payone TransactionStatus] Error handling notification:", error);
+      ctx.status = 200;
+      ctx.body = "TSOK";
+      ctx.type = "text/plain";
+    }
   }
+
 });

package/server/policies/index.js

@@ -2,5 +2,6 @@
 
 module.exports = {
   "is-auth": require("./is-auth"),
-  "is-super-admin": require("./isSuperAdmin")
+  "is-super-admin": require("./isSuperAdmin"),
+  "is-payone-notification": require("./is-payone-notification")
 };

package/server/policies/is-payone-notification.js

@@ -0,0 +1,31 @@
+"use strict";
+
+module.exports = async (policyContext, config, { strapi }) => {
+  const { request } = policyContext;
+  const userAgent = request.header["user-agent"] || request.header["User-Agent"] || "";
+  const clientIp = request.ip || request.connection?.remoteAddress || "";
+
+  if (userAgent !== "PAYONE FinanceGate") {
+    console.log(`[Payone TransactionStatus] Invalid User-Agent: ${userAgent}, IP: ${clientIp}`);
+    return false;
+  }
+
+
+  const isValidIp = (ip) => {
+    if (ip.startsWith("185.60.20.")) {
+      return true;
+    }
+
+    if (ip === "54.246.203.105") {
+      return true;
+    }
+    return false;
+  };
+
+  if (!isValidIp(clientIp)) {
+    console.log(`[Payone TransactionStatus] Invalid IP address: ${clientIp}, User-Agent: ${userAgent}`);
+    return false;
+  }
+
+  return true;
+};

package/server/routes/index.js

@@ -162,6 +162,17 @@ module.exports = {
           auth: false
         }
       },
+
+      {
+        method: "POST",
+        path: "/transaction-status",
+        handler: "payone.handleTransactionStatus",
+        config: {
+          policies: ["plugin::strapi-plugin-payone-provider.is-payone-notification"],
+          auth: false
+        }
+      },
+
     ]
   }
 };

package/server/services/payone.js

@@ -5,6 +5,7 @@ const transactionService = require("./transactionService");
 const paymentService = require("./paymentService");
 const testConnectionService = require("./testConnectionService");
 const applePayService = require("./applePayService");
+const transactionStatusService = require("./transactionStatusService");
 
 module.exports = ({ strapi }) => ({
   // Settings
@@ -59,5 +60,11 @@ module.exports = ({ strapi }) => ({
 
   async initializeApplePaySession(params) {
     return await applePayService.initializeApplePaySession(strapi, params);
+  },
+
+  // TransactionStatus Notification
+  async processTransactionStatus(notificationData) {
+    return await transactionStatusService.processTransactionStatus(strapi, notificationData);
   }
+
 });

package/server/services/transactionService.js

@@ -29,8 +29,6 @@ const logTransaction = async (strapi, transactionData) => {
       transactionData.Error?.CustomerMessage ||
       null,
     body: transactionData || null,
-    raw_request: transactionData.raw_request || null,
-    raw_response: transactionData.raw_response || transactionData,
     created_at: new Date().toISOString(),
     updated_at: new Date().toISOString()
   };
@@ -46,7 +44,7 @@ const logTransaction = async (strapi, transactionData) => {
     value: transactionHistory
   });
 
-  strapi.log.info("Transaction logged:", logEntry);
+  console.log(`Transaction logged: ${logEntry}`);
 };
 
 

package/server/services/transactionStatusService.js

@@ -0,0 +1,87 @@
+"use strict";
+
+const crypto = require("crypto");
+const { getPluginStore, getSettings } = require("./settingsService");
+
+const verifyHash = (notificationData, portalKey) => {
+  const {
+    portalid = "",
+    aid = "",
+    txid = "",
+    sequencenumber = "",
+    price = "",
+    currency = "",
+    mode = "",
+  } = notificationData;
+
+  const hashString = `${portalid}${aid}${txid}${sequencenumber}${price}${currency}${mode}${portalKey}`;
+  const expectedHash = crypto.createHash("md5").update(hashString).digest("hex");
+
+  return expectedHash.toLowerCase() === (notificationData.key || "").toLowerCase();
+};
+
+const processTransactionStatus = async (strapi, notificationData) => {
+  try {
+    const settings = await getSettings(strapi);
+    const txid = notificationData.txid;
+
+    if (!settings || !settings.key) {
+      console.log("[Payone TransactionStatus] Settings not found or key missing");
+      return;
+    }
+
+    const isValid = verifyHash(notificationData, settings.key);
+    if (!isValid) {
+      console.log(`[Payone TransactionStatus] Hash verification failed txid: ${txid}`);
+      return;
+    }
+
+    if (notificationData.portalid !== settings.portalid || notificationData.aid !== settings.aid) {
+      console.log(`[Payone TransactionStatus] Portal ID or AID mismatch txid: ${txid}`);
+      return;
+    }
+
+    const pluginStore = getPluginStore(strapi);
+    let transactionHistory = (await pluginStore.get({ key: "transactionHistory" })) || [];
+
+    const transaction = transactionHistory.find((t) => t.txid === txid || t.id === txid);
+
+    if (transaction) {
+      Object.assign(transaction, {
+        ...notificationData,
+        status: notificationData?.transaction_status,
+        txaction: notificationData?.txaction,
+        txtime: notificationData?.txtime,
+        sequencenumber: notificationData?.sequencenumber,
+        balance: notificationData?.balance,
+        receivable: notificationData?.receivable,
+        price: notificationData?.price,
+        amount: notificationData?.price ? parseFloat(notificationData?.price) * 100 : transaction?.amount,
+        userid: notificationData?.userid,
+        updated_at: new Date().toISOString(),
+        body: {
+          ...transaction?.body,
+          ...notificationData,
+          status: notificationData?.transaction_status
+        }
+      });
+
+      await pluginStore.set({
+        key: "transactionHistory",
+        value: transactionHistory,
+      });
+
+      console.log(`[Payone TransactionStatus] Successfully updated transaction txid: ${txid}`);
+    } else {
+      console.log(`[Payone TransactionStatus] Transaction ${txid} not found in history. Notification ignored.`);
+    }
+
+  } catch (error) {
+    console.log(`[Payone TransactionStatus] Error processing notification: ${error}`);
+  }
+};
+
+module.exports = {
+  verifyHash,
+  processTransactionStatus,
+};

package/server/utils/requestBuilder.js

@@ -2,6 +2,38 @@
 
 const crypto = require("crypto");
 const { normalizeCustomerId } = require("./normalize");
+const calculateKeyHash = (settings, params) => {
+  const portalKey = settings.portalKey || settings.key;
+  const portalid = String(settings.portalid || "");
+  const aid = String(settings.aid || "");
+  const mode = String(settings.mode || "test");
+
+  const requestType = params.request || "";
+
+  // For Capture and Refund operations
+  if (requestType === "capture" || requestType === "refund") {
+    const txid = String(params.txid || "");
+    const sequencenumber = String(params.sequencenumber || "");
+    const amount = String(params.amount || "");
+    const currency = String(params.currency || "EUR");
+
+    const hashString = `${portalid}${aid}${txid}${sequencenumber}${amount}${currency}${mode}${portalKey}`;
+    return crypto.createHash("md5").update(hashString).digest("hex");
+  }
+
+  // For Preauthorization and Authorization operations
+  if (requestType === "preauthorization" || requestType === "authorization") {
+    const amount = String(params.amount || "");
+    const currency = String(params.currency || "EUR");
+    const reference = String(params.reference || "");
+
+    const hashString = `${portalid}${aid}${amount}${currency}${reference}${mode}${portalKey}`;
+    return crypto.createHash("md5").update(hashString).digest("hex");
+  }
+
+  const hashString = `${portalid}${aid}${mode}${portalKey}`;
+  return crypto.createHash("md5").update(hashString).digest("hex");
+};
 
 const buildClientRequestParams = (settings, params, logger = null) => {
   const requestParams = {
@@ -14,16 +46,13 @@ const buildClientRequestParams = (settings, params, logger = null) => {
     ...params
   };
 
-  requestParams.key = crypto
-    .createHash("md5")
-    .update(settings.portalKey || settings.key)
-    .digest("hex");
-
   requestParams.customerid = normalizeCustomerId(
     requestParams.customerid,
     logger
   );
 
+  requestParams.key = calculateKeyHash(settings, requestParams);
+
   const isCreditCard = requestParams.clearingtype === "cc";
   const enable3DSecure = settings.enable3DSecure !== false;