Web App Integration

This page covers the two client-side integration approaches for the Web & SDK contract: redirecting the user to a Unico-hosted journey, and embedding the journey via the iFrame SDK.

Redirecting the user

After creating a process, the response includes a URL that points to the Unico-hosted journey. Use this URL to hand the user off to the capture experience. There are two ways to manage this transition:

1. Standard redirect

Redirect the user directly to the journey URL. When the user completes the process, Unico redirects them back to the URL you specified during process creation.

2. New tab with window.open()

Open the journey in a new browser tab so the user stays in a separate context. Monitor for a URL change to your return URL and close the tab when the process is complete.

For details on the window.open() API, see the MDN documentation.

iFrame

warning

Integrations that do not follow the standards in this documentation may cause unexpected interruptions and will not be covered by Unico support.

Examples of unsupported approaches: embedding the SDK inside a WebView, or loading the iFrame directly via an HTML tag.

How to Start

Step 1 — Installation

The by Unico SDK uses the same package as IDPay:

npm install idpay-b2b-sdk

tip

Install without pinning a specific version so your package manager always pulls the latest minor and patch releases automatically.

Before you start, register your domains with the Unico support team. All domains must use HTTPS.

Step 2 — Call init(options)

Initializes the SDK and pre-loads assets, creating a smoother experience for the end user. Call this as early as possible in your flow.

Parameter	Required	Description
type	Yes	Set to 'IFRAME' for by Unico flows
token	Yes	Process token returned by the Create Process API
env	No	Set to 'uat' for test environments only

import { ByUnicoSDK } from "idpay-b2b-sdk";

ByUnicoSDK.init({
  type: 'IFRAME',
  token,
  // env: 'uat' // only for test environments
});

Step 3 — Call open(options)

Displays the pre-loaded iFrame and starts the message flow between your page and the Unico journey.

Parameter	Required	Description
transactionId	Yes	Process ID returned by the Create Process API
token	Yes	Process token returned by the Create Process API
onFinish	Yes	Callback executed when the journey ends or is closed

The onFinish callback receives a process object with the transaction ID, a redirect URL, and the completion type.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

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

Security

Opt for the iFrame solution with auth token instead of CSP

After careful analysis, the chosen approach uses iframes with authentication tokens rather than implementing a Content Security Policy (CSP). This decision was motivated by the security requirements and the flexibility needed to meet client demands.

Context and challenges with CSP

Content Security Policy is a powerful tool for protecting web applications against XSS and code injection attacks. However, configuring a CSP policy requires defining a strict list of trusted domains. This approach is effective when domains are fixed and predictable — but for clients who 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 frequently change or are created dynamically, the CSP policy must be constantly updated to include new domains. This not only increases maintenance overhead but also exposes every domain listed in the policy as a potential attack surface if not adequately managed.

Solution with iFrame and auth token

To mitigate these risks and meet the flexibility required by clients, the chosen solution combines iframes with authentication tokens, providing an additional layer of security without requiring a static domain list.

How it works:

• Secure authentication — each iFrame is loaded with a unique authentication token per transaction, ensuring only authorized users can access the content. The token is verified in real-time.
• Content isolation — the iFrame runs in a separate browsing 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, the solution adapts to dynamic client domains without requiring constant policy updates.