Version. 1.0.0
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
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.
In order to incorporate this SDK into your app, see Basic configuration
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
QR SDK
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
Adding new enum value to input or output
Adding new field in input or output model
This section describes basic information about QR SDK setup and available methods.
Facade is entry point to communication with QR SDK.
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).
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 < > .
The minSdkVersion must be at least 23 (Android 6.0).
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/"
}
}
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:
2. Technical overview
2.1. Basic information
2.1.1 Facade
2.1.2 Multiple facade types
2.1.3 Method structure
2.2 Basic configuration
2.2.1 Min SDK Version
2.2.2 Artifactory
2.2.3 SDKs version
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'
}
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
Available configuration methods:
QrCoroutineApi.init()
QrStdApi.init()
No input parameters.
QrStdApi
fun init() {
QrStdApi.init()
}
QrCoroutineApi
fun init() {
QrCoroutineApi.init()
}
QrReceiverModel
2.2.1 Source code obfuscation and optimization
2.3 QR SDK Setup
2.3.1 Input
2.3.2 Sample
2.4 Common models
Type Description
Personal Receiver data required for transaction purposes.
Merchant Transaction data containing amount and currency
QrReceiverModel.Personal
Parameter Type Description
globallyUniqueIdentifier String Issuer’s global unique identifier. Application Identifier (AID) or UUID or
REVERSE DOMAIN NAME .
walletCard QrPersonalReceiverWalletCardModel Identifiers for user and his card stored in MobileDC database.
phoneNumber String Phone number with prefix.
deviceId String MobileDC user’s device ID.. A 64 characters length - hexed value .
city String City.
countryCode String Country code ISO 3166-1 alpha-3 .
name String Receiver's name.
categoryCode String Receiver's category code ISO 18245
QrReceiverModel.Merchant
Parameter Type Description
accountUri String Merchant identifier MasterCard with tag 04 or 05.
city String City.
countryCode String Country Code. ISO 3166-1 alpha-3 .
name String Receiver's name.
categoryCode String Receiver's category code ISO 18245
QrPersonalReceiverWalletCardModel
Parameter Type Description
userId Long User identifier in MobileDC database.
cardId Long Associated with user card identifier in MobileDC database.
QrTransactionValueModel
Parameter Type Description
amount Long Amount in minor currency unit.
currency String Currency from which exchange rate should be calculated 3-letters ISO 4217 alpha-3 code.
isDynamic Boolean
Flag determines payment sender’s ability to change the amount that will be sent. If the payment sender can
specify the amount this dynamic property should be set to false. True indicates that the amount is defined by the
payment receiver and cannot be changed later.
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
2.5 Error handling
Exception Parameters Description
RequestCancelled Request was canceled.
UnknownErrorStatus status: String An unknown error occurred.
ValidationError
Parameter Type Description
fieldName String Name of field which not passed validation.
errorMessages List<String> List of error messages.
Specific types of exceptions are described for each method.
Asynchronous. Offline.
This method allows user a conversion from a QR data compliant with the EMV standard to a receiver and transaction data models.
ParseQrCodeData
Parameter Type Description
qr String QR data compliant with the EMV standard.
Success callback with ParseQrCodeResult model.
ParseQrCodeResult
Parameter Type Description
receiver QrReceiverModel Receiver data required for transaction purposes.
transactionValue QrTransactionValueModel Transaction data containing amount and currency
Failure callback with throwable.
QrSdkException
Exception Parameters Description
CountryCode2To3LettersParseError countryCode:String,
message:String?
Couldn't find 3 letters country code equivalent of given 2 letters country
code ( ISO 3166-1 standard)
CurrencyParseNumericCodeError numericCode:String,
message:String?
Couldn't find alpha numeric currency value for given numeric code ( ISO
4217 standard)
Standard Callback
3 QR service
3.1 parseQrCode
3.1.1 Input
3.1.2 Output
3.1.2.1 Success
3.1.2.2 Failure
3.1.3 Sample
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)
Asynchronous. Offline.
This method allows user a conversion from a receiver and transaction data models to a QR data compliant with the EMV standard.
GenerateQrCodeData
Parameter Type Description
receiver QrReceiverModel Receiver data required for transaction purposes.
transactionValue QrTransactionValueModel Transaction data containing amount and currency
Success callback with AddWalletReceiverResult model.
GenerateQrCodeResult
Parameter Type Description
qrCode String QR data compliant with the EMV standard
Failure callback with throwable.
QrSdkException
Exception Parameters Description
CountryCode3To2LettersParseError countryCode:String,
message:String?
Couldn't find 2 letters country code equivalent of given 3 letters
country code ( ISO 3166-1 standard)
CurrencyParseAlphanumericCodeError alphanumericCode:String,
message:String?
Couldn't find numeric currency value for alphanumeric code ( ISO
4217 standard)
3.2 generateQrCode
3.2.1 Input
3.2.2 Output
3.2.2.1 Success
3.2.2.2 Failure
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)
Created.
4. DOCUMENT CHANGELOG
4.1. Version 1.0.0
