# WebID
Page contents
WebID (opens new window) 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 (opens new window) and has been approved by the Federal Financial Supervisory Authority BaFin (opens new window).
WebID is integrated as a third-party provider in the Signicat Assure API.
Need more help?
The WebID documentation is under construction. More technical details will follow later. If you have any questions, please contact us at support@signicat.com.
# 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:
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.
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:
# Create a dossier
- Use the Create dossier (opens new window) endpoint to create a placeholder for all of your end-user’s data.
- Save the
dossierIdyou get in the response to be used in the next requests.
Note:
Ensure you use one dossier per end-user.
# Create a process
Use the Create process (opens new window) endpoint to create an identity verification process in that dossier.
- Ensure you give it the
dossierIdyou got in the 'Create dossier' response. - Enter the
webidprovider in the request body. - Enter the required
processType, eithervideoidoraccountid. 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":"erica.mustermann@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":"1956-03-24",
"contact": {
"email":"erica.mustermann@email.com",
"mobile":"(0)30-23125 000"
}
},
"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 (opens new window).
# 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 (opens new window) 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": "ericamustermann@example.com",
"mobile": "(0)30-23125 000"
},
"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": "ericamustermann@mail.com",
"mobile": "(0)30-23125 000"
},
"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.
# Test using My WebID app
- Download and open the My WebID app. This app is available for iOS (opens new window) and Android (opens new window).
- Enter
#1*in front of the transaction ID. You can find this 9-digit number in theredirectUrlof the Create process response. For example, with"redirectUrl": https://test.webid-solutions.de/service/qa/cn/000603/aid/124389903", you should enter#1*124389903.
# 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:
For VideoID, you can use these test transaction number (TAN) codes to simulate user/agent interaction:
- 123456 for success
- 654321 for failure
# 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, please contact us at support@signicat.com.
# 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.
| 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 | false | |||
| 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": "ericamustermann@example.com",
"mobile": "(0)30-23125 000"
},
"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": "ericamustermann@mail.com",
"mobile": "(0)30-23125 000"
},
"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": "ericamustermann@example.com",
"mobile": "(0)30-23125 000"
},
"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": "ericamustermann@example.com",
"mobile": "(0)30-23125 000"
},
"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.
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:
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:
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