Web
How to integrate
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/loader/prod/sa/latest/lean-link-loader.min.js"></script>
This will enable you to call Lean
globally in your application.
When to load Link Loader
To ensure a seamless user experience your application should load the Link Loader script at initialization or on page load, not when the user initiates account connection or payment.
Loading the CDN files as recommended will allow for the both the SDK and the iframe wrapper to be setup and ready for when you call a Lean method.
Available Methods
.connect()
The connect
method is used to connect a customer to the Data API. You can use this method to generate an Entity
with a single customer login.
Lean.connect({
app_token: "YOUR_APP_TOKEN",
customer_id: customer_id,
permissions: [
"identity","accounts","balance","transactions", "identities",
"scheduled_payments", "standing_orders", "direct_debits", "beneficiaries"
],
sandbox: true,
fail_redirect_url: "",
success_redirect_url: "",
access_from: "2018-11-01T00:00:00+4:00", //optional
access_to: "2022-11-01T00:00:00+4:00" //optional
});
Callback functions
The Web SDK takes an optional parameter for callback
which allows you to receive events on SDK close, completion or error.
function myCallback(responseObject) {
console.log(responseObject);
// insert actions you want to perform on SDK close
}
connectButton.addEventListener("click", function () {
Lean.connect({
app_token: "YOUR_APP_ID",
permissions: [
"identity", "accounts", "balance", "transactions", "identities",
"scheduledPayments", "standingOrders", "directDebits", "beneficiaries"
],
customer_id: customerId.value,
sandbox: "false",
callback: myCallback,
fail_redirect_url: "",
success_redirect_url: ""
});
});
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": "LEA1_RETAIL_SAU",
"is_supported": true
}
}
status enum
The end status of the LinkSDK at close.
Status | Reason |
---|---|
SUCCESS | The initiated flow was completed successfully |
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 |
BANK_SELECTION | The bank list screen |
OPEN_BANKING | Open banking redirect initiation |
UNSUPPORTED_BANK_REQUEST | The unsupported bank list screen |
SUCCESS | The success screen |
FAIL | The failure screen |
secondary_status enum
Further details on failures. May be null
.
bank object
Details on the bank selected by the user.
bank.bank_identifier
| The Lean identifier for the bank. |
bank.is_supported
| 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) |
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": "LEA1_MOCK_RETAIL_SAU",
"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() flows.
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.sa.leantech.me/banks/v1/' \
--header 'lean-app-token: 2c9a80897169b1dd01716a0339e30003' \
--ca-cert ca.pem \
--cert cert.crt \
--key key.pem
Response:
[
{
"identifier": "LEA1_RETAIL_SAU",
"name": "Lean Open Banking MockBank",
"logo": "https://cdn.leantech.me/img/banks/white-lean.png",
"logo_alt": "https://cdn.leantech.me/img/banks/white-lean.svg",
"main_color": "#1beb75",
"background_color": "#ffffff",
"theme": "light",
"country_code": "SAU",
"active": true,
"mock": true,
"bank_type": "RETAIL",
"traits": [
"auth-redirect"
],
"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({
app_token: "2c9a80897169b1dd01716a0339e30003",
permissions: [
"identity", "accounts", "balance", "transactions", "identities",
"scheduled_payments", "standing_orders", "direct_debits", "beneficiaries"
],
customer_id: "552e8102b3c14401a36ac14fadab94de",
sandbox: "true",
bank_identifier: "LEA1_RETAIL_SAU",
fail_redirect_url: "",
success_redirect_url: ""
});
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.
Lean.connect({
app_token: "2c9a80897169b1dd01716a0339e30003",
customer_id: "552e8102b3c14401a36ac14fadab94de",
permissions: ["identity","accounts","balance","transactions", "identities", "scheduledPayments", "standingOrders", "directDebits", "beneficiaries"],
sandbox: true,
fail_redirect_url: "",
success_redirect_url: "",
language: "ar"
});
Language option
language enum
| English |
| Arabic |
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.
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:
Value | Style |
---|---|
"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:
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 |
Troubleshooting
Content Security Policy (CSP)
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:
<meta
http-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:;
"
/>
Migrating from LinkSDK to Link Loader
If you have already integrated LinkSDK and want to use Link Loader, migrating is simple:
- Update the import script tag of LinkSDK in your frontend to the following CDN URL:
<script src="https://cdn.leantech.me/link/loader/prod/sa/latest/lean-link-loader.min.js"></script>
- Remove this tag from your HTML file:
<div id="lean-link"></div>
Updated 3 months ago