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.6"
}

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

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]


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

Was this section helpful? 

java

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

java

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());
}
});

java

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

java

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());
}
});

java

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());
}
});

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"
}

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



Language option

language String

"en" for English, or "ar" for Arabic.

java

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

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.

Customization guide

Presentation options

dialogMode String

Presents the Link SDK with or without a containing modal.

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


buttonBorderRadius 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

themeColor String

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


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


linkColor String

CTAs and helpers.


overlayColor 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

java

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() {}
);

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