Skip to content

WideKYC API

Jump to bottom
WideTechId - Mobile Team edited this page Mar 29, 2023 · 4 revisions

This wiki contains API Documentation for WideKYC REST API

Contents

1. Liveness Detection
   1.1. URL
   1.2. Request Header
   1.3. Request Body
   1.4. Sample Data
      1.4.1. Successful
      1.4.2. Product is Not Activated
      1.4.3. Has Exceeded Subscription Quota
      1.4.4. Finance Administrator Has Not Approved the Product Request
2. ID Recognize
   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. ID Validation
   3.1. URL
   3.2. Request Header
   3.3. Request Body
   3.4. Sample Data
      3.4.1. Successful
      3.4.2. Product is Not Activated
      3.4.3. Has Exceeded Subscription Quota
      3.4.4. Finance Administrator Has Not Approved the Product Request
General Error Response

1. Liveness Detection

By using this API, merchant server will send the request regarding liveness detection of selfie photo to WideKYC Gateway.

1.1. URL

Method URL
POST <server-url>/api/passive-liveness

1.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”

1.3. Request Body

Parameter Data Type Required Description
cust_ref_no String Yes Customer reference number that is generated by merchant server
selfie_image Base64 Yes Base64 format of selfie image

1.4. Sample Data

1.4.1. Successful

Request:

{
    "cust_ref_no" : "3322873",
    "selfie_image": "<Base64>"
}

Response:

{
    "statusCode": "SUCCESSFUL",
    "content": {
        "result": {
            "status": "success",
            "result": "True",
            "trx_id": "202303291030019483",
            "ref_id": "1234567890",
            "timestamp": 1680060646134
        }
    }
}

Status Code:

200

1.4.2. Product is Not Activated

Request:

{
    "cust_ref_no" : "3322873",
    "selfie_image": "<Base64>"
}

Response:

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

Status Code:

200

1.4.3. Has Exceeded Subscription Quota

Request:

{
    "cust_ref_no" : "3322873",
    "selfie_image": "<Base64>"
}

Response:

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

Status Code:

200

1.4.4. Finance Administrator Has Not Approved the Product Request

Request:

{
    "cust_ref_no" : "3322873",
    "selfie_image": "<Base64>"
}

Response:

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

Status Code:

200

2. ID Recognize

By using this API, merchant server will send the request regarding Optical Character Recognition (OCR) of eKTP to WideKYC Gateway.

2.1. URL

Method URL
POST <server-url>/api/id-recognize

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
cust_ref_no String Yes Customer reference number that is generated by merchant server
id_image Base64 Yes Base64 format of eKTP image

2.4. Sample Data

2.4.1. Successful

Request:

{
    "cust_ref_no" : "4222873",
    "id_image" : "<Base64>"
}

Response:

{
    "statusCode": "SUCCESSFUL",
    "content": {
        "result": {
            "status": "success",
            "result": "True",
            "data": {
                "nik": "3671121401010004",
                "nama": "Yu Andi Chen",
                "tempat_lahir": "Fujian",
                "tanggal_lahir": "25-03-1977",
                "jenis_kelamin": "LAKI-LAKI",
                "gol_darah": "-",
                "alamat": "JL. S*L*M*T, P*R*M*H*N R*NC*B*L* N*. 41",
                "rt/rw": "001/009",
                "kelurahan/desa": "KARANG TENGAH",
                "kecamatan": "KARANG TENGAH",
                "agama": "KRISTEN",
                "status_perkawinan": "BELUM KAWIN",
                "pekerjaan": "PELAJAR / MAHASISWA",
                "kewarganegaraan": "WNI",
                "provinsi": "BANTEN",
                "kota": "KOTA TANGERANG"
            },
            "trx_id": "202303291031019484",
            "ref_id": "1234567890",
            "timestamp": 1680060716281
        }
    }
}

Status Code:

200

2.4.2. Product is Not Activated

Request:

{
    "cust_ref_no" : "4222873",
    "id_image" : "<Base64>"
}

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:

{
    "cust_ref_no" : "4222873",
    "id_image" : "<Base64>"
}

Response:

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

Status Code:

200

2.4.4. Finance Administrator Has Not Approved the Product Request

Request:

{
    "cust_ref_no" : "4222873",
    "id_image" : "<Base64>"
}

Response:

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

Status Code:

200

3. ID Validation

By using this API, merchant server will send the request regarding ID validation by Dukcapil (Population and Civil Registration Agency) to WideKYC Gateway.

3.1. URL

Method URL
POST <server-url>/api/id-validation

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
cust_ref_no String Yes Customer reference number that is generated by merchant server
nik Integer Yes Identifier number of individual
name String No Individual name
birth_date String No Individual birth date. The format is DD-MM-YYYY (e.g. 31-01-1981)
birth_place String No Individual birth place (e.g. Jakarta)
address String No Individual address
selfie_image Base64 No Base64 format of selfie image

3.4. Sample Data

3.4.1. Successful

Request:

{
    "cust_ref_no" : "5102873",
    "nik" : "3203012503770011",
    "name" : "GuoHui Chen",
    "birth_date" : "25-03-1977",
    "birth_place" : "Fujian",
    "address" : "Jl Selamet",
    "selfie_image" : "<Base64>"
}

Response:

{
    "statusCode": "SUCCESSFUL",
    "content": {
        "result": {
            "status": success,
            "data": {
                "nik": true,
                "full_name": true,
                "birth_date": true,
                "birth_place": true,
                "address": true,
                "selfie_photo": 10
            },
            "trx_id": "202303291031019484",
            "ref_id": "1234567890",
            "timestamp": 1680060716281
        }
    }
}

Status Code:

200

3.4.2. Product is Not Activated

Request:

{
    "cust_ref_no" : "5102873",
    "nik" : "3203012503770011",
    "name" : "GuoHui Chen",
    "birth_date" : "25-03-1977",
    "birth_place" : "Fujian",
    "address" : "Jl Selamet",
    "selfie_image" : "<Base64>"
}

Response:

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

Status Code:

200

3.4.3. Has Exceeded Subscription Quota

Request:

{
    "cust_ref_no" : "5102873",
    "nik" : "3203012503770011",
    "name" : "GuoHui Chen",
    "birth_date" : "25-03-1977",
    "birth_place" : "Fujian",
    "address" : "Jl Selamet",
    "selfie_image" : "<Base64>"
}

Response:

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

Status Code:

200

3.4.4. Finance Administrator Has Not Approved the Product Request

Request:

{
    "cust_ref_no" : "5102873",
    "nik" : "3203012503770011",
    "name" : "GuoHui Chen",
    "birth_date" : "25-03-1977",
    "birth_place" : "Fujian",
    "address" : "Jl Selamet",
    "selfie_image" : "<Base64>"
}

Response:

{
    "statusCode": "ERROR",
    "responseStatusDetails": [
        {
            "description": "Product is not activated yet by Admin",
            "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