Providing your users with a simple, intuitive and informed experience is key to good UX.
To help keep you and your users informed we provide job status and error messages which your Support teams can use to troubleshoot issues and pass directly onto the user (i.e. in cases of invalid credentials).
To do this, you can poll the
/job endpoint, checking on the status of each step until the job has either
- successfully completed the relevant step/s;
- failed at any of the steps.
The best case scenario, is that all job steps will have completed successfully. Unfortunately this is not always the case, and jobs can fail for different reasons.
In practice, live banks present a number of scenarios that prevent Basiq from fetching a user's accounts and transactions from their internet banking. In the event that a step has failed, the result object will contain an embedded error object, and the information within that will determine how you clear the issue and fetch their data successfully.
Where it occurs
What it means
On "Create connection"
Only occurs on
If you're using the BasiqConnect Simple UI, it is handled for you
If the bank returns detail of the failure (e.g. The user is locked out of internet banking, or there is an MFA challenge that isnt supported), Basiq will return this detail. If no detail is given, Basiq will return a generic error.
For a generic error, retry the
The user may need to log into their banking via the browser, not the app, to confirm they can access with the credentials they have provided to Basiq.
If the error detail specifies that MFA is not supported, they can try to login without MFA through their internet banking, and if they are successful, try again through Basiq.
On "Refresh connection"
Can occur on
This could happen for the same reasons as "Create connection", but could also be that your user has changed their internet banking password.
When your user returns to your application, prompt them to resubmit their credentials, and update these using the
Can occur on any job step, depending on where Basiq encounters the error when navigating the user's internet banking
The bank is presenting a popup to the user in their internet banking. Whenever possible Basiq will navigate through these, but for example if the bank presents new T&Cs to the user and offers only options to "Agree" or "Decline", then Basiq will fail the job with this error
Ask your user to login to their internet banking, navigate to accounts and transactions, and address any CTA's/popups requiring action from the bank
You/your application can then refresh the connection. If the popup has cleared, the job should complete as normal
Can occur on any job step, depending on where Basiq encounters the error condition on the bank's internet banking portal.
The bank is unable to service Basiq's request This is typically due to a maintenance outage or performance issue on the bank's website, but can occasionally happen if the bank has made significant changes to their internet banking
You can let the user know there is a problem fetching data from their bank, and that you will let them know when their data is ready.
Check the status for this bank in the
If the institution status is anything other than major-outage then wait 10 minutes and try again.
If, after a couple of retries, the error has not cleared, then report the
Sandbox users for testing job failure scenarios
We have created test users especially for replicating these failure scenarios in your user flow. These three users will always fail on the same job steps. You can find them here.
Updated 5 days ago