The Basiq Connect Control is a UI component allows applicants to securely connect their bank accounts. It's written in React, however it exposes a vanilla JavaScript interface to ensure it can be used across all frameworks.
Setup
Regardless of the JS framework you are using (eg Angular, VueJS), you will still need to install react
and react-dom
.
Install basiq-connect-control
and it's dependencies:
$ npm install react
$ npm install react-dom
$ npm install @basiq/basiq-connect-control
OPTIONAL:
If you are concerned about support for Internet Explorer, you may also install polyfill libraries along side such as core-js
and react-app-polyfill
.
Usage
The package exports a single function, BasiqConnect
, which takes a config object as a single input parameter. Calling this function will render the bank picker to the use
BasiqConnect()
Where to call If you’re using vanilla JavaScript, you can call BasiqConnect anywhere after the host DOM element is loaded.
If you are using React, you should call it either in componentDidMount
, or, if you are using React Hooks, in useEffect
.
import BasiqConnect from "@basiq/basiq-connect-control"
export const BasiqConnectModal (() => {
useEffect(() => {
BasiqConnect(config)
}, [])
return <div id="basiq-control"></div>
})
Configuration
The following parameters can be passed through the config object. Most are optional values however authentication params are required and can be provided by sending either:
-
the
userId
andtoken
, which can be obtained via the BasiqAPI (see the quick start guide); or -
the connectLinkId, which is the link returned from
/users/{user.id}/auth_link
{
containerId: String, // ID of the DOM element to which Basiq Connect Control will be rendered;
token: String, // CLIENT_ACCESS scope
userID: String,
// or
connectLinkId: String,
// optional fields
upload: Boolean, // should uploading statements be enabled
connect: Boolean, // should connecting to bank with credentials be enabled
companyName: String, // company name to be shown, will default to Basiq Dashboard name
regionOfInstitutions: String, // valid values: Australia, New Zealand
hideTestBanks: Boolean, // should test banks (Basiq, Hooli) be hidden from user
hideBetaBanks: Boolean // should beta banks be hidden from user
}
Handling Jobs
You can listen and react to events emitted by the web app by using the addListener(event, cb) method. Multiple listeners per event are supported. The event you should listen for is jobCreated
, which is triggered when a user links their financial institution using the UI, which kicks off an async job in the background.
This event will pass you the jobId which you can use to poll the jobs/{jobId}
endpoint to check the status of each step. This allows you to:
-
Perform actions as soon as the step you rely on is complete without waiting for the following steps,
-
Allow your user to carry on with their flow, keeping them engaged, and
-
Effectively manage any failed jobs, which is crucial to your application. See the best practices for managing failed jobs
const handleNewJob = async (event) => {
let jobId = await event.detail.id;
pollJob(jobId)
}
window.addEventListener("jobCreated", handleNewJob);
Other events
The BasiqConnect package also provides a basiqConnectMounted
event, which is triggered when the component has rendered. This allows for any handling of loading state to be managed in your UI. This can be done as below:
window.addEventListener("basiqConnectMounted", callback);