BankingAPI is a user-friendly authentication service for markets where no electronic identity providers are widely available. The process uses the bank for user identity verification purpose only.

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
bli_CC is bli_se, bli_dk 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/bli_CC where env is api or test bli_CC is bli_se, bli_dk, 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.
CountryMethodAvailable banksTest bank
Brazilbli_brLogin via these banksSantander
Czech Republicbli_czLogin via these banksČSOB
Denmarkbli_dkLogin via these banksJyske Bank
Estoniabli_eeLogin via these banksCitadele
Finlandbli_fiLogin via these banksAktia
Latviabli_lvLogin via these banksCitadele
Lithuaniabli_ltLogin via these banksCitadele
Polandbli_plLogin via these banksZahodny
Spainbli_esLogin via these banks.CaixaBank
Swedenbli_seLogin via these banks Swedbank
 [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-5352305c9fb0Required
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-urlencodedRequired
HostUse test.zignsec.com for test enviroment and api.zignsec.com for production enviroment. Example: api.zignsec.comRequired

Request Parameters

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 the 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 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 sent to this URL by POST method.No
webhook_emailEmail address. The result will be sent 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.

Error codes

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

API Endpoint

GET from https://env.zignsec.com/v2/eid/sessionid
where
env is api or test
sessionid is retrieved in the setup call, named id in the step 1 reponse.

How To Get Notified of Workflow Finished

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

idA unique session identifier generated for each workflow instance.
errors

A JSON array of error conditions, see error handling.

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

BankingAPIA 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

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 informations.
NumberIbanHolderName
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

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

Response 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"
      }
}