@salla.sa/applepay 3.0.0-beta.1 → 3.0.0

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@salla.sa/applepay",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0",
   "description": "Salla Apple Pay light",
   "main": "dist/app.js",
+  "scripts": {
+    "watch": "echo \"There is no watch!\"",
+    "build": "echo \"There is no build!\"",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/SallaApp/twilight.git"
@@ -21,9 +26,5 @@
   "dependencies": {
     "axios": "^1.10.0"
   },
-  "scripts": {
-    "watch": "echo \"There is no watch!\"",
-    "build": "echo \"There is no build!\"",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
-}
+  "gitHead": "43f7a57e278a226a3e1f77924f9da8f10c7e49ba"
+}

package/src/apple-pay-support.d.ts

@@ -0,0 +1,24 @@
+export declare const APPLE_PAY_METHOD: string;
+
+export declare function applePayMerchantId(): string | null;
+
+export declare function buildApplePayMethodData(opts: {
+  version: number;
+  merchantIdentifier: string;
+  supportedNetworks: string[];
+  countryCode: string;
+}): PaymentMethodData[];
+
+export declare function isApplePayHostedRedirect(): boolean;
+
+export declare function ensureApplePaySdk(): Promise<void>;
+
+export declare function normalizeApplePayNetworks(raw: string[] | Record<string, string> | null | undefined): string[];
+
+export declare function applePayNetworks(): string[];
+
+export declare function resolveApplePayNetworks(
+  networks: string[] | Record<string, string> | null | undefined,
+): string[];
+
+export declare function canCompleteApplePay(currency?: string, networks?: string[] | null): Promise<boolean>;

package/src/apple-pay-support.js

@@ -0,0 +1,187 @@
+/**
+ * Shared Apple Pay support helpers: SDK loading, capability detection, merchant
+ * identifier resolution, and Payment Request method-data construction.
+ *
+ * Lives in @salla.sa/applepay (not a theme) because it is Apple Pay domain
+ * logic and is consumed by every Apple Pay entry point — the storefront
+ * components (salla-quick-buy, salla-add-product-button) and the shared
+ * SallaApplePay session in ./index.js.
+ *
+ * Apple Pay runs through two flows:
+ *   - Native (Safari / Apple devices)      → window.ApplePaySession
+ *   - Payment Request API (other browsers) → Apple's "Scan Code with iPhone"
+ *     QR sheet, which requires Apple's JS SDK to be *loaded and registered*
+ *     before PaymentRequest.canMakePayment() reports the method as available.
+ */
+
+export const APPLE_PAY_METHOD = 'https://apple.com/apple-pay';
+const APPLE_PAY_SDK_ID = 'apple-pay-sdk';
+const APPLE_PAY_SDK_SRC = 'https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js';
+
+let sdkPromise = null;
+
+/**
+ * Salla-native Apple merchant identifier, sourced from store settings. Returns
+ * null when the store has no Apple Pay merchant configured — callers treat that
+ * absence as the guard and skip Apple Pay entirely (no hardcoded fallback).
+ * @returns {string|null}
+ */
+export function applePayMerchantId() {
+  return salla?.config?.get?.('store.settings.buy_now.merchant_identifier') || null;
+}
+
+/**
+ * Whether the store's Apple Pay is a hosted redirect rather than a native sheet.
+ *
+ * MyFatoorah Apple Pay without S2S has no native flow: the checkout page hands off as a
+ * credit_card redirect to MyFatoorah's hosted page. The buy-now surfaces (PDP, sticky bar)
+ * have no redirect path, so they must not offer an Apple Pay button at all.
+ *
+ * The backend publishes this as a single boolean (`ApplePayFeature::isHostedRedirect`).
+ * Compared with `=== true` on purpose: against a backend that predates the field the key is
+ * absent, so this returns false and every surface keeps its current behaviour. That is what
+ * makes the storefront half safe to ship independently of the backend half.
+ * @returns {boolean}
+ */
+export function isApplePayHostedRedirect() {
+  return salla?.config?.get?.('store.settings.buy_now.hostedRedirect') === true;
+}
+
+/**
+ * Build the W3C Payment Request `methodData` for the Apple Pay method. Callers
+ * supply the values (the probe reads them from config; the live session reads
+ * them from the transaction detail), this owns the constant scaffold so the two
+ * can't drift apart.
+ * @param {{ version: number, merchantIdentifier: string, supportedNetworks: string[], countryCode: string }} opts
+ * @returns {PaymentMethodData[]}
+ */
+export function buildApplePayMethodData({ version, merchantIdentifier, supportedNetworks, countryCode }) {
+  return [{
+    supportedMethods: APPLE_PAY_METHOD,
+    data: {
+      version,
+      merchantIdentifier,
+      merchantCapabilities: ['supports3DS'],
+      supportedNetworks,
+      countryCode,
+    },
+  }];
+}
+
+/**
+ * Inject Apple's Pay JS SDK (`1.latest` ships the cross-browser / QR support)
+ * and resolve once it has loaded. Idempotent: a second call reuses the same
+ * in-flight promise and never appends a second <script>. Resolves (rather than
+ * rejects) on load error so a failed CDN fetch simply falls back to "no QR".
+ * @returns {Promise<void>}
+ */
+export function ensureApplePaySdk() {
+  if (typeof document === 'undefined') return Promise.resolve();
+
+  if (sdkPromise) return sdkPromise;
+
+  const existing = document.getElementById(APPLE_PAY_SDK_ID);
+  if (existing) {
+    // Script already in the DOM (e.g. added before this refactor). We can't know
+    // if it finished loading, so resolve immediately — the native/PaymentRequest
+    // probe will just report unavailable until the browser registers the method.
+    sdkPromise = Promise.resolve();
+    return sdkPromise;
+  }
+
+  sdkPromise = new Promise((resolve) => {
+    const script = document.createElement('script');
+    script.src = APPLE_PAY_SDK_SRC;
+    script.setAttribute('id', APPLE_PAY_SDK_ID);
+    script.async = true;
+    script.onload = () => resolve();
+    script.onerror = () => resolve();
+    document.body.appendChild(script);
+  });
+
+  return sdkPromise;
+}
+
+/**
+ * Coerce a networks payload into an array. PHP serializes the list as an object when the
+ * array keys are non-sequential, so both shapes arrive.
+ *
+ * @param {string[]|Object|null|undefined} raw
+ * @returns {string[]}
+ */
+export function normalizeApplePayNetworks(raw) {
+  if (Array.isArray(raw)) return [...raw];
+  if (raw && typeof raw === 'object') return Object.values(raw);
+
+  return [];
+}
+
+/**
+ * The store's buy-now networks from config.
+ *
+ * @returns {string[]}
+ */
+export function applePayNetworks() {
+  return normalizeApplePayNetworks(
+    salla?.config?.get?.('store.settings.buy_now.supportedNetworks')
+      || salla?.config?.get?.('store.settings.buy_now.networks'),
+  );
+}
+
+/**
+ * The networks for this attempt. `null`/`undefined` means "not supplied" and defers to config;
+ * an array — empty included — is the backend's answer and is used as-is.
+ *
+ * @param {string[]|Object|null|undefined} networks
+ * @returns {string[]}
+ */
+export function resolveApplePayNetworks(networks) {
+  return networks == null ? applePayNetworks() : normalizeApplePayNetworks(networks);
+}
+
+/**
+ * Whether Apple Pay can be completed in the current browser: natively
+ * (Safari / Apple devices) or via the Payment Request API (non-Safari browsers
+ * / non-Apple devices → QR-code fallback).
+ *
+ * For the QR path this awaits the SDK before probing, so callers get a stable
+ * answer on first load instead of racing the async script fetch.
+ * @param {string} [currency]
+ * @param {string[]} [networks] The backend's list; null/undefined defers to the buy-now config.
+ * @returns {Promise<boolean>}
+ */
+export async function canCompleteApplePay(currency = 'SAR', networks = null) {
+  const supportedNetworks = resolveApplePayNetworks(networks);
+
+  // Nothing to charge with — checked before the native probe, which would report "available"
+  // and only fail after the shopper taps pay.
+  if (!supportedNetworks.length) return false;
+
+  try {
+    if (window.ApplePaySession?.canMakePayments?.()) return true;
+  } catch (e) { /* not supported natively */ }
+
+  if (typeof window === 'undefined' || !window.PaymentRequest) return false;
+
+  // QR path only: it can't validate the merchant without a merchant identifier,
+  // so treat a missing config key as the guard. Native (above) is unaffected —
+  // it never uses the client-side merchant id.
+  if (!applePayMerchantId()) return false;
+
+  await ensureApplePaySdk();
+
+  try {
+    const request = new PaymentRequest(
+      buildApplePayMethodData({
+        version: 3,
+        merchantIdentifier: applePayMerchantId(),
+        supportedNetworks,
+        countryCode: salla?.config?.get?.('store.store_country') || 'SA',
+      }),
+      { total: { label: 'Salla', amount: { currency: currency || 'SAR', value: '0.00' } } },
+    );
+    return await request.canMakePayment();
+  } catch (e) {
+    return false;
+  }
+}

package/src/http.js

@@ -1,7 +1,12 @@
 import axios from 'axios'
 
+function setBaseCurrencyHeader() {
+    axios.defaults.headers.common.currency = salla?.config?.get?.('user.currency_code');
+}
+
 export default {
     request(method, url, data, successCb = null, errorCb = null) {
+        setBaseCurrencyHeader();
         return axios
             .request({url, data, method: method.toLowerCase(), responseType: 'json'})
             .then(successCb)
@@ -10,6 +15,7 @@ export default {
 
     get(url, successCb = null, errorCb = null, data) {
         // return this.request('get', url, data, successCb, errorCb);
+        setBaseCurrencyHeader();
         return axios
             .get(url, {params: data})
             .then(successCb)
@@ -41,10 +47,12 @@ export default {
             /**
              * @deprecated to support legacy themes
              */
+            setBaseCurrencyHeader();
             $.ajax({
                 url: url,
                 method: method.toUpperCase(),
                 data: payload,
+                headers: { currency: axios.defaults.headers.common.currency },
                 async: false,
                 success: function ({data}) {
                     return resolve(data);

package/src/index.js

@@ -1,6 +1,7 @@
 import http from './http';
 import DetectOS from './DetectOS';
 import { mutateShippingContact } from './utils';
+import { resolveApplePayNetworks } from './apple-pay-support';
 
 // SSR-safe: only access window in browser environment
 if (typeof window !== 'undefined') {
@@ -8,6 +9,19 @@ if (typeof window !== 'undefined') {
   window.Salla.Payments = window.Salla.Payments || {};
 }
 
+// Apple Pay method identifier for the W3C Payment Request API.
+const APPLE_PAY_METHOD = 'https://apple.com/apple-pay';
+
+// Captured at module load, before the Apple Pay SDK is injected: real Safari /
+// Apple devices expose `ApplePaySession` natively, whereas non-Safari browsers
+// only get it once the SDK loads. Keeps native-vs-PaymentRequest routing stable.
+const HAS_NATIVE_APPLE_PAY = typeof window !== 'undefined' && !!window.ApplePaySession;
+
+// Shown when the backend offers no usable network. twilight can ship ahead of Languages-Module,
+// so fall through to `payment_failed` while the key is missing — never a hardcoded sentence.
+const NO_SUPPORTED_NETWORK_KEY = 'pages.checkout.apple_pay_no_supported_network';
+const NO_SUPPORTED_NETWORK_FALLBACK_KEY = 'pages.checkout.payment_failed';
+
 /**
  * Full Example
  *
@@ -51,6 +65,11 @@ const SallaApplePay = typeof window !== 'undefined' ? {
     countryCode: null,
     totals: [],
     shippingCompany: null,
+    // Set true once onCancel has fired for the current transaction, so the
+    // QR (PaymentRequest) dismissal catch can notify on a plain sheet-close
+    // without double-firing when a prior handler (e.g. merchant validation)
+    // already routed through onCancel. Reset at the start of each transaction.
+    canceled: false,
     init: function () {
         document.removeEventListener('payments::apple-pay.start-transaction', SallaApplePay.startSession);
         Salla.event.addEventListener('payments::apple-pay.start-transaction', SallaApplePay.startSession);
@@ -113,19 +132,71 @@ const SallaApplePay = typeof window !== 'undefined' ? {
         return SallaApplePay.detail?.requiredShippingContactFields?.includes('postalAddress');
     },
 
+    /**
+     * Whether the native Apple Pay flow (Safari / Apple devices) can run. Gated
+     * on the module-load capture so the SDK loading later can't flip a
+     * non-Safari browser into the native path.
+     */
+    canUseNative: function () {
+        if (!HAS_NATIVE_APPLE_PAY) {
+            return false;
+        }
+        try {
+            return ApplePaySession.canMakePayments();
+        } catch (e) {
+            return false;
+        }
+    },
+
+    // Sourced from config (via the transaction detail). No fallback: a missing
+    // identifier means Apple Pay isn't configured for this store, and callers
+    // treat that null as the guard to skip Apple Pay.
+    getMerchantIdentifier: function () {
+        return (SallaApplePay.detail && SallaApplePay.detail.merchantIdentifier) || null;
+    },
+
     startSession: async function (event) {
 
         SallaApplePay.detail = event.detail || event;
 
+        // Fresh transaction → clear any cancel flag from a previous attempt.
+        SallaApplePay.canceled = false;
+
+        // Analytics latches — one Submitted and one Succeeded per attempt, and
+        // at most one Failed, however many callbacks fire.
+        SallaApplePay._submittedTracked = false;
+        SallaApplePay._failureTracked = false;
+        SallaApplePay._succeededTracked = false;
+
+        // The cart belongs to the attempt, not to the singleton. The mini embed
+        // supplies one up front; on the PDP it stays null until checkout/mini
+        // answers during merchant validation. Without this a second attempt
+        // reports — and submits to — the previous attempt's cart.
+        SallaApplePay.id = SallaApplePay.detail?.cartId || null;
+
         salla.log('🍏 Pay: payments::apple-pay.start-transaction', SallaApplePay.detail);
 
         SallaApplePay.initDefault();
 
+        // Native (Safari / Apple devices) → classic ApplePaySession. Otherwise
+        // (non-Safari / non-Apple device) → Payment Request API, which renders
+        // Apple's "Scan Code with iPhone" QR sheet.
+        if (!SallaApplePay.canUseNative()) {
+            return SallaApplePay.startPaymentRequestSession(event);
+        }
+
+        return SallaApplePay.startNativeSession(event);
+    },
+
+    startNativeSession: async function (event) {
+
         let version = SallaApplePay.getApplePaySessionVersion();
-        let supportedNetworks = SallaApplePay.detail.supportedNetworks || ['masterCard', 'visa'];
+        // The backend resolves this per shopper, so it goes to Apple verbatim. Adding mada back
+        // here is what let a shopper authorize with Face ID and only then be refused.
+        let supportedNetworks = resolveApplePayNetworks(SallaApplePay.detail.supportedNetworks);
 
-        if (version === 5) {
-            supportedNetworks.push('mada');
+        if (!supportedNetworks.length) {
+            return SallaApplePay.abandonNoSupportedNetwork();
         }
 
         SallaApplePay.request = {
@@ -163,8 +234,17 @@ const SallaApplePay = typeof window !== 'undefined' ? {
             skipBegin = SallaApplePay.detail.onStartedSession(SallaApplePay.session);
         }
         if (!skipBegin) {
-            SallaApplePay.session.begin();
+            try {
+                SallaApplePay.session.begin();
+            } catch (error) {
+                salla.logger.error('🍏 Pay: session.begin() failed', error);
+                SallaApplePay.trackPaymentFailed('client', 'APPLE_PAY_PRESENTATION_FAILED', error?.message || '');
+                SallaApplePay.detail.onError(salla.lang.get('pages.checkout.payment_failed'));
+                Salla.event.createAndDispatch('payments::apple-pay.canceled', {});
+            }
         }
+        // skipBegin path: the caller begins later — onValidateMerchant fires
+        // once the sheet actually opens and emits the (latched) Submitted.
     },
     onPaymentMethodSelected: async (event) => {
         salla.logger.log('🍏 Pay: onPaymentMethodSelected', event);
@@ -247,7 +327,29 @@ const SallaApplePay = typeof window !== 'undefined' ? {
         });
     },
 
+    /**
+     * Give up before the sheet opens: the backend left no usable network.
+     *
+     * Routed through onCancel so the host gets the same terminal signals as a dismissal and the
+     * button recovers. trackPaymentFailed self-gates on Payment Submitted, so the funnel is safe.
+     */
+    abandonNoSupportedNetwork: () => {
+        salla.logger.error('🍏 Pay: no supported network for this shopper — Apple Pay not offered');
+
+        const message = salla?.lang?.get?.(NO_SUPPORTED_NETWORK_KEY);
+        const resolved = !message || message === NO_SUPPORTED_NETWORK_KEY
+            ? salla?.lang?.get?.(NO_SUPPORTED_NETWORK_FALLBACK_KEY)
+            : message;
+
+        SallaApplePay.onCancel({}, resolved || null);
+    },
+
     onCancel: (event = {}, message = null) => {
+        SallaApplePay.canceled = true;
+        // Sheet opened (Payment Submitted already fired) but the attempt ended
+        // without authorization — dismissal, abort, or validation failure.
+        // Latched: a server rejection tracked earlier absorbs this call.
+        SallaApplePay.trackPaymentFailed('client', 'APPLE_PAY_SESSION_CANCELED', message || '');
         SallaApplePay.detail.onError(message || salla.lang.get('pages.checkout.payment_failed'));
         Salla.event.createAndDispatch('payments::apple-pay.canceled', event);
     },
@@ -309,11 +411,15 @@ const SallaApplePay = typeof window !== 'undefined' ? {
         }
 
         Salla.event.dispatch('payments::apple-pay.authorized.init', event);
+        // The shopper has authorised with Face ID / Touch ID and the token is
+        // about to go to the gateway — this is the submission, not the tap.
+        SallaApplePay.trackPaymentSubmitted();
         http.post(SallaApplePay.detail.authorized.url.replace('{id}', SallaApplePay.id), {
             payment_method: 'apple_pay',
             applepay_token: JSON.stringify(event.payment)
         }, ({ data }) => {
             Salla.event.dispatch('payments::apple-pay.authorized.success', data);
+            SallaApplePay.trackPaymentSucceeded(data);
 
             if (typeof SallaApplePay.detail.authorized.onSuccess === 'function') {
                 SallaApplePay.detail.authorized.onSuccess(data);
@@ -325,6 +431,11 @@ const SallaApplePay = typeof window !== 'undefined' ? {
             let response = error?.response;
 
             Salla.event.dispatch('payments::apple-pay.authorized.failed', response);
+            // Backend rejected the token — latch set so the cancel callback
+            // following the failure UI can't emit a second Failed.
+            SallaApplePay.trackPaymentFailed('server',
+                response?.data?.error?.code || 'APPLE_PAY_FAILED',
+                response?.data?.error?.message || '');
 
             if (typeof SallaApplePay.detail.authorized.onFailed === 'function') {
                 SallaApplePay.detail.authorized.onFailed(response);
@@ -464,6 +575,477 @@ const SallaApplePay = typeof window !== 'undefined' ? {
         }
     },
 
+    /* -------------------------------------------------------------------------
+     * Payment Request API flow (non-Safari browsers / non-Apple devices).
+     * Apple renders the "Scan Code with iPhone" QR sheet. Reuses the same
+     * backend endpoints (validate / address / shipping / recalculate / submit)
+     * as the native flow; only the sheet-completion model differs
+     * (event.updateWith / response.complete instead of session.completeXxx).
+     * ---------------------------------------------------------------------- */
+
+    paymentRequest: null,
+    paymentResponse: null,
+
+    getCurrency: () => SallaApplePay.detail.currency || 'SAR',
+
+    prAmount: (value) => ({ currency: SallaApplePay.getCurrency(), value: String(value) }),
+
+    prTotal: () => {
+        const total = SallaApplePay.prepareTotal();
+        return { label: total.label, amount: SallaApplePay.prAmount(total.amount) };
+    },
+
+    prDisplayItems: () => SallaApplePay.prepareLineItems().map(item => ({
+        label: item.label,
+        amount: SallaApplePay.prAmount(item.amount),
+    })),
+
+    prShippingOptions: (selectedId = null) => {
+        const options = SallaApplePay.mappingShippingMethods(SallaApplePay.shipping_methods || []);
+        return options.map((option, index) => ({
+            id: option.identifier,
+            label: option.label,
+            amount: SallaApplePay.prAmount(option.amount),
+            selected: selectedId ? option.identifier === selectedId : index === 0,
+        }));
+    },
+
+    prContactOptions: () => {
+        const fields = SallaApplePay.detail.requiredShippingContactFields || [];
+        return {
+            requestPayerName: fields.includes('name'),
+            requestPayerEmail: fields.includes('email'),
+            requestPayerPhone: fields.includes('phone'),
+            requestShipping: fields.includes('postalAddress'),
+            shippingType: 'shipping',
+        };
+    },
+
+    startPaymentRequestSession: async function () {
+        // No merchant identifier in config → Apple Pay isn't set up for this
+        // store; bail rather than open a QR sheet that can't be validated.
+        const merchantIdentifier = SallaApplePay.getMerchantIdentifier();
+        if (!merchantIdentifier) {
+            salla.logger.error('🍏 Pay: missing merchant identifier — skipping QR Apple Pay');
+            return;
+        }
+
+        const version = SallaApplePay.getApplePaySessionVersion();
+        // Same contract as the native flow. resolveApplePayNetworks also handles the
+        // object-shaped payload, which the old spread would have thrown on.
+        const supportedNetworks = resolveApplePayNetworks(SallaApplePay.detail.supportedNetworks);
+
+        if (!supportedNetworks.length) {
+            return SallaApplePay.abandonNoSupportedNetwork();
+        }
+
+        const methodData = [{
+            supportedMethods: APPLE_PAY_METHOD,
+            data: {
+                version,
+                merchantIdentifier,
+                merchantCapabilities: ['supports3DS'],
+                supportedNetworks,
+                countryCode: SallaApplePay.detail.countryCode || 'SA',
+            },
+        }];
+
+        const requiresShipping = SallaApplePay.isPhysical();
+
+        const details = {
+            total: SallaApplePay.prTotal(),
+            displayItems: SallaApplePay.prDisplayItems(),
+        };
+        if (requiresShipping) {
+            details.shippingOptions = SallaApplePay.prShippingOptions();
+        }
+
+        let request;
+        try {
+            request = new PaymentRequest(methodData, details, SallaApplePay.prContactOptions());
+        } catch (error) {
+            salla.logger.error('🍏 Pay: Failed to create PaymentRequest', error);
+            SallaApplePay.detail.onError(salla.lang.get('pages.checkout.payment_failed'));
+            return;
+        }
+
+        SallaApplePay.paymentRequest = request;
+
+        request.onmerchantvalidation = (event) => {
+            event.complete(SallaApplePay.prValidateMerchant(event));
+        };
+
+        if (requiresShipping) {
+            request.onshippingaddresschange = (event) => {
+                event.updateWith(SallaApplePay.prShippingAddressChange(request));
+            };
+            request.onshippingoptionchange = (event) => {
+                event.updateWith(SallaApplePay.prShippingOptionChange(request));
+            };
+        }
+
+        // Showing the sheet is the QR equivalent of ApplePaySession.begin(): it
+        // must run inside the user gesture (transient activation). Wrapped so the
+        // order-options deferral can drive it — the caller either calls begin()
+        // itself (no options → open the QR sheet now) or discards this request
+        // and the modal's own Apple Pay button starts a fresh one (options found).
+        const beginShow = async () => {
+            // The QR sheet is browser chrome (fixed, top layer) that overlays the
+            // page. Signal open/closed so hosts embedding Apple Pay (e.g. the
+            // mini-checkout modal in an iframe) can hide UI — like their own close
+            // button — that would otherwise collide with the sheet.
+            Salla.event.dispatch('payments::apple-pay.sheet-opened');
+            try {
+                const response = await request.show();
+                SallaApplePay.paymentResponse = response;
+                await SallaApplePay.prPaymentAuthorized(response);
+            } catch (error) {
+                // AbortError → the shopper dismissed the sheet / QR, or merchant
+                // validation rejected. Mirror the native oncancel path so hosts
+                // listening for payments::apple-pay.canceled (to reset checkout UI)
+                // still get notified on a plain dismissal. The `canceled` guard
+                // skips the double-fire when validation already routed through
+                // onCancel via validateMerchant.onFailed.
+                salla.logger.log('🍏 Pay: PaymentRequest closed', error);
+                if (error?.name === 'AbortError' && !SallaApplePay.canceled) {
+                    SallaApplePay.onCancel({});
+                }
+            } finally {
+                SallaApplePay.paymentRequest = null;
+                SallaApplePay.paymentResponse = null;
+                Salla.event.dispatch('payments::apple-pay.sheet-closed');
+            }
+        };
+
+        // Mirror the native path (startNativeSession): expose a hook between
+        // request creation and show(). Returning truthy skips the immediate
+        // show() so the order-options modal can open first. Same shim contract
+        // as native — the caller only needs `.begin()`.
+        let skipBegin;
+        if (typeof SallaApplePay.detail.onStartedSession === 'function') {
+            skipBegin = SallaApplePay.detail.onStartedSession({ begin: beginShow });
+        }
+        if (!skipBegin) {
+            await beginShow();
+        }
+    },
+
+    /** Merchant validation — resolves the promise passed to event.complete(). */
+    prValidateMerchant: async function (event) {
+        Salla.event.dispatch('payments::apple-pay.validate-merchant.init', event);
+        try {
+            const { data } = await http.post(
+                SallaApplePay.detail.validateMerchant.url.replace('{id}', SallaApplePay.id),
+                { validation_url: event.validationURL }
+            );
+
+            // The BE can return HTTP 200 while Apple actually rejected the session
+            // (e.g. statusCode 417 "not a registered merchant in WWDR"), with the
+            // real session under data.data. A valid Apple session always carries a
+            // merchantSessionIdentifier; its absence means validation failed. Without
+            // this the QR sheet just closes silently — notify the shopper and abort.
+            if (!data?.data?.merchantSessionIdentifier) {
+                salla.logger.error('🍏 Pay: merchant validation failed', data?.statusMessage || data);
+                Salla.event.dispatch('payments::apple-pay.validate-merchant.failed', { data });
+                SallaApplePay.onCancel({});
+                // Dismiss the sheet + paired device immediately. Rejecting
+                // event.complete() alone leaves them spinning until Apple's own
+                // timeout; abort() forces an instant close. Deferred a tick so it
+                // runs after this validation update settles (abort() throws if
+                // called while an update is still in flight).
+                setTimeout(() => {
+                    try { SallaApplePay.paymentRequest?.abort(); } catch (e) { /* already closing */ }
+                }, 0);
+                const validationError = new Error('Apple Pay merchant validation failed');
+                validationError.handled = true;
+                throw validationError;
+            }
+
+            Salla.event.dispatch('payments::apple-pay.validate-merchant.success', data);
+
+            if (typeof SallaApplePay.detail.validateMerchant.onSuccess === 'function') {
+                const response = await SallaApplePay.detail.validateMerchant.onSuccess(data);
+                if (response?.redirect) {
+                    window.location = response.redirect;
+                }
+            }
+
+            return data.data;
+        } catch (error) {
+            // Skip when the invalid-session branch above already notified via onCancel.
+            if (!error?.handled) {
+                const response = error?.response;
+                Salla.event.dispatch('payments::apple-pay.validate-merchant.failed', response);
+                if (typeof SallaApplePay.detail.validateMerchant.onFailed === 'function') {
+                    SallaApplePay.detail.validateMerchant.onFailed(response);
+                }
+            }
+            // Rethrow so PaymentRequest aborts the sheet.
+            throw error;
+        }
+    },
+
+    /**
+     * ISO 3166 alpha-2 code → localized country name. The native path sends the
+     * country *name* in `country` (from ApplePayPaymentContact.country) and the
+     * ISO code in `country_code`; W3C PaymentAddress only exposes the ISO code,
+     * so we derive the name the backend expects. Falls back to the code if
+     * Intl.DisplayNames is unavailable or the code is unknown.
+     */
+    prCountryName: (isoCode) => {
+        if (!isoCode) {
+            return isoCode;
+        }
+        try {
+            const locale = (salla?.config?.get?.('user.language_code')) || 'en';
+            return new Intl.DisplayNames([locale], { type: 'region' }).of(isoCode) || isoCode;
+        } catch (e) {
+            return isoCode;
+        }
+    },
+
+    /** Shipping address selected in the sheet → returns a PaymentDetailsUpdate. */
+    prShippingAddressChange: async function (request) {
+        const address = request.shippingAddress;
+        const fallback = {
+            total: SallaApplePay.prTotal(),
+            displayItems: SallaApplePay.prDisplayItems(),
+            shippingOptions: [],
+        };
+
+        if (!address) {
+            return fallback;
+        }
+
+        try {
+            const { data } = await http.post(
+                SallaApplePay.detail.shippingContactSelected.url.replace('{id}', SallaApplePay.id),
+                {
+                    country: SallaApplePay.prCountryName(address.country),
+                    city: address.city,
+                    local: address.dependentLocality || address.region || address.city,
+                    description: address.region,
+                    street: (address.addressLine || []).join(', ') || address.region,
+                    country_code: address.country,
+                    postal_code: address.postalCode,
+                }
+            );
+
+            SallaApplePay.address_id = data.data.address_id;
+            SallaApplePay.shipping_methods = data.data.shipping_methods;
+
+            if (!SallaApplePay.shipping_methods?.length) {
+                return { ...fallback, error: salla.lang.get('pages.checkout.payment_failed') };
+            }
+
+            await SallaApplePay.selectApplePayShippingMethod(SallaApplePay.shipping_methods[0]);
+            await SallaApplePay.recalculateTotal();
+
+            return {
+                total: SallaApplePay.prTotal(),
+                displayItems: SallaApplePay.prDisplayItems(),
+                shippingOptions: SallaApplePay.prShippingOptions(),
+            };
+        } catch (error) {
+            salla.logger.warn('🍏 Pay: PR shipping address change failed', error);
+            return { ...fallback, error: salla.lang.get('pages.checkout.payment_failed') };
+        }
+    },
+
+    /** Shipping option selected in the sheet → returns a PaymentDetailsUpdate. */
+    prShippingOptionChange: async function (request) {
+        const identifier = request.shippingOption;
+        if (!identifier) {
+            return {
+                total: SallaApplePay.prTotal(),
+                displayItems: SallaApplePay.prDisplayItems(),
+                shippingOptions: SallaApplePay.prShippingOptions(),
+            };
+        }
+
+        const ids = identifier.split(',');
+        const shippingMethod = {
+            ship_id: ids[0],
+            private_ship_id: typeof ids[1] === 'undefined' ? null : ids[1],
+            type: typeof ids[2] === 'undefined' ? null : ids[2],
+            route_id: typeof ids[3] === 'undefined' ? null : ids[3],
+        };
+
+        try {
+            if (SallaApplePay.shouldUpdateShippingCompany(shippingMethod)) {
+                await SallaApplePay.selectApplePayShippingMethod(shippingMethod);
+                await SallaApplePay.recalculateTotal();
+            }
+            return {
+                total: SallaApplePay.prTotal(),
+                displayItems: SallaApplePay.prDisplayItems(),
+                shippingOptions: SallaApplePay.prShippingOptions(identifier),
+            };
+        } catch (error) {
+            salla.logger.warn('🍏 Pay: PR shipping option change failed', error);
+            return {
+                total: SallaApplePay.prTotal(),
+                displayItems: SallaApplePay.prDisplayItems(),
+                shippingOptions: SallaApplePay.prShippingOptions(identifier),
+                error: salla.lang.get('pages.checkout.payment_failed'),
+            };
+        }
+    },
+
+    /** Map the PaymentResponse payer fields to the contact shape the API expects. */
+    prContactFromResponse: (response) => {
+        const name = (response.payerName || '').trim();
+        const spaceIndex = name.indexOf(' ');
+        return {
+            givenName: spaceIndex > -1 ? name.slice(0, spaceIndex) : name,
+            familyName: spaceIndex > -1 ? name.slice(spaceIndex + 1) : '',
+            emailAddress: response.payerEmail || null,
+            phoneNumber: response.payerPhone || null,
+            countryCode: response.shippingAddress?.country || SallaApplePay.detail.countryCode || null,
+        };
+    },
+
+    track: function (event, extra = {}) {
+        const id = SallaApplePay.id ? String(SallaApplePay.id) : null;
+        try {
+            salla.analytics?.track(event, {
+                payment_method: 'apple_pay',
+                gateway: 'apple_pay',
+                cart_id: id,
+                checkout_id: id,
+                session_id: salla.config?.get?.('jitsu.session_id') || null,
+                ...extra,
+                // The host knows the surface — PDP quick-buy vs the mini-checkout
+                // embed both render salla-quick-buy and share this package.
+                checkout_type: extra.checkout_type
+                    || SallaApplePay.detail?.checkout_type
+                    || 'applepay_checkout',
+            });
+        } catch (error) {
+            salla.logger.error('🍏 Pay: failed to track ' + event, error);
+        }
+    },
+
+    trackPaymentSubmitted: function () {
+        if (SallaApplePay._submittedTracked) {
+            return;
+        }
+        SallaApplePay._submittedTracked = true;
+        // Checkout Started belongs to the host: the mini-checkout embed already
+        // emits its own on open, and on the PDP the cart does not exist until
+        // checkout/mini answers, so salla-quick-buy fires it there with a real id.
+        SallaApplePay.track('Payment Submitted', {});
+    },
+
+    trackPaymentFailed: function (errorType, errorCode, message = '') {
+        // Payment Failed answers a Payment Submitted, and Submitted is emitted at
+        // authorization. Anything that ends the attempt before that — a dismissed
+        // sheet, a refused presentation, merchant validation — is abandonment or a
+        // setup error, not a failed payment, and counting it here would make
+        // Failed exceed Submitted. Those paths still log, still call
+        // detail.onError and still dispatch payments::apple-pay.canceled, so
+        // hosts and error reporting are unaffected; only the funnel is.
+        if (!SallaApplePay._submittedTracked || SallaApplePay._failureTracked) {
+            return;
+        }
+        SallaApplePay._failureTracked = true;
+        SallaApplePay.track('Payment Failed', {
+            error_type: errorType,
+            error_code: errorCode,
+            error_message: message || '',
+        });
+    },
+
+    trackPaymentSucceeded: function (data) {
+        if (SallaApplePay._succeededTracked) {
+            return;
+        }
+        SallaApplePay._succeededTracked = true;
+        const payload = data?.data || data || {};
+        SallaApplePay.track('Payment Succeeded', {
+            order_id: payload.order_id || null,
+            cart_total: payload.total || SallaApplePay.detail?.amount || null,
+            response_status: 'success',
+            has_redirect: false,
+            redirect_url: null,
+        });
+    },
+
+    /** Authorize + submit the payment, then close the sheet. */
+    prPaymentAuthorized: async function (response) {
+        // Guest checkout → persist the payer contact before submitting.
+        if (SallaApplePay.detail.guestContactSelected) {
+            const contact = SallaApplePay.prContactFromResponse(response);
+
+            // Require familyName too, mirroring the native guest guard
+            // (utils.js mutateShippingContact). Keeps the payload the backend
+            // receives identical to the production native flow — it has only
+            // ever been sent a non-empty last_name from Apple Pay guest checkout.
+            if (!contact.emailAddress || !contact.givenName || !contact.familyName || !contact.phoneNumber) {
+                await response.complete('fail');
+                SallaApplePay.detail.onError(salla.lang.get('common.messages.required_fields'));
+                return;
+            }
+
+            try {
+                await http.post(
+                    SallaApplePay.detail.guestContactSelected.url.replace('{id}', SallaApplePay.id),
+                    {
+                        email: contact.emailAddress,
+                        first_name: contact.givenName,
+                        last_name: contact.familyName,
+                        phone_number: contact.phoneNumber,
+                        country_code: contact.countryCode,
+                    }
+                );
+            } catch (error) {
+                await response.complete('fail');
+                SallaApplePay.detail.onError(
+                    error?.response?.data?.error?.message || salla.lang.get('pages.checkout.payment_failed')
+                );
+                return;
+            }
+        }
+
+        Salla.event.dispatch('payments::apple-pay.authorized.init', response);
+        // Authorised on the paired device; the token is about to be submitted.
+        SallaApplePay.trackPaymentSubmitted();
+
+        let authorizedData;
+        try {
+            const { data } = await http.post(
+                SallaApplePay.detail.authorized.url.replace('{id}', SallaApplePay.id),
+                { payment_method: 'apple_pay', applepay_token: JSON.stringify(response.details) }
+            );
+
+            authorizedData = data;
+            Salla.event.dispatch('payments::apple-pay.authorized.success', data);
+            SallaApplePay.trackPaymentSucceeded(data);
+            await response.complete('success');
+        } catch (error) {
+            const errorResponse = error?.response;
+            Salla.event.dispatch('payments::apple-pay.authorized.failed', errorResponse);
+            // Backend rejected the token — latch set so the sheet-close /
+            // cancel that follows can't emit a second Failed.
+            SallaApplePay.trackPaymentFailed('server',
+                errorResponse?.data?.error?.code || 'APPLE_PAY_FAILED',
+                errorResponse?.data?.error?.message || '');
+            await response.complete('fail');
+            if (typeof SallaApplePay.detail.authorized.onFailed === 'function') {
+                SallaApplePay.detail.authorized.onFailed(errorResponse);
+            }
+            return;
+        }
+
+        // response.complete() has already run above, and it can only be called
+        // once. Run the merchant onSuccess callback OUTSIDE the try/catch so a
+        // throw here (e.g. redirect handling) can't fall into the catch and fire
+        // a second complete('fail') → InvalidStateError that masks the real error.
+        if (typeof SallaApplePay.detail.authorized.onSuccess === 'function') {
+            SallaApplePay.detail.authorized.onSuccess(authorizedData);
+        }
+    },
+
     shouldUpdateShippingCompany(shippingCompany) {
         return SallaApplePay.shippingCompany?.ship_id != shippingCompany?.ship_id || SallaApplePay.shippingCompany?.private_ship_id != shippingCompany?.private_ship_id
     },
@@ -505,8 +1087,16 @@ const SallaApplePay = typeof window !== 'undefined' ? {
                 payments
             });
 
-            // todo :: enhance response from backend
-            SallaApplePay.detail.amount = payments?.gateways?.applePay?.supportedMultiCurrency ? cart.total_in_customer_currency : cart.total;
+            // BE-canary gate keyed on the live payload (not cached config): the unified BE adds
+            // applePay.amount, legacy BE doesn't — so gate and data can never desync.
+            if (payments?.gateways?.applePay?.amount != null) {
+                // Unified BE: Apple Pay is always charged in the store base currency.
+                SallaApplePay.detail.amount = payments.gateways.applePay.amount;
+                SallaApplePay.detail.currency = payments.gateways.applePay.currency ?? SallaApplePay.detail.currency;
+            } else {
+                // Legacy BE .
+                SallaApplePay.detail.amount = payments?.gateways?.applePay?.supportedMultiCurrency ? cart.total_in_customer_currency : cart.total;
+            }
             SallaApplePay.detail.items = (cart.totals || cart.items).map((item) => {
                 return {
                     label: item.title,
@@ -579,8 +1169,10 @@ if (typeof window !== 'undefined') {
 }
 
 //applePay doesn't allow iframes
-// SSR-safe: only initialize in browser
-if (typeof window !== 'undefined' && window.ApplePaySession?.canMakePayments()) {
+// SSR-safe (init only in the browser). Native (Safari) OR any browser with the
+// Payment Request API (non-Safari / QR-code fallback) can start a transaction;
+// capability is confirmed per-flow.
+if (typeof window !== 'undefined' && (SallaApplePay.canUseNative() || window.PaymentRequest)) {
     SallaApplePay.init();
 } else if (typeof document !== 'undefined') {
     // You can hide the Apple Pay button easy with add data-show-if-apple-pay-supported to element like <div data-show-if-apple-pay-supported>