PC SDK for Mobile Reference

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()
        mavenCentral()

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

        // 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.5+, so you need to add PC SDK as a dependency as well. Use the latest version among 5.5.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 SDK 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 SDK 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.

Classes overview

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

  • KYC - core class of KYC SDK. Must be initialized before performing any operations.
  • KYCInfo - provides information about capabilities of KYC Connector.
  • KYCSession - represents a separate session established with KYC Connector. This is rather a data class.
  • KYCManager - manages your sessions. The following guide is primarily devoted to showing proper usage of this class.
  • KYCError - provides details about possible 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.
  • KYCAnalyser, KYCOCRRetreiver, KYCVerifier, - classes that reflect possible configuration options to control the verification.
  • KYCSessionParams - Allows to configure the session before starting it.

There are some other classes and enums you are likely to use. For more information you can refer Classes reference.

Step 1. Initialization

Prior to using any KYC SDK functions, the library must be initialized. You perform initialization once before using KYC SDK 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. Requesting information about KYC Connector

Before opening a session to KYC Connector the application must request information about various verification options that KYC Connector supports. The obtained information can be used to configure the session in a different ways, e.g. you can perform identity verification even without uploading any documents via Tinkoff ID, or you can require the client to get their documents verified by several services like Federal Tax Service and Ministry of Internal Affairs together.

To obtain an actual information about KYC Connector, the app should acquire its URL first, and then you can call KYCManager.getKYCInfo(...):

KYCManager.getKYCInfo(kycUrl, new KYCManager.KYCInfoCallback() {
    @Override
    public void success(@NonNull KYCInfo info) {
        // Explore the configuration
        Log.i(TAG, "Successfully received info: " + info);
    }

    @Override
    public void error(@NonNull KYCError error) {
        // Handle an error
    }
});

Step 3. 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. You also have to pass an instance of KYCSessionParams to tell the KYC Connector how do you want to verify client's identity. You fill KYCSessionParams relying on the data returned in KYCInfo.


// Construct proper session params
KYCSessionParams params = new KYCSessionParams();

// Choose one of available analyzers returned by info.getAvailableAnalysers()
params.setAnalyser(analyser);

// Optional. Set desired preliminary verifier if the chosen analyzer supports preliminary verification.
// Verifier must be selected from info.getAvailableVerifiers() and Verifier.isPreliminaryReady() must return true
params.setPreliminaryVerifier(verifier);

// Optional. Set preferred OCR retriever among those offered in info.getAvailableOcrRetrievers().
// You don't have to specify OCR retriever if you selected an analyzer which performs only preliminary verification.
params.setOcrRetriever(retriever);

// Optional. List of verifiers. The documents will be examined against each specified verifier.
// You don't have to specify verifiers if you selected an analyzer which performs only preliminary verification.
params.setVerifiers(verifiers);

// Start session with constructed params
KYCManager.startSession(
    qrSource, // the content of scanned QR code with initial data (in JSON)
    params,
    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 depends on the type of analyzer you have chosen
    }

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

Step 4. Performing preliminary verification

In case, you passed in KYCSessionParams an analyzer which implies performing preliminary verification, you have to start the verification with specified preliminary verifier:

KYCManager.startVerification(session, session.getPreliminaryVerifier(), new KYCManager.StartVerificationCallback() {
    @Override
    public void success() {
        // Preliminary verification has started
        // Now you have to obtain credentials for specified verifier
        KYCManager.getSessionStatus(session, new KYCManager.SessionStatusCallback() {
            @Override
            public void success(KYCSession session, KYCSession.ExtendedSessionStatus status) {
                // Now credentials for preliminary verification must be available
               KYCCredentials credentials = status.getCredentials();
               // You can extract pre-ready intent instead of constructing it yourself
               Intent intent = credentials.getIntent(appContext);
               // Now you can launch the verification
               startActivity(intent);
            }

            @Override
            public void error(KYCError error) {
                // Failed to obtain session status    
            }
        });
    }

    @Override
    public void error(KYCError error) {
        // Failed to start preliminary verification
    }
});

Step 5. Getting required sources

If the specified analyzer implies some other types of verifications (apart from preliminary verification) you have to determine which types of sources the client will be asked to upload. If the specified analyzer uses only preliminary verification, steps 5-10 must be skipped.

// 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) {
        // Failed to acquire list of required sources
    }
});

For description of the various sources refer to documentation on KYCMediaSourceType.

Step 6. 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 following example demonstrates how to upload all files together:

// Assume that the connector requires a liveness video and a photo of the passport main page
HashMap<KYCMediaSourceType, File> collectedData = new HashMap<>();
collectedData.put(KYCMediaSourceType.VIDEO_LIVENESS_SCAN, videoFile);
collectedData.put(KYCMediaSourceType.PHOTO_PASSPORT_PAGES_2_3, passportPhoto);
KYCManager.uploadAllMedia(session, collectedData, new KYCManager.SessionCallback() {
@Override
public void success(@NonNull KYCSession session) {
    // 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 7. Check the session status

In your app, you are supposed to check the session status from time to time so 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
    }
});

Step 8. 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, String> results) {
        // OCR results received
    }

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

Normally, the result map contains keys with data from the passport: name, dateofbirth, sex, address, number, dateofissue, placeofissue, issuecode.

Step 9. 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
    }
});

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 10. Verify documents

Once, the OCR results have been approved by the client, the session status turns to OCR_APPROVED_BY_USER and then to VERIFYING_OCR_RESULTS. The next step is to get documents verified by each verifier specified in KYCSessionParams when creating a session.

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

KYCManager.startVerification(session, verifier, new KYCManager.StartVerificationCallback() {
    @Override
    public void success() {
        // Preliminary verification has started
        // Now you have to obtain credentials for specified verifier
        KYCManager.getSessionStatus(session, new KYCManager.SessionStatusCallback() {
            @Override
            public void success(KYCSession session, KYCSession.ExtendedSessionStatus status) {
                // Extract credentials required for verification
                KYCCredentials credentials = status.getCredentials();
                if (credentials != null) {
                    // You can extract pre-ready intent instead of constructing it yourself
                    Intent intent = credentials.getIntent(appContext);
                    // Now you can launch the verification
                    startActivity(intent);
                } else {
                    // The chosen verifier does not require any credentials.
                    //You just have to wait until verification is done
                }

            }

            @Override
            public void error(KYCError error) {
                // Failed to obtain session status
            }
        });
    }

    @Override
    public void error(KYCError error) {
        // Failed to start preliminary verification
    }
});

You should invoke the verification process subsequently for each verifier mentioned in KYCSessionParams at the session creation.

Step 11. Obtain your keys

Once the documents verification is successful 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.