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.
The WebID documentation is under construction. More technical details will follow later. If you have any questions, 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.
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
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
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
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:
Create a dossier
- Use the Create dossier endpoint to create a placeholder for all of your end-user's data.
- Save the
dossierId
you get in the response to be used in the next requests.
Ensure you use one dossier per end-user.
Create a process
-
Use the Create process endpoint to create an identity verification process in that dossier.
- Ensure you give it the
dossierId
you got in the 'Create dossier' response. - Enter the
webid
provider in the request body. - Enter the required
processType
, eithervideoid
oraccountid
. See the Supported features section about the differences between these two process types.
- Ensure you give it the
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.
- 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
.
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.
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.
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
- Download and open the My WebID app. This app is available for iOS and Android.
- Enter
#1*
in front of the transaction ID. You can find this 9-digit number in theredirectUrl
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
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
-
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
.
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
.
Status | identResponse 'success' | identResponse 'mismatch' | payMoneyTransferResponse 'success' | Details |
---|---|---|---|---|
Pending | (none) | (none) | (none) | Nothing was received yet or the end-user did not complete the process. |
Processing | true | (none) | (none) | processing only applies for AccountID. VideoID will have a final status (accepted, rejected, inconclusive) as soon as identResponse is received. |
Accepted | true | false | true | |
Inconclusive | true | true | N/A | inconclusive only applies for VideoID. AccountID will fallback to VideoID if mismatch is true . |
Rejected | true | false | false |
Response examples
- accepted:
- inconclusive:
- VideoID
- AcccountID (not possible)
- rejected:
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.
- 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
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
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