Introduction

Connecting to a bank account enables payments and data requests with Lean's APIs. Bank connections are stored as Entities and Payment Sources for Data and Payment applications respectively.

In order to connect a user's bank account you need to implement the following items:

• Create a Customer
• Implement the LinkSDK and use the .connect() method
• Implement a webhook handler for the entity.created and/or payment_source.beneficiary.updated webhooks.

Entity model

An Entity maps to a user's entire relationship with a specific bank. You will need to decide on the permissions you want to gain consent for from your customer during the linking process.

An example Entity object will look something like the following:

{
  "id": "f6dcc0ae-20c6-318c-bdba-49fb2ced41ce",
  "customer_id": "6bc2336a-6d74-4e59-a492-65313423a8f8",
  "bank_identifier": "ENBD_UAE",
  "permissions": {
    "identity": true,
    "accounts": true,
    "balance": true,
    "transactions": true,
    "identities": false,
    "standing_orders": false,
    "scheduled_payments": false,
    "direct_debits": false,
    "beneficiaries": false
  }
}

📘

In UAE, the only relevant permissions are identity (only for retail accounts), accounts, balance and transactions. The remainder permissions will always be set to false.

How to create the entity

Entities are created by first calling the Lean.connect() method in the LinkSDK in your front-end. In order to make a .connect() call you need to provide the permissions for the endpoints you want to make calls for, your app_token and a customer_id.

<button onClick={connectAccount([customer_id])}>Connect Account</button>

<script>
function connectAccount = (customer_id) => {
    Lean.connect({
        app_token: "YOUR_APP_TOKEN",
        customer_id: "6bc2336a-6d74-4e59-a492-65313423a8f8",
        permissions: ["identity", "accounts", "balance", "transactions"],
        sandbox: "false",
    })
}
</script>

When a customer completes the LinkSDK - please note, no details are shared directly from the SDK to your front-end. A Success, Error or Cancelled message can be returned from the SDK via a callback (depending on the platform you're integrating with, this is handled differently) in the following format:

{
    status: "SUCCESS",
    method: "LINK",
    message: "Customer created entity successfully"
}

The details of your newly created entity will instead be sent via a webhook to your backend services. Your front-end should therefore handle the success by making a call to your backend to refresh the data.

Getting confirmation of entity creation

When a customer successfully links their bank with your application a webhook is sent back to your application:

{
    "type": "entity.created",
    "message": "An entity object has been created.",
    "payload": {
        "id": "f08fb010-878f-407a-9ac2-a7840fb56185",
        "customer_id": "6bc2336a-6d74-4e59-a492-65313423a8f",
        "permissions": ["transactions", "balance", "identity", "accounts"],
        "bank_details": {
          "name": "Lean Mock Bank",
          "identifier": "LEANMB2",
          "logo": "https://cdn.leantech.me/img/banks/white-lean.png",
          "main_color": "#1beb75",
          "background_color": "#001E26"
        }
    },
    "timestamp": "2020-10-10T17:19:00.059933Z"
}

The new Entity details can be found under payload in the received webhook. It is up to you which details from this webhook you decide to save to your database, but at the minimum we suggest you save the entity_id for future use. It's also worth noting that a user can have multiple connected Entities - one for each bank they have an account for.