Skip to main content

WebID

WebID is a German eIDV (electronic identity document verification) service for secure online onboarding of end-users. It is compliant with AML regulations such as German AML Law GwG and has been approved by the Federal Financial Supervisory Authority BaFin.

WebID is integrated as a third-party provider in the Signicat Assure API.

Need more help?

If you have any questions about the integration, you can contact us by creating a support ticket in the Signicat Dashboard.

Supported features

Signicat supports the following two main features from WebID in a single point of integration via Assure API:

  • VideoID: The end-user is identified by a support agent in a live video call.
  • AccountID: The end-user identifies themselves by capturing their ID and selfie.

Possible outcomes of the transactions from these services are successful (accepted), rejected or mismatch (inconclusive). For more details about possible response statuses, see Service details for WebID.

Fallback

In some special cases, WebID allows an AccountID process to fallback to VideoID. See more details in Fallback to VideoID.

VideoID

The WebID VideoID service provides call-centre functionality, where trained support agents can verify the validity of the provided identity papers (e.g. a passport) and ask security questions to the end-user during a live video call. The verification process is recorded and evidence is made available for the service provider.

This service consists of three main steps:

VideoID

VideoID

The VideoID service is available in Germany from 7 am to 22 pm. The support agents speak German and English. The end-user might have to wait, but the SLA should be less than 90 seconds. The call itself takes 5 minutes in average.

User flow example

The following verification example shows a typical VideoID user flow.

The example assumes you already have done the initial integration steps with the Assure API, see Set up an API integration. It also assumes you have set up the dossier, process and configured the provider.

The screen images are from WebID's web environment in test mode.

AccountID

With the AccountID service, your end-users can log into their online bank account. They identify themselves by capturing their identity paper and a selfie. Once the image data is analysed and approved, they can log into their bank by using their normal bank login, after which the required micropayment is executed. To finish the procedure, they receive a transaction code on their mobile, which they need to enter on the WebID website.

AccountID

AccountID

This service is currently available 24/7 for banks in Germany and Austria. It has no waiting time and the average transaction time is 3 minutes.

User flow example

The following verification example shows a typical AccountID user flow.

The example assumes you already have done the initial integration steps with the Assure API, i.e. set up client credentials and access token. It also assumes you have set up the dossier, process and configured the provider.

The screen images are from WebID's web environment in test mode.

Integration use case for WebID

Prerequisites

The guide assumes you already have done the initial integration steps with the Assure API, see Set up an API integration.

Here is an overview of the mandatory steps described in the below sections:

  1. Create a dossier
  2. Create a process
  3. Get the result

Create a dossier

Use the Create dossier endpoint to create a placeholder for all of your end-user's data:

curl -X POST \
<ENVIRONMENT>/assure/dossiers \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \

Save the dossierId from the response body to use in the next requests.

Note:

Ensure you use one dossier per end-user.

Get dossier

After creating a dossier, you can see all of its contents anytime you want to. To do that, use the Get dossier endpoint giving it the dossierId.

Create a process

Use the Create process endpoint to create an identity verification process inside the dossier.

Ensure you:

  • Use the dossierId from the "Create dossier" response.
  • Set the provider to webid.
curl -X POST \
<ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes \
-H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"provider": "webid",
"authorizationHeader": "Token xSUNmskaIUGh9hn5B7bKJbNOho"
}'

Enter the required processType, either videoid or accountid. See the Supported features section about the differences between these two process types.

VideoID

Here is an example JSON request body for VideoID with the minimum required fields:

{
"provider": "webid",
"processType":"videoid",
"processParameters": {
"webid":{
"user": {
"firstName":"Erica",
"lastName":"Mustermann",
"dateOfBirth":"1990-02-17",
"contact": {
"email":"email@example.com"
}
},
"userActionParameters":{
"productType":"loan",
"clientName":"ACME Bank",
"redirectUrl":"https://example.org/example/redirect",
"redirectCancelUrl":"https://example.org/example/cancel",
"redirectMismatchUrl":"https://example.org/example/mismatch",
"redirectDeclineUrl":"https://example.org/example/decline"
}
}
}
}

AccountID

Here is an example JSON request body for AccountID with the minimum required fields:

{
"provider": "webid",
"processType":"accountid",
"processParameters": {
"webid":{
"user": {
"firstName":"Erica",
"lastName":"Mustermann",
"dateOfBirth":"1990-02-17",
"contact": {
"email":"email@example.com",
"mobile":"+351911111111"
}
},
"idDocument": {
"nationality":"DEU"
},
"userActionParameters":{
"productType":"loan",
"clientName":"ACME Bank",
"redirectUrl":"https://example.org/example/redirect",
"redirectCancelUrl":"https://example.org/example/cancel",
"redirectMismatchUrl":"https://example.org/example/mismatch",
"redirectDeclineUrl":"https://example.org/example/decline"
}
}
}
}

It is recommended to subscribe to Assure events to be notified when the result is available.

Preferred Language

Optionally, you can also add the preferredLanguage parameter in the 'Create process' request to choose your preferred language in the user interface. For a full list of supported language values, see the description of the ProcessParameters > webid object in the API Reference.

Create process response

In the 'Create process' response, you will receive a redirect URL, for example:

"redirectUrl": "https://test.webid-solutions.de/service/index/cn/000603/aid/178266506"

  • Use this URL to redirect your end-user to the My WebID app or the WebID browser version, where they can perform their identification. It is recommended to redirect the user to the WebID app instead of browser, since the app will give better results. For more details, see the Test WebID section.

User experience tips to improve the onboarding

Consider to include the following tips before the end-user starts the verification:

  • The end-user needs a stable and good internet connection.
  • The end-user needs good lighting to capture the identity document.
  • The end-user should have the identity document ready when the transaction starts.
  • If the end-user is going to do a VideoID process, inform them upfront that there will be a live video interview with a support agent.

Callbacks (events)

After the user has performed the verification, WebID will analyse the images/videos, and send a callback to Assure API with the result. It is recommended to subscribe to Assure events to be notified when the result is available.

Pending process?
  • The time it takes to receive a notification is fairly quick for VideoID, but can take up to 6 days for AccountID. However, you can simulate callbacks with an immediate response in test mode. See Test WebID for more details.
  • If you have subscribed to Assure events, the notification will be sent to you once we receive it from WebID. In the meantime, the status will be pending.
  • In some cases, the end-user may never finish the verification, meaning the process will always be pending.

Get the result

After you have received the notification from Assure API, you can call the Get process endpoint to see the detailed result information.

VideoID

Here is an example response for VideoID:

{
"processId": "2510b01d-bf91-45e4-aadd-c930cb1c1b09",
"provider": "webid",
"processType": "videoid",
"status": "accepted",
"finalResult": {
"firstName": "Erica",
"lastName": "Mustermann",
"dateOfExpiry": "2027-08-23",
"dateOfBirth": "1990-02-17",
"gender": "F",
"nationality": "DE",
"documentType": "identityCard",
"documentNumber": "PA9921465"
},
"providerSpecific": {
"identResponse": {
"actionId": "165001703",
"transactionId": "2510b01d-bf91-45e4-aadd-c930cb1c1b09",
"actionType": "pass",
"success": true,
"mismatch": false,
"responseType": "ident",
"finishedOn": "2023-06-22T12:31:12+02:00",
"identMode": "video_ident",
"identifiedOn": "2023-06-22T12:31:12+02:00",
"idDocument": {
"authority": "Gemeinde Bad Lauchstädt",
"dateOfExpiry": "2027-08-23",
"dateOfIssue": "2017-08-24",
"documentType": "Personalausweis",
"idNumber": "PA9921465",
"mrz": "PA9921465",
"nameAtBirth": "Mustermann",
"nationality": "DE",
"placeOfBirth": "Hamburg"
},
"user": {
"title": "",
"firstname": "Erica",
"lastname": "Mustermann",
"dateOfBirth": "1990-02-17",
"address": {
"street": "",
"addressLine1": "",
"addressLine2": "",
"region": "",
"zip": "",
"city": "",
"country": "DE"
},
"contact": {
"email": "email@example.com",
"mobile": "+351911111111"
},
"gender": "F"
}
}
},
"createdAt": "2023-06-22T10:31:03Z",
"updatedAt": "2023-06-22T10:31:12Z"
}

AccountID

Here is an example response for AccountID:

{
"processId": "1a07334f-4191-40cf-b7d1-a38372df0aa2",
"provider": "webid",
"processType": "accountid",
"status": "accepted",
"finalResult": {
"firstName": "Erica",
"lastName": "Mustermann",
"dateOfExpiry": "2023-06-23",
"dateOfBirth": "1990-02-17",
"gender": "F",
"nationality": "DE",
"documentType": "identityCard",
"documentNumber": "abcdef"
},
"providerSpecific": {
"identResponse": {
"actionId": "127046906",
"transactionId": "1a07334f-4191-40cf-b7d1-a38372df0aa2",
"actionType": "pass",
"success": true,
"mismatch": false,
"responseType": "ident",
"finishedOn": "2023-06-22T12:28:42+02:00",
"identMode": "pay_ident",
"identifiedOn": "2023-06-22T12:28:42+02:00",
"idDocument": {
"authority": "",
"dateOfExpiry": "2027-08-23",
"dateOfIssue": "2017-08-24",
"documentType": "Personalausweis",
"idNumber": "abcdef",
"mrz": "abc123",
"nameAtBirth": "",
"nationality": "DE",
"placeOfBirth": "Hamburg"
},
"user": {
"title": "",
"firstname": "Erica",
"lastname": "Mustermann",
"dateOfBirth": "1990-02-17",
"address": {
"street": "",
"addressLine1": "",
"addressLine2": "",
"region": "",
"zip": "",
"city": "",
"country": ""
},
"contact": {
"email": "email@example.com",
"mobile": "+351911111111"
},
"gender": "F"
},
"productInfos": {
"bankAccount": {
"iban": "DE62888888880012345678"
}
}
},
"payMoneyTransferResponse": {
"actionId": "127046906",
"transactionId": "1a07334f-4191-40cf-b7d1-a38372df0aa2",
"actionType": "pass",
"success": true,
"responseType": "pay_money_transfer",
"finishedOn": "2023-06-22T12:29:16+02:00"
}
},
"createdAt": "2023-06-22T09:50:46Z",
"updatedAt": "2023-06-22T10:29:20Z"
}

Fallback to VideoID

In some special cases, WebID allows an AccountID process to fallback to VideoID. For example, if WebID detects a mismatch between the end-user information and the ID document, it will ask the end-user if they want to continue the verification with a support agent (VideoID).

In these cases, there will be some changes in the 'Get Process' response: The processType will still be accountid, but identMode will be video_ident instead of pay_ident, and there will be no payMoneyTransferResponse.

Different cost

Be aware that a fallback to VideoID might impact the costs. VideoID is normally more expensive than AccountID.

Test WebID

WebID allows running tests in sandbox (test) mode.

Live support call?

If you want to test VideoID in a live call with a support agent, you should book this at least 48 hours prior to the call. This might have a cost. Please, contact your Signicat account manager or Signicat Support if you want to run tests with a real agent.

Order test zip file

To be able to use the Download full result service when testing WebID in sandbox, you must ask WebID to send the test zip file by posting an email to it-service@webid-solutions.de with the following information:

  • Subject: "Release test zip file"
  • Body: "We are testing the WebID service via the Signicat Assure API. Can you please release the zip file for actionId <ACTIONID>?"

In production mode, you do not need to do this.

Test using My WebID app

  1. Download and open the My WebID app. This app is available for iOS and Android.
  2. Enter #1* in front of the transaction ID. You can find this 9-digit number in the redirectUrl of the Create process response. For example, with "redirectUrl": https://test.webid-solutions.de/service/qa/cn/000603/aid/124389903", you should enter #1*124389903.
WebID app

WebID app

Test using the browser

  • Open the redirect URL you received in the Create process response.

    Here is a test mode example for AccountID in a browser:

    WebID app

    WebID app

  • For VideoID, you can use these test transaction number (TAN) codes to simulate user/agent interaction:

    • 123456 for success
    • 654321 for failure

Simulate payment results in AccountID

When testing AccountID, you can simulate different micropayment results. To do that, you must pass redirectTime in userActionParameters in the request. Example:

{
"provider": "webid",
"processType":"accountid",
"processParameters": {
"webid":{
"user": {
"firstName":"Erica",
"lastName":"Mustermann",
"dateOfBirth":"1990-02-17",
"contact": {
"email":"email@example.com",
"mobile":"+351911111111"
}
},
"userActionParameters":{
"redirectCancelUrl":"https://myredirecturl/cancel",
"redirectMismatchUrl":"https://myredirecturl/mismatch",
"redirectDeclineUrl":"https://myredirecturl/decline",
"redirectUrl":"https://myredirecturl/redirect",
"productType":"loan",
"clientName":"Bank of the Internet",
"redirectTime":5
},
"idDocument": {
"nationality":"DEU"
}
}
}
}

SDKs

You can use the My WebID mobile app or the WebID web site via Assure API. For more details, see the WebID integration use case section.

If you want to use WebID in your own native mobile app, you need to contact us by creating a support ticket in the Signicat Dashboard.

Service details for WebID

This section goes more into detail about some useful endpoints when integrating with WebID:

Get process

Possible statuses from WebID

The status only changes when Assure gets an identResponse or a payMoneyTransferResponse from WebID. This means that, if WebID never sends information (e.g. the user never finishes the process), the status will stay pending.

AccountID specifics

For AccountID, you should expect to have two elements in the providerSpecific area, one identResponse and one payMoneyTransferResponse.

The table below details how the possible statuses are mapped for WebID processes. For the VideoID processType the final status depends only on the result of identResponse, while for the AccountID processType it depends on the result of both identResponse and payMoneyTransferResponse.

StatusidentResponse 'success'identResponse 'mismatch'payMoneyTransferResponse 'success'Details
Pending(none)(none)(none)Nothing was received yet or the end-user did not complete the process.
Processingtrue(none)(none)processing only applies for AccountID. VideoID will have a final status (accepted, rejected, inconclusive) as soon as identResponse is received.
Acceptedtruefalsetrue
InconclusivetruetrueN/Ainconclusive only applies for VideoID. AccountID will fallback to VideoID if mismatch is true.
Rejectedtruefalsefalse

Response examples

AccountID accepted
{
"processId": "1a07334f-4191-40cf-b7d1-a38372df0aa2",
"provider": "webid",
"processType": "accountid",
"status": "accepted",
"finalResult": {
"firstName": "Erica",
"lastName": "Mustermann",
"dateOfExpiry": "2027-08-23",
"dateOfBirth": "1990-02-17",
"gender": "F",
"nationality": "DE",
"documentType": "identityCard",
"documentNumber": "abcdef"
},
"providerSpecific": {
"identResponse": {
"actionId": "127046906",
"transactionId": "1a07334f-4191-40cf-b7d1-a38372df0aa2",
"actionType": "pass",
"success": true,
"mismatch": false,
"responseType": "ident",
"finishedOn": "2023-06-22T12:28:42+02:00",
"identMode": "pay_ident",
"identifiedOn": "2023-06-22T12:28:42+02:00",
"idDocument": {
"authority": "",
"dateOfExpiry": "2027-08-23",
"dateOfIssue": "2017-08-24",
"documentType": "Personalausweis",
"idNumber": "abcdef",
"mrz": "abc123",
"nameAtBirth": "",
"nationality": "DE",
"placeOfBirth": "Hamburg"
},
"user": {
"title": "",
"firstName": "Erica",
"lastName": "Mustermann",
"dateOfBirth": "1990-02-17",
"address": {
"street": "",
"addressLine1": "",
"addressLine2": "",
"region": "",
"zip": "",
"city": "",
"country": ""
},
"contact": {
"email": "email@example.com",
"mobile": "+351911111111"
},
"gender": "F"
},
"productInfos": {
"bankAccount": {
"iban": "DE62888888880012345678"
}
}
},
"payMoneyTransferResponse": {
"actionId": "127046906",
"transactionId": "1a07334f-4191-40cf-b7d1-a38372df0aa2",
"actionType": "pass",
"success": true,
"responseType": "pay_money_transfer",
"finishedOn": "2023-06-22T12:29:16+02:00"
}
},
"createdAt": "2023-06-22T09:50:46Z",
"updatedAt": "2023-06-22T10:29:20Z"
}
VideoID accepted
{
"processId": "2510b01d-bf91-45e4-aadd-c930cb1c1b09",
"provider": "webid",
"processType": "videoid",
"status": "accepted",
"finalResult": {
"firstName": "Erica",
"lastName": "Mustermann",
"dateOfExpiry": "2027-08-23",
"dateOfBirth": "1990-02-17",
"gender": "F",
"nationality": "DE",
"documentType": "identityCard",
"documentNumber": "PA9921465"
},
"providerSpecific": {
"identResponse": {
"actionId": "165001703",
"transactionId": "2510b01d-bf91-45e4-aadd-c930cb1c1b09",
"actionType": "pass",
"success": true,
"mismatch": false,
"responseType": "ident",
"finishedOn": "2023-06-22T12:31:12+02:00",
"identMode": "video_ident",
"identifiedOn": "2023-06-22T12:31:12+02:00",
"idDocument": {
"authority": "Gemeinde Bad Lauchstädt",
"dateOfExpiry": "2027-08-23",
"dateOfIssue": "2017-08-24",
"documentType": "Personalausweis",
"idNumber": "PA9921465",
"mrz": "PA9921465",
"nameAtBirth": "Mustermann",
"nationality": "DE",
"placeOfBirth": "Hamburg"
},
"user": {
"title": "",
"firstName": "Erica",
"lastName": "Mustermann",
"dateOfBirth": "1990-02-17",
"address": {
"street": "",
"addressLine1": "",
"addressLine2": "",
"region": "",
"zip": "",
"city": "",
"country": "DE"
},
"contact": {
"email": "email@example.com",
"mobile": "+351911111111"
},
"gender": "F"
}
}
},
"createdAt": "2023-06-22T10:31:03Z",
"updatedAt": "2023-06-22T10:31:12Z"
}
AccountID inconclusive

This status is not possible. AccountID falls back to VideoID if there is a mismatch.

VideoID inconclusive
{
"agentId":158,
"finishedOn":"2022-06-20T09:24:48+02:00",
"identifiedOn":"2022-06-20T09:24:48+02:00",
"idDocument":{
"authority":"Oberbürgermeister Stadt Frankfurt",
"dateOfExpiry":"2027-08-23",
"dateOfIssue":"2017-08-24",
"documentType":"Personalausweis",
"idNumber":"12121212",
"mrz":"",
"nameAtBirth":"",
"nationality":"DE",
"placeOfBirth":"Hamburg"
},
"jointUserActionStatus":null,
"rejectionReason":null,
"success":true,
"user":{
"address":{
"addressLine1":null,
"addressLine2":null,
"region":"",
"city":"Hamburg",
"country":"DE",
"street":"Teststrasse",
"streetNo":"12",
"zip":"24111"
},
"contact":{
"phone":"",
"cell":"+4915142221664",
"email":"stephan.nolte@webid-solutions.de"
},
"customFields":null,
"dateOfBirth":"1990-02-17",
"firstname":"Erica",
"lastname":"Mustermann",
"sex":"female",
"title":""
},
"mismatch":true,
"qesContinue":null,
"identMode":"video_ident",
"productInfos":null,
"actionId":"105155601",
"actionType":"pass",
"customParameters":{
"some":"value",
"another":"value"
},
"responseType":"ident",
"transactionId":"SN-Test-055"
}
AccountID rejected
{
"processId": "901750ac-c926-465e-a1e9-1c79f3ef73a5",
"provider": "webid",
"processType": "accountid",
"status": "rejected",
"providerSpecific": {
"identResponse": {
"actionId": "163819905",
"transactionId": "901750ac-c926-465e-a1e9-1c79f3ef73a5",
"actionType": "pass",
"success": true,
"mismatch": false,
"responseType": "ident",
"finishedOn": "2023-06-22T11:12:09+02:00",
"identMode": "pay_ident",
"identifiedOn": "2023-06-22T11:12:09+02:00",
"idDocument": {
"authority": "",
"dateOfExpiry": "2027-08-23",
"dateOfIssue": "2017-08-24",
"documentType": "Personalausweis",
"idNumber": "abcdef",
"mrz": "abc123",
"nameAtBirth": "",
"nationality": "DE",
"placeOfBirth": "Hamburg"
},
"user": {
"title": "",
"firstname": "Erica",
"lastname": "Mustermann",
"dateOfBirth": "1990-02-17",
"address": {
"street": "",
"addressLine1": "",
"addressLine2": "",
"region": "",
"zip": "",
"city": "",
"country": ""
},
"contact": {
"email": "email@example.com",
"mobile": "+351911111111"
},
"gender": "F"
},
"productInfos": {
"bankAccount": {
"iban": "DE62888888880012345678"
}
}
},
"payMoneyTransferResponse": {
"actionId": "163819905",
"transactionId": "901750ac-c926-465e-a1e9-1c79f3ef73a5",
"actionType": "pass",
"success": false,
"responseType": "pay_money_transfer",
"finishedOn": "2023-06-22T11:13:04+02:00"
}
},
"createdAt": "2023-06-22T09:11:34Z",
"updatedAt": "2023-06-22T09:13:08Z"
}
VideoID rejected
{
"processId": "e6e0caaa-cb77-4e38-a89d-811b591e17d0",
"provider": "webid",
"processType": "videoid",
"status": "rejected",
"providerSpecific": {
"identResponse": {
"actionId": "170063501",
"transactionId": "e6e0caaa-cb77-4e38-a89d-811b591e17d0",
"actionType": "pass",
"success": false,
"mismatch": false,
"responseType": "ident",
"finishedOn": "2023-06-22T11:06:43+02:00",
"identMode": "video_ident",
"idDocument": {
"authority": "Bürgermeisteramt Lübeck",
"dateOfExpiry": "2027-08-23",
"dateOfIssue": "2017-08-24",
"documentType": "Personalausweis",
"idNumber": "L01X00T47",
"mrz": "L01X00T47",
"nameAtBirth": "",
"nationality": "DE",
"placeOfBirth": "Hamburg"
},
"rejectionReason": "general_rejection",
"user": {
"title": "",
"firstName": "Erica",
"lastName": "Mustermann",
"dateOfBirth": "1990-02-17",
"address": {
"street": "",
"addressLine1": "",
"addressLine2": "",
"region": "",
"zip": "",
"city": "",
"country": "DE"
},
"contact": {
"email": "email@example.com",
"mobile": "+351911111111"
},
"gender": "F"
}
}
},
"createdAt": "2023-06-22T09:06:25Z",
"updatedAt": "2023-06-22T09:06:44Z"
}

Download full result

In the Get process response, you get the results for WebID in the provider-specific area. In addition, you can retrieve the full information as they were obtained from the provider. The full information is available in a .zip file obtained from the Download full result service.

Important notes
  • The contents of the .zip file is prepared by WebID, and not Signicat.
  • It might take WebID some time to prepare the file. If it is not ready, you will get a 404 response. You must poll until you get a 200 response. Delay times can be up to one day.
  • In test mode, you need to order the test zip file from WebID. For more details, see Test WebID.

The name of the .zip file is based on field values in the process, consisting of "dossierId_processId_downloadDate.zip", for example 7b5d7b68-3e4d-44c1-b7bd-663215410fbd_dcddb32b-fe44-4268-8f1a-bab7ace241e6_20231018T095323.zip.

AccountID

You can always get a .zip file for AccountID processes, even if the transaction fails and the process is rejected. The transaction callback might take up to a week.

Here is a screen example of a .zip file from an AccountID process:

AccountID .zip file

AccountID .zip file

The main content is as follows:

  • The signed document
  • Pictures of the ID documents
  • Portrait of the end-user
  • User data report with information about the end-user's personal data, including images of the ID document

VideoID

For VideoID, you can only retrieve a .zip file for accepted processes.

Here is a screen image of an example .zip file from a VideoID process:

VideoID .zip file

VideoID .zip file

The main content is as follows:

  • Video recording of the identity verification
  • Audio recording of the identity verification
  • Pictures of the ID document
  • Portrait of the end-user
  • User data report with information about the end-user's personal data, including images of the ID document