Link SDK

Link is Lean’s official SDK that leverages the capabilities of modern browsers and mobile clients, such as asynchronous communication, encryption at REST, transit and much more, while giving you an optimised, customizable, conversion-optimized user journey for your users to connect their accounts.

How to integrate

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:

java

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

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

java

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

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.

java

val lean = Lean.Builder()
.setAppToken("YOUR_APP_TOKEN")
.setVersion("1.6.0")
.showLogs()
.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.

java

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

onSucesss() 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.

List of lastStep Enums

Init & Reconnect

START - SDK initialisation had started

APPLICATION_INFO - application info screen was shown

PERMISSION_SELECTION - permissions screen was shown and user selected some permissions and proceeded to the bank list screen

BANK_LIST - last shown screen was bank list

BANK_CHOSEN - bank was chosen

BANK_LOGIN_FAIL - bank login failed due to wrong creditials

OTP - bank login was success and otp screen was last screen shown

OTP_FAIL - OTP entry failed due to incorrect OTP

ERROR_MFA_REQUEST_ID - this 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_LIST - List of banks for payment source adding process was shown

SOURCE_LOGIN_MFA - Login OTP screen shown

SOURCE_BENEFICIARY_MFA - Beneficiary OTP screen shown

SOURCE_ADDING_COMPLETE - Adding the beneficiary was successful.

SOURCE_ADDING_FAILED - Payment source adding failed

SOURCE_OTP_FAILED - OTP entry failed due to incorrect OTP

SOURCE_BANK_LOGIN_FAILED - Credentials provided by the user for bank login was incorrect

Making Payment

PAYMENT_SOURCE_LIST - List of bank accounts to pay from shown

PAYMENT_LOGIN_MFA - Login OTP screen shown

PAYMENT_MFA - Payment OTP screen shown

PAYMENT_OTP_FAILED - OTP entry failed due to incorrect OTP

INITIATING_PAYMENT_FAILED - Confirming payment failed

PAYMENT_FAILED - Either the payment failed or was rejected by the bank

PAYMENT_CONFIRM - Confirm payment screen last shown

PAYMENT_COMPLETE - Payment was successful

Available Methods

.link()

The .link method is used to connect accounts with the Data API.

[see reference]


.reconnect()

The .reconnect method is used to reauthenticate a customer account with the Data API.

[see reference]


.createPaymentSource()

The .createPaymentSource method is used to connect a bank account as a payment method to your application in the Payments API.

[see reference]


.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.

[see reference]

Was this section helpful? 

java

lean.init(
Activity, customer_id, bank_identifier, permissions, 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());
}
}
);

java

lean.reconnect(
Activity, reconnect_id, 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());
}
});

java

lean.createPaymentSource(
Activity, customer_id, bank_identifer, 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());
}
});

java

lean.pay(
Activity, payment_intent_id, showBalances, account_id, 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());
}
});

Webhook URL

Results from the Link SDK will be sent to your server via a POST request from Lean made to the Webhook URL in the application settings.

Response

type String

The type of the webhook being received in the format of: [Object type].[action]. When triggered by the Lean.link() call, the type will be entity.created.


message String

Description of the event that has triggered the webhook.


payload Object

The resource which has triggered the webhook.

Upon entity creation, this will be the entity object:

View child attributes

id String

The identifier you will use to reference your customer's bank entity when making API calls.


app_user_id String

For your convenience, we’ll also pass the id your application uses to reference your customer.


permissions Array

The permissions your customer granted you.


bank_details Object

Attributes related to the bank that the entity originates from.

View child attributes

name String

The name of the bank where your user's entity and accounts exist.


bank_identifier String

For use with the /bank endpoint, allows you to query data on the bank related to the entity.


logo_url String

A URL pointing to an image of the bank's logo.


main_color String

The HEX value of the primary color the bank uses for display purposes.


background_color String

The HEX value of the secondary color the bank uses for display purposes.


timestamp DateTime

The time at which the webhook was triggered.

json

// Success Example
{
"type": "entity.created",
"message": "An entity object has been created.",
"payload": {
"id": "f08fb010-878f-407a-9ac2-a7840fb56185",
"app_user_id": "00001",
"permissions": ["transactions", "balance", "identity", "accounts"],
"bank_details": {
"name": "Lean Mockbank",
"identifier": "LEANMB1_SAU",
"logo": "https://cdn.leantech.me/img/banks/white-lean.png",
"main_color": "#1beb75",
"background_color": "#001E26"
}
},
"timestamp": "2020-10-10T17:19:00.059933Z"
}

Next Steps

With the Link SDK installed in your application, you can now get entity_ids for the Data API and create payment sources and charges with the Payment API.

Data API Reference

Payments API Reference