Connect for Android

Overview

The MoneyKit Connect SDK offers a fast and secure method to connect bank accounts directly within your Android application. This pre-built framework facilitates linking to a financial institution within your app, ensuring the handling of connections without transmitting sensitive data to your server.

Installation

Add the following line to your app's build.gradle file:

implementation("com.moneykit:connect:0.1.0")

Opening MoneyKit Connect

Before you can open Connect, you need to first create a link_session_token.

A link_session_token can be configured for different flows and is used to control much of the behavior.

Create a Configuration

Starting the MoneyKit Connect flow begins with creating a link_session_token on your server via the MoneyKit API.

Once the link_session_token is passed to your app

1. create an instance of MkConfiguration,
2. then create an instance of MkLinkHandler passing in the previously created MkConfiguration,
3. and call presentLinkFlow(context) on the handler.

val linkSessionToken: String = "your_link_session_token"

val configuration = MkConfiguration(
    sessionToken = linkSession.linkSessionToken,
    onSuccess = { successType ->
        when (successType) {
            is MkLinkSuccessType.Linked -> {
                Timber.i("Linked - Token to exchange: ${successType.institution.token.value}")
                // At this point you should send the exchangeable token to your server, and your
                // server should exchange it via the MoneyKit API for a reusable link token.
            }

            is MkLinkSuccessType.Relinked -> {
                Timber.i("Relinked")
                // At this point you can inform your server that the link is live again
            }
        }
    },
    onExit = {
        if (error != null) {
            Timber.e(error.displayedMessage)
        }
      
        Timber.i("Exited Link")
    },
)

Create a Handler

A Handler is a one-time use object used to open a MoneyKit Connect session. The Handler must be retained for the duration of the Connect flow. It will also be needed to respond to OAuth redirects.

let linkHandler = MkLinkHandler(configuration: configuration)

Open MoneyKit Connect

Finally, open Connect by calling presentLinkFlow(context) on the Handler object. This will usually be done in a button’s click handler. Context should be your current activity.

linkHandler.presentLinkFlow(this)

OAuth Handling

Some configuration is required to allow your app to receive OAuth redirect URLs from Bank apps on user devices. Note that this does not currently apply to the Android Connect SDK for OAuth handled on webpages, as webpage redirects are handled directly within the SDK, but it is still important to follow this step to ensure compatibility with app-to-app authorization in the future.

Manifest

Your app's manifest file AndroidManifest.xml will need to have an intent-filter added to the activity which should receive the redirect from the bank auth app. This may be the activity which normally launches MoneyKit Connect, but if the app needs to e.g. verify that the user is logged in or perform other launch activities in a launch activity, then the intent filter will need to be for that launch activity, which must then perform navigation to the Connect activity. The intent filter should be as follows, with whatever scheme and host you wish to use for your app.

The example below will use moneykitexample://oauth as its redirect URI when initializing its link session.

<intent-filter>
    <action android:name="android.intent.action.VIEW" />

    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data
        android:host="oauth"
        android:scheme="moneykitexample" />

</intent-filter>

Intent Handling in Activity

Now that the Activity is set up to receive deep links, it must look for Intents related to OAuth redirect deep links. It should do this in 2 places:

• in the onCreate method, in case the Activity was launched by a deeplink intent,
• and in the onNewIntent method, in case an already running instance of the Activity received the intent.

class ConnectToBankActivity : Activity() {
    ...

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        ...

        intent?.let {
            handleOauthRedirectIntent(intent)
        }
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)

        intent?.let {
            handleOauthRedirectIntent(it)
        }
    }

    private fun handleOauthRedirectIntent(intent: Intent) {
        // If the intent is for a deeplink, the 'data' property will be set
        val uri = intent.data ?: return

        // Verify that the URI matches the correct pattern to be an oauth redirect URI here - i.e. check that
        // its schema and hostname match what you defined in the intent filter above

        // Once verified, you should access your linkHandler which has been configured with the link session token
        // you started the OAuth flow with, and instruct it to continue the OAuth flow with the received redirect URI.
        // You must also provide your Activity as context to allow the Connect UI to be started.
        linkHandler.continueFlow(this, uri)
    }

Depending on various factors relating to Android's handling of resources and processes for backgrounded apps, the linkHandler instance you originally configured when launching the Connect instance which triggered this OAuth flow may not still be available to you at this point, so it is necessary to persist your link_session_token so that you can reconfigure and reinitialise a linkHandler instance to complete the OAuth flow in every circumstance.

To see a complete example of a way to implement this, please refer to our Android example project.