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

The latest version of this document can be retrieved from https://www.instantor.com/api/doc

Credibility for Your Business

Security is one of the most important aspects of successful e-commerce. Risk reduction is a part of everyday business life and often involves the time-consuming administration of collecting copies of documents. The key is identification and creditworthiness. The Instantor Sigill stands for secure e-commerce and distinguishes you as a trustworthy partner. Let our well-known logo promote your business and display your competitive advantage.

Use

As our client, you are entitled to use the Instantor Sigill in your marketing. For example, you can include our logo on your website, in your email signature, in your promotional material or on your business card.

Depiction of standard journey (workflow) for end user (customer).

How Instantor works

Registration

For Company to be able to use the Instantor service, Company is required to register with Instantor. As a part of the registration process, the Company will receive API name and a secret API key. API name and API key will be used in all communication with Instantor for identification, verification and security purposes.

Communication basics

Requests sent from Company to Instantor may go either through an unsecured HTTP channel, or through the secure version, HTTPS (security guaranteed by a Verisign certificate). Responses sent from Instantor to Company will go through protocols which the Company specified as an endpoint URL (callback URL).
For additional security, all communication is also redundantly encrypted with the AES algorithm.


Instantor procedure for obtaining end user's (customer's) financial data consists of two independent components:

  1. Frontend process: bank login procedure (Instantor's IFrame)

  2. Backend process: data collection, and delivery.

It's up to Company's business logic to connect these components.

Code snippet (IFrame)

Purpose of IFrame is to provide bank login interface to end users. Login process could be successful, or unsuccessful (invalid login credentials, unexpected error, bank is temporarily unavailable, etc.) In all cases, appropriate message is returned within IFrame, and relevant response is triggered providing Company with flexibility to define custom workflow for their users. More details…

For example, if end user provided valid credentials, and login process was successful - redirect user to the next step in a loan application process.

Example of IFrame code snippet for Swedish market. Snippet should be placed somewhere in the body section of the HTML:

<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[
  $(function(){
    try{
    
      /* Enter API name Instantor has provided to you */
      var itor = new Instantor('APIName.se');

      /* Optionally, enter relevant process details */
      
      /* Parameter 'environment' is used to controll endpoint for delivering data. Default is 'prod'. */
      itor.userParam('environment', 'test');

      /* 'uniqueID' is an example of parameter that could be used to link specific request made by an end user to a set of data provided by Instantor. */
      /* Parameter and value are returned in the reports. */
      itor.userParam('uniqueID', '69017b4d-6869-48d5-a029-f21042a69e35);

      /* Initiate the Instantor iframe 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 'process-error':
            /* 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;
          default:
            /* Process encountered an error. */
            break;
        }
      });
    } catch(err) {}
  });
//]]>
</script>
Heads-up! Please, make sure you have loaded jQuery library. You can use your own, local copy, or one provided by CDN (like in this code snippet example). Version 1.7+ is required.

If end user provided valid netbanking credentials, data collection process will start (user details, accounts and transactions). As data is being received from the bank - one or more reports are compiled and sent to Company as HTTP POST request to pre-defined callback URL. Data will be encrypted.

In case of an error during data collection process - a report will be sent as well, and status will denote cause od error. Only in case of successful data collection process - status in the data report will be "ok".

The time required for report to be delivered depends on the amount of data on the users bank account, and on the bank interface speed, but the expected time for 12 months of transactions should be under a minute.


Company will be provided with unique identifier, API key, and a secret API key, which are used for decryption of the report. Instantor API provides all the necessary functionality for decrypting the payload, and are available for .NET, Java and PHP.

After data delivery and decryption, Company is required to respond to the original HTTP request with plain text message in form of OK: <msg_id>, where <msg_id> is unique identifier for that report and is sent as a POST parameter with key msg_id. For more information, take a look at examples provided by Instantor API.

For example:

...source=APIName&msg_id=154c798aa69-1463637551721&action=report%2Fuser%2Fdata&encryption=B64%2FMD5%2FAES%2FCBC%2FPKCS5&payload=fLaaLEvgWN9leASb0g3TNZx4yp0D4yjFcnUNpOgsIHJH9...
			  

Expected response would be:

OK: msg-154c798aa69-1463637551721
			  

Report example

Data collected from the bank will be encrypted and send as HTTP POST request to Company's predefined endpoint URL. Example of decrypted data is listed below.


Report example

{ 
   "instantorRequestId":"30150cb9-1855-4085-9ecb-cf7072742403",
   "processFinishedTime":"2016-11-28T11:38:43.991+01:00",
   "processStartTime":"2016-11-23T10:19:50.824+01:00",
   "processStatus":"ok",
   "reportNumber":2,
   "miscParams":[ 
      { 
         "name":"report_misc_param_name",
         "value":"report_misc_param_value"
      }
   ],
   "accountReportList":[ 
      { 
         "number":"1234-5678-90123",
         "totalNumberOfTransactions":33,
         "wholeMonthsAvailable":3,
         "averageNumberOfTransactionsWholeMonth":10.3,
         "averageAmountOfIncomingTransactionsWholeMonth":0.0,
         "averageAmountOfOutgoingTransactionsWholeMonth":-12.0,
         "averageMinimumBalanceWholeMonth":-36.0,
         "cashFlow":[ 
            { 
               "calendarMonth":"2016-11-01",
               "incoming":0.0,
               "outgoing":0.0,
               "minBalance":-48.0,
               "maxBalance":-48.0,
               "avgBalance":-48.0,
               "isWholeMonth":false
            }
         ]
      }
   ],
   "userDetails":{ 
      "name":"netbanking_owner_name",
      "address":[ 
         "Address 1"
      ],
      "phone":[ 
         "Phone 1"
      ],
      "email":[ 
         "Email 1"
      ],
      "personalIdentifier":[
         { 
            "name":"personal_id_name",
            "value":"personal_id_value"
         }
      ]
   },
   "bankInfo":{ 
      "name":"bank_name",
      "country":"country_identifier",
      "id":"bank_identifier"
   },
   "accountList":[ 
      { 
         "number":"1234-5678-90123",
         "type":"account_type",
         "balance":-48.0,
         "currency":"PLN",
         "iban":"account_iban",
         "holderName":"Jon Doe",
         "openedAt":"date",
         "availableAmount":100.00,
         "nationalBankId":{ 
            "name":"national_bank_id_name",
            "value":"123123123"
         },
         "transactionList":[ 
            { 
               "onDate":"2016-11-01",
               "valueDate":"2016-11-01",
               "bookingDate":"2016-11-01",
               "description":"transaction_description",
               "amount":0.0,
               "balance":-48.0,
               "type":"transaction_type",
               "referenceID":"transaction_reference_id",
               "category":"transaction_category",
               "payerPayeeName":"payer_payee_name",
               "payerPayeeAccount":"payer_payee_account",
               "params":[
                  {
                     "name":"transaction_param_name",
                     "value":"transaction_param_value"
                  }
               ]
            }
         ]
      }
   ]
}

Possible statuses and descriptions

The status field of the process_report variable can be any of the enumerations listed below, while the comment field further describes the listed status.

Status Description
ok Indicates that the process has finished successfully.
When list of accounts and transactions are empty there are 3 possible explanations:
  • There are no transactions in requested date interval (3, 6, or 12 months).
  • There are no current, or savings accounts linked to customer's online netbanking account.
  • Accounts and transactions are omitted in product configuration.
process_error An error occured during data collection, or data processing. Most common cause is communication failure with a bank.
invalid_login The system could not process the bank using the end user provided credentials, thus the end user should be invited to retry again.
abandoned Frame was reloaded, or "Choose another banks" button was clicked.
blocked Data collection process was blocked because there is a previous process which is still in progress.

Java API (last update 14/Jun/2017)

You can download the latest version of the Instantor Java API here:

PHP API (last update 09/Jun/2017)

You can download the latest version of the Instantor PHP API here:

.NET API (last update 14/Jun/2017)

You can download the latest version of the Instantor .NET API here: