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 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}
loginId.
WebView configuration
If you must use a WebView, configure it properly:
- 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 deep link |
| Android Chrome | OAuth redirect returns to your app via deep link |
| WebView | OAuth flow completes without blocked pop-ups |
