Handling OTP reconnects

When making a call to accounts, balance, identity and transactions endpoints, user verification may be required before the request can be completed (for example, an OTP or updated user credentials may be required).

📘

When will an OTP be required?

For corporate banks, this will happen every time you make a call to the API if this happens after a few minutes of your last call. For retail banks, when an OTP is required will depend on the bank in question. Please check with Lean's team to know the exact details.

When this happens, a RECONNECT_REQUIRED response will be returned:

{
    "status": "RECONNECT_REQUIRED",
    "payload": {
        "reconnect_id": "20afcfd3-7ee3-44b8-9d6e-bf74b259fb90",
        "type": "reconnect"
    },
    "results_id": "fae0ff1b-b0b7-481d-9c0a-533e0abfc798",
    "message": "User input is required to reconnect with the bank",
    "timestamp": "2020-12-30T16:40:49.779695Z"
}

When this happens the reconnect_id should be passed to your front-end and initialised like so:

Lean.reconnect({
    app_token: "2c9a80897169b1dd01716a0339e30003",
    reconnect_id: "20afcfd3-7ee3-44b8-9d6e-bf74b259fb90",
    sandbox: "false"
});

📘

Please note that the reconnect_id will expire within 30 days. After 30 days, if you want to receive a new reconnect_id, you should make a new call to our Data API and you will get the new reconnect_id in the response.

Once the user has successfully reconnected their account, a webhook notifying you of successful reconnection will be sent, as well as a results.ready webhook allowing you to pick up the originally requested data.

{
  "type": "entity.reconnected",
  "payload": {
    "id": "a2533394-6fcb-4407-989d-c35e96f34aa3" // the entity_id
    "reconnect_id": "6222a07e-3aa8-42ba-87df-0ef989f36d19"
  },
  "message": "The entity was successfully reconnected.",
  "timestamp": "2021-01-08T18:05:19.244672Z"
}

{
  "type": "results.ready",
  "payload": {
    "id": "9b8ab652-cc95-4fb2-9340-59b0164c8fb2", // results_id
  },
  "message": "Your results are ready.",
  "timestamp": "2021-01-08T18:05:19.244672Z"
}

You can now fetch your results with a GET request:

curl -X GET 'https://sandbox.leantech.me/v1/results/6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4' \
  --header 'Content-Type: application/json' \
  --header 'lean-app-token: YOUR_APP_TOKEN' \