Getting Started

This document provides instructions for embedding PC SDK in Android applications. In order to understand better how to work with PC we recommend you to read the following documents as well:

Architecture and functionalty presentation
Architecture and functionalty

The PC SDK contains native libraries for Android operating system. These libraries allow to implement all functionality of PC right in your mobile App.

Project Integration

Adding dependency to gradle-script

KYC extension over PC SDK can be added into your project as maven-dependency using SafeTech or Airome repository.

To add KYC extension you need to add external maven repository to top-level gradle script as in the example below.

// Sample of project-level build.gradle
// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
    repositories {
        google()
        jcenter()

    }
    dependencies {
        classpath 'com.android.tools.build:gradle:4.1.0'

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

allprojects {
    repositories {
        google()
        jcenter()

        maven {
            url "https://repo.paycontrol.org/android/maven"
        }
    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

The next step is to add KYC extension into your project as a dependency. Latest version can be discovered in the repository.

    // Dependency in your module-level build.gradle
    implementation 'tech.paycon.kyc:kyc-extension:<LATEST_VERSION>'
    implementation 'tech.paycon.sdk.v5:pcsdk:<LATEST_VERSION>'

Note that KYC extension depends on PC SDK 5.3+, so you need to add PC SDK as a dependency as well. Use the latest version among 5.3.x or 5.4.x versions.

Configuring obfuscation

If you are using obfscation and minifaction to build your app, consider adding the following rule to you proguard-rules.pro file:

-keep class tech.paycon.kyc.** {
    <fields>;
    <methods>;
 }

Basic usage scenarios

This section contains examples of proper KYC Extension usage in a mobile application.

Overall description

KYC is a part of PC Platform which allows to perform remote identification in the mobile application based on verifying client's photos and/or videos alongside with their scanned documents. The remote identification is intended to be performed prior to issuing keys by the PC Server and personalizing the mobile application.

KYC extension interacts with eKYC Connector which receives data from the application and performs the analysis. Refer to this page to find out more about eKYC Connector and the general description of the KYC concept.

The KYC extension initiates a session with initial data (which may be delivered e.g. by QR code) and asks the KYC Connector about the required data for remote identification. The KYC Connector sends the list of necessary media files (which usually includes a short live video and a photo of the passport) and KYC extension, in turn, collects the required sources and sends them to the analysis. After the KYC Connector has verified that the person in a video and on a passport photo is the same, it starts OCR procedure to retrieve the information from the passport. After OCR is done, the mobile application receives a notification, so that the client can confirm that all the fields in the password have been recognized properly. After performing a successful OCR procedure, the KYC Extension requests the list of available options for verifying documents. The client is supposed to choose a preferable way to get ther documents verified. Once verification method is defined, KYC Connector sends the documents for verification and notifies the application about results. Upon a successful verification, the KYC Extension requests the keys from the Connector and the app may be personalized with a retrieved PCUser.

Classes overview

While using KYC Extension in your app, you are going to interact with the follwoing classes (all declared in tech.paycon.kyc namespace):

KYC - core class of KYC extension. Must be initialized before performing any operations.
KYCSession - Class which represents a separate session established with KYC Connector. This is rather a data class.
KYCManager - Class which manages your sessions. The follwoing guide is primarily devoted to showing proper usage of this class.
KYCError - Class which represents errors. Call KYCError.getType() to get a code of error or KYCError.getMessage() to get an explanation of what has happened. Refer to documentation on this class to browse the possible error codes.

Step 1. Initialization

Prior to using any KYC Extension functions, the library must be initialized. You perform initialization once before using KYC Extension with an instance of PCSDK which also must be initialized by this moment:

KYC mKYC = KYC.getInstance();
mKYC.init(mPCSDK);

NOTE: To find out more about adding PCSDK to your project and initializing it, refer to this page.

Step 2. Creating a session

To start a session, you call KYCManager.startSession() which either accepts a JSON-encoded initial session data or several entries as String params.

KYCManager.startSession(
    qrSource, // the content of scanned QR code with initial data (in JSON)
    pushId, // Firebase or HMS push token for receiving notifications
    PCPushServiceType.Firebase, // Or PCPushServiceType.HMS for Huawei devices
    new KYCManager.SessionCallback() {
    @Override
    public void success(@NonNull KYCSession session) {
        // The session is created. The next step is to find out which sources must be provided.
        // You can always retrieve an actual sources list by calling
        // KYCManagergetRequiredSources(),
        // however once the session is created this information is already retrieved and
        // you can access cached data by calling KYCSession.getRequiredSources().
    }

    @Override
    public void error(@NonNull KYCError error) {
        // Session was not created. Examine error type for details
    }
});

Step 3. Getting required sources

The first thing to do with a just created session is to determine which types of sources the client will be asked to upload.

// Option 1. Get list of the sources right from the created session 
List<KYCSession.MediaSourceType> requiresSources = session.getRequiredSources();
for (KYCSession.MediaSourceType type: requiresSources) {
    // Collect required sources: record a video, take necessary photos
}

// Option 2. Make a request for KYC Connector (if you want to renew the list of required sources)
// For newly created session result will be the same.
KYCManager.getRequiredSources(session, new KYCManager.SessionCallback() {
    @Override
    public void success(@NonNull KYCSession session) {
        List<KYCSession.MediaSourceType> requiresSources = session.getRequiredSources();
        for (KYCSession.MediaSourceType type: requiresSources) {
            // Collect required sources: record a video, take necessary photos
        }
    }

    @Override
    public void error(@NonNull KYCError error) {
        notifyLiveProcessedFinished();
        postDispensableError(error, getString(R.string.kyc_error_failed_to_send_data));
    }
});

For description of the various sources refer to documentation on KYCSession.MediaSourceType.

Step 4. Upload the collected sources

Once the media files are collected, they must be uploaded for analysis. You can upload each file separately or upload all the files at once. The follwoing example demonstartes how to upload all files together:

// Assume that the connector requires a liveness video and a photo of the passport main page
HashMap<PCKYCSession.MediaSourceType, File> collectedData = new HashMap<>();
collectedData.put(PCKYCSession.MediaSourceType.VIDEO_LIVENESS_SCAN, videoFile);
collectedData.put(PCKYCSession.MediaSourceType.PHOTO_PASSPORT_PAGES_2_3, passportPhoto);
KYCManager.uploadAllMedia(session, collectedData, new KYCManager.SessionCallback() {
@Override
public void success(@NonNull KYCSession pckycSession) {
    // All files were uploaded
}

@Override
public void error(@NonNull KYCError error) {
    // An error has occurred. But some files have probably been uploaded.
    // Call KYCManager.getRequiredSources() to check what still needs to
    // be uploaded.
}
});

Step 5. Check the session status

In your app, you are supposed to check the session status from time to time so as that you are able to handle any changes with the session.

To learn about possible session statuses, refer to the documentation on KYCSession.SessionStatus.

The following code snippet shows how you can check the status:

KYCManager.getSessionStatus(session, new KYCManager.SessionStatusCallback() {
    @Override
    public void success(@NonNull KYCSession session, @NonNull KYCSession.ExtendedSessionStatus status) {
        // Status is updated. Check status.getSessionStatus() for actual status
    }

    @Override
    public void error(@NonNull KYCError error) {
        // Status was not acquired
    }
});

NOTE: In case the analysis has failed (i.e. you have caught the status ANALYSIS_FAILED), you can request the analysis history from the KYC Connector to see what went wrong. Call KYCManager.getStatusHistory() to see the statuses history.

Step 6. Download OCR results

After uploading required media files, the KYC connector will perform the analysis. Once, the analysis is successful, you will receive the status OCR_SUCCESS which means, your passport has been scanned successfully. You are supposed to download scanning results and show it to a client so that they can confirm the correctness of the OCR results.

The code snippet below demonstrates the process of downloading OCR results:

// By this moment session status must OCR_SUCCESS
KYCManager.getOCRResults(session, new KYCManager.OCRResultsCallback() {
    @Override
    public void success(@NonNull KYCSession KYCSession1, @NonNull Map<String, Object> results) {
        // OCR results received
    }

    @Override
    public void error(@NonNull KYCError error) {
        // OCR results are not received
    }
});

Normally, the result map contains key field_texts which is another Map that, in turn, contains keys with data from the passport: name, dateofbirth, sex, address, number, dateofissue, placeofissue, issuecode.

Step 7. Approve OCR results

After the client has checked the OCR results, their validity must be approved by the application. To approve the OCR results, just call KYCManager.approveOCRResults(KYCSession, KYCManager.SessionCallback).

KYCManager.approveOCRResults(session, new KYCManager.SessionCallback() {
    @Override
    public void success(@NonNull KYCSession session) {
        // OCR results have been approved
    }

    @Override
    public void error(@NonNull KYCError error) {
        // Request failed
    }
});

NOTE: In case the OCR results are invalid, you have to provide an opportunity for a client to notify the KYC Connector about the problem. Call KYCManager.declineOCRResults(KYCSession, KYCManager.SessionCallback) for this purpose.

In some cases it is possible that the OCR fails (e.g., the quality of uploaded photo was poor). Then instead of OCR_SUCCESS the session will come to OCR_FAILED. It is also possible that the client rejects OCR results and the session gets its OCR_REJECTED_BY_USER status. Your application may behave the same way in both cases: it can restart an OCR procedure. To do this, you must call KYCManager.getRequiredSources(KYCSession, KYCManager.SessionCallback) to see which pages of the passport must be uploaded again. Then, KYCManager.uploadMedia() must be called to resend required photos.

Step 8. Verify documents validity

Once, the OCR results have been approved by the client, the session status turns to OCR_APPROVED_BY_USER. The next step is to get documents verified by government authorities. The KYC Connector can support several ways of documents verification. To find out which ways can be applied, KYCManager.getVerifiers(KYCSession, KYCManager.VerifiersListCallback) should be called. The method returns the list of available verifiers in a callback.

To find out which verifiers can be supported by KYC Connector, refer to documentation on KYCSession.Verifier enum.

After getting the list of supported verifiers you should provide the opportunity to choose the most suitable verifier for your clients. Refer to documentation on KYC Connector to learn more about each verifier.

The following code snippet shows how to start documents verification with a particular verifier:

KYCManager.getVerifiers(session, new KYCManager.VerifiersListCallback() {
    @Override
    public void success(@NonNull KYCSession session, @NotNull List<KYCSession.Verifier> verifiers) {
        // Show the available verifiers to a client and allow to choose one
        KYCManager.startVerification(session, chosenVerifier, new KYCManager.StartVerificationCallback() {
            @Override
            public void success(@NonNull KYCSession session, @Nullable Object result) {
                // Verification has started
            }

            @Override
            public void error(@NonNull KYCError error) {
                // Cannot start verification
            }
        });
    }

    @Override
    public void error(@NonNull KYCError error) {
        // Cannot get verifiers
    }
});

NOTE: When starting verification via KYCSession.Verifier.FNS or KYCSession.Verifier.KALUGA no further actions are required from the mobile application whereas verification with KYCSession.Verifier.ESIA and KYCSession.Verifier.SBER_ID requires you to handle Object result returned in callback. In fact, when using KYCSession.Verifier.ESIA the result is a String which contains an URL to get logged in gosuslugi.ru, while for KYCSession.Verifier.SBER_ID is a String in a JSON format with credentials required to login via Sber ID.

Step 9. Obtain your keys

Once the documents verification has started you should wait until the session reaches status of PCKEY_READY. This means, the PC symmetric keys have been issued and you can register them on a device. This is a final step when working with KYC SDK. As a result, you receive PCUser object and pass it to PC SDK for further processing. Consider the following example:

KYCManager.getPCUser(session, new KYCManager.GetPCUserCallback() {
    @Override
    public void success(@NonNull KYCSession session, @NonNull PCUser user) {
        // Successfully received PCUser
    }

    @Override
    public void error(@NotNull KYCError error) {
        // Failed to get keys
    }
});

Refer to documentation on PC SDK to learn about further actions with PCUser object.

PC SDK for Mobile Reference