Lean's Link Android SDK is a Kotlin library, distributed as a AAR/JAR and distributed via Jitpack.

To get started update your project level build.gradle to include jitpack:

repositories {
        maven { url 'https://jitpack.io'}
}

Next, add this dependency code to your module's build.gradle file:

dependencies {
    implementation "me.leantech:link-sdk-android:X.X.X"

The latest version is:

Demo app

In order to test out Lean's android Link SDK, please refer to this guide.

Usage

Create a new lean instance with the .Builder() method and pass your app token and list of permissions that you want your user to grant.

These two parameters are necessary and Lean will not be initialised without these.

showLogs() is used to show some basic logs such as which step the user reached etc.

val lean = Lean.Builder()
    .setAppToken("YOUR_APP_TOKEN")
    .setVersion("latest")
    .showLogs()
    .sandbox(true)
    .build()

LeanListener

Each call to lean's method requires passing a LeanListener object which notifies you if the process finished successfully or failed somewhere in between.

lean.connect(requireActivity(), "customer_id", "bank_identifier", ArrayOf[Lean.UserPermissions], object : LeanListener {
    override fun onSuccess() {
    }
    
    override fun onFailure(lastStep: StepCompleted) {
    }
})

onSuccess() is called when the user has successfully has finished all the steps and has logged into their bank account. Once this is complete, your backend has to call lean api the token associated with this user to fetch their bank account details.

onFailure() is called if for any reason the user was unable to finish the process. This method returns lastStep enum value which tells the last step at which the flow was quit.

lastStep is an enum and can have the following values:

Init & Reconnect

STARTSDK initialisation had started
APPLICATION_INFOApplication info screen was shown
PERMISSION_SELECTIONPermissions screen was shown and user selected some permissions and proceeded to the bank list screen
BANK_LISTLast shown screen was bank list
BANK_CHOSENBank was chosen
BANK_LOGIN_FAILBank login failed due to wrong creditials
OTPBank login was success and otp screen was last screen shown
OTP_FAILOTP entry failed due to incorrect OTP
ERROR_MFA_REQUEST_IDThis is a special case which ideally should not happen. This happens when in the collectOtp flow, the passed mfaRequestId is incorrect.

Payment Source

SOURCE_BANK_LISTList of banks for payment source adding process was shown
SOURCE_LOGIN_MFALogin OTP screen shown
SOURCE_BENEFICIARY_MFABeneficiary OTP screen shown
SOURCE_ADDING_COMPLETEAdding the beneficiary was successful
SOURCE_ADDING_FAILEDPayment source adding failed
SOURCE_OTP_FAILEDOTP entry failed due to incorrect OTP
SOURCE_BANK_LOGIN_FAILEDCredentials provided by the user for bank login was incorrect

Payment Source

PAYMENT_SOURCE_LISTList of bank accounts to pay from shown
PAYMENT_LOGIN_MFALogin OTP screen shown
PAYMENT_MFAPayment OTP screen shown
PAYMENT_OTP_FAILEDOTP entry failed due to incorrect OTP
INITIATING_PAYMENT_FAILEDConfirming payment failed
PAYMENT_FAILEDEither the payment failed or was rejected by the bank
PAYMENT_CONFIRMConfirm payment screen last shown
PAYMENT_COMPLETEPayment was successful

Available Methods

.connect()

The connect method is used to enable a customer to use a single log in to create and Entity and a PaymentSource for use with the Data API and Payments API respectively.

lean.connect(
    Activity, customer_id, bankId, paymentDestinationId, userPermissionsArray, customization, new Lean.LeanListener() {
    @Override
    public void onSuccess() {
        Log.d("LEAN_SDK", "SUCCESS");
    }

    @Override
    public void onFailure(@NotNull Lean.StepCompleted lastStep) {
        Log.e("LEAN_SDK", "FAILED -> " + lastStep.toString());
    }
});

.reconnect()

The reconnect method is used to re-authenticate a customer account with the Data API.

lean.reconnect(
    Activity, reconnect_id, customization, new Lean.LeanListener() {
        @Override
        public void onSuccess() {
            Log.d("LEAN_SDK", "SUCCESS");
        }

        @Override
        public void onFailure(@NotNull Lean.StepCompleted lastStep) {
            Log.e("LEAN_SDK", "FAILED -> " + lastStep.toString());
        }
});

.createBeneficiary()

The createBeneficiary method is used to authorize an additional payment destination for an existing payment source in the Payments API.

NOTE: We have renamed the updatePaymentSource() method on the Link SDK. It will now be called createBeneficiary(). The updatePaymentSource() method is now deprecated. Please use the new method as detailed below.

lean.createBeneficiary(
    Activity, customer_id, payment_source_id, payment_destination_id, customization, new Lean.LeanListener() {
    @Override
    public void onSuccess() {
        Log.d("LEAN_SDK", "SUCCESS");
    }

    @Override
    public void onFailure(@NotNull Lean.StepCompleted lastStep) {
        Log.e("LEAN_SDK", "FAILED -> " + lastStep.toString());
    }
});

.pay()

The pay method is used to make a bank to bank transfer from your customer's account to your account in the Payments API.

lean.pay(
    Activity, payment_intent_id, showBalances, account_id, customization, new Lean.LeanListener() {
    @Override
    public void onSuccess() {
        Log.d("LEAN_SDK", "SUCCESS");
    }

    @Override
    public void onFailure(@NotNull Lean.StepCompleted lastStep) {
        Log.e("LEAN_SDK", "FAILED -> " + lastStep.toString());
    }
});

The show_balances parameter is optional and allows you to show/hide the balances of bank accounts when an end user is going through the payment authorization flow. It's RECOMMENDED to always "HIDE" the balances.

๐Ÿ“˜

Attention!

The authorize() method only applies to the Corporate Payment flow.

.authorize()

lean.authorize(
    Activity, customer_id, end_user_id, payment_intent_id, customization, new Lean.LeanListener() {
    @Override
    public void onSuccess() {
        Log.d("LEAN_SDK", "SUCCESS");
    }

    @Override
    public void onFailure(@NotNull Lean.StepCompleted lastStep) {
        Log.e("LEAN_SDK", "FAILED -> " + lastStep.toString());
    }
});

Callback functions

The iOS SDK takes an optional parameter for callback which allows you to receive events on SDK close, completion or error.

Response

The responseObject returned to your callback function is in the following format:

{
  "status": "SUCCESS",
  "message": "User successfully connected their account",
  "last_api_response": "SUCCESS",
  "exit_point": "SUCCESS",
  "secondary_status": "SUCCESS",
  "bank": {
    "bank_identifier": "LEANMB1",
    "is_supported": true
  }
}

status enum
The end status of the LinkSDK at close.

StatusReason
SUCCESSThe initiated flow was completed successfully
CANCELLEDThe initiated flow was cancelled by the user
ERRORThe SDK or user experienced an error - the details for the error are available in the message and secondary_status.

message string

Further details on the end state. May be null.

last_api_response string

Details on the last response status from the Lean API. May be null.

exit_point enum

The last screen displayed before the user exited the SDK.

valuescreen
INITIALThe first screen displayed to users
RECONNECT_INITIALThe first screen displayed to users when using .reconnect()
BANK_SELECTIONThe bank list screen
OPEN_BANKINGOpen banking redirect initiation
CONSENTThe permissions screen
CREDENTIALSThe login detail entry screen
CREDENTIALS_UPDATEThe re-entry form for login details when credentials are outdated
MFAThe OTP entry screen
OPEN_BANKING_ENABLE_PAYMENTSOpen banking redirect initiation for payments
PAYMENT_SOURCESThe screen that lists all a user's payment sources prior to payment initiation
UPDATE_PAYMENT_SOURCEThe update payment source consent screen
PAYMENT_DETAILSThe payment initiation screen
SECURITY_QUESTIONThe security question answer form
MFA_INSTRUCTIONSThe instructions for entering an OTP
UNSUPPORTED_BANK_REQUESTThe unsupported bank list screen
SUCCESSThe success screen
FAILThe failure screen

secondary_status enum

Further details on failures e.g. INVALID_CREDENTIALS. May be null.

bank object

Details on the bank selected by the user.

bank.bank_identifier enumThe Lean identifier for the bank.
bank.is_supported boolWhether the bank is supported by Lean or not (is false when a user selects a bank through the 'My bank is not listed' button)

Unsupported banks

Your users can indicate that their bank is not supported. When this happens, the callback from the LinkSDK will contain a false flag in the bank object.

{
  "status": "CANCELLED",
  "message": "User cancelled the operation",
  "exit_point": "UNSUPPORTED_BANK_REQUEST_SUCCESS",
  "last_api_response": "CANCELLED",
  "secondary_status": "CANCELLED",
  "bank": {
    "bank_identifier": "AHB_UAE",
    "is_supported": false
  }
}

Skip Bank List

In some use cases you may want to provide your own UI for the bank selection screen in the LinkSDK. This can be achieved by passing in a bank_identifier during the .connect() flow.

You can get a list of available bank_identifiers for your application by making a call to the /banks/ endpoint.

Call:

curl -X GET 'https://api.leantech.me/banks/v1/' \
  --header 'lean-app-token: 2c9a80897169b1dd01716a0339e30003'

Response:

[
    {
        "id": 13,
        "identifier": "FAB_UAE",
        "name": "First Abu Dhabi Bank",
        "main_color": "#ffffff",
        "background_color": "#00458A",
        "theme": "light",
        "country_code": "UAE",
        "active": true,
        "traits": [
            "user-input-on-login",
            "auth-credentials"
        ],
        "supported_account_types": [
            "CREDIT",
            "SAVINGS",
            "CURRENT"
        ]
    },
    {
        "id": 12,
        "identifier": "LEANMB1",
        "name": "Lean Mock Bank",
        "main_color": "#FDB813",
        "background_color": "#06357A",
        "theme": "light",
        "country_code": "UAE",
        "active": true,
        "traits": [
            "auth-credentials"
        ],
        "supported_account_types": [
            "CREDIT",
            "SAVINGS",
            "CURRENT"
        ]
    }

You can then use the bank identifier directly with the LinkSDK to skip the bank selection screen:

lean.connect(
    Activity, customer_id, bankIdentifer, paymentDestinationId, userPermissionsArray, customization, new Lean.LeanListener() {
    @Override
    public void onSuccess() {
        Log.d("LEAN_SDK", "SUCCESS");
    }

    @Override
    public void onFailure(@NotNull Lean.StepCompleted lastStep) {
        Log.e("LEAN_SDK", "FAILED -> " + lastStep.toString());
    }
});

Skip Payment Source selection

In Some use cases, you may want to render your own list of Payment Sources - or have business logic around which payment source can be used to make a specific payment. In these cases, you can pass the accounts[n].id parameter from a Customer's Payment Source into the LinkSDK to skip the selection screen within the SDK.

How to get Payment Sources for a Customer

lean.pay(
    Activity, payment_intent_id, showBalances, account_id, customization, new Lean.LeanListener() {
      //if you add the account ID the payment source will be skipped
    @Override
    public void onSuccess() {
        Log.d("LEAN_SDK", "SUCCESS");
    }

    @Override
    public void onFailure(@NotNull Lean.StepCompleted lastStep) {
        Log.e("LEAN_SDK", "FAILED -> " + lastStep.toString());
    }
});

Changing the SDK language

Link SDK is available in English and Arabic, fully supported with a right-to-left UI, including text alignment, icons and images. If no language is provided the default is English. The language parameter is provided to the Lean.Builder()

val lean = Lean.Builder()
    .setLanguage("ar")
    ...

Language option

language enum

enEnglish
arArabic

Customizing Link SDK

We are progressively releasing customization capabilities to the Link SDK to match its UI with your application branding style. This allows customers to programmatically theme the Link SDK directly from any of the methods.

For more detailed documentation on how best to use the customization feature see our guides.

Customisation Guide

Presentation options

dialog_mode string

Presents the Link SDK with or without a containing modal.

"contained" for modal (default), or "uncontained" for no modal.

button_border_radius string

Change the shape of the main button on each step. See guidance for examples.

A unitless number as a String. Options:

ValueStyle
"4"default
"8"Border radius of 8px
"0"Rectangle button
"pill"Always pill shaped, whatever the button height

Color options

theme_color string

Buttons background color, active input borders, and loading spinners.

button_text_color string

Elements inside any primary button such as the text, icons and the loading spinner. It is useful to boost readability of the button color.

link_color string

CTAs and helpers.

overlay_color string

Overlay containing the Link SDK dialog box.

The following color formats are supported:

ExampleFormat
"#000000"Hex
"#000"Shorthand hex
"#000000FF"Hex with alpha
"rgb(0, 0, 0)"Comma separated RGB
"rgba(0, 0, 0, 0.5)"Comma separated RGB with Alpha
"black"Color name

Example

Lean.Customization linkCustomization = new Lean.Customization();

linkCustomization.setThemeColor("#0080ff");
linkCustomization.setButtonTextColor("#ffffff");
linkCustomization.setLinkColor("#0080ff");
linkCustomization.setOverlayColor("rgba(0, 0, 0, 0.8)");
linkCustomization.setButtonBorderRadius("8");
linkCustomization.setDialogMode("uncontained");

lean.connect(
    Activity,
    customer_id,
    bankId,
    paymentDestinationId,
    userPermissionsArray,
    linkCustomization,
    new Lean.LeanListener() {}
);