ZignSec

eID: BankingAPI -eu -mx -br

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 just the bank’s user verification, no account balances or transaction histories are read or touched.

Note: Recently added parameters lookupPersonAddress, lookupPersonAddressWhenMissing and targetError

API Calls

Set up: POST to https://env.zignsec.com/v2/eid/bli_CC
Result: GET from https://env.zignsec.com/v2/eid/sessionid
where env is api or test and bli_CC is bli_se, bli_dk, bli_uk, etc… see the method list below.
and sessionid is the session identifier retrieved from the setup call, named ‘id’ in the response.

Call Order

Step 1. Call our API entry point to set up a login workflow

API Entry Point

POST to https://env.zignsec.com/v2/eid/bli_CC
where env is api or test and bli_CC is bli_se, bli_dk, bli_uk, 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

Method Description
bli_bg Bulgaria: Login via these banks. Test user: EFG Postbank; fake42!
bli_hr Croatia: Login via these banks. Test user: Privredna banka Zagreb (PBZ); fake42!
bli_cz Czech Republic: Login via these banks. Test user: ČSOB; fake42!
bli_dk Denmark: Login via these banks. Test user: Jyske Bank; fake42!
bli_ee Estonia: Login via these banks. Test user: Citadele; fake42!
bli_fi Finland: Login via these banks. Test user: Aktia; fake42!
bli_ge Georgia: Login via these banks. Test user: Bank of Georgia; fake42!
bli_lv Latvia: Login via these banks. Test user: Citadele; fake42!
bli_lt Lithuania: Login via these banks. Test user: Citadele; fake42!
bli_nl Netherlands: Login via these banks. Test user: Triodos Bank; fake42!
bli_no Norway: Login via these banks. Test bank: DNB -user: fake42! -password: 123456
bli_pl Poland: Login via these banks. Test user: Bank Zahodny; fake42!
bli_ro Romania: Login via these banks. Test user: Alpha Bank; fake42!
bli_es Spain: Login via these banks. Test user: CaixaBank; fake42!
bli_se Sweden: Login via these banks. Test user: Swedbank; fake42!
bli_uk United Kingdom: Login via these banks. Note that we use code ‘uk’ instead of the ISO-3166-language code, which is ‘gb’. Test user: Lloyds; fake42!
bli_br Brazil: Login via these banks. Test user: Santander; fake42!
bli_mx Mexico: Login via these banks. Test user: Santander; fake42!
[cc] [cc] is a two letter country code (iso standard) to let the use select from a button list of available identification method(s) for that particular country.

 

Request Header

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

Authorization This header parameter is the personal access token you received from ZignSec during the registration process.
Example: Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Required
Content-Type Specifies 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
Host Use test.zignsec.com for test enviroment and api.zignsec.com for production enviroment.
Example: api.zignsec.com
Required

Request Body Parameters for Step 1 – Request Token

Parameter Description Required
personalnumber Pre-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
bankidentifier Pre-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 the faq is an extensive list of bankidentifiers No
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 reslaystate is ZignSec’s session token (RequestId) which can be used to to retrieve the results from the login session.

No
targetError targetError works as target except it is navigated on user cancel or error situations. No
layout If other html-layout is preferred ohter than the customer’s default setup. Contact ZignSec for layouts and default selection. No
language Default language is always English (EN), but can be overriden both on the customer setting level (by setting ‘DefaultLanguage’), or on call level through this request parameter. No
lookupPersonAddress Currently 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
lookupPersonAddressWhenMissing For 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
custom Any customer specific data. 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.

id The session identifier, a GUID value used to identify the web workflow started. The value is unique to each workflow instance, is randomly-generated by ZignSec, and is returned in the response message immediately following the web service request.
errors A JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error.
code
Code for the error. List of codes is in table below.
description
A string that describes the type of error that occurred.If no errors occur, then this object is empty.
errors : []
redirect_url The 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

Code Description
INVALID_PERSONALNUMBER Invalid Personal number, for example missing
INVALID_APPID Invalid AppId
MISSING_CONFIG Your account has a missing config, contact ZignSec for help
INVALID_REQUEST Something unexpected has gone wrong, contact ZignSec for help

Setup Request example (Swedish Bank)

            POST https://test.zignsec.com/v2/eid/bli_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. Start the login workflow in a web browser

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: Call our API to retrieve status/error or collected user identity data

API Endpoint

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

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

id A GUID value used to identify the web service request. The value is unique to each web service request, is randomly-generated by ZignSec, and is returned in the response message immediately following the web service request.
errors A JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error.
code
Code for the error. List of codes is in table in the response section.
description
A string that describes the type of error that occurred.If no errors occur, then this object is empty.
errors : []
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.
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.

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

CountryCode Represents the ID providers country belonging. And consequentially the identified persons nationality.
FirstName Can be an extraction from a full name depending on the ID provider.
LastName Can be an extraction from a full name depending on the ID provider.
PersonalNumber Normally available in the nordic countries.
DateOfBirth Birth date is extracted from the personal number, currently Sweden, Norway, Finland, Estonia.
Age Computed from the DateOfBirth.
IdProviderName ZignSec’s name for the Identity provider, for example BankIDSE, BankIDNO, NemId or Banking API.
IdentificationDate The time the identification was performed.
IdProviderRequestId Not always set. The identity provider’s unique id for the identification request. For easier tracking.
IdProviderPersonId Not always set. A identity provider specific unique identifier for the person. For example in NemId it could be “PID=3272-7…” and so on.
CustomerPersonId The 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 A sub json structure that shows the raw banking info, such as account list. See the separate break-out table below.

Sub-node BankingAPI 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

AddressRaw Raw unparsed address info from the bank. Note: Will only be shown when the field IsAddressInfoPrivate is set to false by our partner.
FirstName User first name from bank
LastName User last name from bank
MiddleName
BirthDate Format YYYY-MM-DD
Age Calculated from BirthDate
PersonalNumber In countries and banks where available. Formats depending on country.
PhoneNumber In countries and banks where available
Email In countries and banks where available
AddressInfoRaw A complete address if available from the bank, if many rows they are separated by a semi-colon.
BankAccounts Array of bank account informations.
NumberIbanHolderName
DataSource Name of data source provider
DataSourceRequestID Unique data reference
DataSourceRequestTime Timestamp
Bank Country

Id

Name

IsAddressInfoPrivate Data provider visibility flag. Note: Only if this flag is set to true by our provider we will show the Address and AddressRaw sub-responses.
IsPhoneNumberPrivate Data provider visibility flag
IsEmailPrivate Data provider visibility flag

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": "JAN RAGNAR",
            "LastName": "GREN",
            "FullName": "JAN RAGNAR GREN",
            "PersonalNumber": "198710260070",
            "DateOfBirth": "1987-10-26",
            "Age": 30,
            "IdProviderName": "BankingAPI",
            "IdentificationDate": "2018-10-26T13:02:00.518+02:00",
            "IdProviderRequestId": "3413debc-056d-4811-9697-8de5df22fbea",
            "IdProviderPersonId": "",
            "CustomerPersonId": ""
      },
      "BankingAPI": {
            "FirstName": "JAN RAGNAR",
            "LastName": "GREN",
            "MiddleName": null,
            "BirthDate": "1987-10-26T00:00:00",
            "Age": 30,
            "PersonalNumber": "196710260070",
            "PhoneNumber": "",
            "Email": "",
            "AddressInfoRaw": "",
            "BankAccounts": [
                  {
                        "Number": "871026-0070",
                        "Type": "Personkonto",
                        "Iban": "SE0230000000001234567",
                        "HolderName": "GREN JAN"
                  },
                  {
                        "Number": "3204 12 34567",
                        "Type": "Förmånskonto",
                        "Iban": "SE9330000000032041234567",
                        "HolderName": "GREN JAN RAGNAR"
                  }
            ],
            "IdProviderName": "BankingAPI",
            "IdentificationDate": "2018-10-26T13:02:00.518+02:00",
            "IdProviderRequestId": "3413debc-056d-4811-9697-8de5df22fbea",
            "IdProviderPersonalId": null,
            "CustomerPersonalId": null,
            "Bank": {
                  "Country": "se",
                  "Id": "bb6174fd-3115-41f9-91b4-12d6223e2f60",
                  "Name": "Nordea Bank"
            },
            "IsAddressInfoPrivate": false,
            "IsPhoneNumberPrivate": false,
            "IsEmailPrivate": false
      },
      "LookupPersonAddress": {
            "PersonStatus": "",
            "FirstName": "Jan Ragnar",
            "LastName": "Gren",
            "MainFirstName": "Jan",
            "Address": "Tranebergsvägen 3",
            "Address2": null,
            "PostalCode": "18123",
            "Location": null,
            "City": "Solna",
            "Province": null,
            "CountryCode": "se",
            "Phone": null,
            "PhoneNumbers": [
                  "08-51234567",
                  "073-41234567"
            ],
            "Email": null,
            "DateOfBirth": "19871026",
            "BirthYear": 1987,
            "BirthMonth": 10,
            "BirthDayOfMonth": 26,
            "Age": 30,
            "PersonalNumber": "198710260070",
            "_DataSource": "DP05"
      }
}