QR SDK

Version. 1.0.6

Table of Contents

1. QR SDK Overview

   1.1. What is QR SDK?

   1.2. How QR SDK works?

   1.3. Versioning and backward compatibility

2. Technical overview

   2.1. Basic information

   2.2. Basic configuration

   2.3. QR SDK Setup

   2.4. Common models

   2.5. Error handling

3. QR service

   3.1. addExternalReceiver

   3.2. addWalletReceiver

4. DOCUMENT CHANGELOG

   4.1 Version 1.0.0

   4.2 Version 1.0.3

   4.3 Version 1.0.4

   4.4 Version 1.0.5

   4.5 Version 1.0.6

1. QR SDK Overview

1.1. What is QR SDK?

The P2P QR SDK is a module dedicated for parsing transaction data into EMV QR code standard and conversely. Transaction data from this SDK can be further used in other system's components (such as Transfers SDK) for processing transactions.

1.2. How QR SDK works?

In order to incorporate this SDK into your app, see Basic configuration

1.3. Versioning and backward compatibility

SDK is based on semantic versioning. For example: 1.0.0 ( MAJOR.MINOR.PATCH )

• Major version compatibility-breaking changes in SDK public APIs. It is mandatory to update application code, to use SDK, when this is incremented.
• Minor version tracks new, not compatibility-breaking changes in public API of SDK. It is optional to update application code, when this digit is inceremented.
• Patch version tracks internal changes in SDK. No updates in application code are necessary to update to version, which has this number inceremented.

Changes not breaking compatibility:

• Adding new optional interface to SDK setup
• Adding new method to any domain
• Adding new enum value to input or output
• Adding new field in input or output model

2. Technical overview

This section describes basic information about QR SDK setup and available methods.

2.1. Basic information

2.1.1 Facade

Facade is entry point to communication with QR SDK.

2.1.2 Multiple facade types

P2P QR SDK provides two public API's with same functionalities, the API's are:

• QrCoroutineService for projects which uses Kotlin programming language and Coroutines.
• QrStdService for projects which uses Kotlin or Java programming language and standard Callback.

The difference between the API's is a way of providing data to SDK methods and getting the results from them. Input and output as an data models are the same. This documentation presents I/O types in a Kotlin way as it's easier to mark nullable fields (as question mark).

2.1.3 Method structure

Every method description has same structure.

Execution type:

• Asynchronous - Operation could take more time and method is called on thread different than main. The result of execution is provided in callback (described below).
• Synchronous - Result of operation is provided as method return type.

Method type:

• Online - Operation requires Internet connection.
• Offline - Operation can be called without Internet connection.

Input Input parameters with name, type and description.

Output Result delivered by standard Callback with data or result is suspended until the Coroutine completes <>.

2.2 Basic configuration

2.2.1 Min SDK Version

The minSdkVersion must be at least 23 (Android 6.0).

2.2.2 Artifactory

SDK is available on Verestro maven repository and can be configured in project using Gradle build system.

Username and password is provided by Verestro.

repositories{
    maven {
        credentials {
            username "<enter_username_here>"
            password "<enter_password_here>"
        }
        url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
    }
}

2.2.3 SDKs version

QR SDK is available in two versions: debug and release. The difference between version is debug allows to use application with debugger connected. Debug version is ended with appendix "-debug" in version name. Samples below:

For release version, used on production environment in application uploaded to Google Play:

dependencies{
    implementation 'com.verestro.module:qr:{version}'
}

For debugging purposes:

dependencies{
    implementation 'com.verestro.module:qr:{version}-debug'
}

2.2.1 Source code obfuscation and optimization

As SDK is written in Kotlin language we recommend to add following code to gradle configuration:

android {
    ...
    kotlinOptions {
        freeCompilerArgs = [
                '-Xno-param-assertions',
                '-Xno-call-assertions',
                '-Xno-receiver-assertions'
        ]
    }

    packagingOptions {
        exclude '/kotlin_metadata/**'
    }
    ...
}

Then use newest tools for code shrinking, optimization and obfuscation from Google by enabling R8 instead Proguard in gradle.properties file:

android.enableR8=true

2.3 QR SDK Setup

Available configuration methods:

• QrCoroutineApi.init()
• QrStdApi.init()

2.3.1 Input

No input parameters.

2.3.2 Sample

QrStdApi

fun init() {
    QrStdApi.init()
}

QrCoroutineApi

fun init() {
    QrCoroutineApi.init()
}

2.4 Common models

QrReceiverModel

QrReceiverModel.Personal

QrReceiverModel.Merchant

QrPersonalReceiverWalletCardModel

QrTransactionValueModel

2.5 Error handling

SDK returns errors by QRSdkException, which could be catched by application and shown on UI with detailed message. Table below describes general exception types.

QRSdkException

ValidationError

Specific types of exceptions are described for each method.

3 QR service

3.1 parseQrCode

Asynchronous. Offline.

This method allows user a conversion from a QR data compliant with the EMV standard to a receiver and transaction data models.

3.1.1 Input

ParseQrCodeData

3.1.2 Output

3.1.2.1 Success

Success callback with ParseQrCodeResult model.

ParseQrCodeResult

3.1.2.2 Failure

Failure callback with throwable.

QrSdkException

3.1.3 Sample

Standard Callback

fun parseQrCode(parseQrCodeData: ParseQrCodeData) {
    QrStdApi
        .qrStdService
        .parseQrCode(
            parseQrCodeData = parseQrCodeData,
            callback = object : ApiCallback<ParseQrCodeResult> {
                override fun onSuccess(response: ParseQrCodeResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun parseQrCode(parseQrCodeData: ParseQrCodeData): ParseQrCodeResult =
    QrCoroutineApi
        .qrCoroutineService
        .parseQrCode(parseQrCodeData = parseQrCodeData)

3.2 generateQrCode

Asynchronous. Offline.

This method allows user a conversion from a receiver and transaction data models to a QR data compliant with the EMV standard.

3.2.1 Input

GenerateQrCodeData

3.2.2 Output

3.2.2.1 Success

Success callback with AddWalletReceiverResult model.

GenerateQrCodeResult

3.2.2.2 Failure

Failure callback with throwable.

QrSdkException

3.2.3 Sample

Standard Callback

fun generateQrCode(generateQrCodeData: GenerateQrCodeData) {
    QrStdApi
        .qrStdService
        .generateQrCode(
            generateQrCodeData = generateQrCodeData,
            callback = object : ApiCallback<GenerateQrCodeResult> {
                override fun onSuccess(response: GenerateQrCodeResult) {
                    // handle success
                }
                override fun onFailure(error: Throwable) {
                    // handle error
                }
            }
        )
}

Kotlin Coroutines

suspend fun generateQrCode(generateQrCodeData: GenerateQrCodeData): GenerateQrCodeResult =
    QrCoroutineApi
        .qrCoroutineService
        .generateQrCode(generateQrCodeData = generateQrCodeData)

4. DOCUMENT CHANGELOG

4.1. Version 1.0.0

• Created.

4.2. Version 1.0.3

• Disables obfuscation for debug.

4.3. Version 1.0.4

• Updated koin to version 3.5.3.
• Updated java to 17.
• Updated compile and target android version.

4.4. Version 1.0.5

• Sets correct fraction digits for specific currency code.

4.5 Version 1.0.6

• Improved SDKs deploying.