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.
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:
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.
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.
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.
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.
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.
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.
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.
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
In this section, you will learn how to implement Redirect in your web application for using the Unico IDPay product.
This method of controlling the web experience is being deprecated. For better conversion of IDPay in your application, follow the method outlined in the "SDK" section.
The web version offers the option to use the redirect model, but the iframe model is the most recommended.
When creating the transaction, the redirectUrl field was passed as a parameter, which will be used later. You can use this option.
The window.open() option consists of opening a new browser tab for the user to complete the capture flow. Once done, the tab will close and redirect back to the previously visited site. We recommend:
Follow the public documentation on this, which can be found here;
Monitor if the URL has changed (to the redirectUrl), and then close the tab using window.close().
When creating the transaction, the redirectUrl field was passed as a parameter, which will be used later. You need to follow these steps:
In your regular flow (where IDPay is integrated), you will redirect the customer to the link generated via the API;
After this, the customer within the IDPay webpage will complete the necessary steps to continue the flow;
Once completed, they will be redirected back to your page (using the redirectUrl passed when creating the transaction).
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
In this section, you will find how to implement iFrame and Redirect in your web application for using the Unico IDPay product.