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.
To integrate Lean’s Link SDK, you first need to add the SDK to your front-end by importing it as follows:
<script src="https://cdn.leantech.me/link/sdk/web/latest/Lean.min.js" />
You will then need to include the following div within your body:
<div id="lean-link"></div>
This will enable you to call Lean
globally in your application.
.connect()
The .connect()
method is used to connect a customer to both the Payments and Data API. You can use this method to generate a Payment Source
and an Entity
with a single customer login.
.link()
The .link
method is used to connect accounts with the Data API.
.reconnect()
The .reconnect
method is used to reauthenticate a customer account with the Data API.
.createPaymentSource()
The .createPaymentSource
method is used to connect a bank account as a payment method to your application in the Payments API.
.updatePaymentSource()
The .updatePaymentSource
method is used to authorize an additional payment destination for an existing payment source in the Payments API.
.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.
Was this section helpful?
Lean.connect({app_token: "2c9a80897169b1dd01716a0339e30003",permissions: ["identity", "accounts", "transactions", "balance", "payments"],customer_id: "d57a03bc-ef9d-460b-8fa6-3b17e425326c",payment_destination_id: "f8d6fe12-5cc3-4df2-82c2-48b4dd6f74a7",sandbox: "true",});
Lean.link({app_token: "2c9a80897169b1dd01716a0339e30003",permissions: ["identity", "accounts", "transactions", "balance"],customer_id: "d57a03bc-ef9d-460b-8fa6-3b17e425326c",sandbox: "true",});
Lean.reconnect({app_token: "2c9a80897169b1dd01716a0339e30003",reconnect_id: "e9521dc4-adc6-4c09-9994-f8b13f28db85",sandbox: "true",});
Lean.createPaymentSource({app_token: "2c9a80897169b1dd01716a0339e30003",customer_id: "d57a03bc-ef9d-460b-8fa6-3b17e425326c",payment_destination_id: "f8d6fe12-5cc3-4df2-82c2-48b4dd6f74a7",sandbox: "true",});
Lean.updatePaymentSource({app_token: "2c9a80897169b1dd01716a0339e30003",customer_id: "d57a03bc-ef9d-460b-8fa6-3b17e425326c",payment_source_id: "88d7aefe-aae6-4eb3-a314-6e60e73fda35",payment_destination_id: "f8d6fe12-5cc3-4df2-82c2-48b4dd6f74a7",sandbox: "true",});
Lean.pay({app_token: "2c9a80897169b1dd01716a0339e30003",payment_intent_id: "452bcde4-5e48-44bb-8f6d-40c5c286466b"sandbox: "true"});
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.
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
.
String
Description of the event that has triggered the webhook.
Object
The resource which has triggered the webhook.
Upon entity creation, this will be the entity
object:
String
The identifier you will use to reference your customer's bank entity when making API calls.
String
For your convenience, we’ll also pass the id your application uses to reference your customer.
Array
The permissions your customer granted you.
Object
Attributes related to the bank that the entity originates from.
String
The name of the bank where your user's entity and accounts exist.
String
For use with the /bank
endpoint, allows you to query data on the bank related to the entity.
String
A URL pointing to an image of the bank's logo.
String
The HEX value of the primary color the bank uses for display purposes.
String
The HEX value of the secondary color the bank uses for display purposes.
DateTime
The time at which the webhook was triggered.
// 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"}
The Web SDK takes an optional parameter for callback
which allows you to recieve events on SDK close, completion or error. The object returned to your callback function is in the following format:
status enum
The end status of the LinkSDK at close.
Status | Reason |
---|---|
SUCCESS | The initated flow was completed successfully |
USER_CANCELLED | The initiated flow was cancelled by the user |
ERROR | The 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.
value | screen |
---|---|
INITIAL | The first screen displayed to users |
RECONNECT_INITIAL | The first screen displayed to users when using .reconnect() |
BANK_SELECTION | The bank list screen |
OPEN_BANKING | Open banking redirect initiation |
CONSENT | The permissions screen |
CREDENTIALS | The login detail entry screen |
CREDENTIALS_UPDATE | The re-entry form for login details when credentials are outdated |
MFA | The OTP entry screen |
OPEN_BANKING_ENABLE_PAYMENTS | Open banking redirect initiation for payments |
PAYMENT_SOURCES | The screen that lists all a user's payment sources prior to payment initiation |
UPDATE_PAYMENT_SOURCE | The update payment source consent screen |
PAYMENT_DETAILS | The payment initiation screen |
SECURITY_QUESTION | The security question answer form |
MFA_INSTRUCTIONS | The instructions for entering an OTP |
UNSUPPORTED_BANK_REQUEST | The unsupported bank list screen |
SUCCESS | The success screen |
FAIL | The 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_identifier enum
The Lean identifier for the bank.
is_supported bool
Whether the bank is supported by Lean or not (is false
when a user selects a bank through the 'My bank is not listed' button)
function myCallback(status) {console.log(status);// insert actions you want to perform on SDK close}connectButton.addEventListener("click", function () {Lean.link({app_token: "YOUR_APP_ID",permissions: ["identity", "accounts", "transactions", "balance"],customer_id: customerId.value,sandbox: "false",callback: myCallback,});});
{"status": "SUCCESS","message": "User successfully connected their account","last_api_response": "SUCCESS","exit_point": "SUCCESS","secondary_status": "SUCCESS","bank": {"bank_identifier": "ENBD_UAE","is_supported": true}}
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": "SUCCESS","message": "User successfully connected their account","last_api_response": "SUCCESS","exit_point": "SUCCESS","secondary_status": "SUCCESS","bank": {"bank_identifier": "SIB_UAE","is_supported": false}}
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 .link()
and .createPaymentSource
flows.
You can get a list of available bank_identifiers
for your application by making a call to the /banks/
endpoint.
curl -X GET 'https://api.leantech.me/banks/v1/' \--header 'lean-app-token: 2c9a80897169b1dd01716a0339e30003'
// example 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": "ENBD_UAE","name": "Emirates NBD","main_color": "#FDB813","background_color": "#06357A","theme": "light","country_code": "UAE","active": true,"traits": ["auth-credentials"],"supported_account_types": ["CREDIT","SAVINGS","CURRENT"]}
Lean.link({app_token: "2c9a80897169b1dd01716a0339e30003",permissions: ["identity", "accounts", "transactions", "balance"],customer_id: "552e8102b3c14401a36ac14fadab94de",sandbox: "true",bank_identifier: "ENBD_UAE",});
Lean.createPaymentSource({app_token: "2c9a80897169b1dd01716a0339e30003",customer_id: "552e8102b3c14401a36ac14fadab94de",sandbox: "true",bank_identifier: "ENBD_UAE",});
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.
// Payment Source - available from /customers/v1/{customer_id}/payment-sources{"id": "0cb405e4-dbda-4420-9421-5202111934cb","customer_id": "79ed9723-f409-4b21-b7b6-8678be94383d","app_id": "40289089716ab818017178bc1cff0005","bank_identifier": "HSBC_UAE","status": "ACTIVE","beneficiary_cool_off_expiry": null,"accounts": [{"id": "ec02035e-bff8-4ada-832e-c3a71105ba48","account_id": "c6d2121b-7e3a-4ce0-9f47-905497a23b2d","account_name": "CURRENT ACCOUNT","account_number": "030-798508-001","iban": "AE870200000030798508001","balance": 465.38,"currency": "AED","balance_last_updated": "2021-03-01T17:07:30.172853Z"}]},
Lean.pay({app_token: "2c9a80897169b1dd01716a0339e30003",payment_intent_id: "452bcde4-5e48-44bb-8f6d-40c5c286466b"sandbox: "true",account_id: "ec02035e-bff8-4ada-832e-c3a71105ba48"});
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 →String
Buttons background color, active input borders, and loading spinners.
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.
String
CTAs and helpers.
String
Overlay containing the Link SDK dialog box.
The following color formats are supported:
Example | Format |
---|---|
"#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 |
Lean.link({app_token: "123",customer_id: "123",permissions: ["identity", "balance", "accounts", "transactions"],sandbox: true,customization: {theme_color: string,button_text_color: string,link_color: string,overlay_color: string,},});
In order to mitigate potential cross-site scripting issues, most modern browsers use a Content Security Policy (CSP). These policies might prevent the SDK from correctly displaying the images captured during the flow or correctly load styles. If CSP is blocking some of the SDK functionalities, make sure you add the following snippet inside the >head<
tag of your application.
<metahttp-equiv="Content-Security-Policy"content="default-src 'self' https://cdn.leantech.me;script-src 'self' https://cdn.leantech.me;style-src 'self' https://cdn.leantech.me;connect-src blob: https://link.sandbox.leantech.me https://link.leantech.me https://ipv4.icanhazip.com https://ipv6.icanhazip.com https://api.ipify.org https://api6.ipify.org https://graphql.contentful.com https://api.segment.io;img-src 'self' data: https://images.ctfassets.net http://images.contentful.com https://graphql.contentful.com https://cdn.leantech.me;media-src blob:;object-src 'self' blob:;frame-src 'self' data: blob:;"/>
With the Link SDK installed in your application, you can now get entity_id
s for the Data API and create payment sources and charges with the Payment API.