Dashboard
Guides
GuidesAPI Reference

WebView Integration

Reference to integrate the Widget as a WebView on your mobile application

Suggest Edits

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
ParameterTypeDescription
public_keystringThe 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_typestringThe holder_type parameter can be business or individual, and determines the type of account that will be connected to Fintoc. For payment initiation you must always use individual.
productstringThe product parameter can be movements, subscriptions, invoices, or payments, and determines the product and type of Link that will be created.
countrystringThe 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_idstringOptional. 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.
usernamestring or objectOptional. The username pre-fills the username field when making a payment.
The attributes of the username object are below . If a string is sent, it will take the default value for the editable attribute.
webhook_urlstringOnly 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_tokenstringThe 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.

Username Object

To pre-fill a username and change the default values, you can send an object with the following attributes:

username = {
  value: "123456789",
  editable: true
}

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

queryString = "
  public_key=pk_live_XXX
  &holder_type=individual
  &product=payments
  &username[value]=12345678-9
  &username[editable]=false
  &country=cl
  &widget_token=pi_XXX
"

Libraries such as qs can help you automatically format a nested object.

AttributeTypeDescription
valuestringThe username that will be pre-filled on the widget. In Chile you should input the user's RUT and in Mexico you should input the user's phone number.
editableboolWhether the field is editable or not in the widget. By default it's set to true.

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

MethodRedirect URLDescription
onSuccessfintocwidget://succeededThis event will occur after the flow finishes successfully.
onExitfintocwidget://exitThis event will occur after a user closes the Widget prematurely.
onEventfintocwidget://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>

Updated 6 months ago