For the Android use case, using a Webview is recommended. After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your regular flow (where IDPay is integrated), you will open the Webview with the link generated via API.

• You can customize how this opening works in the way that best fits your application.

• You will monitor if there is a URL change (to the redirectUrl) and then close the Webview.

Opening a Webview is quite simple:

import android.webkit.PermissionRequest
import android.webkit.WebChromeClient
import android.webkit.WebView
import android.webkit.WebViewClient

@SuppressLint("SetJavaScriptEnabled")
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_camera)

    findViewById<WebView>(R.id.webView).apply {
        settings.javaScriptEnabled = true
        settings.domStorageEnabled = true
        settings.mediaPlaybackRequiresUserGesture = false
        clearCache(true)
        webViewClient = myWebViewClient
        webChromeClient = object : WebChromeClient() {
            override fun onPermissionRequest(request: PermissionRequest?) {
                request?.grant(request.resources)
            }
        }
        loadUrl("<URL_TO_LOAD>")
    }
}

To control when it is necessary to close the Webview, it can be done as follows:

private val myWebViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView?,
        request: WebResourceRequest?
    ): Boolean {
        if (request?.url.toString() == "<URL_TO_OBSERVER>") {
            // close here your webview
        }
        return super.shouldOverrideUrlLoading(view, request)
    }
}

To do this, it is necessary to enable permissions in the Android Manifest:

<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-permission android:name="android.permission.CAMERA"/>

Example of how it should look in the app:

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.

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.

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.

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

$ npm install idpay-b2b-sdk

Available Methods

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

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

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.

The web version offers the option to use the redirect model, but the iframe model is the most recommended.

1) Using window.open()

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().

2) Using redirect

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).

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.

Introduction

Unico IDPay offers a simple and fast integration. Currently, we standardize integration in applications (mobile or web) through the use of Webview, SDK, and Redirect. This standard enhances the security of your business and customers, abstracting the complexity of handling the users' device camera and capturing selfies.

In our REST API, we provide methods for generating integration links that can be opened and controlled by the applications.

Generating Data in the API

Before moving on to the integration details in your application or website, it is crucial to start by integrating with our API. In this process, two key points will be used:

1. Create Transaction (CreateTransaction):

   • Make sure to fill in the redirectUrl field, as it will be essential for the integration flow.

After completing this initial step, you will be ready to continue with the integration in your application or website.

It is important to remember that once the entire flow is completed, you will need to obtain the transaction result via our API to ensure the process is properly concluded.

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.

For the iOS usage scenario, using WKWebView is one of the recommended approaches.

After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your common flow (which includes IDPay), you will open the WKWebView with the link generated via the API;

• You can customize this opening as needed for your app;

• You will monitor if the URL has changed (to the redirectUrl) and then close the WKWebView.

Opening a WKWebView is quite simple:

import UIKit
import WebKit
import SafariServices

var webView: WKWebView!

override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view.
    self.view.backgroundColor = .white
}

@IBAction func open(_ sender: Any) {
    createWKWebViewFull()
}

func createWKWebViewFull() {
    webView = WKWebView(frame: self.view.bounds, configuration: getWKWebViewConfiguration())
    webView.navigationDelegate = self
    view.addSubview(webView)
    self.loadUrl()
}

func loadUrl() {
    if let url = URL(string:"<URL_TO_LOAD>") {
        webView.load(URLRequest(url: url))
        webView.allowsBackForwardNavigationGestures = true
    }
}

private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
    let config = WKWebViewConfiguration()
    config.allowsInlineMediaPlayback = true
    config.mediaTypesRequiringUserActionForPlayback = []

    return config
}

To control when to close the WKWebView, this can be done as follows:

func webView(_ webView: WKWebView, didCommit navigation: WKNavigation!) {
    if let currentURL = webView.url {
        print("URL changed to: \(currentURL.absoluteString)")
        if currentURL.absoluteString == "<URL_TO_OBSERVER>" {
            closeWebView()
        }
    }
}

@objc func closeWebView() {
    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
        self.webView.removeFromSuperview()
    }
}

Example of how it should look in the app:

To learn more, we recommend reading the following articles and documentation:

• To access the official documentation, click here.

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.

For the use case using Flutter, it is recommended to use inappwebview.

After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your common flow (which includes IDPay), you will open the inappwebview with the link generated via the API;

• You can customize this opening as needed for your application;

• You will monitor if the URL changes (to the redirectUrl) and then close the inappwebview;

To open an inappwebview and control URL changes, you can do it as follows:

  import 'package:flutter_inappwebview/flutter_inappwebview.dart';  
  import 'package:unico_poc_id_pay_inappwebview/RedirectScreen.dart';
  import 'package:unico_poc_id_pay_inappwebview/service.dart';

  Widget setWebView(String URL_TO_LOAD) {
    InAppWebViewGroupOptions options = InAppWebViewGroupOptions(
        crossPlatform: InAppWebViewOptions(
          useShouldOverrideUrlLoading: true,
          mediaPlaybackRequiresUserGesture: false,
        ),
        android: AndroidInAppWebViewOptions(
          useHybridComposition: true,
        ),
        ios: IOSInAppWebViewOptions(
          allowsInlineMediaPlayback: true,
        ));

    return Expanded(
      child: InAppWebView(
        initialUrlRequest: URLRequest(
          url: Uri.parse(URL_TO_LOAD),
        ),
        initialOptions: options,
        androidOnPermissionRequest: (controller, origin, resources) async {
          return PermissionRequestResponse(
              resources: resources,
              action: PermissionRequestResponseAction.GRANT);
        },
        onWebViewCreated: (controller) {
          setState(() {
            _inAppWebViewController = controller;
          });
        },
        onLoadStart: (controller, url) {
          print('CARREGANDO');
          setState(() {
            _link = url.toString();
          });
        },
        onProgressChanged: (controller, progress) {
          setState(() {
            progress == 100 ? _isLoading = false : _isLoading = true;
          });
        },
        onLoadStop: (controller, url) {
          print('CARREGADO');
          setState(() {
            _link = url.toString();
          });
        },
        shouldOverrideUrlLoading: (controller, navigationAction) async {
          var uri = navigationAction.request.url;
          if (uri == Uri.parse("<URL_TO_OBSERVER>")) {
            setState(() {
              _link = "";
            });

            Navigator.push(
              context,
              MaterialPageRoute(
                builder: (context) => const RedirectSreen(),
              ),
            );
            return NavigationActionPolicy.CANCEL;
          }
          return NavigationActionPolicy.ALLOW;
        },
      ),
    );
  }

To obtain camera permission, you can do it as follows:

  import 'package:permission_handler/permission_handler.dart';

  void requestPermission() async {
    var status = await Permission.camera.status;
    if (status.isDenied) {
      if (await Permission.camera.request().isGranted) {
        print("ok");
      }
    }
  }

To obtain camera permission, you can do it as follows:

For more information, we recommend reading the following articles and documentation:

• To access the official documentation, click here.

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.

For iOS usage, using ASWebAuthenticationSession is one of the recommended approaches.

After creating the transaction and obtaining the transaction link, the following implementation is recommended:

• In your regular flow (which includes IDPay), you will open the ASWebAuthenticationSession with the link generated via API.

• You can customize this opening in the way that works best for your app.

• You will monitor if the URL has changed (to the redirectUrl) and then close the page.

To make the flow work, you need to follow the following steps:

Step 1: Create the Payment Authentication Controller

The first step is to create the payment authentication controller. To do this, create a class called IDPayAuthenticationController (or any name you prefer).

Next, import the AuthenticationServices framework at the top of the class.

Declare the class as NSObject and implement the ASWebAuthenticationPresentationContextProviding protocol.

The result should be:

import AuthenticationServices

class IDPayAuthenticationController: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
           if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
               if let mainWindow = windowScene.windows.first {
                   return mainWindow
               }
           }
           return ASPresentationAnchor()
       }
}

Step 2: Implement Authentication

Open the file where you will perform the authentication and add the necessary imports (in our example, we are doing this in ContentView.swift).

import SwiftUI
import AuthenticationServices

To control the authentication state, we will create a @State property.

@State private var isAuthenticated = false

Create an instance of the IDPayAuthenticationController class outside the body of the ContentView structure.

let idPayController = IDPayAuthenticationController()

To validate the payment, create a function called authenticatePayment.

func authenticatePayment() {
    guard let url = URL(string: "URL_AUTHENTICATION") else { return }

    var session: ASWebAuthenticationSession?
    session = ASWebAuthenticationSession(url: url, callbackURLScheme: "BUNDLE") { callbackURL, error in
        guard callbackURL != nil else {
            if let error = error {
                return print("Erro durante a autenticação: \(error.localizedDescription)")
            }
            return
        }

        // Processa o URL de callback para verificar se a autenticação foi bem-sucedida
        session?.cancel()
        isAuthenticated = true
    }

    session?.presentationContextProvider = idPayController
    session?.prefersEphemeralWebBrowserSession = true
    session?.start()
}

Example of how it should look in the app:

For more information, we recommend reading the following articles and documentation:

To access the official documentation, click here.

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.

To use the Unico IDPay product, there are some prerequisites, which are as follows:

• iOS: From version 11.0 (if opened in WebView, iOS 13 and above).

• Android: From version 5.1 (if opened in WebView, Android 8 and above).

• Desktop: No specific version or OS requirements.

The capture frame provided through the SDK is compatible with the following combinations of browsers and operating systems:

In general, the SDK supports WebRTC and the latest versions of the browsers listed above. For compatibility and security reasons, functionality in very old versions of these browsers is not guaranteed.

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.