iDIN Age via iDIN AgeChecked in the Netherlands is an age verification service by a standard bank login process. The process uses the bank for user age verification purpose only.

API Calls

Set up: POST to https://env.zignsec.com/v2/eid/idin_age

Result: GET from https://env.zignsec.com/v2/eid/sessionid
where 
env is API or test 
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/idin_age
where
env is API or test 

Request Parameters

Setting Request Header

JSON example:

ParameterDescriptionRequired
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
targetIf this parameter is supplied the browser session will finally be redirected to this URL-value. The URL-parameter value 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
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

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.
redirect_urlThe URL that the user needs to be redirected to, 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

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.

Step 3. Get status/results

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

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.
errorsA JSON array of error conditions, see error handling.
result

Note: This node is missing (deemed unnecessary) if the authentication is successful – i.e., 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 final 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.

identityThis identity node contains one special Boolean field AgeApproved which is set to true when the identified person has the required age.
IdinAgeChecked

The IdinAgeChecked node contains the following items:

AgeCheckIdRepresents the ID provider’s session identification, presented for tracing purposes..
Status

Status of age verification.

Number Status text Description

3 Aborted
Transaction cancelled by customer

4 Error
Error encountered during transaction.

5 Declined
Transaction declined due to a general restriction not defined 
below.

6 & 7 Approved
Transaction approved.

8 DeclinedIPCountryNotDetected
Transaction declined due to server unable to detect the country from the customer IP address.

9 DeclinedIPCountryDisabled
Transaction declined due to the country blocked for this site operator account.

10 DeclinedIPProxy
Transaction declined due to the IP address being determined as an anonymous proxy.

12 AVNotRequired
Check not required for this country.

17 NotApproved
Not age approved

StatusTextMeaning of status

Example response

{
  "id": "ef17fe5a-a310-4b26-809a-93d0eef4ef57",
  "errors": [],
  "identity": {
    "CountryCode": "NL",
    "IdProviderName": "iDin",
    "IdentificationDate": "2020-02-26T14:59:21.6055264Z",
    "IdProviderRequestId": 1255120,
    "AgeApproved": true
  },
  "IdinAgeChecked": {
    "AgeCheckId": 1255120,
    "Status": 6,
    "StatusText": "Approved"
  },
  "result": {
    "identity": {
      "state": "FINISHED"
    }
  }
}