Android SDK

Introduction

This Android SDK provides an interface to load Aerosync-UI in native Android application. Securely link your bank account through your bank’s website. Log in with a fast, secure, and tokenized connection. Your information is never shared or sold.

1. Create a User

The Aerosync+Aeronetwork SDKs require a user identifier, aeroPassUserUuid, to be passed to the widget on launch. Follow the guide here to create a new user and access the user's aeroPassUserUuid.

2. Install Bank-Link-Sdk

Add latest verion of _com.aerosync/bank-link-sdk_ library to your project dependencies.

Maven Central: https://central.sonatype.com/artifact/com.aerosync/bank-link-sdk/overview
https://repo1.maven.org/maven2/

<dependency>
    <groupId>com.aerosync</groupId>
    <artifactId>bank-link-sdk</artifactId>
    <version>2.1.0</version>
</dependency>
implementation group: 'com.aerosync', name: 'bank-link-sdk', version: '2.1.0'

3. Minimal example to implement bank-link-sdk

AndroidManifest.xml

 <uses-permission android:name="android.permission.INTERNET"/>

Homepage.kt

package com.aerosync.test_client_android

import android.content.Context
import android.content.Intent
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.widget.Toast
import com.aerosync.bank_link_sdk.EventListener
import com.aerosync.bank_link_sdk.EnvironmentType
import com.aerosync.bank_link_sdk.PayloadEventType
import com.aerosync.bank_link_sdk.PayloadSuccessType
import com.aerosync.bank_link_sdk.Widget
import com.aerosync.bank_link_sdk.Theme

class Homepage : AppCompatActivity(), EventListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_homepage)
    }

    fun onClick(v: View?) {
        when (v?.id) {
            R.id.button -> {
                // open Aerosync widget
                var config = Widget(this, this);
                config.environment =  EnvironmentType.PROD; //SANDBOX, PROD
                config.deeplink = "aerosync://bank-link";
                config.token = "<PROD TOKEN>";
                config.configurationId = "xxx";
                config.aeroPassUserUuid = "xxx";
                config.defaultTheme = Theme.LIGHT;
                config.open();
            }
        }
    }

    override fun onSuccess(event: PayloadSuccessType?, context: Context) {
        // perform steps when user have completed the bank link workflow
        // sample code
        Toast.makeText(context, "onSuccess--> $event", Toast.LENGTH_SHORT).show()
        val intent = Intent(context, Homepage::class.java)
        context.startActivity(intent);
    }

    override fun onEvent(event: PayloadEventType?, context: Context) {
        // capture all the Aerosync events
        // sample code
        Toast.makeText(context, "onEvent--> $event", Toast.LENGTH_SHORT).show()
    }

    override fun onError(error: String?, context: Context) {
        // error handling
        // sample code
        Toast.makeText(context, "onError--> $error", Toast.LENGTH_SHORT).show()
    }

    override fun onClose(context: Context) {
        // when widget is closed by user
        // sample code
        Toast.makeText(context,"widget closed", Toast.LENGTH_SHORT).show()
        val intent = Intent(context, Homepage::class.java)
        context.startActivity(intent);
    }
}

4. Bank Link SDK configuration

ParameterTypeRequiredDescription
tokenstringYes

Request AeroSync Token using GET /aggregatorCredentials endpoint.
Reference:

https://api-aeropay.readme.io/reference/aggregatorcredentials

https://developer.aeropay.com/api/aeropay/doc/

environmentEnvironmentTypeYesPermitted values are [SANDBOX, PROD]
configurationIdstringNoUnique ID that represents the client to apply the customization.
aeroPassUserUuidstringYesAeroNetwork User ID
handleMFAbooleanNohandle the additional MFA for balance refresh workflow
jobIdstringNounique identifier for current job.
Required if handleMFA is true.
connectionIdstringNounique identifier for current Aerosync user.
Required if handleMFA is true.
manualLinkOnlybooleanNoUser will only be able to link their bank manually.
defaultThemeThemeNoLaunch the widget in dark or light mode. Permitted values are Theme.LIGHT / Theme.DARK

5. Aerosync-UI Response:

Bank-Link-SDK will send response for below events:


5.1 onSuccess event

This event is triggered when the user successfully completes the bank-link workflow. The callback receives a PayloadSuccessType object.

PropertyTypeDescription
connectionIdString?The unique identifier for the Aerosync connection in a single-account response. null in a multi-account response; read accounts instead.
clientNameStringThe name of the client associated with the session.
aeroPassUserUuidStringUUID of the authenticated AeroPass user.
accountsList<PayloadSuccessAccount>?Present in the multi-account response, with one entry for each linked account. null in the single-account response. See Section 6.

Single-account response

{
  "connectionId": "xxx",
  "clientName": "xxx",
  "aeroPassUserUuid": "xxx",
  "accounts": null
}

Multi-account response

See Section 6.

{
  "connectionId": null,
  "clientName": "xxx",
  "aeroPassUserUuid": "xxx",
  "accounts": [
    {
      "connectionId": "xxx",
      "accountType": "CHECKING",
      "accountNumberDisplay": "1234"
    }
  ]
}

5.2 onClose event

This event will be triggered when the user closes the AeroSync-UI window. If the user closes the AeroSync-UI window by tapping the 'X' button on any page, the callback function will be called which can be used to navigate the user to the previous page on parent component.

5.3 onEvent event

AeroSync-UI triggers this event on each page load. The callback receives a PayloadEventType object.

PropertyTypeDescription
pageTitleStringThe identifier or title of the page.
onLoadApiStringThe identifier of the API loaded for that page.

Example

{
  "pageTitle": "Verify Your Identity",
  "onLoadApi": "/token"
}

5.4 onError event

Triggered when the WebView or AeroSync-UI fails to load, or a bank/account fails to connect. The callback receives a String describing the error (onError(error: String?, context: Context)) — any error code/message is contained within that string, it is not a structured object.

During the multi-account flow (Section 6), each account that fails to connect is reported through onError, while the accounts that connect successfully are returned via onSuccess — so a single session may fire both.

Example:

Code: AC-200 | Message: We had issues connecting to this banking institution. Please select a different bank or try again later.

6. Multi-account linking (v2.1.0+)

Multi-account linking lets a user link multiple accounts in a single session, returning one connection per selected account.

🚧

Opt-in feature — disabled by default

Multi-account linking is off by default. To enable it for your configurationId, reach out to the Aerosync support team. It is available in com.aerosync:bank-link-sdk v2.1.0+.

Behavior

  • When you launch the widget with a configurationId that has multi-account linking enabled, onSuccess returns the multi-account response:
    • accounts contains a non-null list of linked accounts.
    • The top-level connectionId is null.
  • Otherwise, onSuccess returns the regular single-account response:
    • connectionId is set.
    • accounts is null.
📘

Result handling in multi-account

Every account that connects successfully is returned through onSuccess in the accounts list. If an account fails to connect, the widget reports it through onError.


To integrate

  1. Update com.aerosync:bank-link-sdk to v2.1.0 or later:

    implementation group: 'com.aerosync', name: 'bank-link-sdk', version: '2.1.0'
  2. Pass your configurationId, with multi-account linking enabled, in the widget configuration.

  3. Update your onSuccess handler to read accounts. Check event.accounts != null to distinguish a multi-account response from a single-account response.


// Launch the widget with a configurationId that has multi-account linking enabled.
val config = Widget(this, this)

config.configurationId = "xxx" // Configuration ID with multi-account linking enabled
// Set token, aeroPassUserUuid, environment, and other required configuration values.
config.open()

override fun onSuccess(event: PayloadSuccessType?, context: Context) {
    val accounts = event?.accounts

    if (accounts != null) {
        // Process each account that connected successfully in this session.
        accounts.forEach { account ->
            Log.d(
                "AeroSync",
                "${account.connectionId} ${account.accountType} ${account.accountNumberDisplay}"
            )
        }

        return
    }

    // The standard single-account response includes a top-level connection ID.
    Log.d("AeroSync", "${event?.connectionId}")
}

6.1 PayloadSuccessType

PropertyTypeDescription
connectionIdString?The Aerosync connection ID for the single-account response. null in the multi-account response.
clientNameStringThe name of the client associated with the session.
aeroPassUserUuidStringUUID of the authenticated AeroPass user.
accountsList<PayloadSuccessAccount>?One entry for each linked account in the multi-account response. null for the single-account response.

6.2 PayloadSuccessAccount

PropertyTypeDescription
connectionIdStringThe unique identifier for the Aerosync connection.
accountTypeStringThe account type, such as CHECKING or SAVINGS.
accountNumberDisplayStringThe masked or display account number, showing the last four digits.

Did this page help you?