This document describes the JavaScript Instantor API for integration of Instantor service with third-party systems.

For end-users, Instantor iFrame (the iframe) is entry point to Instantor services.
The frame is injected into Company's page (the page), it communicates with the page and provides feedback of process state and final process status to implemented event listeners using Instantor injector script (the script), via JavaScript.

This document assumes basic knowledge of HTML, CSS and JavaScript; assumes you have access to files on your server, and assumes you have some kind of code editor.
Any text-editor (like Notepad, TextEdit, gedit/VIM) will work just fine – of course, full IDE will work just as fine.

Heads up! The iframe requires JavaScript support in the browser, there is no fallback mode for browsers without (or with disabled) support for JavaScript.
Take care! This documentation is the same for all clients and top-level domains, please take care when directly copy-pasting code found on this page into your production-grade code. Some differences may apply, please, read documentation carefully.

Check-list for getting started really quickly:

  1. Load prerequisites – jQuery library,
  2. Link the Instantor script,
  3. Initialize Instantor object,
  4. Add some information about the user,
  5. Load the frame.
  6. Add feedback listener(s)

Adding feedback and event listeners is optional, but it is strongly suggested to do so. That way, you can handle process flow, as well as react to changes in the iframe.

You can fetch following script, and place it somewhere in <body> section of your page:

Heads-up! This snippet is subject to change, do not use it in production code without verifying if everything works correctly.

IMPORTANT!

Make sure you have loaded jQuery library. You can use your own, local copy, or one provided by CDN.
jQuery version 1.7+ is required.
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>
<script type="text/javascript" src="https://www.instantor.com/frame-loader/instantor-0.7.3.min.js"></script>
<script type="text/javascript">
//<![CDATA[
try {
  /* Enter the username Instantor has provided to you */
  var itor = new Instantor('company.inc');

  /* Optionally, enter available user details */
  itor.userParam('user_identification', '12345678901');
  itor.userParam('firstName', 'NAME');
  itor.userParam('lastName', 'SURNAME');
  itor.userParam('account', '7890 7890 7890 78');
  itor.userParam('account', '7890 7890 7890 79');

  /* Optionally, enter some transaction information */
  itor.transactionParam('additional_data', '123');

  /* Initiate the Instantor frame at the targeted DOM element */
  itor.load('#itor');

  /* Optional function to process the feedback messages */
  itor.listener(function(response){
    switch(response){
      case 'process-finished':
        /* Process finished successfully. */
        break;
      case 'invalid-login':
        /* User did not provide correct login credentials. */
        break;
      case 'too-many-retries':
        /* User failed to login too many times, and should not repeat the process
           again for 24 hours in order to prevent a net-banking lock. */
        break;
      default:
        /* Process encountered an error. */
        break;
    }
  });
} catch(err) {}
//]]>
</script>
Take care! Please, make sure the top-level domain of injector script matches your targeted market top-level domain. Failing to do so can result in failed scrapes. See here for more info.

This step-by-step guide will lead you through procedures needed for successful iframe integration – as described in quick-start section above.

1. Adding prerequisites

First of all, Instantor script needs some prerequisites for its work – jQuery library. You can link it from whatever location suits your needs, either locally cached on your server, or from public CDN (for example, from Google's CDN).
Required jQuery version is 1.7 or newer.

Important!

Be sure to load jQuery using HTTPS protocol!

2. Linking the script

Now, Instantor script file needs to be linked in your page. Add the following line somewhere in <body> section of your HTML file:
<script src="https://www.instantor.com/frame-loader/instantor-0.7.3.min.js"></script>

Make sure you are using correct top-level domain for your targeted market. For example, if you are targeting Swedish markets, use instantor.se. If you are integrating Polish client, use instantor.pl, and so on.

You will receive correct domain and injector link from Instantor tech-support.

Country Link
Denmark https://www.instantor.dk/frame-loader/instantor-0.7.3.min.js
Germany https://demo.instantor.com/frame-loader/instantor-0.7.3.min.js
Poland https://www.instantor.pl/frame-loader/instantor-0.7.3.min.js
Sweden https://www.instantor.se/frame-loader/instantor-0.7.3.min.js
Sweden for Business clients https://www.instantor.com/client-business/instantor-0.7.3.min.js

Important!

Never copy the script to your server. The script is frequently updated to reflect changes in the process, caching your own version can lead to unhandled issues.

3. Preparing the code and initializing Instantor object

Once you have linked the script, you'll need to open new code block, and initialize new Instantor JavaScript object (the object).
To successfully initalize the object, you need to pass client identification string you received from Instantor tech support as an argument to object constructor. Failing to do so, Instantor script will fail to load, and report an error in initialization.

Code snippet:

<script>
try {
  var itor = new Instantor('company.inc');
} catch(err) {}
</script>

4. Adding information about current user

To differentiate users undergoing Instantor process, you can add as much user-specific information as you need.
User information is stored as key-value pairs, and it is free-form, with some special keywords. Use method userParam to add user information.

Code snippet:

<script>
try {
  var itor = new Instantor('company.inc');

  itor.userParam('user_identification', '12345678901');
  itor.userParam('firstName', 'NAME');
  itor.userParam('lastName', 'SURNAME');
  itor.userParam('account', '7890 7890 7890 78');
  itor.userParam('account', '7890 7890 7890 79');
} catch(err) {}
</script>

Quick list of special keywords: firstName, lastName, email, personal_id.
Read more about userParam keywords in API reference / userParam section.

You can add additional information about the transaction and/or change some details of the frame using transaction and frame parameters, respectively – using transactionParam and frameParam methods, respectively.
Read more about parameter-setting methods in API reference / frameParam section and API reference / transactionParam section.

Important!

Once the bank login form is loaded, all additional user information will be discarded. Make sure you either accept user-entered information before you load the frame, or you have callback function attached to appropriate event (displayChange) via attachEventListener.

5. Loading the frame

To be able to load Instantor frame into your page – provided that the Instantor object has been initialized with correct client identification, and some user information has been added – you will need containing DOM element in your HTML page. The best practice is to assign <div> element as containing – the iframe is block-level element, so it should be avoided injecting it into inline-level element. Use method load to start the injector.

Code snippet:

<script>
try {
  var itor = new Instantor('company.inc');

  itor.userParam('user_identification', '12345678901');
  itor.userParam('firstName', 'NAME');
  itor.userParam('lastName', 'SURNAME');
  itor.userParam('account', '7890 7890 7890 78');
  itor.userParam('account', '7890 7890 7890 79');

  itor.load('#itor');
} catch(err) {}
</script>
Take care! DOM element should be valid jQuery selector. Failing to provide existing DOM element, the injector script will end with error message.

5. Attaching feedback listeners

Event listeners provide feedback to your page. There are a few different feedback listener methods – the most basic one is waiting for the process to finish.

To attach an listener for process end event, use method listener.

Code snippet:

<script>
try {
  var itor = new Instantor('company.inc');

  itor.userParam('user_identification', '12345678901');
  itor.userParam('firstName', 'NAME');
  itor.userParam('lastName', 'SURNAME');>
  itor.userParam('account', '7890 7890 7890 78');
  itor.userParam('account', '7890 7890 7890 79');

  itor.load('#itor');

  itor.listener(function(response){
    switch(response){
      case 'process-finished':
        /* Process finished successfully. */
        alert('The process has finished successfully.');
        break;
      case 'invalid-login':
        /* User did not provide correct login credentials. */
        alert('Your credentials were rejected by the bank.');
        break;
      case 'too-many-retries':
        /* User failed to login too many times, and should not repeat the process
           again for 24 hours in order to prevent a net-banking lock. */
        alert('You have tried to log in too many times. Please, try again tomorrow.');
        break;
      default:
        /* Process encountered an error. */
        alert('The process encountered an error.');
        break;
    }
  });
} catch(err) {}
</script>

Read more about listener keywords in API reference / listener section.

Beside generic end-of-process listener, there is general-purpose event listener: attachEventListener.

attachEventListener
General-purpose event listener. This listener attaches a callback function to any available event. For example, events are triggered when the frame is fully loaded, when the user accepts the Terms of Use, when the bank login form is loaded, when the bank chooser is loaded, and so on.

Read more about event listener in API reference / attachEventListener section.

This section will try to describe all available methods, and their parameters.

Constructor

Instantor object constructor accepts either two arguments – source and sub-source – or only one – token.

Instantor(source [, sub-source] | token)
source (string)
Main source identification. Received from Instantor tech support. Mandatory, unless replaced with token.
sub-source (string)
Sub-source identification. Optional.
token (string)
User-session token. Received from Instantor platform. Using token will override all other iframe options – all previously entered user information, all transaction parameters. Frame-specific parameters (passed via frameParam) will not be overridden.

Use sub-source only if sub-source is previously enabled by Instantor tech support. Othervise, sub-source information will be ignored.

.load

load method injects the iframe into DOM element, and initializes process handlers. Accepts valid jQuery selector string as it's argument.

Instantor.load(DOM element)
DOM element (string)
Iframe containing DOM element, as jQuery selector. Must be present in the DOM. Mandatory.

.userParam Optional

userParam method adds key-value pairs of user-specific information to the process. Accepts a pair of strings – key and its value.

Adding user-specific information is optionall, but strongly suggested – it is the only way of differentiating end-users, and the only way for conducting successful identification process.

Instantor.userParam(key, value)
key (string)
User information key. Mandatory.
value (string)
User information value. Mandatory.

userParam accepts following special-purpose keys for specific use-cases:

Key Effect
firstName (string) User's first name
lastName (string) User's last name
email (string) User's e-mail address
ssn (string) User's SSN – social security number. Currently supported only in Swedish clients.

.userParamUpdate Optional

userParamUpdate method updates user information for given key with new value. If there are more than one value for that key, new value is appended to the list. Accepts a pair of strings. If the specified key isn't present is user information array, it will be added.
Using this method is optional – use it only if you need to update user-provided information, e.g. if it is entered via form elements.

Instantor.userParamUpdate(key, value)

See API reference / userParam for more information.

.transactionParam Optional

transactionParam method adds key-value pairs of transaction-specific information. It is also used to control the type of reports returned to the client. First argument is always string, second can be string, integer, float or boolean.
For special-purpose keys and their value types, see the following table.

Instantor.transactionParam(key, value)
key (string)
Transaction information key. Mandatory.
value (string | boolean)
Transaction information value. Mandatory.

transactionParam accepts following special-purpose keys for specific use-cases:

Key Effect
verification (boolean) If set to true, Instantor process will test user's identification provided by the bank against client-entered information (via userParam method), and provide results in the report.
If user's information haven't been provided, report will state that verification has failed.
transactions (boolean) If set to true, Instantor process report will include information about user's transaction, as provided by the bank.
aggregated (boolean) If set to true, Instantor process report will be done in aggregated form.
identificationOnly (boolean) If set to true, Instantor process report will report only user information, without transaction data.
Heads up! Transaction parameter directives are not publicly available for all clients, each is provided on per-request basis. If you want to use any of this functionality, please contact Instantor tech support.

.frameParam Optional

frameParam method adds key-value pairs of frame-specific information. It is also used to control the type of reports returned to the client. First argument is always string, second can be string, integer, float or boolean. For special-purpose keys and their value types, see the following table.

This method is optional – it is used for modifying some default iframe behaviour.

Instantor.frameParam(key, value)
key (string)
Frame information key. Mandatory.
value (see following list)
Frame information value. Mandatory.

frameParam accepts following special-purpose keys for specific use-cases:

Key Effect
debug (boolean) Activates or deactivates debug reporting – requires browser with full console reporting support, since it outputs debug information into browser's console. Default is false, off. Set to true to turn on.
Potentially crashes in Internet Explorer older than IE 10 due to lacking console support.
bankID (string) This method is used for setting a bank to be selected as a default when the iframe loads.
Providing incorrect bank identification string, or providing a code for temporarily deactivated bank will fail silently – standard iframe bank drop-down selection list will be shown instead.

List of bank identification strings:

Bank ID Bank
se-danskebank Danske Bank Group. Danske Bank A/S, Danmark
se-handel Svenska Handelsbanken AB (publ)
se-nordea Nordea Bank AB (publ)
se-seb Skandinaviska Enskilda Banken AB (publ)
se-swedbank Swedbank AB (publ)
Bank ID Bank
pl-aliorbank Alior Bank Spółka Akcyjna
pl-bgz Bank BGŻ S.A.
pl-bnpparibas BNP Paribas Banku Polska SA
pl-bzwbk Bank Zachodni WBK S.A.
pl-dnbbank DNB Bank Polska S.A.
pl-eurobank Euro Bank S.A.
pl-getinbank Getin Noble Bank SA
pl-mbank mBank - Bankowość Detaliczna BRE Banku
pl-millennium Bank Millennium Spółka Akcyjna
pl-pekao Bank Polska Kasa Opieki S.A.
pl-pkopb PKO Bank Polski
pl-pocztowy Bank Pocztowy S.A.

Important!

Banks can and will be removed from Instantor iframe drop-down list without prior notice – either due to bank or Instantor system maintenance, problems with specific bank, or some other difficulties.
Choosing non-existing bank will fail silently, and show standard iframe bank selection drop-down list.

.listener Optional

listener method attaches an end-of-process event listener. This way, it is possible to handle a series of events triggered once the process finishes – either successful, or unsuccessful.

Instantor.listener(callbackFunction(argument))
callbackFunction (function)
Callback function being executed when the event is triggered. Mandatory.

Once the callback function is called, function argument will hold one of following string values:

Value Description
process-finished The process has finished successfully.
process-error The process has failed due to unspecified error.
invalid-login The process has failed due to incorrect bank credentials.
too-many-retries User failed to login too many times, and should not repeat the process again for 24 hours in order to prevent a net-banking lock.
required-info-missing User failed provide all required user information. The process has not been started.
process-declined User has declined to start a process. The process has not been started.

.attachEventListener Optional

attachEventListener method is used for attaching callback function to specific iframe event. There can be multiple functions attached to one event.

This method is optional.

Instantor.attachEventListener(eventName, callbackFunction(argument))
eventName (string)
The name of the event being listened to. Mandatory.
callbackFunction (function)
Callback function attached to specific event. Mandatory.

List of possible events with data each event returns:

Event name Response Description
load
{
  status: true | false
}
Triggered when the iframe has been successfully loaded, or when it fails to load. Status is set accordingly – true if successful, false if not.
ready
{
  status: true | false
}
Triggered when the iframe is ready (true), or not ready (false). Iframe is marked as ready when end-user can enter his or hers credentials, or not ready while iframe process is working.
reload
{
  status: true | false,
  sessionID: 'sessionID'
}
Triggered when the iframe gets reloaded – usually when end-user selects different bank. Since selecting different bank (only possible after one bank has been already selected) requires new session ID, whole process is being restarted, thus providing new session ID via this event handler.
Status false is returned only in case of back-end error.
error
{
  message: 'message',
  status: 'fatal' | 'non-fatal'
}
Triggered if error condition occurs – usually during iframe loading. Level is optionall, can be either fatal or non-fatal. If fatal, process is terminated, and will not continue. non-fatal error level will continue process execution.
Message contains error description.
chooseBank
{
  status: true | false
}
Triggered when end-user selects a bank.
Status reflects success state: true for success, false for failure.
processStart
{
  status: true | false
}
Triggered when the process starts.
Status reflects success state: true for success, false for failure.
processEnd
{
  status: true | false
}
Triggered when the process finishes.
Status reflects success state: true for success, false for failure.
displayChange
{
  display: 'bankLogin' | 'bankChooser' | 'reload'
}
Triggered when the iframe changes between one of its displaying modes: bankLogin gets returned when iframe is displaying bank login form, bankChooser gets returned when iframe is displaying bank-selecting chooser (drop-down list, or text-entry field), reload gets returned when iframe is about to reload due to issuing new session ID.
This callback is also triggered when bank login form requires additional information to be entered, e.g. in case of multi-stage bank login procedure.
setMessage
{
  level: 'valid' | 'warning' | 'error' | 'working' | null,
  message: 'message' | false
}
Triggered when the iframe displays new message for end-user.
Level defines the level of validity of the message. Can be one of the following: valid, warning, error or working. If message gets cleared, level will be set to null, and message will be false.
updateFeedback
{
  status: true | false
}
Triggered when user-entered data has been updated – either successfuly, or unsuccessfully.
Status reflects success state: true for success, false for failure.

All examples assume you have already included both jQuery and Instantor libraries in your code; it is expected there is a div in your HTML with ID itor. JavaScript <script> tag is ommited for brevity and readability.

Heads up! All examples will load with client demo.se.

1. Basic operation

Simplest form possible – bare-bones iframe, with no listeners or any other handlers.

try {
  var itor = new Instantor('company.inc');
  itor.load('#itor');
} catch(err) {}

Waiting.

2. Basic user information

Here, iframe is supplied with some user information – first and last name, as well as email address.

try {
  var itor = new Instantor('company.inc');

  itor.userParam('firstName', 'John');
  itor.userParam('lastName', 'Doe');
  itor.userParam('email', 'john@doe.info');
  itor.load('#itor');
} catch(err) {}

Waiting.

3. Process end-event listener

This time, there is attached end-event listener.

try {
  var itor = new Instantor('company.inc');

  itor.listener(function(response) {
    switch(response){
      case 'process-finished':
        alert('Process finished successfully.');
        break;
      case 'process-error':
        alert('Process encountered an error.');
        break;
      case 'invalid-login':
        alert('User did not provide correct login credentials.');
        break;
      case 'too-many-retries':
        alert('User failed to login too many times.');
        break;
      default:
        alert('Process encountered an error.');
        break;
    }
  });
  itor.load('#itor');
} catch(err) {}

Waiting.

More examples coming soon.