# BankConnect: JavaScript Client SDK

The JavaScript Client SDK helps user submit their bank statements via upload or net banking credentials in your Web applications. The SDK will be opened via a web URL.

The first step in integration involves calling the Session API Then the workflow can be implemented in one of the following ways:

# See in action

The demo video below shows how a user submit bank statement using net banking credentials:

The video below shows a user submit bank statement by uploading the PDF file:

# Session API

To start with the integration, call the following API to create a session:

Endpoint

POST https://portal.finbox.in/bank-connect/v1/session/

# Parameters

Name Type Description Required Default
link_id string link_id value Yes -
api_key string API key provided by FinBox Yes -
redirect_url string URL to redirect to incase of success or failure Yes for Redirect Workflow -
from_date string Start date range to fetch statements. Should be of format dd/MM/YYYY No Last 6 month start date
to_date string End date range to fetch statements. Should be of format dd/MM/YYYY No Yesterday
bank_name string pass the bank identifier to skip the bank selection screen and directly open a that bank's screen instead No -

from_date and to_date specify the period for which the statements will be fetched. For example, if you need the last 6 months of statements, from_date will be today's date - 6 months and to_date will be today's date - 1 day. If not provided the default date range is 6 months from the current date. It should be in dd/MM/yyyy format.

NOTE

  • redirect_url in request is a compulsory field in Redirect Workflow but is not required with the Inline Frame workflow
  • Please make sure from_date is always less than to_date
  • Make sure to_date is never today's date, the maximum possible value for it is today's date - 1 day

# Response

On successful API call, it gives a 200 HTTP code with a response in following format:

{
  "redirect_url": "https://bankconnectclient.finbox.in/?session_id=127d12db1d71bd182b"
}

Use redirect_url to open up the BankConnect SDK. This URL can be used embedded inside an <iframe> or can be opened in a new tab or current window.

# Redirect Workflow

JavaScript Client SDK Redirect Workflow

The flow for this involves following steps:

  • Create a session using Session API
  • Get the URL received from above API and open it in a new tab
  • On success / failure, Client SDK will redirect to the specified redirect URL with parameters as follows:
    • Exit: {url}?success=false
    • Success: {url}?success=true&entity_id=<some-entity-id>

NOTE

Since there is no callback received on this flow, it is recommended to configure Webhook

# Inline Frame Workflow

JavaScript Client SDK iframe Workflow

The flow for this involves the following steps:

  • Create a session using Session API
  • Get the URL received from above API and embed it in an <iframe>
  • You'll receive callbacks by implementing an event listener. Based on the event you can close / hide the inline frame.

# Receive callbacks

To receive callbacks in <iframe> workflow, you need to implement an event listener. It can be implemented as follows:

<!DOCTYPE html>
<html lang="en">
<body>
  <script>
    window.addEventListener('message', function (event) {
      console.log("Event -> ", event)
    });
  </script>
  <iframe src="<url-from-create-session>" width="500px" height="700px"></iframe>
</body>Ï
</html>

# Event Object

The event object received by the listener can be one of the following:

# Success

This is received when user completes the upload process.

{
  type: "finbox-bankconnect",
  status: "success",
  payload: {
      "entityId": "1d1f-sfdrf-17hf-asda", //Unique ID that will used to fetch statement data
      "linkId": "<USER_ID_PASSED>" //Link ID is the identifier that was passed while initializing the SDK
  }
}

# Exit

This is received when user exits the SDK.

{
  type: "finbox-bankconnect",
  status: "exit",
  payload: {
      "linkId": "<USER_ID_PASSED>" //Link ID is the identifier that was passed while initializing the SDK
  }
}

# Error

This is received whenever any error occurs in the user flow.

{
  type: "finbox-bankconnect",
  status: "exit",
  payload: {
      "reason": "Reason for failure",
      "linkId": "<USER_ID_PASSED>" //Link ID is the identifier that was passed while initializing the SDK
  }
}

Two Events

In case an error occurs, you'll receive OnError event payload, and then if the user exits the SDK, you'll receive another event payload, this time for OnExit.

Last Updated: 6/25/2020, 8:56:16 AM