Changeset 3772638

Timestamp:

10/29/2026 10:26:33 AM (3 days ago)

Author:

mariusmonek

Message:

• Fixed: Include basket product descriptions in payment requests for express checkout payments.
• Security: generate an idempotency token per order and reuse it for any subsequent requests if the payment was successful.
• Fixed: Ensure the webhook handler ignores payment events that are not associated with WooCommerce.
• The webhook handler updates the WooCommerce order status based on the event type.
• Include the WooCommerce order ID in the payment reference.

Location:

monek-checkout/trunk

Files:

• Blocks/Monek_Blocks.php (modified) (4 diffs)
• Monek-Checkout.php (modified) (2 diffs)
• MonekCheckoutGateway.php (modified) (8 diffs)
• assets/js/monek-embedded-checkout.js (modified) (3 diffs)
• changelog.txt (modified) (1 diff)
• readme.txt (modified) (2 diffs)
• src/Application/Checkout/CurrencyFormatter.php (modified) (1 diff)
• src/Application/Checkout/ExpressCheckoutHandler.php (modified) (1 diff)
• src/Application/Checkout/ExpressPaymentVerifier.php (modified) (1 diff)
• src/Application/Checkout/PaymentPayloadBuilder.php (modified) (3 diffs)
• src/Application/Checkout/PaymentProcessor.php (modified) (2 diffs)
• src/Application/Checkout/StandardCheckoutHandler.php (modified) (5 diffs)
• src/Application/Checkout/StoreContext.php (modified) (2 diffs)
• src/Infrastructure/WordPress/Webhook/WebhookRouteRegistrar.php (modified) (8 diffs)

monek-checkout/trunk/Blocks/Monek_Blocks.php

@@ -4 +4 @@
 
 use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;
+use Monek\Checkout\Application\Checkout\CurrencyFormatter;
+use Monek\Checkout\Application\Checkout\PaymentPayloadBuilder;
+use Monek\Checkout\Application\Checkout\StoreContext;
 
 if (! defined('ABSPATH')) {
@@ -50 +53 @@
         $sdkHandle = 'monek-checkout-sdk';
         if (! wp_script_is($sdkHandle, 'registered')) {
-            wp_register_script($sdkHandle, 'https://checkout-js.monek.com/monek-checkout.iife.js', [], null, true);
+            wp_register_script($sdkHandle, MONEK_CHECKOUT_SDK_URL, [], null, true);
         }
 
@@ -123 +126 @@
         $restNonce = function_exists('wp_create_nonce') ? wp_create_nonce('wp_rest') : '';
 
-        return [
+        $basketDescription = $this->get_basket_description();
+
+        $data = [
             'title' => $gateway ? $gateway->get_title() : __('Monek Checkout', 'monek-checkout'),
             // 'description' => $gateway ? $gateway->get_description() : __('Secure payment powered by Monek.', 'monek-checkout'),
@@ -155 +160 @@
             'customTheme' => $stylingConfiguration['customTheme'] ?? null,
         ];
+
+        if ($basketDescription) {
+            $data['basketDescription'] = $basketDescription;
+        }
+
+        return $data;
+    }
+
+    /**
+     * Builds a base64 encoded basket details from the WooCommerce cart.
+     * The express payment has no associated WooCommerce order to get basket details from.
+     */
+    private function get_basket_description(): ?string
+    {
+        if (! function_exists('WC') || ! WC()->cart || WC()->cart->is_empty()) {
+            return null;
+        }
+
+        $paymentPayloadBuilder = new PaymentPayloadBuilder(new CurrencyFormatter(), new StoreContext());
+
+        return $paymentPayloadBuilder->buildBasketFromCart(WC()->cart);
     }
 

monek-checkout/trunk/Monek-Checkout.php

@@ -5 +5 @@
  * Author: Monek Ltd
  * Author URI: https://www.monek.com
- * Version: 4.3.4
+ * Version: 4.4.0
  * Text Domain: monek-checkout
  * Requires Plugins: woocommerce
@@ -44 +44 @@
 if (! defined('MONEK_PLUGIN_URL')) {
     define('MONEK_PLUGIN_URL', plugin_dir_url(__FILE__));
+}
+
+if (! defined('MONEK_CHECKOUT_SDK_URL')) {
+    define('MONEK_CHECKOUT_SDK_URL', 'https://checkout-js.monek.com/monek-checkout.iife.js');
 }
 

monek-checkout/trunk/MonekCheckoutGateway.php

@@ -38 +38 @@
     private CurrencyFormatter $currencyFormatter;
     private StoreContext $storeContext;
+    private PaymentPayloadBuilder $paymentPayloadBuilder;
     private string $publishable_key;
     private string $secret_key;
@@ -67 +68 @@
         $this->storeContext = new StoreContext();
         $paymentPayloadBuilder = new PaymentPayloadBuilder($this->currencyFormatter, $this->storeContext);
+        $this->paymentPayloadBuilder = $paymentPayloadBuilder;
         $paymentProcessor = new PaymentProcessor(
             (string) $this->publishable_key,
@@ -81 +83 @@
             $this->currencyFormatter
         );
-        $this->standardCheckoutHandler = new StandardCheckoutHandler($paymentProcessor, $this->logger);
+        $this->standardCheckoutHandler = new StandardCheckoutHandler($paymentProcessor, $this->logger, $this->storeContext);
 
         add_action('woocommerce_update_options_payment_gateways_' . $this->id, [$this, 'process_admin_options']);
@@ -139 +141 @@
             'svix_signing_secret' => [
                 'title' => __('Webhook URL key', 'monek-checkout'),
-                'type' => 'text',
+                'type' => 'password',
                 'description' => __('Paste the signing secret for your svix endpoint.', 'monek-checkout'),
                 'default' => '',
@@ -440 +442 @@
         wp_register_script(
             $sdkHandle,
-            'https://checkout-js.monek.com/monek-checkout.iife.js',
+            MONEK_CHECKOUT_SDK_URL,
             [],
             monek_get_plugin_version(),
@@ -479 +481 @@
         }
 
+        $basketDescription = $this->buildBasketDescription($payPageOrder);
+
         $settings = [
             'gatewayId' => $this->id,
+            'pluginVersion' => monek_get_plugin_version(),
             'publishableKey' => $this->publishable_key,
             'showExpress' => ('yes' === $this->show_express),
@@ -504 +509 @@
         }
 
+        if ($basketDescription) {
+            $settings['basketDescription'] = $basketDescription;
+        }
+
         $stylingConfiguration = $this->getStylingConfiguration();
         $settings['themeMode'] = $stylingConfiguration['themeMode'];
@@ -577 +586 @@
             'state' => $order->get_billing_state(),
         ];
+    }
+
+    /**
+     * Builds a base64 encoded basket description for the SDK.
+     * Get the basket description based on the current order or cart (for ApplePay).
+     */
+    private function buildBasketDescription(?WC_Order $payPageOrder): ?string
+    {
+        if ($payPageOrder) {
+            return $this->paymentPayloadBuilder->buildBasketFromOrder($payPageOrder);
+        }
+
+        if (function_exists('WC') && WC()->cart && ! WC()->cart->is_empty()) {
+            return $this->paymentPayloadBuilder->buildBasketFromCart(WC()->cart);
+        }
+
+        return null;
     }
 

monek-checkout/trunk/assets/js/monek-embedded-checkout.js

@@ -248 +248 @@
     const version = configuration.pluginVersion || '';
     const versionPrefix = version ? `${version.replace(/\./g, '')}-` : '';
-    
+
     try {
       if (windowObject.crypto?.randomUUID) {
-        return `MNK-wc${versionPrefix}${windowObject.crypto.randomUUID()}`;
+        return `MNK-wc-${versionPrefix}${windowObject.crypto.randomUUID()}`;
       }
     } catch (error) {
@@ -259 +259 @@
     }
 
-    return `MNK-wc${versionPrefix}${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    return `MNK-wc-${versionPrefix}${Date.now()}-${Math.random().toString(36).slice(2)}`;
   }
 
@@ -492 +492 @@
     const callbacks = {
       getAmount: () => ({ minor: getOrderTotalMinor(), currency: configuration.currencyNumeric || '826' }),
-      getDescription: () => configuration.orderDescription || 'Order',
+      getDescription: () => configuration.basketDescription || configuration.orderDescription || 'Order',
       getCardholderDetails: buildCardholderDetails,
       onPaymentAuthorised: verifyExpressPayment,

monek-checkout/trunk/changelog.txt

@@ -1 +1 @@
 *** Monek Checkout Changelog ***
+
+2026-10-29 version 4.4.0
+* Fixed - Include basket product descriptions in payment requests for express checkout payments.
+* Security - Generate an idempotency token per order and reuse it for any subsequent requests if the payment was successful.
+* Fixed - Ensure the webhook handler ignores payment events that are not associated with WooCommerce.
+* Fixed - The webhook handler updates the WooCommerce order status based on the event type.
+* Added - Include the WooCommerce order ID in the payment reference.
 
 2026-09-30 version 4.3.4

monek-checkout/trunk/readme.txt

@@ -5 +5 @@
 Tested up to: 7.1
 Requires PHP: 8.3
-Stable tag: 4.3.4
+Stable tag: 4.4.0
 License: GPLv3
 License URI: https://www.gnu.org/licenses/gpl-3.0.html
@@ -72 +72 @@
 == Changelog ==
 
+= 4.4.0 =
+* Fixed: Include basket product descriptions in payment requests for express checkout payments.
+* Security: generate an idempotency token per order and reuse it for any subsequent requests if the payment was successful.
+* Fixed: Ensure the webhook handler ignores payment events that are not associated with WooCommerce.
+* The webhook handler updates the WooCommerce order status based on the event type.
+* Include the WooCommerce order ID in the payment reference.
+
 = 4.3.4 =
 * Restore PHP 8.2 compatibility.

monek-checkout/trunk/src/Application/Checkout/CurrencyFormatter.php

@@ -13 +13 @@
 
         return (int) round($amountFloat * pow(10, $decimals));
+    }
+
+    public function toMajorUnits(string $amount, string $currencyCode): string
+    {
+        $decimals = $this->getDecimals($currencyCode);
+
+        if ($decimals === 0) {
+            return $amount;
+        }
+
+        $amount = trim($amount);
+        $negative = str_starts_with($amount, '-');
+        $digits = ltrim($negative ? substr($amount, 1) : $amount, '0');
+        $digits = $digits === '' ? '0' : $digits;
+
+        $digits = str_pad($digits, $decimals + 1, '0', STR_PAD_LEFT);
+
+        $major = substr($digits, 0, -$decimals);
+        $fraction = substr($digits, -$decimals);
+
+        return ($negative ? '-' : '') . $major . '.' . $fraction;
     }
 

monek-checkout/trunk/src/Application/Checkout/ExpressCheckoutHandler.php

@@ -121 +121 @@
             $order->add_order_note('Express payment verified.');
         }
+
+        $tokenTransactionId = $this->verifier->readTokenTransactionId($claims);
+        if ($tokenTransactionId !== '') {
+            $order->update_meta_data('_express_token_transaction_id', $tokenTransactionId);
+            $order->add_order_note(sprintf('Express token transaction verified (txn: %s).', $tokenTransactionId));
+        }
     }
 

monek-checkout/trunk/src/Application/Checkout/ExpressPaymentVerifier.php

@@ -116 +116 @@
     }
 
+    public function readTokenTransactionId(array $claims): string
+    {
+        return $this->readClaim($claims, ['tokenTransactionId']);
+    }
+
     public function readMinorAmount(array $claims): ?int
     {

monek-checkout/trunk/src/Application/Checkout/PaymentPayloadBuilder.php

@@ -62 +62 @@
             }),
             'storeCardDetails' => false,
-            'idempotencyToken' => $this->storeContext->generateIdempotencyToken((int) $order->get_id()),
+            'idempotencyToken' => $this->storeContext->resolveIdempotencyToken($order),
             'source' => 'EmbeddedCheckout',
             'url' => home_url(),
-            'basketDescription' => $this->createBasketDetails($order),
+            'basketDescription' => $this->buildBasketFromOrder($order),
             'paymentReference' => $paymentReference,
             'originId' => $this->storeContext->buildOriginId(),
@@ -89 +89 @@
     }
 
-    private function createBasketDetails(WC_Order $order): string
+    public function buildBasketFromOrder(WC_Order $order): string
     {
         $items = [];
@@ -104 +104 @@
             $line_tax     = (float) $item->get_total_tax();
 
-            // Avoid division by zero
-            $unit_price = $quantity > 0 ? $line_total / $quantity : 0;
+            $items[] = $this->buildBasketItem(
+                $product->get_sku() ?: (string) $product->get_id(),
+                $item->get_name(),
+                (int) $quantity,
+                $line_total,
+                $line_tax
+            );
+        }
 
-            // Tax rate calculation (approx)
-            $tax_rate = 0;
-            if ( $line_total > 0 && $line_tax > 0 ) {
-                $tax_rate = round( ( $line_tax / $line_total ) * 100, 2 );
+        return $this->assembleBasket($items);
+    }
+
+    /**
+     * Builds the basket structure from the WooCommerce cart. This is used for express payment flow that is initiated before a WooCommerce order exists.
+     */
+    public function buildBasketFromCart(\WC_Cart $cart): string
+    {
+        $items = [];
+
+        foreach ( $cart->get_cart() as $cartItem ) {
+            $product = $cartItem['data'] ?? null;
+            if ( ! $product ) {
+                continue;
             }
 
-            $items[] = [
-                'sku'            => $product->get_sku() ?: (string) $product->get_id(),
-                'commodityCode'  => '',
-                'description'    => $item->get_name(),
-                'quantity'       => (int) $quantity,
-                'unitPrice'      => round( $unit_price, 2 ),
-                'unitOfMeasure'  => '',
-                'total'          => round( $line_total, 2 ),
-                'taxRate'        => $tax_rate,
-                'taxAmount'      => round( $line_tax, 2 ),
-            ];
+            $quantity   = (int) ($cartItem['quantity'] ?? 0);
+            $line_total = (float) ($cartItem['line_total'] ?? 0);
+            $line_tax   = (float) ($cartItem['line_tax'] ?? 0);
+
+            $items[] = $this->buildBasketItem(
+                $product->get_sku() ?: (string) $product->get_id(),
+                $product->get_name(),
+                $quantity,
+                $line_total,
+                $line_tax
+            );
         }
 
+        return $this->assembleBasket($items);
+    }
+
+    private function buildBasketItem(string $sku, string $description, int $quantity, float $lineTotal, float $lineTax): array
+    {
+        // Avoid division by zero
+        $unitPrice = $quantity > 0 ? $lineTotal / $quantity : 0;
+
+        // Tax rate calculation (approx)
+        $taxRate = 0;
+        if ( $lineTotal > 0 && $lineTax > 0 ) {
+            $taxRate = round( ( $lineTax / $lineTotal ) * 100, 2 );
+        }
+
+        return [
+            'sku'            => $sku,
+            'commodityCode'  => '',
+            'description'    => $description,
+            'quantity'       => $quantity,
+            'unitPrice'      => round( $unitPrice, 2 ),
+            'unitOfMeasure'  => '',
+            'total'          => round( $lineTotal, 2 ),
+            'taxRate'        => $taxRate,
+            'taxAmount'      => round( $lineTax, 2 ),
+        ];
+    }
+
+    private function assembleBasket(array $items): string
+    {
         $basket = [
             'taxType'   => 0,

monek-checkout/trunk/src/Application/Checkout/PaymentProcessor.php

@@ -94 +94 @@
         $authCode = $decodedBody['AuthCode'] ?? $decodedBody['authCode'] ?? null;
         $errorCode = $decodedBody['ErrorCode'] ?? $decodedBody['errorCode'] ?? null;
+        $transactionId = $decodedBody['TransactionId'] ?? $decodedBody['transactionId'] ?? null;
 
         $isSuccessful = in_array((string) $result, ['Success'], true);
@@ -102 +103 @@
             'auth_code' => $authCode ? (string) $authCode : null,
             'error_code' => $errorCode ? (string) $errorCode : null,
+            'transactionId' => is_scalar($transactionId) ? (string) $transactionId : '',
             'raw' => is_array($decodedBody) ? $decodedBody : null,
         ];

monek-checkout/trunk/src/Application/Checkout/StandardCheckoutHandler.php

@@ -12 +12 @@
     private PaymentProcessor $paymentProcessor;
     private Logger $logger;
+    private StoreContext $storeContext;
 
-    public function __construct(PaymentProcessor $paymentProcessor, Logger $logger)
+    public function __construct(PaymentProcessor $paymentProcessor, Logger $logger, StoreContext $storeContext)
     {
         $this->paymentProcessor = $paymentProcessor;
         $this->logger = $logger;
+        $this->storeContext = $storeContext;
     }
 
@@ -64 +66 @@
         $this->assertRequiredDataPresent($request);
 
+        // Generate a WooCommerce style payment ref using the order ID, or fall back to the payment reference provided.
+        $wooCommerceOrderReference = $order->get_id() ? 'WOO-ORDER-' . $order->get_id() : $request->getPaymentReference();
+
         $response = $this->paymentProcessor->process(
             $order,
@@ -69 +74 @@
             $request->getSessionIdentifier(),
             $request->getExpiry(),
-            $request->getPaymentReference()
+            $wooCommerceOrderReference
         );
 
@@ -76 +81 @@
         }
 
+        $order->update_meta_data('_monek_payment_reference', $wooCommerceOrderReference);
+        $order->update_meta_data('_monek_transaction_id', $response['transactionId'] ?? '');
+
+        $order->add_order_note(sprintf('Payment Reference: %s', $wooCommerceOrderReference));
+
         if (! $response['success']) {
+            $this->storeContext->clearIdempotencyToken($order);
             $message = $response['message'] ?: __('Payment failed. Please try again.', 'monek-checkout');
             throw new \Exception(esc_html($message));
@@ -84 +95 @@
         $order->update_meta_data('_monek_session', $request->getSessionIdentifier());
         $order->update_meta_data('_monek_result', $response['raw'] ? wp_json_encode($response['raw']) : '');
-        $order->update_meta_data('_monek_payment_reference', $request->getPaymentReference());
         $order->payment_complete();
         $order->save();

monek-checkout/trunk/src/Application/Checkout/StoreContext.php

@@ -7 +7 @@
     private const DEFAULT_COUNTRY_CODE = '826';
     private const PARTIAL_ORIGIN_ID = 'a6c921f4-8e00-4b11-99f4-';
+    private const IDEMPOTENCY_META_KEY = '_monek_idempotency_token';
 
     public function getNumericCountryCode(): string
@@ -29 +30 @@
     }
 
-    public function generateIdempotencyToken(int $orderId): string
+    public function resolveIdempotencyToken(\WC_Order $order): string
     {
+        $existing = (string) $order->get_meta(self::IDEMPOTENCY_META_KEY);
+        if ($existing !== '') {
+            return $existing;
+        }
+
         $version = monek_get_plugin_version();
-        return 'wc-' . str_replace('.', '', $version) . $orderId . '-' . wp_generate_uuid4();
+        $token   = 'wc-' . str_replace('.', '', $version) . '-' . $order->get_id() . '-' . wp_generate_uuid4();
+        $order->update_meta_data(self::IDEMPOTENCY_META_KEY, $token);
+        $order->save_meta_data();
+        return $token;
+    }
+
+    public function clearIdempotencyToken(\WC_Order $order): void
+    {
+        $order->delete_meta_data(self::IDEMPOTENCY_META_KEY);
+        $order->save_meta_data();
     }
 

monek-checkout/trunk/src/Infrastructure/WordPress/Webhook/WebhookRouteRegistrar.php

@@ -3 +3 @@
 namespace Monek\Checkout\Infrastructure\WordPress\Webhook;
 
+use Monek\Checkout\Application\Checkout\CurrencyFormatter;
 use WP_REST_Request;
 use WP_REST_Response;
@@ -17 +18 @@
     // Delay in ms between order lookup retries
     private const ORDER_LOOKUP_RETRY_DELAY_MICROSECONDS = 250000;
+
+    private const PAYMENT_REFERENCE_META_KEY = '_monek_payment_reference';
+    private const TRANSACTION_ID_META_KEY = '_monek_transaction_id';
+    private const LAST_SVIX_ID_META_KEY = '_monek_last_svix_id';
+    private const REFUND_AMOUNTS_META_KEY = '_monek_refund_amounts';
 
     public function register(): void
@@ -51 +57 @@
         }
 
-        $paymentReference = $this->extractPaymentReference($body);
-        if ($paymentReference === '') {
-            $this->log('webhook: missing paymentReference', ['body' => $body], 'warning');
-            return new WP_REST_Response(['ok' => false, 'error' => 'missing_reference'], 400);
-        }
-
-        $orderId = $this->locateOrderByPaymentReferenceWithRetry($paymentReference);
-        if (! $orderId) {
-            $this->log('webhook: order not found', ['reference' => $paymentReference], 'warning');
-            return new WP_REST_Response([
-                'ok' => true,
-                'error' => 'order_not_found',
-                'reference' => $paymentReference,
-            ], 200);
+        $eventType = $this->extractEventType($body);
+        if ($eventType === '') {
+            $this->log('webhook: missing event type - event ignored', ['fields' => array_keys($body)], 'warning');
+            return new WP_REST_Response(['ok' => true, 'status' => 'ignored', 'reason' => 'missing_event_type'], 200);
+        }
+
+        $orderId = $this->resolveOrderId($body, $eventType);
+        if ($orderId instanceof WP_REST_Response) {
+            return $orderId;
         }
 
@@ -76 +77 @@
         }
 
+        // Svix redelivers on timeouts/non-2xx; skip events we have already processed
+        $svixId = $this->getHeaderValue($request, 'svix-id');
+        if ($svixId !== '' && $order->get_meta(self::LAST_SVIX_ID_META_KEY) === $svixId) {
+            $this->log('webhook: duplicate delivery ignored', ['svix_id' => $svixId, 'order_id' => $orderId]);
+
+            return new WP_REST_Response(['ok' => true, 'status' => 'duplicate', 'order_id' => $orderId], 200);
+        }
+
+        if ($svixId !== '') {
+            $order->update_meta_data(self::LAST_SVIX_ID_META_KEY, $svixId);
+        }
         $order->update_meta_data('_monek_last_webhook', wp_json_encode($body));
 
-        $targetStatus = 'payment-confirmed';
-
-        $transactionId = $this->extractTransactionId($body);
-
-        if ($order->get_status() !== $targetStatus) {
+        return $this->handleSvixEventType($order, $body, $eventType);
+    }
+
+    // Reversals and refunds reference the original transaction id (the payment reference can change on refund)
+    // Everything else references the payment reference
+    private function resolveOrderId(array $body, string $eventType)
+    {
+        // Event types look like "reversal.success" or "refund.success"
+        $isParentLookup = strpos($eventType, 'reversal') === 0 || strpos($eventType, 'refund') === 0;
+
+        if ($isParentLookup) {
+            $keys = ['ParentReference', 'parentReference', 'parent_reference'];
+            $metaKey = self::TRANSACTION_ID_META_KEY;
+            $missing = 'missing_parent_reference';
+        } else {
+            $keys = ['PaymentReference', 'paymentReference', 'payment_reference'];
+            $metaKey = self::PAYMENT_REFERENCE_META_KEY;
+            $missing = 'missing_payment_reference';
+        }
+
+        $reference = $this->extractPaymentValue($body, $keys);
+        if ($reference === '') {
+            $this->log('webhook: ' . $missing . ' - event ignored', ['event_type' => $eventType, 'fields' => array_keys($body)], 'warning');
+
+            return new WP_REST_Response(['ok' => true, 'status' => 'ignored', 'reason' => $missing], 200);
+        }
+
+        // Only sales can race the checkout finalisation; a reversal/refund's original transaction already exists
+        $orderId = $this->locateOrderByMetaKeyWithRetry($reference, $metaKey, $isParentLookup ? 1 : self::ORDER_LOOKUP_MAX_ATTEMPTS);
+        if (! $orderId) {
+            $this->log('webhook: order not found', ['reference' => $reference, 'event_type' => $eventType], 'warning');
+
+            // 404 so Webhook service retries later in case the order is saved after the webhook event
+            return new WP_REST_Response([
+                'ok' => false,
+                'error' => 'order_not_found',
+                'reference' => $reference,
+            ], 404);
+        }
+
+        return $orderId;
+    }
+
+    // Maps a Svix event type "operation.result" to a WooCommerce order status
+    private function handleSvixEventType($order, array $body, string $eventType): WP_REST_Response
+    {
+        $parts = explode('.', $eventType, 2);
+        $operation = $parts[0];
+        $result = $parts[1] ?? '';
+
+        $targetStatus = null;
+        // Statuses a failed/referred sale must never overwrite
+        $protectedStatuses = ['payment-confirmed', 'processing', 'completed', 'refunded', 'cancelled'];
+
+        $message = $this->extractMessage($body);
+        $transactionId = $this->extractPaymentValue($body, ['CrossReference', 'crossReference', 'TxId', 'txId']);
+
+        if ($operation === 'sale' && $result === 'success') {
+            // Guard against late/out-of-order deliveries reviving a refunded or cancelled order
+            $targetStatus = in_array($order->get_status(), ['refunded', 'cancelled'], true) ? null : 'payment-confirmed';
+        } elseif ($operation === 'sale' && ($result === 'decline' || $result === 'error')) {
+            $targetStatus = in_array($order->get_status(), $protectedStatuses, true) ? null : 'failed';
+        } elseif ($operation === 'sale' && $result === 'refer') {
+            $targetStatus = in_array($order->get_status(), $protectedStatuses, true) ? null : 'on-hold';
+        } elseif ($operation === 'refund' && $result === 'success') {
+            $targetStatus = $this->isFullRefund($order, $body, $transactionId) ? 'refunded' : null;
+        } elseif ($operation === 'reversal' && $result === 'success') {
+            $targetStatus = 'cancelled';
+        }
+
+        if ($targetStatus === null) {
+            $order->add_order_note(sprintf(
+                'Monek webhook %s received; order status left unchanged (%s).%s',
+                $eventType,
+                $order->get_status(),
+                $message !== '' ? ' Message: ' . $message : ''
+            ));
+            $status = 'unchanged';
+        } elseif ($order->get_status() === $targetStatus) {
+            $order->add_order_note(sprintf('Monek webhook %s received (already %s).', $eventType, $targetStatus));
+            $status = 'unchanged';
+        } else {
             $order->update_status(
                 $targetStatus,
-                sprintf('Webhook set status to %s (ref: %s).', $targetStatus, $paymentReference)
+                sprintf(
+                    'Monek webhook %s set status to %s.%s',
+                    $eventType,
+                    $targetStatus,
+                    $message !== '' ? ' Message: ' . $message : ''
+                )
             );
 
             if ($transactionId !== '') {
-                $order->add_order_note(sprintf('Monek Transaction ID: %s', $transactionId));
-            }
-        } else {
-            $order->add_order_note(sprintf('Webhook ping received (already %s). Ref: %s', $targetStatus, $paymentReference));
+
+                $labels = [
+                    'cancelled' => 'Monek reversal Transaction ID',
+                    'refunded'  => 'Monek refund Transaction ID',
+                ];
+                $label = isset($labels[$targetStatus]) ? $labels[$targetStatus] : 'Monek Transaction ID';
+
+                $order->add_order_note(sprintf('%s: %s', $label, $transactionId));
+            }
+            $status = 'updated';
         }
 
         $order->save();
 
-        $this->log('webhook: status updated', [
-            'reference' => $paymentReference,
-            'order_id' => $orderId,
-            'status' => $order->get_status(),
+        $this->log('webhook: svix event handled', [
+            'order_id' => $order->get_id(),
+            'transaction_id' => $transactionId,
+            'event_type' => $eventType,
+            'result' => $status,
+            'order_status' => $order->get_status(),
         ]);
 
+        // Always 200 so svix does not retry non-confirming events
         return new WP_REST_Response([
             'ok' => true,
-            'reference' => $paymentReference,
-            'order_id' => $orderId,
-            'status' => $order->get_status(),
+            'status' => $status,
+            'event_type' => $eventType,
+            'order_id' => $order->get_id(),
+            'transaction_id' => $transactionId,
+            'order_status' => $order->get_status(),
+            'message' => $message
         ], 200);
     }
 
-    private function extractTransactionId(array $body): string
-    {
-        if (isset($body['crossReference'])) {
-            return (string) $body['crossReference'];
-        }
-
-        if (isset($body['Data']['CrossReference'])) {
-            return (string) $body['Data']['CrossReference'];
-        }
-
-        if (isset($body['TxId'])) {
-            return (string) $body['TxId'];
-        }
-
-        if (isset($body['txId'])) {
-            return (string) $body['txId'];
-        }
-
-        return '';
-    }
-
-    private function extractPaymentReference(array $body): string
-    {
-        if (isset($body['paymentReference'])) {
-            return (string) $body['paymentReference'];
-        }
-
-        if (isset($body['Data']['PaymentReference'])) {
-            return (string) $body['Data']['PaymentReference'];
-        }
-
-        if (isset($body['reference'])) {
-            return (string) $body['reference'];
+    private function extractEventType(array $body): string
+    {
+        foreach (['EventType', 'eventType'] as $key) {
+            $value = $body[$key] ?? null;
+            if (is_scalar($value) && trim((string) $value) !== '') {
+                return strtolower(trim((string) $value));
+            }
+        }
+
+        // No event type:  fall back to ResponseCode ("00" = approved, anything else = declined)
+        $responseCode = $this->extractResponseCode($body);
+        if ($responseCode === '') {
+            return '';
+        }
+
+        return $this->inferOperation($body) . ($responseCode === '00' ? '.success' : '.decline');
+    }
+
+    // Infers sale/refund/reversal from MessageType
+    private function inferOperation(array $body): string
+    {
+        $messageType = $body['Data']['MessageType'] ?? $body['messageType'] ?? '';
+        $messageType = is_scalar($messageType) ? strtoupper((string) $messageType) : '';
+
+        if (strpos($messageType, 'REFUND') !== false) {
+            return 'refund';
+        }
+
+        if (strpos($messageType, 'REVERSAL') !== false || strpos($messageType, 'VOID') !== false) {
+            return 'reversal';
+        }
+
+        return 'sale';
+    }
+
+    private function isFullRefund($order, array $body, string $transactionId): bool
+    {
+        $amount = $body['Data']['Amount'] ?? $body['amount'] ?? null;
+        if (! is_scalar($amount) || ! is_numeric($amount)) {
+            return false;
+        }
+
+        $orderMinor = (new CurrencyFormatter())->toMinorUnits($order->get_total(), (string) $order->get_currency());
+
+        $totalRefunded = $this->saveRefundAmount($order, (int) $amount, $transactionId);
+
+        $fullRefund = $totalRefunded >= $orderMinor;
+
+        if (! $fullRefund) {
+            $formatter = new CurrencyFormatter();
+            $currency = (string) $order->get_currency();
+            $eventMajor = $formatter->toMajorUnits((string) $amount, $currency);
+            $totalMajor = $formatter->toMajorUnits((string) $totalRefunded, $currency);
+
+            $order->add_order_note(sprintf(
+                'Partial refund of %s (total refunded: %s); Monek refund Transaction ID: %s',
+                $eventMajor,
+                $totalMajor,
+                $transactionId !== '' ? $transactionId : 'NONE'
+            ));
+        }
+
+        return $fullRefund;
+    }
+
+    // Stores the refund amount (minor units) in order meta and returns the total refunded
+    // Keyed by transaction ID so redelivered webhooks are not counted twice
+    private function saveRefundAmount($order, int $amountMinor, string $transactionId): int
+    {
+        $refunds = $order->get_meta(self::REFUND_AMOUNTS_META_KEY, true);
+        $refunds = is_array($refunds) ? $refunds : [];
+
+        if ($transactionId !== '') {
+            $refunds[$transactionId] = $amountMinor;
+        } else {
+            $refunds[] = $amountMinor;
+        }
+
+        $order->update_meta_data(self::REFUND_AMOUNTS_META_KEY, $refunds);
+
+        return (int) array_sum(array_map('intval', $refunds));
+    }
+
+    private function extractResponseCode(array $body): string
+    {
+        $code = $body['Data']['ResponseCode'] ?? $body['responseCode'] ?? '';
+
+        return is_scalar($code) ? trim((string) $code) : '';
+    }
+
+    private function extractMessage(array $body): string
+    {
+        $message = $body['Data']['Message'] ?? $body['message'] ?? '';
+
+        return is_scalar($message) ? trim((string) $message) : '';
+    }
+
+    private function extractPaymentValue(array $body, array $keys): string
+    {
+        $data = isset($body['Data']) && is_array($body['Data']) ? $body['Data'] : [];
+
+        foreach ([$body, $data] as $source) {
+            foreach ($keys as $key) {
+                if (isset($source[$key]) && is_scalar($source[$key]) && trim((string) $source[$key]) !== '') {
+                    return trim((string) $source[$key]);
+                }
+            }
         }
 
@@ -155 +335 @@
      * the async webhook delivery).
      */
-    private function locateOrderByPaymentReferenceWithRetry(string $paymentReference): ?int
-    {
-        for ($attempt = 1; $attempt <= self::ORDER_LOOKUP_MAX_ATTEMPTS; $attempt++) {
-            $orderId = $this->locateOrderByPaymentReference($paymentReference);
+    private function locateOrderByMetaKeyWithRetry(string $ref, string $metaKey, int $maxAttempts = self::ORDER_LOOKUP_MAX_ATTEMPTS): ?int
+    {
+        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
+
+            $orderId = $this->locateOrderByReference($ref, $metaKey);
             if ($orderId) {
                 if ($attempt > 1) {
                     $this->log('webhook: order found after retry', [
-                        'reference' => $paymentReference,
+                        'reference' => $ref,
                         'attempt' => $attempt,
                     ]);
@@ -170 +351 @@
             }
 
-            if ($attempt < self::ORDER_LOOKUP_MAX_ATTEMPTS) {
+            if ($attempt < $maxAttempts) {
                 usleep(self::ORDER_LOOKUP_RETRY_DELAY_MICROSECONDS);
             }
@@ -178 +359 @@
     }
 
-    private function locateOrderByPaymentReference(string $paymentReference): ?int
+    private function locateOrderByReference(string $ref, string $metaKey): ?int
     {
         if (! function_exists('wc_get_orders')) {
@@ -187 +368 @@
             'limit' => 1,
             'return' => 'ids',
-            'meta_key' => '_monek_payment_reference',
-            'meta_value' => $paymentReference,
+            'meta_key' => $metaKey,
+            'meta_value' => $ref,
             'orderby' => 'date',
             'order' => 'DESC',