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.

Registration

In order for Company to use the Instantor service, it first needs to register with Instantor. As a part of the registration process, the Company will receive its API name and a secret API key. API name and API key will consequently 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 a protocols which the Company specified as its URL callback.
For additional security, all communication is also redundantly encrypted with the AES algorithm.


Instantor procedure for credit ability check consists of two independent components:

  1. User bank login procedure (iframe)

  2. Scoring and report delivery

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

Code snippet

Place this snippet 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.dk/frame-loader/instantor-0.7.3.min.js"></script>
<script type="text/javascript">
//<![CDATA[
  $(function(){
    try{
      /* Enter the username Instantor has provided to you */
      var itor = new Instantor('customer.se');

      /* Optionally, enter available user details */
      itor.userParam('userIdentification', '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('xyz', '123');

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

Report is delivered to the client via URL provided by the Company using HTTP POST method. 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 should be under a minute.


Client will be provided with his unique identifier and secret api key, which are used for decryption of the report. Instantor API provides all the necessary functionality for decrypting the payload. After succesfuly delivery and decryption, the client 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.

Push Examples

If a user has provided correct authentication credentials for his internet banking account, credit rating will ensue. After a user has been rated this information will be automatically pushed to the Company specified callback URL via the HTTP POST method.


Push Example

{
  "basicInfo": {
    "scrapeReport": {
      "scrapeDate": "2014-12-09T00:00:00",
      "status": "ok",
      "comment": "Process finished successfully",
      "reportNumber": 2,
      "isFinal": true
    },
    "bank": {
      "country": "SE",
      "abbreviation": "swedbank",
      "name": "Swedbank AB"
    },
    "source": "customer.inc",
    "username": "Ellie Butler",
    "address": "Limesfield Circle, 77653 Peterborough, Saint Lucia",
    "phone": "555 490-0732",
    "email": "ellie.butler@example.org",
    "miscEntryList": [
      {
        "provider": "customer.inc",
        "key": "client",
        "value": "credigo"
      },
      {
        "provider": "customer.inc",
        "key": "ssn",
        "value": "1234567890"
      },
      {
        "provider": "customer.inc",
        "key": "firstName",
        "value": "Ellie M."
      },
      {
        "provider": "customer.inc",
        "key": "lastName",
        "value": "Butler"
      },
      {
        "provider": "customer.inc",
        "key": "account",
        "value": "8770741-8188424403"
      },
      {
        "provider": "swedbank",
        "key": "PersonalNumber",
        "value": "191234567890"
      }
    ]
  },
  "reportTime": "2014-12-09T13:54:23.758+01:00",
  "scrapeTime": "2014-12-09T13:53:26.331+01:00",
  "successfulLogin": true,
  "accountNumbersForVerification": [
    "87707418188424403"
  ],
  "nameForVerification": "Ellie M. Butler",
  "personalNumberForVerification": "1234567890",
  "bankReport": {
    "bank": {
      "country": "SE",
      "abbreviation": "swedbank",
      "name": "Swedbank AB"
    },
    "owner": "Ellie Butler",
    "scrapeStatus": "ok",
    "monthsAvailable": 3,
    "numberOfAccounts": 4,
    "accountNumbersVerified": [
      {
        "accountNumber": "87707418188424403",
        "verified": true
      }
    ],
    "nameVerified": true,
    "personalNumberVerified": true,
    "totalNumberOfTransactions": 4,
    "averageNumberOfTransactionsMonth": 1.33,
    "averageAmountOfIncomingTransactionsMonth": 24.82,
    "averageAmountOfOutgoingTransactionsMonth": -601.08,
    "averageMinimumBalanceMonth": 21928.79,
    "numberOfLoans": 0,
    "amountOfLoans": 0,
    "cashFlow": [
      {
        "month": 0,
        "incoming": 0,
        "outgoing": -1803.24,
        "minBalance": 20726.63,
        "numberOfLoans": 0,
        "amountOfLoans": 0
      },
      {
        "month": -1,
        "incoming": 0,
        "outgoing": 0,
        "minBalance": 22529.87,
        "numberOfLoans": 0,
        "amountOfLoans": 0
      },
      {
        "month": -2,
        "incoming": 74.46,
        "outgoing": 0,
        "minBalance": 22529.87,
        "numberOfLoans": 0,
        "amountOfLoans": 0
      }
    ]
  },
  "scrape": {
    "scrapeReport": {
      "scrapeDate": "2014-12-09T00:00:00",
      "status": "ok",
      "comment": "Process finished successfully",
      "reportNumber": 2,
      "isFinal": true
    },
    "bank": {
      "country": "SE",
      "abbreviation": "swedbank",
      "name": "Swedbank AB"
    },
    "userDetails": {
      "name": "Ellie Butler",
      "address": "Limesfield Circle, 77653 Peterborough, Saint Lucia",
      "phone": "555 490-0732",
      "email": "ellie.butler@example.org"
    },
    "companyDetails": null,
    "accountList": [
      {
        "number": "8770741-8188424403",
        "kind": "Giro",
        "balance": 6287.04,
        "currency": "EUR",
        "iban": "HH77819086222927567182",
        "holderName": "Ellie Butler",
        "transactionList": [
          {
            "onDate": "2014-11-24T00:00:00",
            "description": "Fake transfer to\/from : VitalOnline",
            "amount": -872.11,
            "balance": 6287.04
          },
          {
            "onDate": "2014-11-23T00:00:00",
            "description": "Fake transfer to\/from : HyperMotors",
            "amount": -621.53,
            "balance": 7159.15
          },
          {
            "onDate": "2014-11-13T00:00:00",
            "description": "Fake transfer to\/from : NationalMed",
            "amount": -309.6,
            "balance": 7780.68
          },
          {
            "onDate": "2014-09-12T00:00:00",
            "description": "Fake transfer to\/from : Circuits Inc.",
            "amount": 74.46,
            "balance": 8090.28
          }
        ]
      },
      {
        "number": "3966783-6522599775",
        "kind": "Giro",
        "balance": 4981.88,
        "currency": "PAB",
        "iban": "UH63761019650696043401",
        "holderName": "Ellie Butler"
      },
      {
        "number": "8067332-6349708985",
        "kind": "Giro",
        "balance": 172.14,
        "currency": "IDR",
        "iban": "WY62548283773871265346",
        "holderName": "Ellie Butler"
      },
      {
        "number": "8686746-4402465208",
        "kind": "Giro",
        "balance": 9285.57,
        "currency": "BYR",
        "iban": "TZ65001337444202837642",
        "holderName": "Ellie Butler"
      }
    ]
  }
}

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.
incomplete Indicates that the process is still incomplete and that additional reports will follow.
partial Indicates that the process is still incomplete and that additional reports will follow.
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.
insufficient_data An indication that although a user has successfully logged in, either no accounts of interest could be located or the user had not used the accounts for an extended period of time (no transactions). In either case, no calculations can be performed, and all transaction variables will be set to "Unknown".
bank_error This could either indicate that the bank responded with an internal server error message, or that the bank was inaccessible for processing (server outage or maintenance).
parse_error If an error occurs while processing the users account, a parse error status will be set, meaning that we were unable to fully process the end users account at this time. Most parse errors will usually be promoted into bank errors after a human moderator has surveyed the problem which has raised the issue.
scrape_error This status indicates an issue with scraping process, due to changes in bank interface – either temporary, or permanent. Users account information was not accessed or parsed.
abandoned Frame was reloaded, or "Choose another banks" button was clicked.
timed_out Customer did not finish the login process, or the data collection process did not complete within predefined time interval.
blocked Data collection process was blocked because there is a previous process which is still in progress.
custom* Additional custom status messages may be available, dependent on specific country/company/bank combinations (e.g. banned_user, bank_redirect, etc…)

Java API (last update 11/Jan/2013)

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

PHP API (last update 24/Aug/2011)

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

.NET API (last update 7/Sep/2011)

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