SDK

In this section, you will find how to implement the Unico SDK in your web application for using the by Unico

---

The use of integrations that do not comply with the standards outlined in this documentation may result in unexpected system interruptions, which will not be covered or supported by by Unico.

Examples: Embedding the by Unico SDK (iFrame) within a webview, implementing the iFrame using an HTML tag, etc.

How to start

---

To use by Unico through the Unico Web SDK, the first step is to register the domains, always using the HTTPS protocol, that will be used as hosts to display the user journey experience.

Please inform the person responsible for your integration project or the Unico support team to carry out this configuration.

To begin using the SDK, we should start with the installation of the Unico web SDK:. by Unico uses the same SDK that is used for IDPay:

$ npm install idpay-b2b-sdk

When installing the Unico SDK package, deploy without specifying the version you are using so that your dependency manager always updates minors and patches to the latest version.

To check previous versions, go to https://www.npmjs.com/package/idpay-b2b-sdk?activeTab=versions.

Available methods

---

1

init(options)

This method initializes the SDK by preloading assets, creating a smoother experience for the end user. At this point, it is necessary to send the token received as a result of the CreateProcess.

Parameters:

• options - an object with the following configuration properties:

  • type

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

  • token

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

import { UnicoSDK } from “idpay-b2b-sdk”;

UnicoSDK.init({
  type: 'IFRAME',
  env: 'uat'//only if the environment is uat
  token,
});

2

open(options)

This method opens the by Unico experience. For the IFRAME flow, this function displays the already preloaded iFrame and initiates the messaging flow between the client 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 to obtain the process details and carry out the entire flow correctly (can be obtained when creating the process via API).

• token

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

• onFinish(process)

  • Receives a callback function that will be executed at the end of the by Unico journey, passing 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);
}

UnicoSDK.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​

---

Opt for the Iframe Solution with Auth Token Instead of CSP

---

After careful analysis of our needs and challenges, we have decided to adopt a solution based on iframes with authentication tokens rather than implementing a Content Security Policy (CSP). This choice was motivated by various considerations related to the security and 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 often 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, it would be necessary to constantly update the CSP policy to include these new domains. This not only increases maintenance efforts but also exposes the domains to which the CSP policy applies. Each domain added to the CSP policy is potentially a vulnerability point if not adequately managed.

Solution with Iframe and Auth Token

---

To mitigate these risks and meet the flexibility required by our clients, we opted 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 the isolation of 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 our clients' dynamic domains without the need for constant updates to security policies.

---

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.