README

Intro

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: User bank login procedure (iframe) 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 Delivery

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.

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

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…)

wongatech / instantor_php_api

Maintainers

Details