WebView Integration
Reference to integrate the Widget as a WebView on your mobile application
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.This parameter is not required for the Payment Initiation product. |
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 . This parameter is not required for the Payment Initiation product. |
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. |
session_token | string | Only used for the Payment Initiation product The sessionToken parameter corresponds to the token created by the backend when creating a Checkout Session and it is used to deploy and configure the Widget. |
widget_token | string | The widget_token parameter corresponds to the token created by the backend that initializes and configures the widget for the Subscriptions product.Right now, only the subscriptions product uses a widget_token parameter. |
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=movements
&country=cl
&link_token=pi_XXX
"
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("product", "payments")
.appendQueryParameter("public_key", "pk_live_INSERT_YOUR_API_KEY")
.appendQueryParameter("session_token", "pi_INSERT_YOUR_sec_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": "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 occur after the flow finishes 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 ofhttps://webview.fintoc.com/widget.html
(e.g.:https://webview.fintoc.com/widget.html?[...]&_on_event=true
). Once enabled, it will be possible to receiveonEvent
events. Starting May 1st, 2023, this functionality will be enabled by default, so it is necessary to handle theonEvent
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 18 days ago