Technical documentation MDC SDK

class App : Application() {

    override fun onCreate() {
        super.onCreate()
        if (isIsolatedProcess()) {
			return
        }

		//call all required methods
    }

}

Asynchronous. Online.

Adds new address with given parameters.

Success with Long value as addressId / failure callback.

fun addAdress(addAddress: AddAddress) {
    mobileDcApi
        .addressesService
        .addAddress(addAddress, { addressId ->
            // Address added
        }, {
            // Something went wrong
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Gets all addresses for the current user.

No input parameters.

Success callback with list of user addresses.

fun getAll() {
    mobileDcApi
        .addressesService
        .getAll({
            // List of addresses
        }, { throwable ->
            // Something went wrong
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Update address for the current id.

Success / Failure callback.

private fun updateAddress(updateAddress: UpdateAddress) {

    mobileDcApi
        .addressesService
        .updateAddress(updateAddress, {
            //address updated successfully
        }, { throwable ->
            // Something went wrong, maybe user data was incorrect
            // Check exceptions described in Error handling chapter
        })
}

Method for delete user address with given address id.

Success callback/ Failure callback.

fun deleteAddress(addressId: Long) {
    mobileDcApi
        .addressesService
        .deleteAddress(addressId, {
            //Success, address deleted
        }, {
            //Something went wrong
            //Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Creates new user wallet account if not exist with IBAN in Mobile DC backend.

When user already exist calling this method will be also finished with success.

Success callback. Called when new user is created or already exist with passed input data.

Failure callback.

class SignedAccountInfo {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("userId", "externalUserId")
            .claim("iban", "IN15HIND23467433866365")
            .claim("countryCode", "IND")
            .build()

        val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey)
        // ...
    }
}

private fun addUserWithIban() {

    val signedAccountInfo: String = getSignedAccountInfo()

    mobileDcApi
        .userService
        .addUserWithIban(signedAccountInfo, { ibanId ->
            //user already exist or was added with selected iban
        }, {
            //failure, check exceptions, maybe signedAccountInfo is wrong?
        })
}

Asynchronous. Online.

Update user wallet account with given parameters.

Most of it's fields are optional. Fields requirement depends on product integration process.

Success / failure callback.

fun updateUser(updateUser: UpdateUser) {
    mobileDcApi
        .userService
        .updateUser(updateUser, {
            //user updated successfully
        }, { throwable ->
            // Something went wrong, maybe user data was incorrect
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Get data of current user.

No input parameters.

Success callback with User model.

Failure callback.

fun getUser() {
    mobileDcApi.userService
        .getUser({ user ->
            // Getting user went successfully
			showUser(user)
        }, { throwable ->
            // Something went wrong
            // Check exceptions described in error handling chapter
        })
}

Asynchronous. Online.

Activate user account by finalizing registration process with SMS code sent to the phone number provided during new user wallet account creation.

Success / failure callback.

fun finalizeUserRegistration(otp: CharArray) {
    mobileDcApi
        .userService
        .finalizeUserRegistration(otp, { 
           // User wallet account was successfully activated
        }, { throwable ->
            // Something went wrong. 
            // Check exceptions described in error handling chapter
        })
}

Asynchronous. Offline.

Authenticates user locally after providing correct pin.

Provide method to verify user without connection into Mobile DC.

Success / failure callback.

fun authenticateByPin(mobileDcApi: MobileDcApiKotlin, pin: CharArray) {
    //Wallet Pin created during user registration process associated with user account
    mobileDcApi
        .userService
        .authenticateByPin(pin, {
            //user is verified
        }, { throwable ->
            // Something went wrong, maybe pin is incorrect? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Offline.

Method that check if biometric authentication is enabled.

Note: Authentication could be disabled by system when Android Keystore state changed (eg. User disabled screen lock or add new authentication method).

State of biometrics should be checked before every biometrics authentication usage.

Success callback with status of authentication or failure callback.

fun isBiometricAuthenticationEnabled() {
    mobileDcApi
            .userService
            .isBiometricAuthenticationEnabled({ isBiometricEnabled ->
                if (isBiometricEnabled) {
                    // Biometric authentication is enabled, process startBiometricAuthentication method
                } else {
                    // Biometric authentication is disabled, use enableBiometricAuthentication
                }
            }, { throwable ->
                // Something went wrong
                // Check exceptions
            })
}

Asynchronous. Online.

Method for enabling device level authentication and updating biometric public key.

To perform this method device must have set PIN, pattern or password. To check these use KeyguardManager.

Success / failure callback.

Asynchronous. Offline.

Disable possibility to use biometric authentication.

No input parameters.

Success / failure callback.

fun disableBiometricAuthentication() {
    mobileDcApi
        .userService
        .disableBiometricAuthentication({
            //Biometric authentication cannot be no longer used. Use enableBiometricAuthentication to enable it again
        }, {
            //Something went wrong
            //Check exceptions described in Error handling chapter            
        })
}

Asynchronous. Online.

Method for enabling device level authentication and updating biometric public key with Wallet Pin.

To perform this method device must have set PIN, pattern or password. To check these use KeyguardManager.

Success / failure callback.

//KeyguardManager example
keyguardManager = context.getSystemService(KEYGUARD_SERVICE)

fun isDeviceSecure(): Boolean {
    return keyguardManager.isKeyguardSecure
}
//if isDeviceSecure return true device is safe and enableBiometricAuthenticationWithWalletPin method can be performed

fun enableBiometricAuthenticationWithWalletPin(walletPin: CharArray, biometricAuthType : BiometricAuthType) {
    mobileDcApi.userService
        		.enableBiometricAuthenticationWithWalletPin(walletPin, biometricAuthType,
					{
            			// Biometric authentication is enabled. Read startBiometricAuthentication description to authenticate user.
        			},
 					{ throwable ->
            			// Something went wrong
            			// Check exceptions described in Error handling chapter
        			}
				)
}

Asynchronous. Offline.

Create CryptoObject for biometric authentication.

Depends on usage of androidx/android support library an different CryptoObject can be provided by Android SDK.

Success callback.

Failure callback.

  mobileDcApi
            .userService
            .startBiometricAuthentication(CryptoObjectType.BIOMETRIC_PROMPT_ANDROIDX)
            {
             	// Creating Object for biometric authentication is done
            }, {
				// Something went wrong maybe: private key is not created or not authenticated
				// Check exceptions 
            }

fun wrapToBiometricAuthenticationResult(biometricAuthenticationData: BiometricAuthenticationData): BiometricAuthenticationResult {
   
	val cryptoObject = biometricAuthenticationData.cryptoObject as CryptoObject //Casting to androidx/support version of CryptoObject

    return BiometricAuthenticationResult(
        cryptoObject.signature,
        cryptoObject.cipher,
		cryptoObject.mac
	)
}

customViewForBiometricAuthentication = BiometricPrompt


fun startAuthentication(){
	mobileDcApi
            .userService
            .startBiometricAuthentication(CryptoObjectType.BIOMETRIC_PROMPT_ANDROIDX)
            { biometricAuthenticationData ->
             	verifyAuthentication(wrapToBiometricAuthenticationResult(biometricAuthenticationData))
            }, {
				// Something went wrong maybe: private key is not created or not authenticated
				// Check exceptions 
            }
}

fun verifyAuthentication(biometricAuthenticationResult:BiometricAuthenticationResult){
	 mobileDcApi
            .userService
            .authenticateWithBiometric(biometricAuthenticationResult)
        {
            // success authentication is done
        },
        { throwable ->
            // Something went wrong maybe private key is not authenticated?
            // Check exceptions
             
        }
    )
}


 val biometricPrompt: BiometricPrompt = BiometricPrompt(activityFragment, executor,
    object : BiometricPrompt.AuthenticationCallback() {
        override fun onAuthenticationError(
            errorCode: Int,
            errString: CharSequence
        ) {
            super.onAuthenticationError(errorCode, errString)
            Toast.makeText(context,"Authentication error", Toast.LENGTH_SHORT).show()
        }

        override fun onAuthenticationSucceeded(
            result: BiometricPrompt.AuthenticationResult
        ) {
            super.onAuthenticationSucceeded(result)
            Toast.makeText(
                context,
                "Authentication succeeded!", Toast.LENGTH_SHORT).show()

            startAuthentication()
        }


        override fun onAuthenticationFailed() {
            super.onAuthenticationFailed()
            Toast.makeText(
                context, "Authentication failed", Toast.LENGTH_SHORT).show()
        }
    })

Asynchronous. Offline.

Starts system biometric authentication.

After invoke system waits for a biometric authentication.

Method can throw BiometricVerificationException.

Success callback.

Failure callback.

fun authenticateWithBiometrics(biometricAuthenticationResult: BiometricAuthenticationResult) {
    mobileDcApi
        .userService
        .authenticateWithBiometric(biometricAuthenticationResult, { authorizationResult ->
            // authentication with biometric is finished with success, use authorizationResult to loginBySignature
        }, { throwable ->
            // Something went wrong, was authentication passed?
            // Check exceptions
        })
}

Asynchronous. Online.

Authenticates user in Mobile DC backend after providing trusted identity.

Creates / refreshes user session.

Success / failure callback.

class TrustedIdentity {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("userId", "externalUserId")
            .build();

        val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey);
        // ...
    }
}

fun loginByTrustedIdentity(mobileDcApi: MobileDcApiKotlin, trustedIdentity: String) {
    //where trustedIdentity should be generated by server and passed to mobile application
    mobileDcApi
        .userService
        .loginByTrustedIdentity(trustedIdentity, {
            //user is logged
        }, { throwable ->
            // Something went wrong, maybe trustedIdentity is wrong? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Authenticates user in Mobile DC backend after providing correct pin.

Creates / refreshes user session.

Success / failure callback.

fun loginByPin(mobileDcApi: MobileDcApiKotlin, pin: CharArray) {
    //Wallet Pin created during user registration process associated with user account
    mobileDcApi
        .userService
        .loginByPin(pin, {
            //user is logged
        }, { throwable ->
            // Something went wrong, maybe pin is incorrect? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Authenticates user in Mobile DC backend after local biometric authentication (startBiometricAuthentication and authenticateWithBiometric methods).

Creates / refreshes user session.

AuthorizationResult provided in success callback from authenticateWithBiometric method.

Success / failure callback.

fun loginBySignature(authorizationResult: AuthorizationResult) {
    mobileDcApi
            .userService
            .loginBySignature(authorizationResult, {
                // User is authenticated
            }, { throwable ->
                // Something went wrong
                // Check exceptions
            })
}

Asynchronous. Online.

Changes user's wallet PIN with given parameters.

Success / failure callback.

fun changeWalletPin(walletPin:CharArray, newWalletPin:CharArray) {
    mobileDcApi
        .userService
        .changeWalletPin(walletPin, newWalletPin, {
            //user's Wallet PIN is changed
        }, { throwable ->
            // Something went wrong, maybe current PIN is wrong? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Resets wallet pin with given parameters.

Success / failure callback.

fun resetWalletPin(userLogin: CharArray, loginType: UserType, newPin: CharArray, password: CharArray) {
    mobileDcApi
        .userService
        .resetWalletPin(userLogin, loginType, newPin, password, {
            //user's pin is changed
        }, { throwable ->
            // Something went wrong, maybe password is wrong? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Changes user's password with given parameters.

Success / failure callback.

fun changePassword(password:CharArray, newPassword:CharArray) {
    mobileDcApi
        .userService
        .changePassword(password, newPassword, {
            //user's password is changed
        }, { throwable ->
            // Something went wrong, maybe current password is wrong? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Reset user's password with given parameters.

Success callback with key and optionally with LimitedResourceInfo.

Failure callback.

fun initializeResetUserPassword(userLoginType: UserType, userLogin: CharArray) {
    mobileDcApi
        .userService
        .initializeResetUserPassword(userLoginType, userLogin, { response ->
            val key = response // key is necessary to call the finalizeResetUserPassword method. 
        }, { throwable ->
            // Something went wrong. 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Reset user's password with given parameters.

Success callback with key.

Failure callback.

fun initializeResetUserPassword(initializeResetUserPassword: InitializeResetUserPassword) {
    mobileDcApi
        .userService
        .initializeResetUserPassword(initializeResetUserPassword, { response ->
            val key = response.key // key is necessary to call the finalizeResetUserPassword method. 
			val limitedResourceInfo = response.limitedResourceInfo // limitedResourceInfo contains information about 
            // rate limited APIs, all parameters are nullable
        }, { throwable ->
            // Something went wrong. 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Set new user password with given parameters.

Success / failure callback.

fun finalizeResetUserPassword(userLoginType: UserType, userLogin: CharArray, 
	key: CharArray, otp: CharArray, newPassword: CharArray) {
    mobileDcApi
        .userService
        .finalizeResetUserPassword(userLoginType, userLogin, key, otp, newPassword, { 
           // The OTP has been sent
        }, { throwable ->
            // Something went wrong. 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Change the user's email address to a new one.
After confirming the change of the email, the one-time password ( OTP) will be sent to this address.

Success callback with key.

Failure callback.

fun initializeEmailUpdate(email: CharArray) {
    mobileDcApi
        .userService
        .initializeEmailUpdate(email, { response ->
            val key = response // key is necessary to call the finalizeChangeEmail method.
        }, { throwable ->
            // Something went wrong.
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Set new user email.

Success / failure callback.

fun finalizeEmailUpdate(key: CharArray, otp: CharArray) {
    mobileDcApi
        .userService
        .finalizeEmailUpdate( key, otp, { 
           // The user's email has been changed
        }, { throwable ->
            // Something went wrong. 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Method for resend OTP.

Success / failure callback.

fun resendOtp(userLoginType: UserType, userLogin: CharArray) {
    mobileDcApi
        .userService
        .resendOtp( userLoginType, userLogin, { 
           // OTP has been sent
        }, { throwable ->
            // Something went wrong. 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Offline.

Cancels user session.

No input parameters.

Success / failure callback.

fun logout() {
    mobileDcApi
        .userService
        .logout({
            //User session has been canceled. Refresh user session to restore it.
        }, {
            //Something went wrong
            //Check exceptions described in Error handling chapter            
        })
}

Asynchronous. Online.

Delete data of current user and reset SDK state when success. The user can be hard or soft deleted depending on project’s configuration.
Hard - method used to delete user with deleting data connected to the user (eg. card).
Soft - method used to delete user without deleting data connected to the user (eg. card)

Usage of this method causes clearing all data related to selected user.

No input parameters.

Success/failure callback.

fun deleteUser() {
    mobileDcApi
        .userService
        .deleteUser({
            //user is deleted, all data related to user, device cards etc is cleared. SDK is restarted.
        }, { throwable ->
            // Something went wrong
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Adds new payment card with given parameters.

Success callback with cardId.

fun addCard(addCard: AddCard){
    mobileDcApi
        .cardsService
        .addCard(addCard, { cardId ->
            // Card added
        }, { throwable ->
            // Something went wrong, maybe any field is wrong? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Adds new payment card with given parameters.

Success callback with cardId.

fun addCard(cardNumber:CharArray, expirationDate:CharArray, description:CharArray, 
	firstName:CharArray, lastName:CharArray){
    	mobileDcApi
        	.cardsService
        	.addCard(cardNumber, expirationDate, description, firstName, lastName, { cardId ->
           	 // Card added
        	}, { throwable ->
          	  // Something went wrong, maybe any field is wrong? 
           	 // Check exceptions described in Error handling chapter
       	 })
}

Asynchronous. Online.

Provides user cards from Mobile DC backend.

No input parameters.

Success callback with list of user cards.

Failure callback.

fun getCards() {
    mobileDcApi
        .cardsService
        .getAll({ cards ->
            showCardList(cards)
        }, {
            // Something went wrong
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Delete card with given card id.

Success / failure callback.

fun deleteCard(cardId: Long) {
    mobileDcApi
        .cardsService
        .deleteCard(cardId, {
            //Success
        }, {
            //Something went wrong
            //Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Card verification- initialize 3D Secure. Provides the data needed for the 3D Secure verification process.

Success callback with Initialize3dsResult.

fun initialize3ds(mobileDcApi: MobileDcApiKotlin, cardId: Long) {
        mobileDcApi
                .cardsService
                .initialize3ds(cardId, { result ->
                    val paymentId = result.paymentId
                    val pageContent = result.pageContent

                    // Check is pageContent not null
                    if (pageContent != null) {
                        // Necessary convert from CharArray to ByteArray
                        val pageContentToByteArray = pageContent.toByteArray()
                        openWebView(paymentId, pageContentToByteArray)
                    } else {
                        // Card verification error
                    }
                }, { throwable ->
                    // Something went wrong, maybe cardId is invalid?
                    // Check exceptions described in Error handling chapter
                })

    }

    fun openWebView(paymentId: CharArray, pageContent: ByteArray) {
        //Bind your webView
        val myWebView = findViewById<WebView>(R.id.myWebView)

        //JavaScript is disabled in a WebView by default. You can enable it through the WebSettings
        //attached to your WebView. You can retrieve WebSettings with getSettings(), then enable JavaScript 
        //with setJavaScriptEnabled().
        val webSettings: WebSettings = myWebView.getSettings()
        webSettings.javaScriptEnabled = true

        //Necessary bind this class to the JavaScript that runs in your WebView with addJavascriptInterface() 
        //and name the interface Android.
        myWebView.addJavascriptInterface(WebAppInterface(), "Android")

        // Decode pageContent from initialize3ds response
        val viewPageContent = String(Base64.decode(pageContent, Base64.DEFAULT))
        // Load page in vebWiew
        myWebView.loadData(viewPageContent, "text/html; charset=UTF-8", "utf-8")
    }

//To bind a new interface between your JavaScript and Android code, call addJavascriptInterface(),
//passing it a class instance to bind to your JavaScript and an interface name that your JavaScript 
//can call to access the class, like below example

    class WebAppInterface {
        // Get the pares parameter from the web page
        @JavascriptInterface
       	fun setData(pares: String?) {
            // onPares interface method provides the pares parameter after interaction with webView. 
            //Parameter pares is needed to perform finalize3ds
            // Necessary convert from String to CharArray
            val paresToCharArray = pares?.toCharArray()
            // close webView
            // Then you need to properly handle the parameter pares to be able to call finalize3ds
            //with the parameter pares and paymentId.
        }
    }

Asynchronous. Online.

Card verification - finalize 3D Secure. Verifies the payment card by the 3D Secure.

Success callback with Finalize3dsResult.

fun finalize3ds(mobileDcApi: MobileDcApiKotlin, cardId: Long, cvc: CharArray, pares: CharArray, 
	paymentId: CharArray) {
    	mobileDcApi
        	    .cardsService
            	.finalize3ds(cardId, cvc, pares, paymentId, { result ->
                	val amountValidation = result.amountValidation
                	val cavv = result.cavv
           		 }, { throwable ->
            	    // Something went wrong, maybe any field is invalid?
                	// Check exceptions described in Error handling chapter
            })
}

Asynchronous. Online.

Card verification - initialize 3D Secure. Provides the data needed for the 3D Secure verification process.

Success callback with Initialize3DSv2Result

fun initialize3DSv2(mobileDcApi : MobileDcApiKotlin){
    mobileDcApi
        .cardsService
        .initialize3DSv2(initialize3DSv2, { initialize3DSv2Result ->
            when (initialize3DSv2Result.status) {
                "SUCCESS" -> {
                    //3DS success, no more action is required
                }

                "CHALLENGE_REQUIRED" -> {
                    showWebView(initialize3DSv2Result.challengeHtmlFormBase64, challengeUrl)
                }

                else -> //failure
            }
        }, { throwable ->
        	// Something went wrong
            // Check exceptions described in Error handling chapter
        })
}


//WebView implementation

fun showWebView(challengeHtmlFormBase64: String, challengeUrl : String) {

    val viewPageContent = String(Base64.decode(challengeHtmlFormBase64, Base64.DEFAULT))
    val webViewUrlDetectionClient = WebViewUrlDetectionClient(challengeUrl)

    with(webView) {
        webViewClient = webViewUrlDetectionClient
		settings.javaScriptEnabled = true
		visibility = View.VISIBLE
        loadData(
            viewPageContent,
            "text/html; charset=UTF-8",
            "utf-8"
        )
    }
}


//sample WebViewClient implementation for handing redirect on challangeUrl
class WebViewUrlDetectionClient(private val challengeUrl: String): WebViewClient() {
    override fun onPageStarted(view: WebView, url: String, favicon: Bitmap?) {
        super.onPageStarted(view, url, favicon)
        if (url.equals(challengeUrl, true)) {
            //call finalize3DSv2(cardId, initialize3DSv2Result.authenticationId)
        }
    }
}

Asynchronous. Online.

Card verification - finalize 3D Secure. Verifies the payment card by the 3D Secure.

Success callback/ Failure callback.

fun finalize3DS(mobileDcApi : MobileDcApiKotlin) {

    val finalize3DSv2Input = Finalize3DSv2(cardId, authenticationId)

    mobileDcApi
        .cardsService
        .finalize3DSv2(
            finalize3DSv2Input, {
                //3DS finished with success
            }, { throwable ->
            	// Something went wrong
                // Check exceptions described in Error handling chapter
            }
        )
}

Method for updating payment card data.

Success callback/ Failure callback.

fun updateCard(cardId: Long, description: CharArray?, isDefault: Boolean?, firstName: CharArray?, lastName: CharArray?){
	val updateCard = UpdateCard(cardId).apply {
		this.description = description
		this.firstName = firstName
		this.lastName = lastName
		this.isDefault = isDefault
	}

    mobileDcApi
        .cardsService
        .updateCard(updateCard) {
            // Card updated
        }, { throwable ->
            // Something went wrong, maybe any field is wrong? 
            // Check exceptions described in Error handling chapter
        })
}

Asynchronous. Online.

Card verification - verify card after 3ds.

Success callback/ Failure callback.

fun verifyCard(cardId: Long, amount: CharArray?, amountValidation: Boolean) {
    val verifyCard: VerifyCard = VerifyCard(cardId).apply {
        this.amount = if (amountValidation) amount else null
    }
    mobileDcApi
        .cardsService
        .verifyCard(verifyCard, {
            //handle success
        }, { throwable ->
            //handle failure
        })
}

Asynchronous. Online.

Pairs device using given password and user identifier.

Deprecated, use pairByPassword(PairByPassword)

Success / failure callback.

fun pairByPassword(
    email: CharArray, //user email
    password: CharArray, //user password
    fcmToken: CharArray  // saved FCM token from Firebase service
) {

    mobileDcApi
        .deviceService
        .pairByPassword(UserType.EMAIL, email, password, fcmToken,
            {
                //device is paired, now you can use this device to manage Mobile DC resources
            },
            { throwable ->
                // Something went wrong, maybe any field is wrong?
                // Check exceptions described in Error handling chapter
            }
        )
}

Asynchronous. Online.

Pairs device using given password and user identifier.

Success / failure callback.

val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken =
    CloudMessagingRegistrationToken(
        type: CloudMessagingType, //messaging token type
        token: String // saved cloud messaging token
    )
 
val pairByPassword: PairByPassword =
    PairByPassword(
        userLoginType: UserType, //user identifier type
        userLogin: CharArray, //user identifier
        password: CharArray, //user password
        cloudMessagingRegistrationToken: CloudMessagingRegistrationToken, //cloud messaging registration token information
        biometricAuthType: BiometricAuthType?, //Optional biometric authentication type
        externalDeviceId: String? //Optional external device id
)
 
fun pairByPassword(pairByPassword: PairByPassword) {
    mobileDcApi
        .deviceService
        .pairByPassword(pairByPassword,
            {
                //device is paired, now you can use this device to manage Mobile DC resources
            },
            { throwable ->
                // Something went wrong, maybe any field is wrong?
                // Check exceptions described in Error handling chapter
            }
        )
}

Asynchronous. Online.

Binds device to user in Mobile DC backend with Trusted Identity genetated by client server.

Deprecated, use pairByTrustedIdentity(PairByTrustedIdentity).

Success / failure callback.

class TrustedIdentity {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("userId", "externalUserId")
            .build();

        val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey);
        // ...
    }
}

fun pairDeviceByTrustedIdentity(
    mobileDcApi: MobileDcApiKotlin,
    trustedIdentity: String
) {

    val fcmToken = getFcmRegistartionToken() // get saved FCM token from FirebaseMessagingService, or from 
		//FirebaseInsanceId::getToken()

	mobileDcApi
        .deviceService
        .pairByTrustedIdentity(
            trustedIdentity,
            fcmToken, {
                //device is paired, now you can use this device to manage Mobile DC resources
            }, { throwable ->
                //some error occured, check exception
            })
}

Asynchronous. Online.

Binds device to user in Mobile DC backend with Trusted Identity genetated by client server.

Success / failure callback.

class TrustedIdentity {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("userId", "externalUserId")
            .build();

        val trustedIdentity = JwtGenerator.generate(claims, certificates, privateKey);
        // ...
    }
}

val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken =
    CloudMessagingRegistrationToken(
        type: CloudMessagingType, //messaging token type
        token: String // saved cloud messaging token
    )
 
val pairByTrustedIdentity: PairByTrustedIdentity =
    PairByTrustedIdentity(
        trustedIdentity: String, //JSON Web Token containing registration data
        cloudMessagingRegistrationToken: CloudMessagingRegistrationToken, //cloud messaging registration token information
        externalDeviceId: String? //Optional external device id
)
 
fun pairByTrustedIdentity(pairByTrustedIdentity: PairByTrustedIdentity) {
    mobileDcApi
        .deviceService
        .pairByTrustedIdentity(pairByTrustedIdentity,
            {
                //device is paired, now you can use this device to manage Mobile DC resources
            },
            { throwable ->
                // Something went wrong, maybe any field is wrong?
                // Check exceptions described in Error handling chapter
            }
        )
}

Asynchronous. Online.

Binds device to user in Mobile DC backend using username and password.

Deprecated, use pairByTrustedIdentity(PairByExternalCredentials).

Success / failure callback.

fun pairByExternalCredentials() {

    val username: CharArray = getCharArrayFromInput() //get username provided by user
    val password: CharArray = getCharArrayFromInput() //get password provided by user
    val fcmToken = getFcmToken() // get saved FCM token from Firebase service

    mobileDcApi
        .deviceService
        .pairByExternalCredentials(
            username,
            password,
            fcmToken, {
                //device is paired, now you can use this device to manage Mobile DC resources
            }, { throwable ->
                //some error occured, check exception
            })
}

Asynchronous. Online.

Binds device to user in Mobile DC backend using username and password.

Success / failure callback.

val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken =
    CloudMessagingRegistrationToken(
        type: CloudMessagingType, //messaging token type
        token: String //saved cloud messaging token
    )
 
val pairByExternalCredentials: PairByExternalCredentials = PairByExternalCredentials(
    userName: CharrArray, //username provided by user
    password: CharrArray, //password provided by user
    cloudMessagingRegistratinoToken: CloudMessagingRegistrationToken, //cloud messaging registration token information
    biometricAuthType: BiometricAuthType?, //Optional biometric authentication type
    externalDevice: String? //Optional external device id
)
 
fun pairByExternalCredentials(pairByExternalCredentials: PairByExternalCredentials) {
 
    mobileDcApi
        .deviceService
        .pairByExternalCredentials(pairByExternalCredentials,
            {
                //device is paired, now you can use this device to manage Mobile DC resources
            },
            { throwable ->
                // Something went wrong, maybe any field is wrong?
                // Check exceptions described in Error handling chapter
            }
        )
}

Asynchronous. Offline.

Method allow to check is Device already paired with MDC Backend.

No input parameters.

Success / failure callback.

fun isDevicePaired() {
    mobileDcApi
        .deviceService
        .isDevicePaired()
        {
           // return is device paired state
		},
		{throwable ->  
           // some error occurred, check exception
        }
}

Asynchronous. Online.

Removes all data collected by SDK and binding between user and device in Mobile DC backend.

Pairing device to user can be made by <<pairBy...>> methods.

No input parameters.

Success / failure callback.

fun unPairDevice() {
    
	mobileDcApi
        .deviceService
        .unPairDevice({
            //device is unPaired, SDK cannot be not longer used
            //application can remove all data in context of sDKDefaultBackoffStrategy
            //for use SDK again call pairBy.. method
        }, { throwable ->
            //some error occured, check exception
        })
}

Asynchronous. Offline.

Processes data sent by backend (push notification data).
Application should check Verestro senderId in RemoteMessage object (RemoteMessage::from method) to verify sender. Method can throw InvalidPushException in case of invalid push content passed to it.

Success/failure callback.

//FirebaseMessagingService class from Firebase

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    super.onMessageReceived(remoteMessage)

    val senderId: String? = remoteMessage.from
    val pushData = remoteMessage.data

	//check push source only when push source is Verestro sender Id

    if (isVerestroSenderId(senderId)) {
        mobileDcApi
            .cloudMessagingService
            .process(pushData, {
               //push sent to SDK
            }, {
                //some error
            })

    } else {
        //proceed push from another source different then Verestro
    }
}

getSource (Deprecated in 2.14.6)

Input

Output

Sample

//FirebaseMessagingService class from Firebase

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    super.onMessageReceived(remoteMessage)

    val senderId: String? = remoteMessage.from
    val pushData = remoteMessage.data

	//check push source only when push source is uPaid sender Id

    if (isUpaidSenderId(senderId)) {

		//checking push source and passing to proper uPaid module

        mobileDcApi
            .cloudMessagingService
            .getSource(pushData, { source ->
                when (source) {
                    "UCP" -> processUcpPush(pushData)
                }
            }, {
                //some error
            })

    } else {
        //proceed push from another source
    }
}


private fun processUcpPush(pushData: Map<String, String>) {
    ucpApi
        .cloudMessagingService
        .process(pushData, {
            //push processed in UCP
        }, {
            //some error
        })
}

updateRegistrationToken

Input

CloudMessagingRegistrationToken

Output

Sample

//application should listen for FCM token changes in FirebaseMessagingService::onNewToken method
val cloudMessagingRegistrationToken: CloudMessagingRegistrationToken =
    CloudMessagingRegistrationToken(
        type: CloudMessagingType, //messaging token type
        token: String //saved cloud messaging token
    )

fun updateRegistrationToken(cloudMessagingRegistrationToken: CloudMessagingRegistrationToken) {
    mobileDcApi
        .deviceService
        .isDevicePaired({ isPaired ->
            //token update is required only if device is already paired
            if (isPaired) {
                mobileDcApi
                    .cloudMessagingService
                    .updateRegistrationToken(cloudMessagingRegistrationToken, {
                        //token updated
                    }, {
                        //some error, always retry action until success
                        //when internet or server connection is not reachable try again later
                    })
            }
        }, {
            //some error
        })
}

updateFcmRegistrationToken (deprecated in 2.14.6)

Input

Output

Sample

//application should listen for FCM token changes in FirebaseMessagingService::onNewToken method

private fun updateFcmToken(newFcmToken: String) {
    mobileDcApi
        .deviceService
        .isDevicePaired({ isPaired ->
            //token update is required only if device is already paired
            if (isPaired) {
                mobileDcApi
                    .cloudMessagingService
                    .updateFcmRegistrationToken(newFcmToken, {
                        //token updated
                    }, {
                        //some error, always retry action until success
                        //when internet or server connection is not reachable try again later
                    })
            }
        }, {
            //some error
        })

TransactionsHistory domain

getTransactionsHistory

Input

TransactionsFilters

TransactionsNextPage

Output

TransactionDetails

TransactionsNextPage

Sample

//sample filters
val lastFiveTransactionForCard = TransactionsFilters()
lastFiveTransactionForCard.cardId = "1"
lastFiveTransactionForCard.limit = 5 //when not set default is 10

//another sample filters
val allTransactionsForUser: TransactionsFilters? = null

//another sample filters
val lastThreeTransactionsForUser = TransactionsFilters()
lastThreeTransactionsForUser.limit = 3


//indicates starting point of transaction history
//can be used while loading more history or for paging
var nextPage: TransactionsNextPage? = null


fun getTransactionsHistory(filters: TransactionsFilters?) {
    mobileDcApi
        .transactionsHistoryService
        .getTransactionsHistory(filters, nextPage, { transactionsHistory ->
                val transactions = transactionsHistory.transactions
                showTransactions(transactions)

                //save nextPage for getting next items
                nextPage = transactionsHistory.nextPage
            }, {
                //something went wrong, check exception
            })
}

getTransactionDetails

Input

GetTransactionDetails

Output

GetTransactionDetailsResult

TransactionDetailsAttachment

Sample

//sample entry data
val getTransactionDetails = GetTransactionDetails(1210L)

fun getTransactionDetails(getTransactionDetails: GetTransactionDetails) {
    mobileDcApi
        .transactionsHistoryService
		.getTransactionDetails(getTransactionDetails, { getTransactionDetailsResult ->
                //succes
            }, {
                //something went wrong, check exception
            })
}

storeAttachment

Input

TransactionAttachment

Output

Sample

//sample entry data
val inputStream = contentResolver.openInputStream(uri)
val mimeType = contentResolver.getType(uri)

val transactionAttachment = TransactionAttachment(
    transactionId = 10023L,
    attachment = inputStream,
    mimeType = "image/jpeg"
)


//transaction attachment with optional file name
val transactionAttachment = TransactionAttachment(
    transactionId = 10023L,
    attachment = inputStream,
    mimeType = "image/png"
	fileName = "picture.png"
)


val transactionAttachment = TransactionAttachment(
    transactionId = 10023L,
    attachment = inputStream,
    mimeType = "image/png"
	fileName = "1636362847509"
)


fun storeAttachment(transactionAttachment: TransactionAttachment) {
    mobileDcApi
        .transactionsHistoryService
		.storeAttachment(transactionAttachment, {
                //succes
            }, {
                //something went wrong, check exception
            })
}

generateAttachmentLink

Input

GenerateAttachmentLink

Output

GenerateAttachmentLinkResult

Sample

//sample entry data
val generateAttachmentLink = GenerateAttachmentLink(1210L, "2145")

fun generateAttachmentLink(generateAttachmentLink: GenerateAttachmentLink) {
    mobileDcApi
        .transactionsHistoryService
		.generateAttachmentLink(generateAttachmentLink, { generateAttachmentLinkResult ->
                //succes
            }, {
                //something went wrong, check exception
            })
}


//sample usage when loading link from getTransactionDetails returns 403 HTTP status
fun getTransactionDetails() {
	mobileDcApi
		.transactionHistoryService
		.getTransactionDetails(GetTransactionDetails(transactionId), { getTransactionDetailsResult ->
			loadAttachmentsImages(getTransactionDetailsResult)
		}, {
			//something went wrong, check exception
		}
	)
}


private fun loadAttachmentsImages(getTransactionDetailsResult: GetTransactionDetailsResult) {
	val attachments: List<TransactionDetailsAttachment> = getTransactionDetailsResult.attachments
	attachments.forEach { transactionDetailAttachment ->
		loadImage(getTransactionDetailsResult.id, transactionDetailAttachment)
	}
}


private fun loadImage(attachment: TransactionDetailsAttachment, transactionId: Long) {
    //downloading file may differ in your project. This is only example in synchronised code
    val request = Request.Builder().url(attachment.link).build()
    val response = OkHttpClient().newCall(request).execute()
    val httpCode = response.code()
    when (httpCode) {
        403 -> {
            refreshAttachment(transactionId, attachment.id)
        }
        200 -> {
            //convert stream to bitmap and load into image view
        }
        else -> {
            //check other status
        }
    }
}

private fun refreshAttachment(transactionId: Long, attachmentId: String) {
    mobileDcApi
        .transactionsHistoryService
        .generateAttachmentLink(
            GenerateAttachmentLink(transactionId, attachmentId), { generateAttachmentLinkResult ->
				//sample with Glide library usage
				Glide.with(context).asBitmap()
					.load(generateAttachmentLinkResult.link)
					.into(nextImageView)
      	}, {
           //something went wrong, check exception
        })
}

deleteAttachment

Input

DeleteAttachment object contains following fields.

Output

Sample

val transactionDetailsResult: GetTransactionDetailsResult = GetTransactionDetails(1L)
val deleteAttachment: DeleteAttachment = DeleteAttachment(transactionDetailsResult.id, 
	transactionDetailsResult.transactionDetailsAttachment.id)

private fun deleteAttachment(deleteAttachment) {

    mobileDcApi.transactionService
        .deleteAttachment(deleteAttachment, {
                //Deletion of attachment went succesfully
            }, { throwable ->
                //Something went wrong, check exception with documentation
            })
}

updateSingleTransactionData

Input

UpdateSingleTransactionData

Output

Sample

fun updateSingleTransactionData(updateSingleTransactionData: UpdateSingleTransactionData) {
    mobileDcApi
        .transactionsHistoryService
        .updateSingleTransactionData(updateSingleTransactionData, {
            //Transaction updated successfully
        }, {
            //Something went wrong, check exception with documentation
        })
}

DOCUMENT CHANGELOG

Version 1.0.1

• Created.

Version 2.0.0

• Changed approach to SDK setup.

• Removed methods used to fingerprint authentication.

• Added NetworkConnection exception and CoreSdkException.

• Added new reason codes to existing exceptions.

• New methods in user domain: addUser, loginByTrustedIdentity, changePassword.

• New methods in device domain: pairByPassword, pairByExternalCredentials, unPairDevice.

• New methods in cards domain: getAll.

• New domains: ibans, transactionsHistory.

Version 2.1.0

• Added new methods in User domain (authenticateByPin, loginByPin, changeWalletPin, resetWalletPin, initializeResetUserPassword, finilizeResetUserPassword).
  

• Added new methods in Cards domain (addCard, initialize3ds, finalize3ds, deleteCard).

Version 2.1.1

• Added information about SDK size.

• Added information about SDK ingetration on lower Android API level.

Version 2.2.0

• Improved Mobile DC SDK startup time.

Version 2.3.1

• Added new methods in user domain (isBiometricAuthenticationEnabled, enableBiometricAuthentication, startBiometricAuthentication, authenticateByBiometric, loginBySignature).

• Fixed security reports sending.

• Consumer proguard rules update.

Version 2.4.0

• Added optional log handler to MobileDcCoreConfigurationBuilder.

• Added disableBiometricAuthentication method.

• Added BiometricTypeAuth paramter to pairing methods.

Version 2.5.0

• Added getUser method.

Version 2.6.0

• Added addUser method.

Version 2.6.1

• Disabled sending native checksum in pairDevice process.

Version 2.7.0

• Added addresses service to facade.

Version 2.8.0

• Added addresses service to facade.

• Fixed checksum sending.

• Added apk certificate description.

• Added updateUser method to User domain.

Version 2.9.0

• Security issue codes are more precisely and give us more information about issue.

• Marked addAddress as deprecated.

• Added new one addAddress method which returning addressId of added address.

Version 2.9.3

• Device un-pairing device with unPaidDevice is now avaliable for not logged in users.

• Un-pair process (unPaidDevice method) requires application restart if UCP SDK is used and card was already digitized for another user.

• Login methods now clearing SDK data when device is removed from server

  When any login method fails with BackendException and CANT_FIND_DEVICE reason application should proceed with device pairing again.

Version 2.10.0

• Added new method for adding address with NewAddress model. Previous method is deprecated now.

• Added new method in Cards service: updateCard.

• Added new methods in Addresses servive: updateAddress, deleteAddres.

Version 2.10.1

• Removed false-positive security rules.

• Improved security reports sent to Wallet Server.

Version 2.11.2

• Added DeveloperOptions configuration in setup.

• Added logout method.

Version 2.11.3

• Updated security libraries.

Version 2.11.5

• Added new optional to DeveloperOptions, introducing new security checks.

• Added method verifyCard to verify card after 3DS. Card domain.

• Extended TransactionsFilters in getTransactionHistory. Transaction history domain. 

• Added new method to addCard with AddCard model. The old method was marked as deprecated. Card domain.

• Added new response parameter to getAll method. Card domain. 

• Added new request parameter to updateCard method. Card domain.

• Added new permission: QUERY_ALL_PACKAGES for security checks.

Version 2.11.6

• Minor fixes in user session.

Version 2.11.8

• Added new method for initializing reset user password with InitializeResetUserPassword model. Previous method is deprecated now.

Version 2.11.10

• Added new chapter Firebase Cloud Messaging configuration.

• Updated Security processes overview with Error codes handling in application.

• Introduced new approach to handling security issue. To provide better experience new status was added CoreSdkException with reason SECURITY_EVENT_OCCURRED. Error could be provided in every SDK methods if security issue was detected. Change doesn't impact on onSecurityIssue callback.

Version 2.11.12

• Added more protections for Android Keystore issues related to access by retrying and adding multi-thread synchronization.

Version 2.12.0

• IMPORTANT Updated security tools after EMV Security Evaluation. Please refer to setup. and Application Isolated Process.

  • added new security checks which which requires additional action on application side,

  • added new fields in DeveloperOptions object - allowDebug and enableAdditionalSecurityChecks.

• Updated Gradle and R8 tools.

• Added new methods related to transaction history and attachment in TransactionsHistoryService:

  • getTransactionDetails,

  • storeAttachment,

  • generateAttachmentLink,

  • deleteAttachment.

• Added new fields related to MCC (mcc, mccCategory) in methods getTransactionHistory and getTransactionDetails.

Version 2.12.1

• Fixed aggressive security process check from MDC SDK 2.12.0.

Version 2.13.2

• Updated documentation for Application Isolated Process with Magisk information.

• Updated recommended configuration and documentation for extractNativeLibs flag configuration, native libs should be in uncompressed form. Read more in Basic configuration section.

• Isolated security process mechanism improvements (related to enableAdditionalSecurityChecks configuration flag).

• Update Kotlin version to Kotlin version to 1.5.31 and Koin to 2.1.6.

• Updated Jackson dependency to 2.13.2 (with jackson-databind 1.13.2.2 security patch).

• Added new methods:

  • initialize3DSv2 in Cards domain,

  • finalize3DSv2 in Cards domain,

  • deleteUser in User domain.

• Added new field "nip" in AddUser model.

• Added logs for all facade methods  (available in SDK debug version).

Version 2.13.3

• IMPORTANT Removed security check for disabling permission QUERY_ALL_PACKAGES i application AndroidManifest file.

  Read more in Basic configuration : Android permission chapter.

Version 2.13.5

• Added new value in additional DeveloperOptions, responsible for verification SDK code obfuscation.

• Added information about using SDK on Android API 31+ in Basic Configuration chapter.

• Wraped in try-catch block callbacks from setup method to prevent process breaking in SDK.

Version 2.13.6

• Added new returned fields to methods: getTransactionsHistory and getTransactionDetails.

Version 2.14.6

• Important! Introduced Play Integrity API instead Safetynet Attestation API - could require additional configuration. Read more in Security processes overview chapter. Enabling requiresrequires Google API console changes. Added new BackendException statues related to Attestation API
  

• Important! Introduced SSEnew delivery message from server service which uses different channle: SSE, RNS as an alternative for only cloud messaging service (FCM). Enabled by default for not paired devices.
• Important! Added optional configuration method - MobileDcCloudMessagingConfiguration. Interface allows to register not-non-paired devices in SSEnew servicedelivery providedmessage byfrom Verestro.server sevice. Significally optimizes RNS message delivery, usage is strongly recommended. AlreadyIf this interface is present, already paired devicedevice, iswill be registered in SSEnew delivery message server service, during first login() call.
  

• Added method updateSingleTransactionData in transactions history service.

• Added new methods for device pairing - old methods became deprecated.
• Added new optional fileld optionalto toall new pair device methods - externalDeviceId.
• Introduced RefreshSession mechanism for user HTTP token management - extends a duration of session and allows to use SDK methods.methods longer. Usage is transparent for application which still should handle USER_UNATHORIZED error status.