Skip to content

Merchant Specific API

Jump to bottom
WideTechId - Mobile Team edited this page Oct 27, 2022 · 1 revision

This wiki contains API Documentation for Merchant-Specific API

Contents

1. Initialize to Merchant Server (Customized by Merchant)
   1.1. URL
   1.2. Request Header
   1.3. Request Body
   1.4. Sample Data
      1.4.1. Successful
2. Initialize to WideKYC Gateway
   2.1. URL
   2.2. Request Header
   2.3. Request Body
   2.4. Sample Data
      2.4.1. Successful
      2.4.2. Product is Not Activated
      2.4.3. Has Exceeded Subscription Quota
      2.4.4. Finance Administrator Has Not Approved the Product Request
3. Check Result
   3.1. URL
   3.2. Request Header
   3.3. Request Body
   3.4. Sample Data
      3.4.1. Successful
      3.4.2. Trx ID Has Exceeded Expiration Time
General Error Response

1. Initialize to Merchant Server (Customized by Merchant)

Every merchant must have merchant server that will send data to merchant app and WideKYC Gateway. Merchant server must have an API that will be used by merchant app to initialize request. The URL, request, and response are defined by merchant. Below is the provided example that later can be customized by merchant based on their requirements.

1.1. URL

Method URL
POST <server-url>/initMerchant

1.2. Request Header

N/A

1.3. Request Body

Parameter Data Type Required Description
product Integer Yes Product code. Available values:
00 = Liveness Detection
01 = ID Recognize
02 = ID Validation
serviceLevel Integer Yes Service level type based on the chosen product. Available values:
-For Liveness Detection:
62000 = Medium liveness validation
62001 = Advanced liveness validation
-For ID Recognize:
62010 = No SDK validation
62011 = Medium ID Recognize validation
62012 = Advanced ID Recognize validation
-For ID Validation:
62020 = ID Validation with UI
62021 = ID Validation non UI
metaInfo String Yes Device meta info

1.4. Sample Data

1.4.1. Successful

Request:

{
   "product":"00",
   "serviceLevel":"62000",
   "metaInfo":"{\"deviceId\":\"eb2a3288-961b-4118-a394-c1bb97ca4973\",\"getDeviceType\":\"android\",\"getDeviceModel\":\"sdk_gphone_x86\",\"getAppName\":\"com.wide.mobile.kyc\",\"getAppVersion\":\"1.0\",\"getOsVersion\":\"11\"}"
}

Response:

{
    "statusCode": "SUCCESSFUL",
    "content": {
        "trxId": "OWI0OWI4ZGEtODgxOC00MTE2LWJjMGQtYTk1YTc3MzllMDkyLjIwMjIxMDI0MTI0OTAxNDUxNg==",
        "product": "00",
        "gatewayUrl": "http://34.101.86.149:9090/api/start",
        "serviceLevel": "62000"
    }
}

Status Code:

200

2. Initialize to WideKYC Gateway

After merchant app has initialized request to merchant server then merchant server will process the request to WideKYC Gateway.

2.1. URL

Method URL
POST <server-url>/api/initialize

2.2. Request Header

Parameter Data Type Required Description
token String Yes Access token of each merchant. Access token can be obtained from portal after merchant has registered to portal and has been approved by Finance Administrator
Content-Type String Yes Content type of the request. Fill the value with “application/json”

2.3. Request Body

Parameter Data Type Required Description
product Integer Yes Product code. Available values:
00 = Liveness Detection
01 = ID Recognize
02 = ID Validation
serviceLevel Integer Yes Service level type based on the chosen product. Available values:
-For Liveness Detection:
62000 = Medium liveness validation
62001 = Advanced liveness validation
-For ID Recognize:
62010 = No SDK validation
62011 = Medium ID Recognize validation
62012 = Advanced ID Recognize validation
-For ID Validation:
62020 = ID Validation with UI
62021 = ID Validation non UI
metaInfo String Yes Device meta info
channel String No Channel where the request is coming from. If the value is not filled then the channel is SDK
transactionRefNo String Yes Transaction reference number that is generated by merchant server

2.4. Sample Data

2.4.1. Successful

Request:

{
   "product":"00",
   "serviceLevel":"62000",
   "metaInfo":"{\"deviceId\":\"eb2a3288-961b-4118-a394-c1bb97ca4973\",\"getDeviceType\":\"android\",\"getDeviceModel\":\"sdk_gphone_x86\",\"getAppName\":\"com.wide.mobile.kyc\",\"getAppVersion\":\"1.0\",\"getOsVersion\":\"11\"}",
   "channel" : "SDK",
   "transactionRefNo" : "111"
}

Response:

{
    "statusCode": "SUCCESSFUL",
    "content": {
        "trxId": "YzVhMTdiNmEtYTUwNi00NmRjLWI1M2YtYjhjNDg1MGYwODJhLjIwMjIxMDI1MTIzMDAxNDU5Nw==",
        "product": "00",
        "gatewayUrl": "http://34.101.86.149:9090/api/start",
        "serviceLevel": "62000",
        "transactionRefNo": "111"
    }
}

Status Code:

200

2.4.2. Product is Not Activated

Request:

{
   "product":"00",
   "serviceLevel":"62000",
   "metaInfo":"{\"deviceId\":\"eb2a3288-961b-4118-a394-c1bb97ca4973\",\"getDeviceType\":\"android\",\"getDeviceModel\":\"sdk_gphone_x86\",\"getAppName\":\"com.wide.mobile.kyc\",\"getAppVersion\":\"1.0\",\"getOsVersion\":\"11\"}",
   "channel" : "SDK",
   "transactionRefNo" : "444"
}

Response:

{
    "statusCode": "ERROR",
    "responseStatusDetails": [
        {
            "description": "Product is not activated. Please Check Available Products in Manage Product Menu",
            "type": "Exception"
        }
    ]
}

Status Code:

200

2.4.3. Has Exceeded Subscription Quota

Request:

{
   "product":"02",
   "serviceLevel":"62020",
   "metaInfo":"{\"deviceId\":\"eb2a3288-961b-4118-a394-c1bb97ca4973\",\"getDeviceType\":\"android\",\"getDeviceModel\":\"sdk_gphone_x86\",\"getAppName\":\"com.wide.mobile.kyc\",\"getAppVersion\":\"1.0\",\"getOsVersion\":\"11\"}",
   "channel" : "SDK",
   "transactionRefNo" : "1122"
}

Response:

{
    "statusCode": "ERROR",
    "responseStatusDetails": [
        {
            "description": "Quota Exceeded",
            "type": "Exception"
        }
    ]
}

Status Code:

200

2.4.4. Finance Administrator Has Not Approved the Product Request

Request:

{
   "product":"02",
   "serviceLevel":"62020",
   "metaInfo":"{\"deviceId\":\"eb2a3288-961b-4118-a394-c1bb97ca4973\",\"getDeviceType\":\"android\",\"getDeviceModel\":\"sdk_gphone_x86\",\"getAppName\":\"com.wide.mobile.kyc\",\"getAppVersion\":\"1.0\",\"getOsVersion\":\"11\"}",
   "channel" : "SDK",
   "transactionRefNo" : "555"
}

Response:

{
    "statusCode": "ERROR",
    "responseStatusDetails": [
        {
            "description": "Product is not activated yet by Admin",
            "type": "Exception"
        }
    ]
}

Status Code:

200

3. Check Result

After the product has finished to be used, the result will be checked. Merchant server will send the request to WideKYC Gateway. Before consuming this API, make sure WideKYC SDK has been started/launched.

3.1. URL

Method URL
POST <server-url>/api/checkResult

3.2. Request Header

Parameter Data Type Required Description
token String Yes Access token of each merchant. Access token can be obtained from portal after merchant has registered to portal and has been approved by Finance Administrator
Content-Type String Yes Content type of the request. Fill the value with “application/json”

3.3. Request Body

Parameter Data Type Required Description
trxId String Yes Transaction ID to process the product that is generated by WideKYC Gateway

3.4. Sample Data

3.4.1. Successful

Request:

{  
    "trxId":"NDExMjcxY2YtMDdlOC00YzhlLTlkYjctNjQyYjRiZTkyM2FhLjIwMjIxMDI3MTAzNTAxNDgxMA=="
}

Response:

{
    "statusCode": "SUCCESSFUL",
    "content": {
        "result": {
            "timestamp": "2022-10-27 10:37:50.542",
            "status": 200,
            "errors": "",
            "message": "success",
            "data": {
                "result": true
            },
            "ref_id": "202210271035014810",
            "transactionRefNo": "11111"
        }
    }
}

Status Code:

200

3.4.2. Trx ID Has Exceeded Expiration Time

Request:

{  
    "trxId":"ZDNjZDIyMWEtYWVhMy00YjA3LThlOWQtZjI0ZTZhMWMzYWI1LjIwMjIwNzA3MTMxNjAwOTg5Mw=="
}

Response:

{
    "statusCode": "ERROR",
    "responseStatusDetails": [
        {
            "description": "error service already expired ",
            "type": "Exception"
        }
    ]
}

Status Code:

200

General Error Response

WideKYC uses HTTP status code to indicate the error status. The details of the status codes and their descriptions can be seen below:

Status Code Description
200 OK – Response is either successful or not successful while throwing exception.
401 Unauthorized – Client does not have authorization to consume WideKYC’s API.
404 Not Found – URL is not available.
500 Internal Server Error – Something went wrong on the server. Please contact support.
503 Service Unavailable – Server cannot handle request temporarily due to maintenance or overload.
504 Gateway Timeout – Server that acts as gateway or proxy did not receive response in time from the upstream server.

If the status code is 200, parameter statusCode is always included in the response body to show whether the response is successful or error.

Parameter Description
statusCode If the value is SUCCESSFUL then the response is successful. If the value is ERROR then the response is error.

WideKYC • Main • Website

Home

Integration

API Documentation

References

Website ↗

Clone this wiki locally