Skip to main content

iFrame

For the web usage scenario, iFrame is recommended for the following reasons:

  • Greater security;
  • Integrated experience with your flow;
  • Higher conversion rate when using iFrame;
  • Ease of implementation;
Note

To use iFrame, you must request the onboarding team to register the domains that will host the iFrame for the user journey of by Unico. See the motivation for this pre-registration below.

To start using iFrame, we must begin with the installation of the Unico web SDK. by Unico uses the same SDK utilized for IDPay:

$ npm install idpay-b2b-sdk@0.0.22-beta.3

Available Methods:

init(options)

This method initializes the SDK, preloading assets to create a smoother experience for the end user. At this point, you need to send the token received as a result of CreateProcess.

Parameters:

options - an object with the following configuration properties:

  • type

    • The type of flow that will be initialized. In by Unico, we use the IFRAME option.

  • token

    • Receives the token of the created process. This token is important for authenticating the journey and ensuring that only authorized domains use it (it can be obtained when creating the process via the API).
import { IDPaySDK } from “idpay-b2b-sdk”;

IDPaySDK.init({
  type: 'IFRAME',
  token,
});

open(options)

This method opens the by Unico experience. For the IFRAME flow, this function displays the pre-loaded iframe and initiates the messaging flow between the client's page and the by Unico experience.

Parameters:

options - an object with configuration properties:

  • processId

    • Receives the ID of the created process. This ID is important for retrieving the process details and executing the entire flow correctly (it can be obtained when creating the process via the API).

  • token

    • Receives the token of the created process. This token is important for authenticating the journey and ensuring that only authorized domains use it (it can be obtained when creating the process via the API).

  • onFinish(process)

    • Receives a callback function that will be executed at the end of the by Unico journey, passing as an argument the process object with the following data: { captureConcluded, concluded, id }
const processId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const process = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinishCallback = process => {
  console.log('Process', process);
}

IDPaySDK.open({
  transactionId: processId,
  token: token,
  onFinish: onFinishCallback
});

The sequence diagram below demonstrates how to use the SDK and the API result from by Unico to configure the iFrame:

Security​

Choosing the Iframe Solution with Auth Token over CSP​

After careful analysis of our needs and challenges, we decided to adopt a solution based on iframes with authentication tokens instead of implementing a Content Security Policy (CSP). This choice was motivated by several security-related considerations and the flexibility required to meet our clients' demands.

Context and Challenges with CSP​

Content Security Policy (CSP) is a powerful tool for protecting web applications against various types of attacks, such as Cross-Site Scripting (XSS) and code injection. However, when configuring a CSP policy, it is necessary to define a strict list of trusted domains. This approach is effective when the domains are fixed and predictable. However, for our clients, who frequently use dynamic and variable domains, this rigid configuration presents significant challenges.

Vulnerability with Dynamic Domains​

Dynamic domains pose a substantial security risk when using CSP. When a client has domains that change frequently or are created dynamically, it would be necessary to constantly update the CSP policy to include these new domains. This not only increases maintenance effort but also exposes the domains to which the CSP policy applies. Each domain added to the CSP policy is potentially a point of vulnerability if not properly managed.

Solution with Iframe and Auth Token​

To mitigate these risks and meet the flexibility demanded by our clients, we chose to use iframes combined with authentication tokens. This solution provides an additional layer of security and avoids the need to expose or manage an extensive and dynamic list of domains.

How it Works​

  • Secure Authentication: Each iframe is loaded with a unique authentication token for each transaction, ensuring that only authorized users can access the content. This token is verified in real-time, providing an additional layer of security and control.
  • Content Isolation: The use of iframes allows for isolating content in a separate context, reducing the risk of interference between different origins and mitigating potential attacks.
  • Flexibility for Dynamic Domains: By not relying on a static CSP policy, our solution easily adapts to clients' dynamic domains without the need for constant updates to security policies.

Questions?​

Didn’t find something or still need help? If you are already a client or partner, you can contact us through the Help Center.