Important!

This JavaScript reference page covers integration of Iframe for banks in Spain and Finland.

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. Add DOM element for the frame,
  2. Link the Instantor script,
  3. Initialize Instantor object,
  4. Add some information about the user,
  5. Load the frame.
  6. Add feedback listener

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

<script type="text/javascript" src="https://www.instantor.com/instantor-0.3.12.js"></script>
<script type="text/javascript">
//<![CDATA[
try{
  /* Enter the username Instantor has provided to you */
  var itor = new Instantor('company.inc');

  /* Enter all available user details */
  itor.userparam('user_identification', '12345678901');
  itor.userparam('first_name', 'NAME');
  itor.userparam('last_name', 'SURNAME');
  itor.userparam('account', '7890 7890 7890 78');

  /* Initiate the Instantor iframe */
  itor.load('#itor');

  /* Optional function to process the feedback messages */
  itor.listener(function(response){
    switch(response){
      case 'process-finished':
        /* Process finished successfully. */
        break;
      case 'process-error':
        alert('Process encountered an error.');
        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;
      case 'paused':
        /* N-th step of bank log-in procedure. DO NOT hide iframe on this step. */
        break;
      default:
        /* Process encountered unhandled exception. */
        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 DOM element

First of all, Instantor frame needs containing DOM element in your HTML where it will
get injected. That can be any block-level HTML element, <div>, or
<section> would do fine.

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.

2. Linking the script

Secondly, 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.es/instantor-0.3.12.js"></script>

Make sure you are using correct top-level domain for your targeted market. For example,
if you are targeting Finnish markets, use instantor.fi, if you are
integrating Spanish client, use instantor.es.

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

Country Link
Finland https://www.instantor.fi/instantor-0.3.12.js
Spain https://www.instantor.es/instantor-0.3.12.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.

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');
}
</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('first_name', 'NAME');
  itor.userparam('last_name', 'SURNAME');
  itor.userparam('account', '7890 7890 7890 79');
}
</script>

Quick list of special keywords: first_name, last_name,
email, account, dni.

Read more about userparam keywords in API
reference → .userparam
section.

You can add additional and/or change some details of the frame — using
frameparam method.
Read more about frameparam in API
reference → .frameparam
section.

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('first_name', 'NAME');
  itor.userparam('last_name', 'SURNAME');
  itor.userparam('account', '7890 7890 7890 79');

  itor.load('#itor');
}
</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.

6. Attaching feedback listener

Event listener provide process feedback to your page. 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('first_name', 'NAME');
  itor.userparam('last_name', 'SURNAME');>
  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 'process-error':
        /* Process encountered an error. */
        alert('The process encountered an error.');
        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;
      case 'paused':
        /* N-th step of bank log-in procedure. DO NOT hide iframe on this step. */
        break;
      default:
        /* Process encountered unhandled exception. */
        alert('The process encountered unhandled exception: '+response);
        break;
    }
  });
}
</script>

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

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

Constructor

Instantor object constructor accepts two arguments: source,
and sub-source.

Instantor(source [, sub-source])
source (string)
Main source identification. Received from Instantor tech support.
Mandatory.
sub-source (string)
Sub-source identification. Optional.

.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
first_name (string) User’s first name
last_name (string) User’s last name
email (string) User’s e-mail address
account (string) User’s account
dni (string) User’s dni

.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 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
width (string) Sets iframe width. Default is 660px, accepts any valid CSS width.
Use '100%' to fill containing DOM element width.
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.
branding (string) Hides branding in header and footer. By default brand is always visible.
Example of hiding brand: Instantor.frameparam(‘branding’, ‘0’);

.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.
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.
server-overloaded The process has failed due to server overload.
paused The process has been paused. Chosen bank has multi-step log-in procedure,
current step has been displayed, awaiting additional user credentials.
Take care! Paused response indicates additional user credentials are
required for bank login, make sure you do not hide iframe on this response.

Request identifier

The request identifier is a UUID v4 string issued whenever a user tries to login into a bank.

It can be used to uniquely identify each login attempt and each report.

Take care! The request identifier is generated only when a user starts the login process.
It is undefined until a user tries to login.When in doubt, use the safer .on_request_identifier_change method instead of .get_request_identifier

Example flow

Process step Request identifier availability
1. You create a new Instantor object: var itor = new Instantor(username); identifier is NOT set
2. You call itor.load('#itor') identifier is NOT set
3. User selects a bank identifier is NOT set
4. User fills in credentials and tries to login identifier IS set to identifier1
5. User login failed identifier IS set to identifier1
6. User selects a new bank identifier IS set to identifier1
7. User fills in credentials and tries to login again identifier IS NEW and set to identifier2
8. User successfully logs in identifier IS set to identifier2

Example code snippet


  /* Enter the username Instantor has provided to you */
  var itor = new Instantor('company.inc');

  /* checking: the request identifier is currently NOT set */
  itor.get_request_identifier(); // undefined

  /* you can be notified when the request identifier is set */
  itor.on_request_identifier_change(function(identifier){
    // the identifier is now set
    // this gets triggered whenever a user tries to login
    // NOTE: it can be triggered multiple times per user visit to your page

    alert(identifier); // will alert the identifier string
  })

  /* Initiate the Instantor iframe */
  itor.load('#itor');

  /* checking: the request identifier is still NOT set */
  itor.get_request_identifier(); // undefined

.on_request_identifier_change
Optional

on_request_identifier_change
method attaches a listener function that is triggered when a new
request identifier
is issued.

The
request identifier
is issued whenever a user tries to login into a bank. It can be used to uniquely identify each login attempt and report.
See Request identifier documentation

Instantor.on_request_identifier_change(callback);
callback
(function)
Callback function that gets executed whenever the request identifier changes.
Mandatory.

The callback function will be invoked and passed one parameter: the new request identifier.

It can be triggered multiple times per user visit, please see Request identifier documentation

.get_request_identifier
Optional

get_request_identifier
method returns the value of the current request identifier.

The
request identifier
is issued whenever a user tries to login into a bank. It can be used to uniquely identify each login attempt and report.
See Request identifier documentation

var identifier = Instantor.get_request_identifier();

The method returns a string that identifies the current login attempt.
If the user did not try to login yet, this returns undefined.

The request identifier can change multiple times per user visit, please see Request identifier documentation

.set_active_bank Optional

set_active_bank method is used for setting a bank to be selected as
a default when the iframe loads.

Instantor.set_active_bank(bank_id)
bank_id (string)
Bank ID, as provided by Instantor tech support. Mandatory.

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.

Alternatively, for clients in Spain, bank_id can be se to four-number
bank code.

List of bank identification strings:

Bank ID Bank
es-abanca Abanca
es-bancamarch Banca March
es-pastor Banco Pastor
es-sabadell Banco Sabadell
es-bmn Banco Mare Nostrum
es-bancopopular Banco Popular
es-bankia Bankia
es-bankinter BankInter-ES
es-bbva BBVA
es-catalunya Caixa Catalunya
es-cajaespana EspañaDuero
es-cajarural Caja Rural
es-cajamar Cajamar
es-deutsche Deutsche Bank
es-evo EVO
es-ibercaja Ibercaja
es-ingdirect ING Direct
es-kutxa Kutxabank
es-lacaixa La Caixa
es-liberbank Liberbank
es-santander Santander
es-unicaja Unicaja
es-ingenieros Caja de Ingenieros

Bank code Bank
0019 Deutsche Bank
0049 Santander
0061 Banca March
0075 Banco Popular
0081 Banco de Sabadell
0128 BankInter-ES
0182 BBVA
0238 Banco Pastor
0239 EVO
0487 Banco Mare Nostrum
1465 ING Direct
2013 Caixa Catalunya
2038 Bankia
2080 Abanca
2085 Ibercaja
2095 Kutxabank
2100 La Caixa
2103 Unicaja
2425 Caja España
3058 Cajamar
3025 Caja de Ingenieros
Take care! Bank codes are available only for listed Spanish
banks. Using bank codes for different countries, or using unlisted Spanish bank
codes will not set active bank — it will fail silently, and show standard
iframe bank selection drop-down list.
Bank ID Bank
aktia Aktia
fi-danskebank Danske Bank
handel Handelsbanken
fi-lahitapiola LähiTapiola
nordea Nordea
fi-omasp Oma SP
op Osuuspankki
suupo POP Pankki
fi-saasto Säästöpankki
fi-spankki S-Pankki

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.

.on_load Optional

on_load method is used for triggering a callback function when the
iframe is fully loaded and ready.

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

.get_bank_list Optional

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

Instantor.get_bank_list(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: [
    {
      identification: 'bank identification string',
      name: 'bank name',
      icon: string
    }
    …
  ]
}

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

Bank logo icon is optional, if you want to use that feature, please contact Instantor
tech support. Once enabled, response string will contain Base64-encoded 16×16
pixels PNG image with bank logo.

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”.
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.3 to Version 0.7, follow these guidelines:

  • Replace all calls to method .userparam with .userParam;
    replace user param “magic words” first_name and
    last_name with their camelCase equivalents —
    firstName and lastName.
  • Replace all calls to method .frameparam with .frameParam;
    there are additional supported “magic words”.See .frameParam reference for
    more info.
  • There is no support for end-event listener keyword
    paused, that functionality is partially replaced by
    .attachEventListener with event name displayChange.See .attachEventListener
    reference for more info.
  • Replace calls to method .set_active_bank with .frameParam
    with “magic word” bankID; different realms use different
    bank identification strings.
  • Replace calls to method .on_load with .attachEventListener
    with event name load.
  • There is no equivalent to method .set_alternative_link.

Please, read Version 0.7 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) {}

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) {}

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) {}

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) {}

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