WebView Integration

Integration

To integrate the Widget using a WebView on iOS and Android, you must use the following HTML:

https://webview.fintoc.com/widget.html

The widget configuration needs to be passed through a querystring instead of using client side JavaScript.

📘
Using React Native?
Check our @fintoc/fintoc-react-native npm library to integrate the WebView to your application quickly!

How it works

When including the Fintoc WebView in your mobile application, you need to pass the following query params to configure it, depending on the product that you want to use:

https://webview.fintoc.com/widget.html
  ?public_key=pk_live_00000
  &holder_type=individual
  &product=payments
  &country=cl
  &widget_token=pi_XXXXXX_sec_YYYYYYYY

Parameter	Type	Description
`public_key`	`string`	The `public_key` is used to identify your web application or web page within Fintoc. Links created with a `public_key` will get assigned to the organization or user that owns said `public_key`. This token will determine whether you're using the sandbox or the production environment. Remember that the `public_key` of the sandbox starts with `pk_test_`, while the production one starts with `pk_live_`.
`holder_type`	`string`	The `holder_type` parameter can be `business` or `individual`, and determines the type of account that will be connected to Fintoc.
`product`	`string`	The `product` parameter can be `movements`, `subscriptions`, `invoices`, or `payments`, and determines the product and type of Link that will be created.
`country`	`string`	The `country` parameter must be the `ISO 3166-1 alfa-2` code of the country to which you're trying to connect. It can be `cl` or `mx`. Defaults to `cl`.
`institution_id`	`string`	Optional. The `institution_id` parameter corresponds to the `id` of a financial institution. If included, said institution will be pre-selected. For example, the value `mx_banco_banamex` would command the widget to open with Banamex by default.
`username`	`string`	Optional. The `username` parameter corresponds to the username of a financial institution. If included it will fill the username field of the financial institution login form and prevent the user from editing it.
`webhook_url`	`string`	Only used for `movements` and `invoices` products, if you are integrating `payments` or `subscriptions` you don't need this. The `webhook_url` parameter corresponds to the URL that will get a request with the new Link after its successful creation, including its link_token.
`widget_token`	`string`	The `widget_token` parameter corresponds to the token created by the backend that initializes and configures the widget. Right now, only the `payments` and `subscriptions` products uses a `widget_token` parameter.

Usage Example

Here are some snippets to get you started as quickly as humanly possible:

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.activity_main)
  supportActionBar?.hide()
    
  val widgetInitizalizationUrl = generateWidgetInitializationUrl()
  
  // Modify Webview settings - all of these settings may not be applicable
  // or necessary for your integration.
  val fintocWebview = findViewById<WebView>(R.id.webview)
  val webSettings = fintocWebview.settings
  webSettings.javaScriptEnabled = true
  webSettings.domStorageEnabled = true
  webSettings.cacheMode = WebSettings.LOAD_NO_CACHE
  webSettings.useWideViewPort = true
  WebView.setWebContentsDebuggingEnabled(true)

  fintocWebview.loadUrl(widgetInitizalizationUrl.toString())
}

private fun generateWidgetInitializationUrl() : Uri {
  val builder = Uri.parse("https://webview.fintoc.com/widget.html")
    .buildUpon()
    .appendQueryParameter("holder_type", "individual")
    .appendQueryParameter("product", "payments")
    .appendQueryParameter("public_key", "pk_live_INSERT_YOUR_API_KEY")
    .appendQueryParameter("widget_token", "pi_INSERT_YOUR_sec_WIDGET_TOKEN")
    return builder.build()
}

import UIKit
import WebKit

class ViewController: UIViewController, WKNavigationDelegate, UIScrollViewDelegate, WKUIDelegate {

    private var webView: WKWebView!

    override func loadView() {
        let webConfiguration = WKWebViewConfiguration()
        webView = WKWebView(frame: .zero, configuration: webConfiguration)
        webView.uiDelegate = self
        view = webView
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        webView.navigationDelegate = self
        webView.allowsBackForwardNavigationGestures = false
        webView.scrollView.bounces = false
        webView.isMultipleTouchEnabled = false
       	webView.configuration.preferences.javaScriptCanOpenWindowsAutomatically = true

        // zoom
        webView.scrollView.delegate = self
        webView.scrollView.minimumZoomScale = 1.0
        webView.scrollView.maximumZoomScale = 1.0

        let url = generateInitializationURL()
        webView.load(URLRequest(url: url))
    }

    override var prefersStatusBarHidden : Bool {
        return true
    }

    @objc(scrollViewWillBeginZooming:withView:) func scrollViewWillBeginZooming(_ scrollView: UIScrollView, with view: UIView?) {
        scrollView.pinchGestureRecognizer?.isEnabled = false
    }

  	func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
        if navigationAction.targetFrame == nil {
            webView.load(navigationAction.request)
        }
        if let url = navigationAction.request.url {
            UIApplication.shared.open(url)
        }
        return nil
    }

    func generateInitializationURL() -> URL {
        let params = [
            "holder_type": "individual",
            "product": "payments",
            "public_key": "pk_live_INSERT_YOUR_API_KEY",
            "widget_token": "pi_INSERT_YOUR_sec_WIDGET_TOKEN",
        ]
        var components = URLComponents()
        components.scheme = "https"
        components.host = "webview.fintoc.com"
        components.path = "/widget.html"
        let queryItems = params.map { URLQueryItem(name: $0, value: $1) }
        components.queryItems = queryItems
        return components.url!
    }
  
    func webView(
      _ webView: WKWebView,
      decidePolicyFor navigationAction: WKNavigationAction,
      decisionHandler: @escaping ((WKNavigationActionPolicy) -> Void)
    ) {
      guard let url = navigationAction.request.url else {
        decisionHandler(.allow)
        return
      }
      let linkScheme = "fintocwidget";
      let actionScheme = url.scheme;
      let actionType = url.host ?? "";
      if actionScheme == linkScheme {
        switch actionType {
          case "succeeded":
          	print("Succeeded!")
          	break
         	case "exit":
          	print("Exited")
            break
          default:
          	print("Another widget action detected: \(actionType)")
          	break
        }
        decisionHandler(.cancel)
        return
      } else {
        decisionHandler(.allow)
      }
}

Notice that the Swift example has a webView method. This method defines what happens when a user clicks on a link inside the WebView. On the example, the link gets opened in Safari, but you can customize this behaviour at will (links could be opened inside the same application, for example). This is important because, when using the Payment Initiation product, after finishing the payment flow the user can click a link to download the transaction voucher. You should allow links to be opened.

WebView Redirections

Once the WebView is integrated, you can interact with its events using redirections.

Method	Redirect URL	Description
`onSuccess`	fintocwidget://succeeded	This event will be occur after a Link gets created successfully.
`onExit`	fintocwidget://exit	This event will occur after a user closes the Widget prematurely.
`onEvent`	fintocwidget://event/{event_name}?queryparam={value}	This event will occur in every event available on the widget. More information about these events can be found here.

🚧
onEvent (WebView)
The onEvent event for WebView is disabled by default and can be enabled by passing the queryparam _on_event={any_value} as a parameter of https://webview.fintoc.com/widget.html (e.g.: https://webview.fintoc.com/widget.html?[...]&_on_event=true). Once enabled, it will be possible to receive onEvent events. Starting May 1st, 2023, this functionality will be enabled by default, so it is necessary to handle the onEvent redirection before this date to avoid breaking the integration with the Widget.

To use these methods on Android and iOS, you can use the following snippets:

webview.webViewClient = object : WebViewClient() {
  override fun shouldOverrideUrlLoading(view: WebView?, url: String?): Boolean {
    val parsedUri = Uri.parse(url)
    if (parsedUri.scheme.equals("fintocwidget")) {
      val action: String? = parsedUri.host
      val linkData: HashMap<String, String?>? = parseLinkUriData(parsedUri)
      if (action.equals("succeeded")) {
        // onSuccess
      }
      if (action.equals("exit")) {
        // onExit
      }
    }
    return true
  }
}

webview.setWebViewClient(new WebViewClient() {
  public boolean shouldOverrideUrlLoading(WebView view, String url) {
    Uri parsedUri = Uri.parse(url);
    if (parsedUri.getScheme().equals("fintocwidget")) {
      String action = parsedUri.getHost();
      HashMap<String, String> linkData = parseLinkUriData(parsedUri);
      if (action.equals("succeeded")) {
        // onSuccess
      }
      if (action.equals("exit")) {
        // onExit
      }
    }
  }
}

func webView(
          _ webView: WKWebView,
          decidePolicyFor navigationAction: WKNavigationAction,
          decisionHandler: @escaping ((WKNavigationActionPolicy) -> Void)
        ) {
          guard let url = navigationAction.request.url else {
            decisionHandler(.allow)
            return
          }
          let linkScheme = "fintocwidget";
          let actionScheme = url.scheme;
          let actionType = url.host ?? "";
          if actionScheme == linkScheme {
            switch actionType {
            case "succeeded":
              // onSuccess
              break
            case "exit":
              // onExit
              break
            default:
              print("Widget action detected: \(actionType)")
              break
            }
            decisionHandler(.cancel)
            return
          } else {
            decisionHandler(.allow)
          }
    }

🚧
iOS - adding fintocwidget URL Scheme
Before integrating the Fintoc widget with your iOS app, it's important to add fintocwidget as a permitted URL scheme inside the app's Info.plist file. This is required for security reasons.

<key>CFBundleURLTypes</key>
	<array>
		<dict>
			<key>CFBundleURLSchemes</key>
			<array>
				<string>fintocwidget</string>
			</array>
			<key>CFBundleURLName</key>
			<string>your.bundle.id</string>
		</dict>
	</array>