2 Identity theft and fraud prevention web-based application

JostKYC API



JostKYC API allows verification using a popup system while selecting your customized colour themes that conforms to your website colours. This allows you to verify your users without them leaving your website. It provides a unique system to make your users stay focused.

All successful and approved verification will return a callback response if provided. The callback response contains a preview link field to view user verification details. Check the preview sample section below for details. To use JostKYC API, you must sign up for an account. You will require your Connection ID from your "Connection Settings" area of your account.

For all successful verification request, an initial status indicating that verification was completed is sent to callback url (if provided). When the verification is reviewed and approved or suspended either by Merchant or Jostkyc, another status indicator is sent to the callback url.

All submitted verification, usually are reveiwed within 24 hours by our agents. During review, a verification may be approved if all details are valid or suspended if any details provided is invalid and merchant and/or user are/is notified depending on notification settings set by in merchant's account. The provided merchant request callback url is also notified. The callback notification should be handled by merchant in order to update user verification status on merchant platform.

You can read JostKYC Guide for guidance and requirements. Read below for more details on how to integrate. We also provide support for mobile integration. Check the mobile integration section for sample code

Notice to Merchants

  • All completed verifications are automically callbacked as status "Done". When it is reviewed and approved, its status changes to "Completed". It is therefore important you handle the callback appropraitely
  • It is your duty to review your verifications. You can suspend if you find any details supplied as being invalid. When you suspend, user will be notified and you should provide thesame initial verification link on your platform for user to be able to verify. This time around, when they come back, Jostkyc will direct them to provide only invalid details.
  • Only suspend users on Jostkyc for reasons related to their verification.


JostKYC popup API allows you to integerate JostKYC with your website without leaving navigating away. It is easy and very handy to integrate. All that you require to integrate popup API is a reference to Jquery Library, a reference to our third-party Webcam Library and a reference to JostKYC Popup API

Our Popup API requires that you call our function through any click event. The html element with the click event must have the class 'jcverify'. You must also attach the required data attributes to this html element. JostKYC Popup API requires that your website is SSL encrypted. User must also have a working webcam. With our Popup API, you can specify one of two options for verification. The options are:

  • Basic: This option omits Bank or Driver's license verification. It is an option that may be utilized by merchants who do not want to capture BVN, Bank or Driver's license details of their customers.
    This option will verify email, face capture and ID capture only
  • Standard: This is the full end-to-end verification options. That captures bank details or drivers' license, email verification, face and photo ID. This is the verification option that we strongly advice that you use.
    This option will verify email, bank verification number, bank account number or drivers' license, face capture and ID capture only

Check below for paramters, scripts and callbacks.


Parameters

Note: parameters are all in lower cases.

PARAMETER VALUE OPTION STATUS DETAILS
type Basic | Standard Optional Default is Standard
option BVN | Bank | License Optional
request_id XXXXXXXX Optional Unique ID to identify request
emailrequest Jostkyc | Remote Optional Default is Jostkyc. If set to Remote, then Jostkyc platform will send email verification code to merchant callback. Merchant must handle callback to send email code to user. If set to Jostkyc, email verification is sent directly to user from Jostkyc platform. The verification code is stored in field TOKEN
id XXXXXXXXXXXXXXXX Required Connection ID
callback URL Optional Verification response will be sent to
footerbackground #083154 Optional Footer colour. Default is #083154
button #083154 Optional Button colour. Default is #083154
country Nigeria | Others Optional Default is Nigeria
phone 2348193837776 Required User phone number
email uchesegun@gmail.com Required User email
firstname Uche Optional User firstname
lastname Segun Optional User lastname


Sample Script

Below is a sample script for JostKYC Popup API

<a href="#" class="jcverify" data-type="Standard" data-option="Bank" data-id="XXXXXXXXXXXXXXXXX" data-email="sample@yahoo.com" data-request_id="time()" 
 data-callback="https://jostkyc.com/api_test" data-firstname="Firstname" data-lastname="Lastname" data-phone="23480XXXXXXXX" 
 data-country="Nigeria" data-type="Standard" >Click Here</a>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<script src="https://jostkyc.com/asset/js/webcam.min.js"></script>
<script src="https://jostkyc.com/inline/jc.js"></script>
 



Verification Completion

You can monitor if a verification process has been completed by a user or not. An hidden field with class name 'jostkyc_is_completed' is always prevented at every view. The value of the field could be 'Yes','No' or ''. It is 'Yes' when verification process is completed and '' when verification process is still in progress. It is 'No' when verification process is terminated for any reason.

Using this field, you can know when user has completed verification and redirect to a success page. Check the sample code below.


//The hidden field is in the format and values may be "Yes", "No", ""
//<input type="hidden" class="jostkyc_is_completed" name="jostkyc_is_completed" value="No">

<script>
  $(document).ready(function(){
                  setInterval(timer, 1000);                     
                });
    function timer()
        {
  var status= $(".jostkyc_is_completed").val();
            if(status=="Yes")
                  {
    window.location = "https://mysite.com/success";
                  }
        }
</script>
 


Callback

Below are the parameters that will be sent back in JostKYC Popup API to callback url if provided.
PARAMETER VALUE OPTION DETAILS
status 0 | 1 | 2 | 3 | 4 0 for Pending, 1 for Completed, 2 for Suspended, 3 for Done, 4 for Email Verification Code
request_id XXXXXXXX Unique ID to identify request
message Parameters are not set Message is json of verification details when status is 1 or 3, email of verified user when status is 2 else text description. The json message for status 1 will contain key with value "COMPLETED" and status 3 will contain key with value "DONE"

Sample Callback

  $status = $_POST["status:];
  $request_id =$_POST["request_id"];
  $message = $_POST["message"];
       if($status=="1")
                {
  //Status Completed
   /**{"status":"1","request_id":"xxxxxxxx","message":"{"PHOTOCAPTURE":"https://jostkyc.com/captures/xxxxxxx_xxxx/face_xxxx.xxxx.jpeg",
"IDCAPTURE":"https://jostkyc.com/captures/xxxxx_xxxxx/id_xxxx.xxxx.jpeg","STATUS":"COMPLETED","EMAIL":"sample@yahoo.com",
"PREVIEW":"https://jostkyc.com/preview/xxxxxxx","DETAILS":"Verification successful"}"} **/
  $json= json_decode($message,true);
  $email=$json["EMAIL"];
  //Do other operations;
                }
       if($status=="4")
                {
  // Status Remote Email
  $json= json_decode($message,true);
  $email=$json["EMAIL"];
  $firstname = $json["FIRSTNAME"];
  $token = $json["TOKEN"];
  //Create sample email
  $message = "Dear ".$firstname.",<br><br> Use <b>".$token."</b> as your KYC email verification token. Please disregard if you do not initiate any verification process<br>";
  //Send email;
  //Do other operations
                }
           if($status=="2")
                {
  //Status Suspended
  $email=$message;
  //Create sample email
  $message = "Hello,<br><br> Your KYC has been rejected. You must login to your account to re-capture your KYC details. You must ensure that you provide accurate, clear and valid details only.<br>";
  //Send email;
  //Do other operations
                }


Jostkyc mobile integration follows same method as explained above. All request and responses will come in thesame format. Hoewever, we have customized scripts to ease your integration depending on the platform you are using to develope your mobile app.

Our mobile integration relies on the native browser of the IDE you are using. Whatever the IDE is, you may inject your values into the native browser and reference url 'https://jostkyc.com/inline/jcmobile.php'. The reference url already loads Jquery Library, a reference to our third-party Webcam Library and a reference to a mobile version of JostKYC Popup API

Note: You are free to implement and/or customize your mobile application whichever way you want. As such it is not complusory you reference 'https://jostkyc.com/inline/jcmobile.php' as you may decide to reference your own customized private url. However, we advice that you reference the mobile version of JostKYC Popup API that will not load as a popup. Check below for sample scripts for some platforms

  • Ionic: uses inappbrowser which supports both Android and IOS platforms. To use the inappbrowser, you have to install the plugin within your application environment and include it in your app.module.ts file. In your page where the verification is called, you will have to import the installed inappbrowser. Then you can pass your values to it as described in the parameters section above. Check below for the sample integration process

    Install InAppBrowser
    $ ionic cordova plugin add cordova-plugin-inappbrowser
    $ npm install --save @ionic-native/in-app-browser
     


    In your app.modules.ts page, reference the installed InAppBrowser
    /** Import installed InAppBrowser */
    import { InAppBrowser } from "@ionic-native/in-app-browser";
    @NgModule({
      declarations: [
      ],
      imports: [
      ],
      bootstrap: [IonicApp],
      entryComponents: [
      ],
      providers: [
        {provide: ErrorHandler, useClass: IonicErrorHandler},
        /** Reference InAppBrowser*/
        InAppBrowser
      ]
    })
    export class AppModule {}
     


    In your page, import your installed InAppBrowserapp and load url. For this example, we are passing values from a page on our webserver as such we are referencing 'https://jostkyc.com/inline/jctest.php'. In your own case, you reference directly your own local page (where you would then reference 'https://jostkyc.com/inline/jcmobile.php') or you can inject your values directly (in which case you should directly reference 'https://jostkyc.com/inline/jcmobile.php' in your url) Check 'https://ionicframework.com/docs/native/in-app-browser/' on how to inject.
    import { Component } from "@angular/core";
    /** Import installed InAppBrowser **/
    import { InAppBrowser } from "@ionic-native/in-app-browser";
    @Component({
      selector: "page-jcverify",
      templateUrl: "jcverify.html",
    })
    export class JcverifyPage {
     private script = "";
      constructor(private iab: InAppBrowser
      ) {
    /** Your url should be your local page or https://jostkyc.com/inline/jcmobile.php (if you are injecting directly) **/
    const browser = this.iab.create("https://jostkyc.com/inline/jctest.php","_self","location=no,clearcache=yes,footer=yes,clearsessioncache=yes,closebuttoncaption=close");
    /** Use this script below if you are injecting values directly. Check https://ionicframework.com/docs/native/in-app-browser/ for further guide on this**/ 
    browser.on("loadstop").subscribe(event => {
      browser.executeScript({code:"values_to_inject"});
    });
      }
    }
     

  • Android Studio: uses webview suppport. To use webview, you can add it in the activity layout or add it on create. For this sample, we will be using on create. Also since Jostkyc uses javascript and camera, you have to grant access to internet and javascript. You can pass your values using javascript to the .jcverify class. Check below for the sample integration process

    Add webview to onCreate() method
    val myWebView = WebView(activityContext)
    setContentView(myWebView)
     


    Set internet permission in your manifest
    <manifest>
        <uses-permission android:name="android.permission.INTERNET" />
    </manifest>
     


    Enable javascript, zoom, domstorage, file access
    WebView myWebView = (WebView) findViewById(R.id.webview);
    WebSettings webSettings = myWebView.getSettings();
    webSettings.setJavaScriptEnabled(true);
    webSettings.setDomStorageEnabled(true);
    webSettings.setBuiltInZoomControls(true);
    webSettings.setAllowFileAccess(true);
    /** Allow camera access in webview
    webSettings.setWebChromeClient(new WebChromeClient() {
       @Override
       public void onPermissionRequest(final PermissionRequest request) {
          if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
             request.grant(request.getResources());
          }
       }
    
     });
     


    Load page
    /** Your url should be your local page or https://jostkyc.com/inline/jcmobile.php (if you are injecting directly) **/
    myWebView.loadUrl("https://jostkyc.com/inline/jctest.php")
     


  • Phonegap: also uses inappbrowser which supports both Android and IOS platforms. To use the inappbrowser, you have add the plugin within your application environment and include it in your config.xml file to target your desired platform. Check below for the sample integration process

    Add plugin
     $ cordova plugin add org.apache.cordova.inappbrowser
     


    Add plugin to config.xml to target platform
     <feature name="InAppBrowser">
     /** To target Android platform **/
        <param name="android-package" value="org.apache.cordova.inappbrowser.InAppBrowser" />
     /** To target IOS platform **/
       <param name="ios-package" value="CDVInAppBrowser" />
    </feature>
     


    In your page, load url. For this example, we are passing values from a page on our webserver as such we are referencing 'https://jostkyc.com/inline/jctest.php'. In your own case, you reference directly your own local page (where you would then reference 'https://jostkyc.com/inline/jcmobile.php') or you can add an eventlistener which you will use to inject your values directly (in which case you should directly reference 'https://jostkyc.com/inline/jcmobile.php' in your url)
    
    /** Your url should be your local page or https://jostkyc.com/inline/jcmobile.php (if you are injecting directly) **/
    var ref = window.open("https://jostkyc.com/inline/jctest.php", "_self", "location=no,clearcache=yes,footer=yes,clearsessioncache=yes,closebuttoncaption=close");
    ref.addEventListener("loadstop", function() {"values_to_inject"});
     


  • Note: In you choose the inject method, you must attach your values as data attributes to the class .jcverify.