> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate the Widget as a WebView

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

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:

```text theme={null}
https://webview.fintoc.com/widget.html
```

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

<Info>
  **Using React Native?**

  To integrate the WebView in a React Native app, use the [`@fintoc/fintoc-react-native`](https://github.com/fintoc-com/fintoc-react-native) library.
</Info>

## 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:

```text Text theme={null}
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.<br />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](/reference/payments-api/checkout-sessions/checkout-sessions-create). 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:

```text theme={null}
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:

```kotlin theme={null}
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()
}
```

```swift theme={null}
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](/docs/payments/overview-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](/docs/resources/widget/widget-events). |

<Warning>
  **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.
</Warning>

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

```kotlin theme={null}
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
  }
}
```

```java theme={null}
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;
  }
});
```

```swift theme={null}
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)
          }
    }
```

<Warning>
  **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.
</Warning>

```xml theme={null}
<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](/docs/resources/test-mode), then confirm your app receives the `fintocwidget://succeeded` redirect.