<iframe> API integration

After going through the Prerequisites and ensuring that your LoanPASS client is configured for embedding, integration should be fairly straightforward.

Embedding the <iframe>

An <iframe> should be added to the page with the src set to the appropriate URL for embedding. The URL for embedding will depend on your client access ID (for example, if your login page is at https://app.loanpass.io/login/example-client, your client access ID is example-client).

The correct URL to use for the <iframe> src attribute will be one of the following:

• Staging: https://staging.loanpass.io/frame-redirect/{client_access_id}
• Sandbox: https://integrationsandbox.loanpass.io/frame-redirect/{client_access_id}
• Production: https://app.loanpass.io/frame-redirect/{client_access_id}

After embedding the <iframe>, iframe.contentWindow.postMessage({ type: "connect" }) should be called on the <iframe> to enable the <iframe> API. Afterwards, the <iframe> will send back a listening event, which indicates further messages can be sent.

Example: Vanilla JS

const loanpassOrigin = "https://app.loanpass.io";

const iframe = document.createElement("iframe");
iframe.src = `${loanpassOrigin}/frame-redirect/example-client`;
iframe.addEventListener("load", () => {
    // Connect to send and receive messages
  iframe.contentWindow.postMessage({ message: "connect" }, loanpassOrigin);
});

// Attach the message listener
window.addEventListener("message", event => {
  // Validate the message came from the LoanPASS <iframe>
  if (event.origin !== loanpassOrigin) {
    console.warn("Received message from unexpected origin", event);
    return;
  }

  // ... do something with the message ...
  console.log("Received message", event.data);
});

var container = document.getElementById("loanpass-container");
container.appendChild(iframe);

Example: React Hooks

const LoanpassWidget = props => {
  const iframeRef = useRef(null);
  const loanpassOrigin = "https://app.loanpass.io";

  // Create an event listener to listen for messages
  const messageListener = useCallback(event => {
    // Validate the message came from the LoanPASS <iframe>
    if (event.origin !== loanpassOrigin) {
      console.warn("Received message from unexpected origin", event);
      return;
    }

    // ... do something with the message ...
    console.log("Received message", event.data);
  }, [loanpassOrigin]);

  const onLoad = useCallback(() => {
    const contentWindow = iframeRef.current?.contentWindow;

    if (contentWindow == null) { return; }

    // Connect to send and receive messages
    contentWindow.postMessage({message: "connect"}, loanpassOrigin);
    console.log("Connected to window");
  }, [loanpassOrigin]);

  useEffect(() => {
    // Attach the message listener
    window.addEventListener("message", messageListener);

    return () => {
      // Clean up the message listener
      window.removeEventListener("message", messageListener);
    };
  }, [messageListener, loanpassOrigin]);

  return (
    <iframe
      ref={iframeRef}
      onLoad={onLoad}
      src={`${loanpassOrigin}/frame-redirect/example-client`}
    />
  );
};

Sending messages

After embedding the <iframe>, messages can be sent by calling iframe.contentWindow.postMessage({ /* message object*/ }). When sending a message, the postMessage function also takes an origin that should receive the message. As shown in the above examples, this should be set to the same origin used to embed the LoanPASS app.

The connect message should be sent first, then the integration should wait for the listening message! This will configure the LoanPASS app to listen for other messages, and will configure the LoanPASS app to send messages back to your app. The listening message indicates the that LoanPASS app is ready to handle more messages.

For a list of messages, see Messages. For more details about calling postMessage, see the MDN postMessage docs.

Receiving messages

After embedding the <iframe> and sending the connect message, the LoanPASS app will send any messages back to your app through postMessage calls. Your app can receive these events with a function like window.addEventListener("message", (event) => { /* ... */ }).

For good security hygiene, we recommend validating that event.origin matches the origin of the embedded LoanPASS app, as shown in the examples.

For a list of messages, see Messages. For more details about receiving postMessage events, see the MDN postMessage event docs.