Information

This JavaScript reference page covers integration of Iframe for banks in Sweden, Germany, Denmark, Poland and Czech Republic.

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.

The iframe requires JavaScript support in the browser, there is no fallback mode for browsers without (or with disabled) support for JavaScript.

Take care! The documentation is the same for all clients and top-level domains, please do not directly copy-paste code found on this page into your production-grade code. Some differences may and do apply – please, read the documentation carefully.

Check-list for getting started really quickly:

  1. Load prerequisites – jQuery library,
  2. Add DOM element for the frame,
  3. Link the Instantor script,
  4. Initialize Instantor object,
  5. Add some information about the user,
  6. Load the frame.
  7. 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 copy-paste the following script, and place it somewhere in <body> section of your page. Just make sure there is a DOM element in the page for containing the frame (the one passed as a parameter to .load method) – e.g. <div id="itor"></div>.

Make sure you have loaded jQuery library before the Instantor snippet. You can use your own, local copy, or one provided by CDN. jQuery version 1.7, or newer is required.

Heads-up! This snippet is subject to change, do not use it in production code without verifying if everything works correctly.
<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.se/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. Adding DOM element

Secondly, Instantor frame needs containing DOM element in your HTML where it will get injected. That can be any block-level HTML element – for example, <div>, or <section>.

For example, put <div> with ID itor somewhere in your HTML:

<div id="itor"></div>

All examples here assume <div id="itor"> is present in the DOM tree.

Please, make sure your CSS code is not interfering with Instantor iframe, nor with iframe-containing DOM element – do not limit heights, the script will actively resize iframe height to match inner content height.

3. 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.se/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
Czech Republic https://www.instantor.cz/frame-loader/instantor-0.7.3.min.js
Denmark https://www.instantor.dk/frame-loader/instantor-0.7.3.min.js
Germany https://www.instantor.de/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, can stop working at any moment without prior notices, caching your own version can lead to unhandled issues.

4. 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>

5. 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 method.

6. 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>

Provided target DOM element should be valid jQuery selector. Failing to provide existing DOM element, the injector script will end with error message. Providing non-empty DOM element will result with content being overwritten by Instantor iframe.

7. 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, their parameters and their return values.

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 has functionality only for Swedish clients.
See .frameParam section for more info.

.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.
width (string) Sets iframe width. Default is 100%, accepts any valid CSS width.
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.
alternateColors (boolean) Switches to alternate iframe color-scheme. Alternate color-scheme must be previously built-in by Instantor team. If not, this switch has no effect.
prefillSSN (boolean) If set to true, activates automatic SSN-field pre-filling on bank login forms if the SSN is provided via .userParam.
Available only for Swedish banks, does nothing in other countries.

List of bank identification strings:

Bank ID Bank
se-danskebank Danske Bank Group
se-forex Forex Bank
se-handel Svenska Handelsbanken
se-ica ICA Banken
se-lansforsakringar Länsförsäkringar AB
se-nordea Nordea Bank
se-seb Skandinaviska Enskilda Banken
se-skandia Skandiabanken
se-swedbank Swedbank och Sparbankerna
Bank ID Bank
pl-aliorbank Alior Bank Spółka Akcyjna
pl-bgz Bank BGŻ S.A.
pl-bph Bank BPH
pl-pekao Bank Polska Kasa Opieki S.A.
pl-pocztowy Bank Pocztowy S.A.
pl-bnpparibas BNP Paribas Banku Polska
pl-bosbank BOŚ S.A.
pl-bpse25 BPS e25 - Bank Polskiej Spółdzielczości S.A.
pl-bzwbk Bank Zachodni WBK S.A.
pl-citibank Bank Handlowy w Warszawie S.A.
pl-ca Credit Agricole Bank Polska S.A.
pl-deutsche Deutsche Bank Polska S.A.
pl-eurobank Euro Bank
pl-getinbank Getin Noble Bank SA
pl-ingbank ING Bank Śląski
pl-mbank mBank S.A.
pl-meritum Meritum Bank
pl-millennium Bank Millennium Spółka Akcyjna
pl-pkopb PKO Bank Polski
pl-pkobp-nowy PKO Bank Polski – Nowy serwis
pl-plusbank24 Plus Bank
pl-toyota Toyota Bank
Bank ID Bank
cz-airbank Air Bank
cz-citibank Citibank
cz-sporitelna Česká spořitelna
cz-csob ČSOB
cz-equa EQUA Bank
cz-era ERA Bank
cz-erbank Evropsko-Ruská banka
cz-expobank Expobank (LBBW)
cz-fio FIO Bank
cz-gemoney GE Money Bank
cz-ingbank ING Bank
cz-mbank mBank
cz-oberbank Oberbank
cz-rbekonto RB eKonto
cz-sberbank Sberbank
cz-unicredit UniCredit Bank
cz-zuno ZUNO Bank
Bank ID Bank
dk-danskebank Danske Bank
dk-jyskebank Jyske Bank
dk-nordea Nordea Bank Danmark

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.
timed-out The process has failed due to bank communication timeout.
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,
  level: 'end level',
  success: true | false
}
Triggered when the process finishes.
Status reflects success state: true for success, false for failure – failure to finish the process means the process has been explicitly cancelled or declined by user, not by closing the Iframe, or abandoning the scrape.

Level contains string representation of process end level. See .listener method for more info.
processDescription
{
  string
}
Triggered when the process finishes.
If the description is provided by back-end, it will be returned as single string with process end description. If not provided, this even will not be triggered.
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.

.getBankList Optional

getBankList method returns a list of currently available banks for given TLD.

Instantor.getBankList(callbackFunction(response))
callbackFunction (function)
Callback function being executed when the response is received. Mandatory.

Once the callback function is called, function response will hold the following JavaScript object, filled with real values:

{
  status: true | false,
  errorMessage: 'error message',
  tld: {
    name: 'TLD identification',
    count: number
  },
  banks: [
    {
      UUID: 'bank UUID',
      identification: 'bank identification string',
      name: 'bank name'
    }
    …
  ]
}

If unsuccessful, response will contain error message, while count and list of banks will be set to null.

Take care! This method must be previously assigned to a TLD. If you want to use this method, please contact Instantor tech support. If not, this method will always return error message "Unsupported operation".

.destroy Optional

destroy method dereferences initialized iframe, removes its DOM element, removes all its referenced callback functions and event listeners.

Instantor.destroy()

Since JavaScript language does not allow dereferencing of an object within that object, to completely purge Instantor object, additional code on client side is needed to remove initialized variable.

Read! If you are integrating Instantor iframe for more than one realm, please read this paragraph.

There are two main Iframe injector code-bases: one for Spain and Finland, and another for all other realms – Sweden, Denmark, Germany, Poland and Czech republic.
Code-base groups are easily recognized by their version number, found in injector script file name: Spain and Finland use instantor-0.3.12.js, indicating code-base group Version 0.3, while other realms use instantor-0.7.3.js, indicating code-base group Version 0.7.

As long as you're writing code inside one of those code-bases, no changes are needed, code written for integrating iframe in, for example, Sweden is fully reusable in Poland, or any other realm in the group.

Reusing the code in cross-group realm, some changes must be made, since there are a few syntactic diferences, methods react to differently named "magic-words", some methods are differently named, and finally, some features are not supported.

Differences

For the beginning, script URLs are different, meaning you must use different scripts for different realms, regardless of the group.

While migrating existing code from Version 0.7 to Version 0.3, follow these guidelines:

  • Replace all calls to method .userParam with .userparam; replace user param "magic words" firstName and lastName with their lowercase equivalents – first_name and last_name.
    There is no support for "magic word" ssn.
  • Replace all calls to method .frameParam with .frameparam; take into account reduction of supported "magic words" – alternateColors and prefillSSN are not supported, bankID is replaced by separate method.
    See .frameparam for more info.
  • Replace calls to method .frameParam with "magic word" bankID with call to .set_active_bank; different realms use different bank identification strings.
  • Replace calls to method .attachEventListener with event name load with call to method .on_load.
  • There is no equivalent to .attachEventListener method for events other than load and processEnd – those are replaced with separate methods, .on_load and listener, respectively.
  • There is no equivalent to method .transactionParams. Use .userparam instead.

Please, read Version 0.3 API reference for more info.

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('demo.se');
  itor.load('#itor');
} catch(err) {}

Waiting.

See this example on jsFiddle: http://jsfiddle.net/Instantor/1vavt92k/.

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('demo.se');

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

Waiting.

See this example on jsFiddle: http://jsfiddle.net/Instantor/ez0423dr/.

3. Process end-event listener

This time, there is attached end-event listener.

try {
  var itor = new Instantor('demo.se');

  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.

See this example on jsFiddle: http://jsfiddle.net/Instantor/hhawuonk/.

4. Pre-selecting the bank

Pre-selecting the bank will show that bank login form, instead of default bank chooser. Swedish Nordea Bank will be shown here – if it is available.

try {
  var itor = new Instantor('demo.se');
  itor.frameParam('bankID', 'se-nordea');
  itor.load('#itor');
} catch(err) {}

Waiting.

See this example on jsFiddle: http://jsfiddle.net/Instantor/zdec7nx2/.

5. Fetching the list of active banks

Here is the example of fetching the list of currently active banks.

try {
  var itor = new Instantor('demo.se');
  itor.getBankList(function(response){
    if (response.status === true) {
      alert('Number of available banks: ' + response.tld.count);
    } else {
      alert('An error occured.\r\n' + response.errorMessage);
    }
  });
} catch(err) {}

Waiting.

See this example on jsFiddle: http://jsfiddle.net/Instantor/ut7zknvk/.