OAuth Integration

Set up Flinks Connect with OAuth for web and mobile platforms, including deep linking and WebView configuration.

Many US financial institutions use OAuth for authentication. When a customer selects an OAuth-supported institution in Flinks Connect, they are redirected to their bank’s website to authorize the connection, then redirected back.

Web integration

iframe setup

Embed Flinks Connect as an iframe with the required redirectUrl parameter:

<iframe
  height="760"
  src="https://{instance}-iframe.private.fin.ag/?redirectUrl=https://example.com/callback&consentEnable=true"
></iframe>

Handling events

Use the Event Listener to track the OAuth flow:

<script>
  window.addEventListener("message", function (e) {
    const data = e.data;
    switch (data.step) {
      case "APP_MOUNTED":
        // Flinks Connect loaded successfully
        break;
      case "INSTITUTION_SELECTED":
        // User selected their financial institution
        break;
      case "REDIRECT":
        // User completed the flow — capture the loginId
        console.log("loginId:", data.loginId);
        break;
      case "POPUP_BLOCKED":
        // OAuth pop-up was blocked by the browser
        break;
      case "POPUP_OPENED":
        // OAuth authorization window opened
        break;
    }
  });
</script>

Ensure your website allows pop-ups from the Flinks domain, as OAuth connections open the bank’s authorization page in a new window.

Mobile integration

For mobile apps, OAuth requires special handling because WebViews may not fully support the redirect flow.

Recommended approach: system browser

Use the device’s system browser (Safari on iOS, Chrome on Android) instead of a WebView for the best OAuth experience:

1. Open Flinks Connect in the system browser using your iframe URL.
2. Add oauthWindowRedirect=true to enable full-page redirects instead of pop-ups.
3. Set up a deep link or universal link so the OAuth callback returns the user to your app.

https://{instance}-iframe.private.fin.ag/?oauthWindowRedirect=true&redirectUrl=myapp://callback&...

Deep linking

After the OAuth flow completes, Flinks redirects to your redirectUrl with the loginId:

myapp://callback?loginId={loginId}&institution={institution}

Configure your app to handle this deep link and extract the loginId.

WebView configuration

If you must use a WebView, configure it properly:

iOS

• Use SFSafariViewController or ASWebAuthenticationSession for the OAuth flow
• Standard WKWebView may block redirects to external domains
• Ensure your app’s domain is properly configured for universal links

Android

• Enable JavaScript in your WebView: webView.getSettings().setJavaScriptEnabled(true)
• Enable DOM storage: webView.getSettings().setDomStorageEnabled(true)
• Handle external URLs by opening them in the system browser

Hybrid (React Native, Flutter)

• Set webview=true in the iframe URL parameters
• Use oauthWindowRedirect=true for OAuth institutions
• Handle the redirect URL in your native code to capture the loginId

Testing

Test your OAuth integration across multiple environments:

Platform	What to verify
Desktop browser	Pop-up opens and redirects work correctly
iOS Safari	OAuth redirect returns to your app via deep link
Android Chrome	OAuth redirect returns to your app via deep link
WebView	OAuth flow completes without blocked pop-ups

Use the Toolbox sandbox with Flinks Capital for initial testing. Note that Flinks Capital does not use OAuth — you’ll need to test OAuth flows with real US institutions in your production environment.