5. Securing Embedded UIs

Platform offers a comprehensive framework designed to ensure the security of its web components. This framework encompasses a wide range of security measures. By addressing security at multiple levels, Platform aims to protect sensitive data and maintain the integrity of its web applications

Platform uses MerchantSession to enable embedded web components to access merchant data and allow merchants to interact with that.

Obtaining a new Merchant Session

This example illustrates a server-side implementation for obtaining a secure session using the partner's private key.

It's crucial to highlight that the private key should never be exposed to the client-side and must remain securely stored for server-to-server communications only. By implementing this approach, partners ensure that the access token acquisition process is both secure and compliant with best practices for protecting sensitive credentials. This setup helps maintain the integrity of interactions between the partner's web application, through the partner backend application to Platform's services.

Backend NodeJS

const axios = require('axios');
const express = require('express');
const app = express();

// Replace with your actual API endpoint and any necessary authentication
const API_ENDPOINT = 'https://<PAYENGINE_HOST>/api/merchant'; // Example endpoint
const API_KEY = 'your_api_key'; // Platform API Key
const MERCHANT_ID = 'your_merchant_id'; // Platform assigned Merchant ID

app.post('/accessToken', async (req, res) => {
  try {
    const data = {
      expires_in: 900,
      // Setting scope to 'readonly' restricts actions like hiding the Refund button in the transaction widget
      scope: 'readonly' // Optional.
    };
    
    const apiURL = `${API_ENDPOINT}/${MERCHANT_ID}/sessions`;
    
    const response = await axios.post(apiURL, data, {
      headers: {
        'Content-Type': 'application/json', 
        'Authorization': `Basic ${API_KEY}`, 
      },
    });

    // ... code to store session in the backend
    
    res.json({
      access_token: response.data.access_token,
      expires_in: response.data.expires_in
    });
  } catch (error) {
    // ERROR HANDLING AND RETRYING
  }
});

Note: Setting the scope parameter to 'readonly' restricts certain actions in the embedded widgets, such as hiding the Refund button in the Transactions widget, disabling the Export button etc.

Load Platform Library

To access the latest Platform tokenization features and APIs, please update to [email protected] or higher. This update provides essential improvements and ensures compatibility with our latest security standards.

When Platform library needs the access token, it will use the fetchAccessToken to ask the host application to make a server side call and obtain the access token. It is important to note that Platform will call fetchAccessToken whenever access token is needed or when it needs to be refreshed.

This example demonstrates how to implement client-side code using Platform's public key and fetchAccessToken callback, ensuring that sensitive private key data remains secure and never exposed to the client side.

Frontend React

import { useEffect } from "react";
import { loadPlatform } from "payengine";


const MyComponent = () => {

  const fetchAccessToken = async () => {
    const response = await fetch('/accessToken', { method: "POST" });
    if (!response.ok) {
      //Handle error as per your app's design
      return undefined;
    } else {
      const jsonResponse = await response.json();
      return jsonResponse;
    }
  }
    
  useEffect(() => {
      // Load Platform on first render only
      loadPlatform({
        publicKey: config.PAYENGINE_PUBLIC_KEY, 
        fetchAccessToken: fetchAccessToken 
      }).then((pe) => {
          console.log(pe)
      });  
  }, []);
  
  return (
    <>
      <payment-platform 
        type="boarding" 
        merchant-id="<payengine_merchant_id>" 
      </payment-platform>        
    </>
  )   
}

Plain HTML/JS

Specify your onload callback function. This function will get called when all the dependencies have loaded.

<script type="text/javascript">
  var onloadCallback = function() {
    alert("Platform is ready!");
  };
</script>

Insert the JavaScript resource, setting the onload parameter to the name of your onload callback function

<script src="<PAYENGINE_SCRIPT_URL>?key=<PAYENGNE_PUBLIC_KEY>&onload=onloadCallback"
    async defer>
</script>

Implement fetchAccessToken method to obtain a new access token

Full sample code

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Platform WebComponent</title>
    <script type="text/javascript">
      const fetchAccessToken = async () => {
        const response = await fetch('/accessToken', { method: "POST" });
        if (!response.ok) {
          //Handle error as per your app's design
          return undefined;
        } else {
          const response = await response.json();
          return response;
        }
      }
      
      function onloadCallback() {
        console.log("Platform is ready!");
        Platform.fetchAccessToken = fetchAccessToken
      }
    </script>
    <script src="https://console.payengine.dev/js/1.0.0/embed.js?key=<YOUR-PUBLIC-KEY>&onload=onloadCallback"></script>
  </head>

  <body>
    <h1>Mechant Onboarding</h1>
    <payment-platform merchant-id="<YOUR-MERCHANT-ID>" type="boarding"></payment-platform>
  </body>
</html>

Logout - Revoke Access Token

While access tokens automatically expire, it's crucial to immediately invalidate them when a user's session ends on the server. Relying solely on token expiration creates a security vulnerability and a suboptimal user experience.

This section provides an example of both client-side and server-side implementations for partners

For immediate session revocation on logout, we recommend implementing client-side access token revocation.

Frontend

To invalidate the access token on the client side, call the following method in your JavaScript code.

Platform.logout()

This ensures that the user's session is terminated, preventing further authenticated requests until they log in again.

Backend NodeJS

You can call the API endpoint to revoke the access token. However, since you are not expected to store the access token for later revocation, it is recommended to use the client-side method instead.

const axios = require('axios');
const express = require('express');
const app = express();

// Replace with your actual API endpoint and any necessary authentication
const API_ENDPOINT = 'https://<PAYENGINE_HOST>/api/merchant'; // Example endpoint
const API_KEY = 'your_api_key'; // Platform API Key
const MERCHANT_ID = 'your_merchant_id'; // Platform assigned Merchant ID

app.delete('/accessToken/:accessToken', async (req, res) => {
  try {
    const apiURL = `${API_ENDPOINT}/${MERCHANT_ID}/sessions/${req.params.accessToken}`;
    const response = await axios.delete(apiURL, {
      headers: {
        'Content-Type': 'application/json', 
        'Authorization': `Basic ${API_KEY}`, 
      },
    });

    // ... code to clean up backend data
    
    res.json({
      // Aappropriate response as your app's requirements 
    });
  } catch (error) {
    // ERROR HANDLING AND RETRYING
  }
});