SDK

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

---

For web usage, the recommended approach is to use the Unico SDK for the following reasons:

• Higher security;

• Integrated experience with your flow;

• Higher conversion rate when using the SDK;

• Easier implementation.

The use of integrations that do not comply with the standards established in this documentation may result in unexpected disruptions in the system's functionality, which will not be covered or supported by IDPay.

For example: Implementing the Unico by iFrame within a webview, implementing the iFrame through an HTML tag, etc.

How to get started

---

To use IDPay through the Unico IDPay SDK, the first step is to register the domains that will be used as hosts to display the user journey experience.

Notify the person responsible for your integration project or the Unico support team to make this configuration.

To begin using the SDK, we should start with the installation of the Unico web SDK:

$ npm install idpay-b2b-sdk

Available Methods

---

1

init(options)

This method allows the SDK to be initialized, regardless of a transaction ID, making the end-user experience smoother. This is because when the transaction ID and token become available, the application will already have been pre-loaded through this method. If this method is not called directly by the application, the end user will experience a long load time when the SDK is opened for the first time.

Parameters:

• options

  • Receives an object with configuration properties:

    • type

      • The type of flow that will be initialized. Currently, we offer two types of flows (REDIRECT and IFRAME). For new applications, we recommend using the IFRAME type, which makes the end-user experience much smoother and with less friction, as it avoids the need to leave the checkout screen, and the experience can be preloaded.

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

IDPaySDK.init({
  type: 'IFRAME',
  env: 'uat' // Só irá ser preenchido se for ambiente de testes.
});

2

open({ transactionId, token, onFinish? })

This method opens the IDPay experience according to the flow type chosen previously in the initialization function. For the REDIRECT flow, this function performs a simple redirect to the IDPay capture flow route. For the IFRAME flow, this function displays the pre-loaded iframe and starts the messaging flow between the customer's page and the IDPay experience.

Parameters:

• options

  • Receives an object with configuration properties:

    • transactionId

      • Receives the ID of the created transaction. This ID is important to obtain the transaction details and complete the flow correctly (it can be obtained during transaction creation via the API).

    • token

      • Receives the token for the created transaction. This token is important to authenticate the transaction and ensure that only authorized domains use it (it can be obtained during transaction creation via the API).

    • optional onFinish(transaction, type)

      • Receives a callback function that will be executed at the end of the IDPay capture flow, passing two arguments:

        • The transaction object with the following data: { captureConcluded, concluded, id }

          • The response type, which can be FINISH for cases where the flow was completed successfully, or ERROR for cases where the flow was interrupted by an error¹.

[1] In cases of an error in the flow, the transaction status will not be changed, and a callback via webhook, if configured, will not be triggered.

const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

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

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

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

Security

---

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

Context and Challenges with CSP

---

The Content Security Policy (CSP) is a powerful tool to protect 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 works well when 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 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 the maintenance effort but also exposes the domains that the CSP policy applies to. 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 required by our clients, we opted to use iFrames combined with authentication tokens. This solution provides an additional layer of security and eliminates 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 content to be isolated 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.

---

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.