Skip to Content

Business Scenario

In the traditional way of financial services, customer has to go to agents for identification relevant activities. For example, open bank accounts, sign official paper. But in the digital world, customer requires more convenient and sophisticated solution to deal with such problem. Online identification and digital signing provides great benefits for user experiences and cost saving.

Solution

As the best-in-class solution of digital identification, IDnow is a good candidate to fulfill business scenario of identification and online signing. The IDnow has different products and various services to support online identification and signing. Here I am going to utilize “IDnow Vidio-Ident” to identify user online and create authentic business partner in SAP system.

Getting more information of IDnow here: https://www.idnow.eu/

Architecture

The architecture is simple, SAP and IDnow are integrated via RESTful API. A Fiori application is provided to ask user to fill in all necessary information for user account creation. IDnow agent will be involved to identify user online or offline to make sure customer’s information is authentic and valid. Verification result then will be sent back to SAP to create user account.


Prerequisites

In order to integrate with IDnow, you have to contact with IDnow (https://www.idnow.eu/company/contact/b2b/) to register your company ID and get test API key for calling IDnow APIs.

Here you can get the latest version of IDnow API document: https://www.idnow.de/wp-content/uploads/2017/11/IDnow_API_2017-11-13.pdf

Because we are using RESTful API to do communication between SAP and IDnow, you have to make sure the gateway service is available in SAP system in case of integrating to SAP on-Premise system.

Technical Detail

IDnow uses different subdomains for certain purpose:

Term Definition

go.idnow.de

(go.test.idnow.de)

Interface/Website the user sees, when identifying for a product of a company

gateway.idnow.de

(gateway.test.idnow.de)

Interface for companies to send client data to IDnow (before identification) or to retrieve data from IDnow (after identification)
api.idnow.de Interface for companies to test their implementation

The gateway service is mainly used by us to communicate with IDnow. In the testing environment, the domain “gateway.test.idnow.de” is recommended to use, otherwise you might get charged by some real-world activities.

To ensure all parameters are encrypted, all requests to the IDnow server are always performed using HTTPS rather than HTTP.

Starting Identification

Following IDnow service is used to start identification process and return with a unique transaction number:

/api/<version>/<companyid>/identifications/<transactionNo>/start

You have to provide following attributes to complete the request URL:

  • Version: v1
  • Company ID: the company ID you registered in IDnow
  • Transaction No: any number contains following characters: a-zA-Z0-9_-

For example, the URL https://gateway.test.idnow.de/api/v1/<conpanyid>/identifications/<transactionNo>/start is used in this example.

There are two mandatory header parameters required in this API calling:

Field Content
X-API-KEY <API Key>
Content-Type application/json

Following screenshot shows request URL and header parameters in postman:


There are abundant parameters in the API body definition, in order to capture as much information of user identification as possible. Refer to the API document for detail of those body parameters.

In our example, we pass following data to IDnow:


Test IDnow service in the postman by pressing button “Send”. IDnow will return a unique internal ID back:


Following code snippet shows how to start identification in application:

		onSubmitForm: function(oEvent){
			var sUrl = "https://gateway.test.idnow.de/api/v1/xxxx/identifications/" + this.oUserData.contractID + "/start";
			var oUserData = sap.ui.getCore().getModel("data").getData();
			var sBirthday = "";
			if (oUserData.birthday){
				sBirthday = oUserData.birthday.toISOString().split("T")[0];
			}
			var oData = {
				"birthday": sBirthday,
				"birthplace": oUserData.birthPlace,
				"birthname": oUserData.birthName,
				"city": oUserData.city,
				"country": oUserData.country,
				"custom1": oUserData.contractID,
				"custom2": "X-AUTOTEST-HAPPYPATH",			// for test only. identification will be successful
				"custom3": null,
				"custom4": null,
				"custom5": null,
				"trackingid": null,
				"email": oUserData.email,
				"firstname": oUserData.firstName,
				"gender": oUserData.gender,
				"lastname": oUserData.lastName,
				"mobilephone": oUserData.mobile,
				"nationality": oUserData.nationality,
				"preferredLang": "en",
				"street": oUserData.street,
				"streetnumber": oUserData.houseNumber,
				"title": "",//oUserData.title,
				"zipcode": oUserData.zipcode,
				"questions": null
			};
			if(oUserData.title === "0001"){
				oData.title = "MR";
			}else if(oUserData.title === "0002"){
				oData.title = "MS";
			}
			var that = this;
			// call IDnow service to get identification id
			$.ajax({
				url: sUrl,
				type: "POST",
				async: false,
				headers: {
					"X-API-KEY": this.API_KEY,
					"Content-Type": "application/json"
				},
				data: JSON.stringify(oData)
			}).done(function(data){
				$.sap.log.info("Identification is created");
				var oModel = that.getView().getModel("rst");
				// set the identification ID
				oModel.setProperty("/identificationID", data);
				// prepare the output of identification
				var sHtml = "<h1>" + data.id + "</h1>";
				oModel.setProperty("/HTML", sHtml);

				// navigate to the identification page
				that.getRouter().navTo("identification", {
					ID: data.id
				});
			}).fail(function(xhr, textStatus, errorThrown){
				$.sap.log.error("Error during the identification creation");
			});
		}

Performing an Identification

After receiving internal ID from previous step, it is possible to redirect the user to IDnow’s identification process: redirect to identification process. The identification process can also be embedded as an iframe or opened as a popup dialog box.

The subdomain “go.test.idnow.de” is used for identification process. The link of identification process can be combined in following pattern:

https://go.test.idnow.de/<companyid>/identifications/<transactionNo>

After the identification is started, we can go to above link to check identification process:


Using following URL to start identification process:

https://go.test.idnow.de/<companyid>/identifications/<transactionNo>/start

A popup dialog box will be opened and ideally an agent will chat with you online.


Because we are using testing subdomain for testing, so no agent will be available to interview online.

Following code snippet implements starting identification process as a popup window:

		onStartIdentification: function(oEvent) {
			// build up the iframe in the panel
			var oUserModel = sap.ui.getCore().getModel("data");
			var oUserData = oUserModel.getData();

			/**
			 * embedding iframe of identification doesn't work now
			 * am waiting for the technical support from IDnow
			 * this will be uncommented after it is solved
			 */
			// build up the url of identification process
			var sUrl = "https://go.test.idnow.de/xxxx/identifications/" + oUserData.contractID + "/identification/start";
			window.open(sUrl, "_blank", "width=600,height=800,left=50,top=50,location=no,menubar=no,resizable=yes,scrollbars=yes,status=no,titlebar=no,toolbar=no");
		},

Simulate Identification Process

In order to get through the identification process in testing environment, we can utilize testing scenarios which are provided by IDnow. There are 3 different testing methods available to process an identification:

Testing Method User Agent
Automated Company test implementation IDnow Test-robot
Manual Human IDnow Test-robot
With Agent Human Human

Here we pick up “Manual” testing method to go through identification process with IDnow. According to the API document, the testing scenario can be controlled by certain naming convention: “<Prefix>-<test_scenario>”.

Prefix Description
X-MANUALTEST Performs a test where you can use the web or app, but the agent is automated
X-AUTOTEST Both the user and the agent are automated. No user interaction required

 

For the test scenario, we pick up “HAPPYPATH” which ident is finished successfully and no changes are made. The testing scenario can be passed when starting identification:


Then we can simulate the identification process by passing following URL request:

https://api.test.idnow.de/api/v1/<companyid>/identifications/<transactionNo>/start

Using postman to start identification in simulation mode:


And leave the body empty: {}. Then sending request to IDnow:


In the request result, the status is changed to “STARTED” which means identification is started.

See following code snippet for start simulation:

		testStartIdentification: function(oEvent) {
			// get generated identification ID
			var oUserData = sap.ui.getCore().getModel("data").getData();
			var sId = oUserData.contractID;
			var that = this;
			// Start the identification for created identification
			$.ajax({
				type: "POST",
				url: "https://api.test.idnow.de/api/v1/xxxx/identifications/" + sId + "/start",
				headers: {
					"X-API-KEY": this.API_KEY,
					"Content-Type": "application/json"
				},
				data: "{}"
			}).done(function(data) {
				$.sap.log.info("Identification is started");
				MessageToast.show("Identification is started");
				that.getView().getModel("result").setProperty("/", data);

				// set button property
				that.getView().getModel("btnProperty").setProperty("/startVideoChat", true);
			}).fail(function(xhr, textStatus, errorThrown) {
				$.sap.log.error("Identification cannot be started");
				MessageToast.show("Identification cannot be started");
			});
		},

Then we can simulate the video chat by passing following URL request:

https://api.test.idnow.de/api/v1/<companyid>/identifications/<transactionNo>/requestVideoChat

Using postman to request Video Chat in simulation mode:


Leave the body empty “{}” and send request to IDnow:


Returned status represents the URL request is accepted by IDnow.

See below snippet for request video chat:

		testVideoChat: function(oEvent) {
			var sId = sap.ui.getCore().getModel("data").getData().contractID;
			var that = this;

			// start the video request
			$.ajax({
				type: "post",
				url: "https://api.test.idnow.de/api/v1/xxxx/identifications/" + sId + "/requestVideoChat",
				headers: {
					"Content-Type": "application/json"
				},
				data: "{}"
			}).done(function(data) {
				MessageToast.show("Identification is completed");
				// update the status
				var oModel = that.getView().getModel("result");
				oModel.setProperty("/status", "SUCCESS");

				// update the button property
				that.getView().getModel("btnProperty").setProperty("/createBP", "true");
			}).fail(function(xhr, textStatus, errorThrown) {
				$.sap.log.error("Identification has error during video chat process");
				MessageToast.show("Identification has error during video chat process");
			});
		},

Create Business Partner

Assume that user information was verified by IDnow service/agents, we can create business partner now for the user who went through the IDnow identification process.

We can consume SAP S/4 odata service to create new business partner. Creating business partner in SAP S/4 is simple, so this will not be introduced in this document as I am focus on IDnow APIs here.

Other IDnow APIs

Apart from above APIs, IDnow also provides following APIs to deal with identifications:

  • Login to the server
  • List identifications
  • Retrieve single identification
  • Delete an identification
  • Copy an identification
  • Archive an identification

Using following URL to log into the server to get access token:

https://gateway.test.idnow.de/api/v1/<companyid>/login

We can use postman to send this request:


The API key should be maintained in body of request:


Then sending request to IDnow.


The access token is returned as request result. Here the access token can be used for following query request. For example, query all identifications:

https://gateway.test.idnow.de/api/v1/<companyid>/identifications

The access token which acquired in previous step can be used as header parameter to get identifications.


As a result, system will retrieve all identifications and list them in json format:


If you want to retrieve single identification data, it is possible to retrieve single identification data directly via following URL:

https://gateway.test.idnow.de/api/v1/<companyid>/identifications/<ident.zip>

https://gateway.test.idnow.de/api/v1/<companyid>/identifications/<transactionNo>

In postman we can retrieve single identification as following:


After sending request to IDnow, we get identification detail information in json mode:


Rest of IDnow APIs are similar to APIs above. Please refer to API document for detail information.

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply