Frontend API and SignalR

Frontend API Process

It is advised that customers make use of the DirectID Widget or Angular module when integrating with DirectID. This generally provides the fastest integration path and allows our customers to benefit from our frequent UX and process improvements.

In some situations however our customers may find it more suitable to create their own client or web frontend application. This guide provides a step by step overview of the process from a client application point of view and provides a reference of the relevent SignalR events which should a client application should handle.

 

Step 1 (optional) – Confirm that User Session Token is valid

To avoid errors when connecting to the DirectID API, use /user/session/check to confirm that the session token passed to your application upon initialisation is valid.

 

Step 2 - Establish SignalR Connection

To listen for important information broadcast by DirectID's API you will need to create a SignalR hub. This is a complex process, and DirectID strongly recommends using an existing SignalR Hub library or module for your chosen language.

At all times you should listen for the fatalError() event, which indicates that the DirectID API login process cannot be completed and must be started over. Usually this occurs when there is an issue with the user's chosen bank.

 

Step 3 (optional) – Retrieve most popular banks by geolocation

To get a list of the most popular providers for a given location, you can use /bank/favorites/{Country Code}The returned data objects include a provider name and a Provider ID which will be used throughout the process.

Alternatively you can construct your own list of popular banks using Provider IDs supplied by DirectID.

 

Step 4 – User selects bank by searching or by using most popular banks

To retrieve a list of banks from the DirectID API use /bank/search/{Search Term}?SearchAll={bool}.

Banks are matched against the given search term using a trigram algorithm.

Set SearchAll to false to return only banks which match the filters set for your account. By default this is set to true.

Returned banks contain the same Provider ID as objects returned by /bank/favourites/{Country Code}

 

Step 5 – Retrieve login form for selected bank

Use /bank/form/{Provider ID} to retrieve a login form for a given Provider ID.

 

Step 6 – Submit login form for selected bank

Use /bank/login/{Provider ID} to submit a completed login form to the DirectID API and begin the login process.

 

Step 7 – Await SignalR messages from the DirectID API to update progress and prompt for additional information

The DirectID API will send notifications of login progress through SignalR on setLoginProgress(). A listener on this event can be used to update the waiting user on this progress, for example using a progress bar or counter.

The errorTo() listener will be fired if the user has entered invalid login details. You can use this to present the login or MFA form again, along with any related messaging to help the user avoid the error on subsequent login attempts.

 

Step 8 (Bank Dependent) – Submit MFA form

Some banks require the user to pass multi-factor authentication (MFA) checks.

The SignalR event mfaFormAvailable() indicates that an MFA form is ready to be loaded. You should load the form by making a GET request to /bank/mfa. The response will contain the MFA form fields, which should be presented to the user.

Once completed, the form data should be submitted to /bank/mfa via a POST request.

Note: Previously MFA form fields were included with the SignalR event, but due to file-size restrictions were moved to a separate API endpoint.

 

Step 9 (optional) – Submit Account Selection form

When account selection is not required, the showConnected() SignalR message indicates a successful connection to the user's bank and the end of the login process. 

If you are using account selection, the showConnected() message does not mean the flow has finished, as it is extended to allow for account selection.

The SignalR event requestAccountDetailsConfirmation() occurs when the account summary for the user's bank accounts has been returned, which will be included in the event data.

The user should then select their chosen account and provide additional account number or routing number information if this could not be retrieved from their bank.

The user's selection along with their self-asserted account information (e.g. account or routing number) should then be submitted to /user/bank/accountselection


SignalR 

SignalR is a real time communication framework developed by Microsoft. The documentation can be found here.

To facilitate real time communication between the DirectID Widget and the DirectID API you must use a SignalR client. This communication is uni-directional and is used to allow the API to notify the client of events. Microsoft provide SignalR clients for JavaScript (with jQuery), .NET and Java (including Android). Open source clients can be found for other languages and platforms, for example Objective C or Swift.


SignalR Listener Reference

setLoginProgress (stepName, currentStep, totalSteps, longRunning)

Called when updating the front end with the current state of the backend flow.

Properties

  • stepName: Text to be displayed describing the current step
  • currentStep: The current step number
  • totalSteps: The total step numbers
  • longRunning: Has this step been running for a long time

 

showMFAForm (form, timeoutSeconds, errorMessage)

Called when the user is required to provide an MFA response.

Properties

  • form: The required fields that the user must answer
  • timeoutSeconds: Any time limit on the MFA response
  • errorMessage: Any associated error message to display to the user

 

showConnected ()

Called when the bank login process is completed.

 

errorTo (state, message)

Called to instruct the Widget to change to another state in the event of an issue, for example to return to the bank login state if the user has entered incorrect details

Properties

  • state: The state to error to, can be either ‘Login’ or ‘MFA’
  • message: An error or instructional message to be shown to the user

 

fatalError (error, displayError)

Called to instruct the Widget to go to the fatal error state and prevent continuation of the process. For example this can occur when the user has entered their details incorrectly 3 times.

Properties

  • error: Error message
  • displayError: A boolean to determine if this message should be shown to the user. If set to false typical behaviour would be to show a generic error message

 

requestAccountDetailsConfirmation (accountsToSelect, maxAccountsToSelect)

Called to request that the user selects one or more accounts from retrieved accounts and provide additional information where required.

Properties

  • accountsToSelect: Array of account objects for the user to select from
  • maxAccountsToSelect: The number of accounts the user should select