Integration Guide

Prerequisites

Getting Client ID and Pass Key
Installing SDK

Getting Authentication Token

Generate a partner token that will authenticate all subsequent API calls.

For detailed instructions, request/response examples, and token caching strategies, see Getting Authentication Token.

You will pass this token as x-onekyc-token in all subsequent steps

Generating SDK token

To start the SIV process, you will need to generate an SDK token that will be unique for a single process or submission.

You can generate it via Initiate Flow API.

The API expects a phoneNumber or email to be provided and it has to be verified.

{
  "flow": "STANDALONE_IDENTITY_VERIFICATION",
  "source": "SDK",
  "successRedirectionUrl": "http://myserver.com/success-page",
  "failureRedirectionUrl": "http://myserver.com/failure-page",
  "additionalDetails": {
    "phoneNumber": "628188888889",
    "dataVerification": {
      "phoneNumber": {
        "isVerified": true,
        "verificationReferenceId": "string-referencing-to-phonenumber-verification"
      }
    },
  },
  "userLocale": "id_ID"
}

{
  "flow": "STANDALONE_IDENTITY_VERIFICATION",
  "source": "SDK",
  "successRedirectionUrl": "http://myserver.com/success-page",
  "failureRedirectionUrl": "http://myserver.com/failure-page",
  "additionalDetails": {
    "email": "[email protected]",
    "dataVerification": {
      "email": {
        "isVerified": true,
        "verificationReferenceId": "string-referencing-to-email-verification"
      }
    },
    "userLocale": "id_ID"
  }
}

Getting Submission Results

Once KTP and Selfie have been captured and received by our system, we will start processing the submission asyncly.

When the submission is completed, you can get the results via our callback webhook.

Callback will be sent as an HTTP request to your desired API. To do so you will need to provide us with:

full endpoint URL e.g. https://myhttpserver.com/callback-endpoint
required headers (key and value) in case your API is protected
IPs or IP Range to whitelist

You can check request payload we will send below

{
    "submissionId": "c64b4c8c-9a8f-4e9c-b86a-0908291c855e",
    "userId": "421453511adsasdl",
    "userIdType": "MY_USER_ID",
    "partnerSessionId": "b719f79b-ae7a-440a-8f9c-5f661ca34e7",
    "status": "COMPLETED",
    "result": "VALID",
    "submissionDetails": {
        "verificationResult": {
            "nik": "PASS",
            "name": "PASS",
            "dateOfBirth": "PASS",
            "selfie": "PASS"
        },
        "ktpData": {
            "nik": "3208201808850001",
            "name": "JOHN DOE",
            "region": "SEMARANG",
            "dateOfBirth": "18-02-1960",
            "bloodType": "-",
            "religion": "KRISTEN",
            "province": "JAWA TIMUR",
            "city": "KOTA SURABAYA",
            "address": "SEMARANG SELATAN",
            "district": "WAYANG",
            "town": "BUBUTAN",
            "gender": "male",
            "rt": "008",
            "rw": "020",
            "occupation": "PELAJAR/MAHASISWA",
            "validUntil": "",
            "citizenship": "INDONESIA",
            "maritalStatus": "BELUM KAWIN",
            "issuanceDate": "28-12-2017"
        },
        "certificateRegistration": {
            "eligibleToActivate": true,
            "onboardingCode": "NEW_USER",
            "shouldSkipActivation": true
        },
        "imageUrls": {
            "KTP": "https://sample-image.com/ktp.jpg",
            "SELFIE": "https://sample-image.com/selfie.jpg",
            "ADDITIONAL_SELFIE": "https://sample-image.com/additional-selfie.jpg"
        }
    }
}

Manually getting submission result

In case callback is not received, you can also manually get the results using Get Submission Details API.