NADRA Biometric Verification

JS Bank is using an SDK which will be integrated in mobile app for customer’s NADRA Biometric Verification.

NADRABiometricVerification

POST

NADRA Biometric Verification




Description

 

JS Bank is using an SDK which will be integrated in mobile app for customer’s NADRA Biometric Verification. This SDK uses mobile camera to take a snap of the user selected finger. It then sends the image to NADRA. Now JS Bank will expose their BVS API to partners to update their existing endpoint to this API. This API will then call the existing service for NADRA verification.

 

 

Version


V1


Resource URL

https://sandbox.jsbl.com/userauth/bvs/v0/verify

 

 

 

Request Parameters

 

Name Description Parameter Type Sample Value

operation

operation Body verify

client_id

client_id Body 44t8mbBJLnE7TUadvvOXsm8tXdGQx1GK

client_secret

client_secret Body JxsB39ZBcwGXSpzn

finger

finger Body LEFT_INDEX

session

session Body 2131100000034258477

identifier

identifier Body 8890239000001

institution

institution Body NADRA

wsq

wsq Body Base64 encoded picture data in wsq format

application

application Body com.inov8.jsblmfs

device

device Body android

version

version Body  

applicationVersion

applicationVersion Body 2.2

manufacturer

manufacturer Body Xiaomi

model

model Body Redmi Note 4

 

 

Response Parameters

 

Name Description Parameter Type Sample Value

code

Response status code JSON Response Body  100

message

Response status message JSON Response Body  successful

session

Session ID JSON Response Body

 30dc423f-1364-4832-8224

-af38c7223db6

identifier

CNIC is the identifier JSON Response Body  8890239000001

birthPlace

Birth place in UTF-8 unicode JSON Response Body  کراچی وسطی,کراچی وسطی

presentAddress

Present address in UTF-8 unicode JSON Response Body

 \u202eمکان\u202a

\u202cنمبر\u202ad-36\u202c،\u202a

\u202cبلاک\u202a f\u202c،\u202a

\u202cمحلہ\u202a \u202cنارتھ\u202a

\u202cناظم\u202a \u202cآباد،\u202a \u202c

کراچی\u202a \u202cوسطی\u202c

cardExpired

Card Expired JSON Response Body  yes

cardType

Card Type JSON Response Body  idcard

name

Name JSON Response Body  محمد حارث اظفر

dateOfBirth

Date of Birth JSON Response Body  1992-07-24

 

 

 

Mobile SDK:

 



Integration



  • Add the following lines to the gradle (app) on root level
allprojects {
    repositories {
        jcenter()
        maven {
            url 'http://artifactory.paysyslabs.com/instascan-complete'
            credentials {
                username = "jsbank-developer"
                password = "AP9N3fsG4oAMheeKJuxJDhNVQaE"
            }
        }
    }
}
  • Add the following lines to the gradle (app) in dependencies
compile 'com.paysyslabs:instascan:1.1.7.2-SNAPSHOT'

Usage:


The scanning activity must inherit NadraActivity to make use of the Instascan SDK.



Initializing


The developer will need to call initializeNadraActivity in the onCreate method of the activity with the CNIC and the finger that needs to be scanned.



@Override
protected void onCreate(Bundle savedInstanceState) {
    initializeNadraActivity(this, "1234512345671", Fingers.LEFT_INDEX);
}

Setting up the scan container


You must return the ID of the layout where you want the camera preview to be displayed.



@Override
public int getScanFragmentContainer() {
    return R.id.your_layout_id;
}





Callbacks/Overrides



Callback Return Type Parameters Notes
getLicenseKey String   The subscription key should be returned if not using proxied mode
getScanFragmentContainer int   ID of the container where you want the camera preview
shouldUseLegacyCaptureFrame boolean   (Optional, defaults to false) If true, the camera preview will be displayed on One Third of the screen
shouldSegment boolean   (Optional, defaults to false) If true, the image captured will be segmented before being sent for processing
shouldInvert boolean   (Optional, defaults to true) If false, the colors won't be inverted
shouldRetryOnBadCapture boolean   (Optional, defaults to false) If true, onBadCapture will not be called and the SDK will retry capturing automatically
getNfiqThreshold int   (Optional, defaults to 4) The minimum NFIQ score of an acceptable image, onBadCapture or retry will be done if NFIQ is above this score
getOverlapThreshold float   (Optional, defaults to 0.75f) The minimum ratio of overlap, onBadCapture or retry will be done if ratio is below this defined value
getDebugStorageBasePath String   (Optional, defaults to System.getenv("EXTERNAL_STORAGE"))
getForcedTracing boolean   (Optional, defaults to false) if true, the SDK will log requests/responses to the debug storage path in a file named 'istrace.log'
onSuccessfulScan   PersonData personData When a scan is successfull, PersonData contains the information
onError   String code, String message When an error occurs
onInvalidFingerIndex   String code, String message, List validFingers When an invalid finger is specified
onRequestStarted     This can be used to start a spinner. Fired when the request is about to be sent
onResponseReceived     This can be used to dismiss a spinner. Fired when the response is received or an error has occurred



Custom Proxy Support


For the concern of not keeping the Instascan license key on application, a custom proxy flow is integrated to the SDK which will post request to a custom URL with some authorization data, that custom URL will in turn post request to Instascan API after successful authorization.



Client (Android):


  1. Integrate the new SDK (with support of custom proxy) to the application.
  2. In your activity, use the following callbacks:

 



@Override
public String getCustomProxyURL() {
    return "https://sandbox.jsbl.com/userauth/bvs/v0/verify
";
}

@Override
public String getCustomCookie() {
    return "JSESSIONID=somesessionid";
}

@Override
public boolean useCustomProxy() {
    return true;
}

@Override
public Map<String, String> getCustomAuthenticationData() {
    HashMap<String, String> authorizationData = new HashMap<>();
    authorizationData.put("Consumer Key", "FVG3cH4GYCCvAptLthIMmXTyz9dA1QJA");
 authorizationData.put("Consumer Secrete", "OzxgB7g1OsBFWKMF");
    return authorizationData;
}

 

 

  1. If useCustomProxy returns false, application will have the previous flow. i.e the sdk will itself post requests to the Instascan API (pl.quickpay.pk/instascan). Otherwise, the SDK will call post the request to URL returned by getCustomProxyURL.
  2. getCustomAuthenticationData returns a map which will contain authorizations keys.
  3. If custom proxy is used, License key from the application will not be used. Rather it will be sent via server end. Thus license key can be removed from application.

 

 

Server:


  1. Request Body from client will have the following tags:
    • operation
    • data
    • forward
  2. operation will be appended to pl.quickpay.pk/instascan/
  3. data will contain the map sent from application in getCustomAuthenticationData.
  4. In case of successful authorization, forward will be posted to pl.quickpay.pk/instascan/{operation} with the license key added to headers Ocp-Apim-Subscription-key
  5. Response received will be directly sent back to application.

Body Parameters


Name Values Description
Request Body
(required)

Add values in JSON Body

HTTP Basic

OAuth 2.0

API Key

Request Payload


{
  "operation": "verify",
  "data": {
    "client_id": "xx",
    "client_secret": "xx"
  },
  "forward": {
    "finger": "LEFT_INDEX",
    "session": "2131100000034258477",
    "identifier": "4230121490545",
    "institution": "NADRA",
    "wsq": "FINGER_DATA",
    "sdk": {
      "application": "com.yourcompany.application",
      "device": "android",
      "version": "1.0.5",
      "applicationVersion": "1.0",
      "manufacturer": "LG",
      "model": "Nexus 5"
    }
  }
}


Response - 100


successful

{
  "status": {
    "code": "100",
    "message": "successful"
  },
  "data": {
    "session": "e540ac6e-c440-47c3-a84c-fd4c6c0bee29",
    "identifier": "4230121490545",
    "tags": {
      "cardExpired": "2022-08-31",
      "birthPlace": "‮اوک رج، ٹینیسی‬",
      "presentAddress": "اوک رج، ٹینیسی‬",
      "cardType": "idcard",
      "name": "میگن فاکس",
      "dateOfBirth": "1986-05-16",
    }
  }
}




Response - 110


citizen number is not verified

{
  "status": {
    "code": "110",
    "message": "citizen number is not verified"
  }
}






Response - 111


fingerprints does not exist in citizen database

{
  "status": {
    "code": "111",
    "message": "fingerprints does not exist in citizen database"
  },
  "data": {
    "session": "8bb9fe71-191a-402a-bcda-bed7d80c6fd1",
    "identifier": "CNIC_NUMBER"
  }
}




Response - 112


error generating session id

{
  "status": {
    "code": "112",
    "message": "error generating session id"
  }
}




Response - 114


invalid verification reference number

{
  "status": {
    "code": "114",
    "message": "invalid verification reference number"
  }
}




Response - 115


Invalid service provide transaction id

{
  "status": {
    "code": "115",
    "message": "Invalid service provide transaction id"
  }
}




Response - 118


finger verfication has been exhausted for current finger.

{
  "status": {
    "code": "118",
    "message": "finger verfication has been exhausted for current finger."
  },
  "data": {
    "session": "1a01c4c0-4374-46ac-98bf-73799c2fc21f",
    "identifier": "CNIC_NUMBER"
  }
}




Response - 119


verification limit for current citizen number has been exhausted

{
  "status": {
    "code": "119",
    "message": "verification limit for current citizen number has been exhausted"
  }
}




Response - 120


invalid input finger template

{
  "status": {
    "code": "120",
    "message": "invalid input finger template"
  }
}




Response - 121


invalid finger index

{
  "status": {
    "code": "121",
    "message": "invalid finger index"
  },
  "data": {
    "session": "4772708a-4bab-4b69-a3ae-ec4919e53100",
    "identifier": "CNIC_NUMBER",
    "tags": {
      "fingerIndexes": "1,6,8,7"
    }
  }
}




Response - 122


fingerprints does not matched

{
  "status": {
    "code": "122",
    "message": "fingerprints does not matched"
  },
  "data": {
    "session": "4772708a-4bab-4b69-a3ae-ec4919e53100",
    "identifier": "CNIC_NUMBER",
    "tags": {
      "fingerIndexes": "1,6,8,7"
    }
  }
}




Response - 123


invalid finger template type

{
  "status": {
    "code": "123",
    "message": "invalid finger template type"
  }
}



Response - 124


this operation will only be enabled if biometric verification of all available fingers is failed

{
  "status": {
    "code": "124",
    "message": "this operation will only be enabled if biometric verification of all available fingers is failed"
  }
}




Response - 125


contact number is not valid

{
  "status": {
    "code": "125",
    "message": "contact number is not valid"
  }
}




Response - 175


transaction id already exist

{
  "status": {
    "code": "175",
    "message": "transaction id already exist"
  }
}




Response - 185


Invalid area name

{
  "status": {
    "code": "185",
    "message": "Invalid area name"
  }
}

API Specific Errors


Code Description
500 Internal Server Error
501 Failure decoding fingerprint
502 Failed to preprocess image
503 The image must be sharp. Please try again!
504 Failed to generate ISO template
505 Identifier is required
506 Unknown finger supplied
507 Institution must be specified
508 No institution found for: XYZ
509 User is already registered with ID: XYZ
510  Support not available for this tenant
511  No user found for provided fingerprint
512  Invalid operation
513  Internal inconsistency
516 OTC support not available for this institution
517 Data must be supplied for OTC requests
518 Citizen number is invalid
519  Secondary citizen number is invalid
401 Invalid client_id or client_secret
402 Bad Request - Invalid <Identifier>
404 Resource not found

FAQs

We take security very seriously. This API will make sure you execute your transactions in a safe and controlled environment. We are using the OAuth2 security mechanism.

This API can power your app with a robust set of permission-based consumer and business account and transactional data while adhering to bank-level security requirements. Effectively managing data is also key for regulatory reporting. You use the API to authenticate your users easily through your web/desktop and mobile applications. This will enable you to extend reach and attract additional customers.

In order to actually access the account and retrieve the requested data, account holders need to authorize your application and allow it to access their account. This is achieved using OAuth 2.

The Client Token, commonly referred to as access_token in code samples, is a credential that can be used by a client to access an API.

You can find all the validation rules under the API docs.

Working...