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>/startYou 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>/startA 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>/startUsing 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>/requestVideoChatUsing 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>/loginWe 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>/identificationsThe 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.
- SAP Managed Tags:
