Authenticating

This is the first step in authenticating clients with a financial institution. It can be started in many ways, via the JavaScript, iFrame, Online, Email or REST API's. When client's authenticate they need to provide valid login credentials to the specified financial institution and answer any challenge requests such as Multi Factor Authentication or Two Factor Authentication. 

Starting and completing an Authentication call will allow you to:

• View Profile Information like Name, Address, Email and Telephone Numbers
• View Account's and Balances
• View Account Transaction History including
  • Payroll
  • Income
  • NSF Transactions or Stop Payments
  • Average Balances
  • Loan Payback Ratios
• Get details financial analysis

Using the Online or Email methods

Login to your Dashboard and choose the Bank Integration from the left side menu. From there you can send a link to a client, or use the same link online.
Note: Links can only be used for one client and can be re-used later

Using the iFrame integration

This API and all contingency flows are available in a single iFrame URL. You must fetch the iFrame URL first and it's unique per session. Send a POST request to https://api.heliumverify.com/rest/banks/start-iframe

1. client_identifier : a unique string up to 255 characters to identify this client. Usually this could be something like "Jane:Doe:Account123".
2. force_fresh* : the server will respond with the same iframe_url if called anytime within 24h. force_first being set to true will cause a new iframe_url to be sent always.

The endpoint will respond with the iframe_url set which should then be used as the src parameter to an HTML iframe object.

Using the JS API

This option allows you to customize the UI to some degree, including fonts and colours. Use the HeliumBankAuthentication class and specify the div it should used in.

hbs = HeliumBankAuthentication()
hbs.setCallback(new HeliumBankAuthenticationListener(){
  function onLoad(){ // ... };
  function onFailed(){ // ... } ;
  function onError(){ // ... } ;
  function onSuccess( // ... };
  function onMFARequired() { // ... };
  function onM2FARequired(){ // ... }; 
});

hbs.loadInto($('#foo-div'));

The callbacks are called after library calls complete. If you need to change colours or fonts, wait for onLoad to be called and manipulate the view using your favourite JS library and the DOM. 

Using the Rest API

At least the username (or card number) and password need to be supplied to start this API. 

1. Call to bank/authorization
   1. user_or_card 
   2. password
   3. branch*
2. Receive a response with one of the following status values
   1. failed : the financial institution has returned the credentials are incorrect
   2. error : the server or financial institution have encountered encountered an error
   3. mfa_required : complete the challenge, using multifactor authentication
   4. 2fa_required : complete the challenge, using two-factor authentication
   5. success
3. At this point you either need to do one of the following
   1. success : read the data using one of the Bank API's, such as the Complete Response, Transaction History or Profile Identity
   2. mfa_required : present the user with a dialog using the message and challenge fields. Then POST with challenge_response and session_id set to the answer
   3. 2fa_required : present the user with a dialog using the message and challenge fields. Then POST with challenge_response and session_id set to the answer
   4. error: You should not retry. We internally retry things so if you get this status it's not recoverable right now. Try again in a few minutes / hours / days
   5. failed : Allow the client to retry the process