BankingAPI is a user-friendly authentication service for markets where no electronic identity providers are widely available. The workflow runs a standard bank login process but the purpose of the login is the bank’s user verification and get account balances and transaction histories.

API Calls

Set up: POST to https://env.zignsec.com/v2/eid/iv_cc
Result: GET from https://env.zignsec.com/v2/eid/sessionid
where
env is API or test
iv_cc is iv_se, iv_es, iv_pl, etc – see the method list below.
sessionid is the session identifier retrieved from the setup call, named id in the response.

Call Sequence

Step 1. Set up session

POST to https://env.zignsec.com/v2/eid/iv_cc
where
env is API or test
iv_cc is iv_se, iv_es, iv_pl, etc… see below method list.

Note: To preselect a specific bank set the BankIdentifier parameter. To only allow a specific person to login set the PersonalNumber parameter.

List of Supported Countries and Banks

Note: If you do not have access to a domestic bank account you can in our test environment use the test bank together with “fake42!” as username and anything for password. Please note that this option is not possible on production accounts.

MethodCountrySupported banksTest bank
iv_czCzech RepublicLogin via these banksČSOB
iv_plPolandLogin via these banksBank Zahodny
iv_esSpainLogin via these banksCaixaBank
iv_seSwedenLogin via these banksSwedbank
iv_brBrazilLogin via these banksSantander
iv_fiFinlandLogin via these banksAktia
iv_[cc]  [cc] is the two letter country code (ISO 3166) to let the user select from the available identification method(s) for that country. 

Request Header

In order to send a message you need to authenticate yourself using the credentials given by ZignSec.

AuthorizationThis header parameter is the personal access token you received from ZignSec during the registration process.
Example: Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Required
Content-TypeSpecifies the media type of the request body data. Set to application/x-www-form-urlencoded. for post data and application/json if JSON object.
Example: Content-Type: application/x-www-form-urlencoded
Required
HostUse test.zignsec.com for test environment and api.zignsec.com for production environment.
Example: api.zignsec.com
Required

Request Body Parameters for Step 1 – Request Token

ParameterDescriptionRequired
personalnumberPre-selects and locks the login workflow to only allow for the specified person to login. It is currently supported in Sweden. This also enhances the user experience needing less keyboard input. Example:personalnumber=195206040759 (Swedish format is YYYYMMDDCCCC)No, but recommended
bankidentifierPre-selects the login workflow to use the specified bank – thus not showing the first page for selecting the bank from a list. This can enhance the user experience. In FAQ is an extensive list of bankidentifiersNo
relaystate

This optional parameter will be returned to you at the redirect back to your server. Use it to link an unique ID of your choice that you can parse. If not relaystate is specified, ZignSec will automatically set the ZignSec’s unique session identifier, the RequestID token here.

Example: relaystate=zignsec_eid_1234

No
configid

Here you can send in a GUID that represent a specific configuration. This is used to separate between multiple certificates, different layouts or to make different webhooks calls. If only one configuration it is used automatically.

Example: configid=d638a4ab-7382-4c5d-98e8-e90d3aa3e1be

No
target

If this parameter is supplied the browser session will finally be redirected to this URL-value. The URL-parameter value must must be URL-encoded.

Example: target=http%3A%2F%2Flocalhost%3A8080%2Fzignsec%2Freturn will result in a browser redirect to for example http://localhost:8080/zignsec/return?relaystate=96a09f3f-b764-4ed0-b9e8-2b29d95dcf15&service=eIDBasic where relaystate is ZignSec’s session token (RequestID) which can be used to to retrieve the results from the login session.

No
targetErrortargetError works as target except it is navigated on user cancel or error situations.No
layoutIf other html-layout is preferred other than the customer’s default setup. Contact ZignSec for layouts and default selection.No
languageDefault language is always English (EN), but can be overridden both on the customer setting level (by setting ‘DefaultLanguage’), or on call level through this request parameter.No
lookupPersonAddressCurrently works for Swedish Banking API. If set to true will automatically do a Swedish person address lookup with the verified PersonalNumber through the LookupPerson API using the official population register. The call will be charged separately. For a response example go here.No
lookupPersonAddressWhenMissingFor Swedish Banking API. If set to true works like lookupPersonAddress except that the address is fetched only if was not available from the bank.No
customAny customer specific data.No
webhookURL. The result will be send to this URL by POST method.No
webhook_emailEmail address. The result will be send to this Email.No

Response Body for Step 1 – Request Token

Each request returns a response with status and details. Both the request and the status request follow the same response structure described below.

idA unique session identifier generated for each workflow instance.
errorsA JSON array of error conditions, see error handling FAQ.
redirect_urlThe URL that the user need to be redirected to complete the data via the web interface. It is possible to load the URL in an iframe.

Table of response errors

CodeDescription
INVALID_PERSONALNUMBERInvalid Personal number, for example missing
INVALID_APPIDInvalid AppID
MISSING_CONFIGYour account has a missing config, contact ZignSec for help
INVALID_REQUESTSomething unexpected has gone wrong, contact ZignSec for help

Setup Request example (Swedish Bank)

POST https://test.zignsec.com/v2/eid/iv_se HTTP/1.1
User-Agent: Fiddler
Host: test.zignsec.com
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Authorization: YOUR_KEY...

Step 2. Run the login workflow

Simply navigate to the [redirect_url] to start the login workflow in a browser. It may be convenient to load the URL into an HTML IFrame element to get a windowed login integration in an existing web site.
In parallel, a Banking API login process is setup in the background. The exact backend technique is different from bank to bank.

Step 3. Get status/results

GET from https://env.zignsec.com/v2/eid/sessionid
where env is API or test and sessionid is retrieved in the setup call (named ‘id’ in the step 1 response).

How to get notified of Workflow Finished

Note that there is both active and passive notification for when the workflow is finished :

  • Callback: Set Target URL parameter in step 1 and when the target URL is navigated you can do the above collect-GET.
  • Webhook. To set up a webhook URL for callback, contact ZignSec. Results will be posted to the URL, see this example.
  • Polling: Repeatedly call the above collect-GET until the results contain a final result.

Response Description

idA unique session identifier generated for each workflow instance.
errors

A JSON array of error conditions, see error handling FAQ.

result

Note: This node is missing (deemed unnecessary) if the authentication is successful – ie when an identity node is present.

An object that describes the main result of the service call. It contains the following parameters:

Identity
The results for the Identity service are collected under this identity sub-item

state
Indicates whether the verification of the customer is completed or not. Possible values are PENDING, FINISHED. ERROR.
PENDING is a temporary state indicating that the user is involved in the process
FINISHED is a permanent state showing that the customer has completed the entire process and the call has a final result.
ERROR is a final state showing that the customer has completed with error, like timeout, aborted, exception.

Identity

This is a verified identity of the customer. The following parameters can be found in this object.

CountryCodeRepresents the ID providers country belonging. And consequentially the identified persons nationality.
FirstNameCan be an extraction from a full name depending on the ID provider.
LastNameCan be an extraction from a full name depending on the ID provider.
PersonalNumberNormally available in the nordic countries.
DateOfBirthBirth date is extracted from the personal number, currently Sweden, Norway, Finland, Estonia.
AgeComputed from the DateOfBirth.
IdProviderNameZignSec’s name for the Identity provider, for example BankIDSE, BankIDNO, NemId or Banking API.
IdentificationDateThe time the identification was performed.
IdProviderRequestIdNot always set. The identity provider’s unique id for the identification request. For easier tracking.
IdProviderPersonIdNot always set. A identity provider specific unique identifier for the person. For example in NemId it could be “PID=3272-7…” and so on.
CustomerPersonIdThe eID product has the possibility to save a customer specific reference for the person, to enable simplified login processes. If such a number was sent in, it will be shown here for completeness sake.
method

The name of the method initiated, for

Examplesbid” or “sbid-another

BankingAPI_IncomeVerA sub json structure that shows the raw banking info, such as account list. See the separate break-out table below.

Sub-node BankingAPI_IncomeVer json showing additional bank data fields

Address

User address information taken from Bank and structured into components.

Note: Will only be populated for certain countries and banks.

Note: Will also only be shown when the field IsAddressInfoPrivate is set to false by our partner.
AddressRow1
AddressRow2
PostalCode
Location
City
Country

AddressRawRaw unparsed address info from the bank. Note: Will only be shown when the field IsAddressInfoPrivate is set to false by our partner.
FirstNameUser first name from bank
LastNameUser last name from bank
MiddleName 
BirthDateFormat YYYY-MM-DD
AgeCalculated from BirthDate
PersonalNumberIn countries and banks where available. Formats depending on country.
PhoneNumberIn countries and banks where available
EmailIn countries and banks where available
AddressInfoRawA complete address if available from the bank, if many rows they are separated by a semi-colon.
BankAccountsArray of bank account information’s.
Number
Iban
HolderName
DataSourceName of data source provider
DataSourceRequestIDUnique data reference
DataSourceRequestTimeTimestamp
Bank

Country

Id

Name

IsAddressInfoPrivateData provider visibility flag. Note: Only if this flag is set to true by our provider we will show the Address and AddressRaw sub-responses.
IsPhoneNumberPrivateData provider visibility flag
IsEmailPrivateData provider visibility flag
IncomeVerification

PrimaryIncome

SecondaryIncomes

OtherRecurIncome

MeanAmountPayment
Last45dFound
Avg3m
Avg6m
Avg12m
MeanTimeBetweenPayments
Trend3m
Trend6m
Trend12m
DaysAgoLastPayment
AmountLastPayment
SpanMonths
NumPayments
Descriptions
AccountReportList
number
totalNumberOfTransactions
wholeMonthsAvailable
averageNumberOfTransactionsWholeMonth
averageAmountOfIncomingTransactionsWholeMonth
averageAmountOfOutgoingTransactionsWholeMonth
averageMinimumBalanceWholeMonth

cashFlow

calendarMonth
incoming
outgoing
minBalance
maxBalance
avgBalance
isWholeMonth

 

Get Results-request example

GET https://test.zignsec.com/v2/eid/bc539499-4953-4b54-8743-b1adb8d4de78/ HTTP/1.1
Authorization: YOUR-KEY..
Content-Type: application/x-www-form-urlencoded
Host: test.zignsec.com

Get Results-reponse example (with lookupPersonAddress=true)

Note: If lookupPersonAddress is not set, the lookupPersonAddress node will be missing in the response.

{
  "identity": {
    "CountryCode": "SE",
    "FirstName": "Geovanny",
    "LastName": "Thompson",
    "FullName": "Geovanny Thompson",
    "PersonalNumber": "130749441",
    "DateOfBirth": "0001-01-01",
    "Age": -1,
    "Gender": "",
    "Phone": "PRIVATE: 555 883-2534",
    "Email": "PRIVATE: [email protected]",
    "AddressInfoRaw": "PRIVATE: W Alexander Close 174, 88436 Irving, Mauritania",
    "IdProviderName": "BankingAPI",
    "IdentificationDate": "2019-11-11T16:06:27.689+01:00",
    "IdProviderRequestId": "43407434-c5ff-4d10-846d-eabfdcf79006",
    "IdProviderPersonId": "",
    "CustomerPersonId": ""
  },
  "BankingAPI_IncomeVer": {
    "FirstName": "Geovanny",
    "LastName": "Thompson",
    "MiddleName": null,
    "BirthDate": "0001-01-01T00:00:00",
    "Age": -1,
    "PersonalNumber": "130749441",
    "PhoneNumber": "PRIVATE: 555 883-2534",
    "Email": "PRIVATE: [email protected]",
    "AddressInfoRaw": "PRIVATE: W Alexander Close 174, 88436 Irving, Mauritania",
    "BankAccounts": [
      {
        "Balance": -3580.0,
        "Currency": "SEK",
        "AvailableAmount": -3580.0,
        "TransactionList": null,
        "Number": "SE5340709596405913100964",
        "Type": "Current",
        "Iban": "SE2743603823371374344355",
        "HolderName": "Geovanny Thompson"
      },
      {
        "Balance": 3534.0,
        "Currency": "SEK",
        "AvailableAmount": 3534.0,
        "TransactionList": null,
        "Number": "SE3654324420752957217050",
        "Type": "Savings",
        "Iban": "SE3813643784646221790868",
        "HolderName": "Geovanny Thompson"
      }
    ],
    "IdProviderName": "BankingAPI",
    "IdentificationDate": "2019-11-11T16:06:27.689+01:00",
    "IdProviderRequestId": "43407434-c5ff-4d10-846d-eabfdcf79006",
    "IdProviderPersonalId": null,
    "CustomerPersonalId": null,
    "Bank": {
      "Country": "se",
      "Id": "f8fc6cbc-7c0c-4cf6-916a-21af63eb8188",
      "Name": "Swedbank"
    },
    "IsAddressInfoPrivate": true,
    "IsPhoneNumberPrivate": false,
    "IsEmailPrivate": false,
    "IncomeVerification": {
      "PrimaryIncome": {
        "MeanAmountPayment": 20021.75,
        "Last45dFound": 1,
        "Avg3m": 20003.0,
        "Avg6m": 20001.17,
        "Avg12m": 20021.75,
        "MeanTimeBetweenPayments": 30.45,
        "Trend3m": 1.33,
        "Trend6m": 1.33,
        "Trend12m": 1.33,
        "DaysAgoLastPayment": 0,
        "AmountLastPayment": 20124.0,
        "SpanMonths": 11.17,
        "NumPayments": 12,
        "Descriptions": [
          "Fake account transaction; Fake; Primary/Fake money transfer : SystemsNet"
        ]
      },
      "SecondaryIncomes": {
        "MeanAmountPayment": 16662.31,
        "Last45dFound": 1,
        "Avg3m": 43330.67,
        "Avg6m": 46617.5,
        "Avg12m": 48306.33,
        "MeanTimeBetweenPayments": 9.83,
        "Trend3m": 0.77,
        "Trend6m": 0.72,
        "Trend12m": 0.69,
        "DaysAgoLastPayment": 19,
        "AmountLastPayment": 15011.0,
        "SpanMonths": 11.47,
        "NumPayments": 36,
        "Descriptions": [
          "Fake account transaction; Fake; Primary/Fake money transfer : Enterprises UK",
          "Fake account transaction; Fake; Secondary/Fake money transfer : iIndustrial",
          "Fake account transaction; Fake; Secondary/Fake money transfer : Robotic Tech"
        ]
      },
      "OtherRecurIncome": {
        "MeanAmountPayment": 2923.5,
        "Last45dFound": 1,
        "Avg3m": 3898.0,
        "Avg6m": 3898.0,
        "Avg12m": 3898.0,
        "MeanTimeBetweenPayments": 21.0,
        "Trend3m": 1.0,
        "Trend6m": 1.0,
        "Trend12m": 1.0,
        "DaysAgoLastPayment": 0,
        "AmountLastPayment": 2859.0,
        "SpanMonths": 10.5,
        "NumPayments": 16,
        "Descriptions": [
          "Fake account transaction; Fake; OtherRecur/Fake money transfer : Shipping Tech",
          "Fake account transaction; Fake; OtherRecur/Fake money transfer : ImportsWorld"
        ]
      },
      "Version": "1.0"
    },
    "AcoountReportList": [
      {
        "number": "SE5340709596405913100964",
        "totalNumberOfTransactions": 218,
        "wholeMonthsAvailable": 11,
        "averageNumberOfTransactionsWholeMonth": 17.636363636363637,
        "averageAmountOfIncomingTransactionsWholeMonth": 40787.18,
        "averageAmountOfOutgoingTransactionsWholeMonth": -3748.55,
        "averageMinimumBalanceWholeMonth": -229273.36,
        "cashFlow": [
          {
            "calendarMonth": "2019-11-01",
            "incoming": 4751.0,
            "outgoing": -1046.0,
            "minBalance": -7341.0,
            "maxBalance": -3580.0,
            "avgBalance": -6659.91,
            "isWholeMonth": false
          },
          {
            "calendarMonth": "2019-10-01",
            "incoming": 38291.0,
            "outgoing": -4795.0,
            "minBalance": -41866.0,
            "maxBalance": -5369.0,
            "avgBalance": -23377.84,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-09-01",
            "incoming": 41612.0,
            "outgoing": -2935.0,
            "minBalance": -80580.0,
            "maxBalance": -40025.0,
            "avgBalance": -61618.2,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-08-01",
            "incoming": 40769.0,
            "outgoing": -3162.0,
            "minBalance": -117298.0,
            "maxBalance": -78272.0,
            "avgBalance": -96780.48,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-07-01",
            "incoming": 40148.0,
            "outgoing": -4577.0,
            "minBalance": -152636.0,
            "maxBalance": -116694.0,
            "avgBalance": -133762.94,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-06-01",
            "incoming": 42656.0,
            "outgoing": -5524.0,
            "minBalance": -190553.0,
            "maxBalance": -151910.0,
            "avgBalance": -171958.1,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-05-01",
            "incoming": 42904.0,
            "outgoing": -4700.0,
            "minBalance": -229435.0,
            "maxBalance": -189035.0,
            "avgBalance": -208933.9,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-04-01",
            "incoming": 39651.0,
            "outgoing": -1044.0,
            "minBalance": -266594.0,
            "maxBalance": -227972.0,
            "avgBalance": -247158.37,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-03-01",
            "incoming": 42857.0,
            "outgoing": -3726.0,
            "minBalance": -306230.0,
            "maxBalance": -266579.0,
            "avgBalance": -286808.71,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-02-01",
            "incoming": 39771.0,
            "outgoing": -2475.0,
            "minBalance": -343232.0,
            "maxBalance": -305050.0,
            "avgBalance": -325354.39,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-01-01",
            "incoming": 39165.0,
            "outgoing": -3583.0,
            "minBalance": -378873.0,
            "maxBalance": -342448.0,
            "avgBalance": -360368.61,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2018-12-01",
            "incoming": 40835.0,
            "outgoing": -4713.0,
            "minBalance": -414710.0,
            "maxBalance": -378588.0,
            "avgBalance": -396400.68,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2018-11-01",
            "incoming": 38939.0,
            "outgoing": -3690.0,
            "minBalance": -449221.0,
            "maxBalance": -413647.0,
            "avgBalance": -421921.0,
            "isWholeMonth": false
          }
        ]
      },
      {
        "number": "SE3654324420752957217050",
        "totalNumberOfTransactions": 219,
        "wholeMonthsAvailable": 11,
        "averageNumberOfTransactionsWholeMonth": 18.181818181818183,
        "averageAmountOfIncomingTransactionsWholeMonth": 40633.18,
        "averageAmountOfOutgoingTransactionsWholeMonth": -3651.82,
        "averageMinimumBalanceWholeMonth": -239793.64,
        "cashFlow": [
          {
            "calendarMonth": "2019-11-01",
            "incoming": 23433.0,
            "outgoing": -1108.0,
            "minBalance": -19434.0,
            "maxBalance": 3534.0,
            "avgBalance": -17030.73,
            "isWholeMonth": false
          },
          {
            "calendarMonth": "2019-10-01",
            "incoming": 39855.0,
            "outgoing": -3029.0,
            "minBalance": -56512.0,
            "maxBalance": -18736.0,
            "avgBalance": -36970.81,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-09-01",
            "incoming": 40565.0,
            "outgoing": -5242.0,
            "minBalance": -91340.0,
            "maxBalance": -55617.0,
            "avgBalance": -74183.17,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-08-01",
            "incoming": 41695.0,
            "outgoing": -4032.0,
            "minBalance": -129112.0,
            "maxBalance": -90940.0,
            "avgBalance": -109482.32,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-07-01",
            "incoming": 38335.0,
            "outgoing": -3380.0,
            "minBalance": -163558.0,
            "maxBalance": -126994.0,
            "avgBalance": -144652.74,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-06-01",
            "incoming": 42124.0,
            "outgoing": -2945.0,
            "minBalance": -202737.0,
            "maxBalance": -163558.0,
            "avgBalance": -183816.43,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-05-01",
            "incoming": 41711.0,
            "outgoing": -3668.0,
            "minBalance": -242164.0,
            "maxBalance": -201353.0,
            "avgBalance": -221102.68,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-04-01",
            "incoming": 39634.0,
            "outgoing": -4287.0,
            "minBalance": -277295.0,
            "maxBalance": -240757.0,
            "avgBalance": -258602.1,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-03-01",
            "incoming": 41972.0,
            "outgoing": -5916.0,
            "minBalance": -313107.0,
            "maxBalance": -276127.0,
            "avgBalance": -294810.84,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-02-01",
            "incoming": 39813.0,
            "outgoing": -2404.0,
            "minBalance": -350289.0,
            "maxBalance": -311714.0,
            "avgBalance": -331959.43,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2019-01-01",
            "incoming": 38510.0,
            "outgoing": -3842.0,
            "minBalance": -385783.0,
            "maxBalance": -349592.0,
            "avgBalance": -366846.58,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2018-12-01",
            "incoming": 42751.0,
            "outgoing": -1425.0,
            "minBalance": -425833.0,
            "maxBalance": -384260.0,
            "avgBalance": -406955.06,
            "isWholeMonth": true
          },
          {
            "calendarMonth": "2018-11-01",
            "incoming": 18176.0,
            "outgoing": -1302.0,
            "minBalance": -442544.0,
            "maxBalance": -425586.0,
            "avgBalance": -434213.76,
            "isWholeMonth": false
          }
        ]
      }
    ]
  }
}