OAuth Integration

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:

Open Flinks Connect in the system browser using your iframe URL.
Add oauthWindowRedirect=true to enable full-page redirects instead of pop-ups.
Set up an HTTPS universal link (iOS) or App Link (Android) so the OAuth callback returns the user to your app.

Flinks only supports https redirect URIs. Custom URI schemes such as myapp:// are not supported. Use an HTTPS URL that your app claims through universal links or App Links.

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

Returning to your app

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

https://yourapp.com/callback?loginId={loginId}&institution={institution}

Configure your app’s universal link (iOS) or App Link (Android) to open on this HTTPS URL and extract the loginId.

WebView configuration

If you must use a WebView, configure it properly:

iOS
Android
Hybrid (React Native, Flutter)

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

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

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 universal link
Android Chrome	OAuth redirect returns to your app via App Link
WebView	OAuth flow completes without blocked pop-ups

Simulate an OAuth flow in the Toolbox

You can test the full front-end OAuth experience in the Toolbox by adding demoOutbound=true to the iframe URL. This routes the Flinks Capital demo institution through the OAuth flow, so you can walk the OAuth screens end to end with sandbox data.

Generate an Authorize Token

Call /GenerateAuthorizeToken with your customerId, instance, and flinks-auth-key to obtain a token for the iframe. Use the Toolbox credentials.

Load the iframe in OAuth demo mode

Load Flinks Connect with demoOutbound=true and the token you generated:

https://{instance}-iframe.private.fin.ag/v2/?demoOutbound=true&authorizeToken={token}

Walk through the simulated OAuth screens

The demo reproduces the full front-end OAuth sequence:

Consent page
Financial institution selection
FI redirecting page
FI online banking: username / password
FI online banking: consent screen
FI online banking: account selection
Success page (returns the loginId)

demoOutbound=true runs the Flinks Capital demo institution through the OAuth flow, which is how you exercise the OAuth screens in the sandbox. When you’re ready for end-to-end validation against a real OAuth institution, use a client (production) instance.

Getting Started

AI

Connect

Enrich

Pay

Webhooks

Upload

Dashboard

Outbound

Security

Support

Web integration

iframe setup

Handling events

Mobile integration

Recommended approach: system browser

Returning to your app

WebView configuration

Testing

Simulate an OAuth flow in the Toolbox

​Web integration

​iframe setup

​Handling events

​Mobile integration

​Recommended approach: system browser

​Returning to your app

​WebView configuration

​Testing

​Simulate an OAuth flow in the Toolbox

Web integration

iframe setup

Handling events

Mobile integration

Recommended approach: system browser

Returning to your app

WebView configuration

Testing

Simulate an OAuth flow in the Toolbox