Integrate the Widget as a WebView

Embed the Fintoc Widget inside your iOS or Android app with a native WebView, configured through URL query parameters.

Integration

To integrate the Widget as a WebView on iOS and Android, load the following URL:

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

Pass the Widget configuration in the query string instead of in client-side JavaScript.

📘
Using React Native?
To integrate the WebView in a React Native app, use the @fintoc/fintoc-react-native library.

How it works

To include the Fintoc WebView in your mobile application, pass the following query parameters to configure it, depending on the product you want to use:

https://webview.fintoc.com/widget.html
  ?public_key=YOUR_PUBLIC_KEY
  &holder_type=individual
  &product=payments
  &country=cl
  &session_token=YOUR_SESSION_TOKEN

Parameter	Type	Description
`public_key`	`string`	Identifies your web application within Fintoc. Links created with a `public_key` are assigned to the organization or user that owns the key. This key also determines the environment: sandbox keys start with `pk_test_`, and production keys start with `pk_live_`.
`holder_type`	`string`	Type of account to connect to Fintoc. One of `business`, `individual`. Not required when `product` is `payments` (Payment Initiation).
`product`	`string`	Product and type of `Link` to create. One of `movements`, `subscriptions`, `invoices`, `payments`.
`country`	`string`	ISO 3166-1 alpha-2 code of the country to connect to. One of `cl`, `mx`. Defaults to `cl`. Not required when `product` is `payments` (Payment Initiation).
`webhook_url`	`string`	URL Fintoc sends a request to after Fintoc creates a `Link`, including the `Link` object's `link_token`. Only the `movements` and `invoices` products use this parameter.
`session_token`	`string`	Token your backend creates with a Checkout Session. The Widget uses `session_token` to load and configure the payment flow. Only used for `payments` (Payment Initiation).
`widget_token`	`string`	The token your backend creates to initialize and configure the Widget for the `subscriptions` product. Only the `subscriptions` product uses `widget_token`.
`link_token`	`string`	Identifier of an existing `Link`. Include it to configure the Widget for a `Link` already created with the `movements` product.

You can also include nested parameters in your query by using the following query string format:

queryString = "
  public_key=YOUR_PUBLIC_KEY
  &holder_type=individual
  &product=movements
  &country=cl
  &link_token=YOUR_LINK_TOKEN
"

Usage example

The following snippets show the WebView set up on Android and iOS:

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.javaScriptCanOpenWindowsAutomatically = 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("product", "payments")
    .appendQueryParameter("public_key", "YOUR_PUBLIC_KEY")
    .appendQueryParameter("session_token", "YOUR_SESSION_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": "YOUR_PUBLIC_KEY",
            "session_token": "YOUR_SESSION_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)
      }
}

The Swift example includes a webView method that handles link clicks inside the WebView. In the example, links open in Safari, but you can customize this behavior. For example, links can open inside the same app. This matters because customers using Payment Initiation can click a link to download the transaction voucher after they finish the payment flow. Allow these links to open so the customer can download the voucher.

WebView redirections

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

Method	Redirect URL	Description
`onSuccess`	`fintocwidget://succeeded`	Fires after the flow finishes successfully.
`onExit`	`fintocwidget://exit`	Fires after your customer closes the Widget before finishing.
`onEvent`	`fintocwidget://event/{event_name}?queryparam={value}`	Fires for every event available on the Widget. For more information about these events, see Widget events.

🚧
onEvent (WebView)
The onEvent event for WebView is enabled by default. Handle the fintocwidget://event/{event_name} redirection in your app so the Widget integration keeps working.

To use these methods on Android and iOS, 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
      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();
      if (action.equals("succeeded")) {
        // onSuccess
      }
      if (action.equals("exit")) {
        // onExit
      }
    }
    return true;
  }
});

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, 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>

Test the integration

Load the WebView with a pk_test_ public key to run against the sandbox environment. Complete the flow with Fintoc's test credentials, then confirm your app receives the fintocwidget://succeeded redirect.