Handling OTP reconnects

When making a call to accounts, balances, 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",
	"data": null,
	"results_id": "7a16ac21-e09c-4d5f-b56a-ff68b26202cc",
	"message": "User input is required to reconnect with the bank",
	"meta": null,
	"timestamp": "2023-08-15T05:26:17.765780126Z",
	"status_detail": null
}

When this happens the results_id should be passed to your front-end in the reconnect_id parameter of reconnect():

Lean.reconnect({
    app_token: "2c9a80897169b1dd01716a0339e30003",
    reconnect_id: "7a16ac21-e09c-4d5f-b56a-ff68b26202cc",
});

📘

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": "7a16ac21-e09c-4d5f-b56a-ff68b26202cc"
  },
  "message": "The reconnect was successful and the results are ready for collection from the results endpoint.",
  "timestamp": "2021-01-08T18:05:19.244672Z",
  "event_id":"f0e65d5e-ebfa-43c5-934b-b91cafc57f39"
}

{
  "type": "results.ready",
  "payload": {
    "id": "9b8ab652-cc95-4fb2-9340-59b0164c8fb2", // results_id
  },
  "message": "Your results are ready.",
  "timestamp": "2021-01-08T18:05:19.244672Z",
	"status":"ping_results_ready",
  "event_id":"8d76fca0-8431-40c9-8f3f-2aa708b65559"
}

You can now fetch your results with a GET request to the /results endpoint (see Results API reference). Bear in mind that results API's response will be paginated so you will need to handle this.