Samsung Pay Web Checkout - IFrame Mobile Integration

Overview

This guide explains how to integrate the Samsung Pay Web Checkout SDK for the mobile flow when the SDK is embedded inside an <iframe>.

When using the SDK inside an iframe:

• The parent page must listen for postMessage() events.
• The parent page must open or navigate to the Samsung Pay mobile checkout URL.
• loadPaymentSheet() must be called inside the iframe where the SDK is loaded.

Important:

• The SDK may rely on document.referrer (or similar browser behavior) when communicating with the parent page.
• If the referrer is removed (for example, by using Referrer-Policy: no-referrer), communication between the iframe and parent page may fail.
• Make sure your referrer policy allows the required communication during integration.

---

Integration Flow

• The parent page registers a message event listener using window.addEventListener("message", ...).

1. Clicking 'Pay with Samsung Pay' button triggers loadPaymentSheet(paymentMethods, transactionDetail).
2. The SDK inside the iframe sends a Samsung Pay mobile checkout URL to the parent page using postMessage().
3. The parent page opens the Samsung Pay checkout page in a new tab or navigates in the same tab.
4. After checkout is completed, a payment_result message is sent to the parent page.
5. The parent page forwards the payment_result back to the iframe using postMessage().

• The loadPaymentSheet() Promise resolves inside the iframe.

---

Implementation Guide

Step 1: Add a postMessage listener on the parent page

// Actual origin of the iframe document that loads the SDK
// Replace with your real origin of the iframe that contains the SDK
const IFRAME_WITH_SDK_ORIGIN = "https://sdk.example.com";

window.addEventListener("message", (event) => {
  if (!event.data) {
    return;
  }

  // Handle Samsung Pay mobile checkout URL
  if (event.data.mobileUrl) {
    // Validate message origin
    if (event.origin !== IFRAME_WITH_SDK_ORIGIN) {
      return;
    }

    console.log("MOBILE URL FROM SDK:", event.data.mobileUrl);

    // Open Samsung Pay checkout page
    window.open(event.data.mobileUrl);

    return;
  }

  // Handle payment result
  if (event.data.type === "payment_result") {
    const childIframe = document.getElementById("child-iframe");

    if (!childIframe || !childIframe.contentWindow) {
      return;
    }

    // Forward payment result back to SDK iframe
    childIframe.contentWindow.postMessage(
      event.data,
      IFRAME_WITH_SDK_ORIGIN
    );

    // Add your transaction result handling here
  }
});

Step 2: Open the Mobile Checkout URL

When mobileUrl is received from the SDK:

• Log or persist the URL for debugging.
• Open the Samsung Pay checkout page using window.open(url);

Step 3: Forward payment results to the iframe

When the parent page receives a payment_result message:

1. Find the iframe element using a stable id.
2. Forward the original event.data payload back to the iframe.
3. Keep the payload structure unchanged whenever possible.

Sample code:

childIframe.contentWindow.postMessage(
  event.data,
  IFRAME_WITH_SDK_ORIGIN
);

The SDK inside the iframe uses this message to resolve the loadPaymentSheet() Promise.

---

Event Data Structure

Property	Type	Description
event.data	Object	Message payload object
event.data.mobileUrl	String	Samsung Pay mobile checkout URL
event.data.type	String	Message type (example: "payment_result")
event.data.content	Object	Payment result payload consumed by the SDK
event.origin	String	Sender origin (scheme + host + port)

---

Additional Notes

• Avoid using postMessage(...,"*")
• Always use an explicit targetOrigin.

Sample code:

childIframe.contentWindow.postMessage(
  event.data,
  IFRAME_WITH_SDK_ORIGIN
);