LeanSDK
This SDK supports iOS 11+ and requires XCode 12.5.X and above
Lean's Link iOS SDK is a framework, distributed as a binary xcframework for simulators and iPhone devices, used by developers to let their end users connect their bank accounts through a series of easy steps in a friendly UI.
Installation
Swift Package Manager
To connect this repository to your project via Swift Package Manager. In XCode go to File > Swift Packages > Add Package Dependency and enter the URL for this repository.
Please note: You must have github connected to XCode for SPM to work.
Manually
You can download the LeanSDK.xcframework file manually here.
You can then add it to your project the same way you would with any other framework dependency.
Usage with Swift UI
Once the package has been added to your project, you should initialize the SDK within your app.
To get started call Lean.manager.setup(appToken, sandbox) this will set the application token and sandbox environment during runtime of your application.
// TestApp.Swift
import SwiftUI
import LeanSDK
@main
class LeanTestAppApp: App {
required init() {
Lean.manager.setup(
appToken: "YOUR_APP_TOKEN",
sandbox: true,
version: "1.25.0"
)
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
In Swift UI you must set up a LeanView for your further calls to populate into. You can do this with Lean.manager.generateView() - in the example below you can see how to use Lean.manager to make a link call.
// ContentView.swift
import SwiftUI
import LeanSDK
struct ContentView: View {
@State private var isPresented = false
var linkPermissions = [LeanPermission.Identity, LeanPermission.Accounts,
LeanPermission.Transactions, LeanPermission.Balance]
var body: some View {
VStack {
Button("Link", action: { handleLink() })
}
.fullScreenCover(isPresented: $isPresented, content: {
Lean.manager.generateView().ignoresSafeArea()
})
}
func handleLink() {
Lean.manager
.link(customerId: String, permissions: linkPermissions,
customization: LeanCustomization?,
success: { (status) in
print("Entity Linked")
print(status.status)
isPresented = false
}, error: { (status) in
print(status.status)
print(status.message!)
print(status.method)
isPresented = false
})
isPresented = true
}
}
Setting the version
version takes a String and can point to either a specific SDK version i.e. "1.25.0" or an alias i.e. "latest".
We recommend passing in a specific version to ensure stability in the case that a change to the SDK breaks your application.
latest is subject to change at relatively short notice - but does allow for any bugfixes to shipped over the air - meaning fixes can be applied without the need to resubmit your application to the app store.
A QA version of the SDK is available with next-release and should only be used in test applications to ensure that the next latest patch will not break your implementation of the LinkSDK.
Setting the language
language is set in Lean.manager.setup. It is optional and defaults to nil, in which case it will default to English.
If you wish to provide a value you can provide a String either "en" for English, "ar" for Arabic.
Example:
Lean.manager.setup(
...
language: "ar"
)
Setting the country
In most cases you don't need to set a country, but if you're operating in KSA you may need to. Speak with our integrations team if you're not sure.
country is set in Lean.manager.setup. It is optional and defaults to nil, in which case no specific country is set.
Example:
Lean.manager.setup(
...
country: LeanCountry.SaudiArabia
)
Usage with View Controllers
When using LinkSDK with standard MVC swift - you must initialize the SDK and provide the SDK with a View Controller to present itself inside.
// ViewController.swift
import UIKit
import LeanSDK
class ViewController: UIViewController {
var linkPermissions = [LeanPermission.Identity, LeanPermission.Accounts,
LeanPermission.Transactions, LeanPermission.Balance]
override func ViewDidLoad() {
super.viewDidLoad()
Lean.manager.setup(
appToken: "YOUR_APP_TOKEN",
sandbox: true,
version: "1.25.0",
)
}
}
@IBAction func handleLink(_ sender: Any) {
Lean.manager.link(presentingViewController: self, customerId: CUSTOMER_ID, permissions: linkPermissions, bankId: nil, success: { status in
print("Entity Linked")
}, error: { status in
print(status.status)
})
}
Methods
The LinkSDK has 5 methods to connect and manage your customer's Accounts, Data and Payments.
Each of these methods is available through Lean.manager.{METHOD}()
.link()
.link() allows your customer to connect their bank account for the Data API - allowing you to access accounts, balances and transactions. To link an account for Payments, see the createPaymentSource() Method.
Lean.manager.link(
presentingViewController: self: UIViewController,
customerId: String,
permissions: Array<LeanPermissions>,
bankId: bankId?
customization: LeanCustomization?,
success: { (status) in ... executes code on success },
error: { (status) in ... executes code on failure }
)
LeanPermissions are an array of ENUMs available through the LeanSDK package. Available values are:
- LeanPermissions.Identity
- LeanPermissions.Accounts
- LeanPermission.Transactions
- LeanPermission.Balance
.reconnect()
.reconnect() allows you to reconnect and entity - when you make a call to the Data API that requires reconnection - you will receieve a reconnect_id for this flow.
Lean.manager.reconnect(
presentingViewController: self,
reconnectId: reconnectId,
customization: LeanCustomization?,
success: { (status) in ... executes code on success },
error: { (status) in ... executes code on failure }
)
.createPaymentSource()
Create a payment source from your customer's bank account.
Lean.manager.createPaymentSource(
presentingViewController: self,
customerId: customerId,
bankId: bankId?,
customization: LeanCustomization?,
success: { (status) in ... executes code on success },
error: { (status) in ... executes code on failure }
)
.updatePaymentSource()
The updatePaymentSource method is used to authorize an additional payment destination for an existing payment source in the Payments API.
Lean.manager.updatePaymentSource(
presentingViewController: self,
customerId: customerId,
paymentSourceId: paymentSourceId,
paymentDestinationId: paymentDestinationId,
customization: LeanCustomization?,
success: { (status) in ... executes code on success },
error: { (status) in ... executes code on failure }
)
.pay()
Initiate a payment from a customer's bank account.
Lean.manager.pay(
presentingViewController: self,
paymentIntentId: paymentIntentId,
accountId: accountId?,
customization: LeanCustomization?,
success: { (status) in ... executes code on success },
error: { (status) in ... executes code on failure }
)
.connect()
Connect a bank account and create an Entity for the Data API and a Payment Source for the Payment API with a single sign on.
Lean.manager.connect(
presentingViewController: self: UIViewController,
customerId: String,
permissions: Array<LeanPermissions>,
bankId: bankId?
paymentDestinationId: paymentDestinationId?
customization: LeanCustomization?,
success: { (status) in ... executes code on success },
error: { (status) in ... executes code on failure }
)
LeanPermissions are an array of ENUMs available through the LeanSDK package. Available values are:
- LeanPermissions.Identity
- LeanPermissions.Accounts
- LeanPermission.Transactions
- LeanPermission.Balance
- LeanPermission.Payments
Responses
Success responses will allow you to execute code upon the success of the LinkSDK flow you have called.
Error responses return a struct with the following details:
struct LeanStatus {
method: String,
status: String,
message: String?,
lastApiResponse: String?,
exitPoint: String?,
secondaryStatus: String?,
bankDetails: {
bankIdentifier: String?,
isSupported: Bool?
}
}
| Attribute | Description |
|---|---|
| method | The method called by the SDK, can be LINK, RECONNECT, CREATE_PAYMENT_SOURCE or PAY |
| status | The end status of the call, can be ERROR or CANCELLED - if cancelled this means the user exited the flow. |
| message | Further details on the reason for the error, or where the user exited the flow. This is an optional. |
| lastApiResponse | The last API response status recieved from Lean. This is an optional. |
| exitPoint | The last screen shown before the user closed the SDK |
| secondaryStatus | More details on the main status - for example INVALID_CREDENTIALS |
| bankDetails.bankIdentifier | The ID of the selected bank |
| bankDetails.isSupported | Whether the selected bank is supported or not |
You can read more in depth documentation by going to our API Documentation
Open banking
In order to show Open Banking enabled banks to the end user you must provide failRedirectUrl and successRedirectUrl to each relevant method initialisation call.
For example
Lean.manager.link(
...
failRedirectUrl: String?,
successRedirectUrl: String?
...
)
Customization
You can customize the UI of LinkSDK using LeanCustomization.
Colors should be provided as valid CSS color formats - color name, HEX, RGB, RBGA (comma separated)
var customConfig = LeanCustomization(
buttonTextColor: String?,
buttonBorderRadius: String?,
linkColor: String?,
overlayColor: String?,
themeColor: String?,
dialogMode: String?
)
Lean.manager.link(
...
customization: customConfig,
...
)
Accepted color strings
| Type | Value |
|---|---|
| Name | "blue" |
| Hex | "#0000ff" |
| RGB | "rgb(0,0,255)" |
| RGBA | "rgba(0,0,0,255,0.5)" |