Technical documentation MDC SDK

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

dependencies{
	implementation 'pl.upaid.module:mobiledc:{version}'
} 

dependencies{
	implementation 'pl.upaid.module:mobiledc:{version}-debug'
}

  <uses-sdk tools:overrideLibrary= "pl.upaid.module.ucp, 
    pl.upaid.module.mobiledc, pl.upaid.internal.module.mcbp-v3,
    pl.upaid.internal.module.security, com.mastercard.mpsdk, 
	pl.upaid.nativesecurity, pl.upaid.module.delivery, pl.upaid.internal.module.worker " />

dependencies{
	implementation 'androidx.work:work-runtime-ktx:2.7.1'
} 

//AndroidManifest.xml

<application
    android:extractNativeLibs="false"
    ... >
</application>

//build.gradle

android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging false
        }
    }
}

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

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

android.enableR8=true

<manifest package="com.sampleapp">
	
	<!-- remove permission from manifest -->
	<uses-permission
    	android:name="android.permission.QUERY_ALL_PACKAGES"
    	tools:ignore="QueryAllPackagesPermission"
    	tools:node="remove" />
        
        CONTACT VERESTRO TO GET 

	<!-- declare application visibility -->
	<queries>
  
  		IMPORTANT!
        CONTACT VERESTRO TO GET PACKAGES LIST
  
    </queries>

//java sample

cardsService.getAll(
        new SuccessDataCallback<List<Card>>() {
            @Override
            public void onSuccess(List<Card> cards) {
                //show cards on UI
            }
        }, new FailureCallback() {
            @Override
            public void onFailure(@NotNull Throwable throwable) {
                //show error
            }
        });

SuccessDataCallback and FailureCallback could be replaced by lambda like in kotlin sample below

//kotlin sample

cardsService.getAll({ cards ->
    //show cards on UI
}, {
    //show error
})

...

implementation('com.google.firebase:firebase-messaging:22.0.0')

...

val firebaseOptions =
            FirebaseOptions
                .Builder()
                .setApplicationId(applicationId)
                .setGcmSenderId(senderId)
                .setProjectId(projectId)
                .setApiKey(apiKey)
                .build()
FirebaseApp.initializeApp(this, firebaseOptions)

//init default project
FirebaseApp.initializeApp(this, firebaseOptions)
 
//init additional project
FirebaseApp.initializeApp(this, firebaseOptionsOther, otherProjectName)

//getting token for default project
FirebaseMessaging.getInstance().token
    .addOnCompleteListener {
        //handle token, save in storage to provide in SDK methods
    }
  
  
//getting token for additional project
val messaging = FirebaseApp.getInstance("other").get(FirebaseMessaging::class.java)
messaging.token.addOnCompleteListener {
    //handle token save in storage to provide in SDK methods
}

//Mobile DC setup configuration for enableAdditionalSecurityChecks 

val developerOptions = DeveloperOptions()
developerOptions.enableAdditionalSecurityChecks = true

MobileDcApiConfigurationBuilder()
 	// other require configuration
    .withOptionalDeveloperOptions(developerOptions)


//Sample Application declaration for handing isolated process

class SampleApplication : Application {

    override fun onCreate() {
        super.onCreate()

        if (isIsolatedProcess()) {
            return
        }
		
		//sample methods called in application
        startKoin()
        initializeMobileDcModule()
        initUcpModule()
        initFirebase()
		//other methods..
    }


	private fun isIsolatedProcess(): Boolean {
    	return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
        	android.os.Process.isIsolated()
    	} else {
        	try {
            	val activityManager = getSystemService(ACTIVITY_SERVICE) as ActivityManager
            	activityManager.runningAppProcesses
            	false
        	} catch (securityException: SecurityException) {
            	securityException.message?.contains("isolated", true) ?: false
        	} catch (exception: Exception) {
            	false
        	}
    	}
	}
}

Some data like Token Verification Code can be encrypted using JWE per RFC 7516.

class RsaJweDecrypter {

    @Throws(Exception::class)
    fun decrypt(encryptedData: String, privateKey: PrivateKey): ByteArray {
        val parse = JWEObject.parse(encryptedData)
        parse.decrypt(RSADecrypter(privateKey))
        return parse.payload.toBytes()
    }
}

Some fields are signed using JWT per RFC 7519.

Data signing should be done on server side.

{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}

class JwtGenerator {
    
    fun generate(
        jwtClaimsSet: JWTClaimsSet,
        certificates: List<X509Certificate>,
        privateKey: PrivateKey
    ): String {

        val claims = buildFinalClaims(jwtClaimsSet)

        val certChains = certificates
            .map { it.encoded }
            .map { Base64.encode(it) }

        val jwsHeader = JWSHeader.Builder(JWSAlgorithm.RS256)
            .x509CertChain(certChains)
            .build()

        val signer = RSASSASigner(privateKey)

        val jwsObject = JWSObject(
            jwsHeader,
            Payload(claims.toJSONObject())
        )

        jwsObject.sign(signer)

        return jwsObject.serialize()
    }


    private fun buildFinalClaims(jwtClaimsSet: JWTClaimsSet): JWTClaimsSet {

        val epochSeconds = Instant.now().epochSecond

        return JWTClaimsSet
            .Builder(jwtClaimsSet)
            .claim("iat", epochSeconds)
            .jwtID(UUID.randomUUID().toString())
            .build()
    }
}

Some fields are signed on Wallet Server using JWT per RFC 7519.

{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}

class JWTVerifier {

        fun verify(
            signedData: String,
            rsaPublicKey: RSAPublicKey,
            iatToleranceSeconds: Long
        ): JWTClaimsSet {
            
            val signedJWT = SignedJWT.parse(signedData)
            val signatureResult = signedJWT.verify(RSASSAVerifier(rsaPublicKey))
            if (!signatureResult) {
                throw ValidationException("Invalid signature")
            }
            
            val jwtClaimsSet = signedJWT.getJWTClaimsSet()
            
            //optionally check iat with tolerance
            val isIatInAllowedTimeRange = jwtClaimsSet
                .getIssueTime()
                .toInstant()
                .plusSeconds(iatToleranceSeconds)
                .isAfter(Instant.now())
            
            if (!isIatInAllowedTimeRange) {
                throw ValidationException("Signed JWT expired")
            }
            
            return jwtClaimsSet
        }
    }

keytool -importkeystore -srckeystore cert.jks -destkeystore cert.p12 -srcstoretype jks -deststoretype pkcs12

openssl pkcs12 -nokeys -in cert.p12 -out cert.pem

openssl x509 -inform der -in deployment_cert.der -out certificate.pem

Asynchronous. Offline. Mobile DC initialization method. Contains all necessary data to configure SDK.

Should be called at very beginning of application lifecycle. For example in Android Application::onCreate method.

Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished.

When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand.

Note: Please be aware to use this method before usage of any MobileDC methods or another Verestro product.

SDK Event Listeners - errors catching

The application should prevent throwing exceptions in MDC SDK Event Listeners described below as it could cause breaking process in SDK.

In case of error in application event listener implementation SDK runs this code in try-catch block.

var eventsTrace = arrayListOf<Int>()//make use of this in case of error/failure/unexpected behaviour to retrace sdk internal processes


val mobileDcCoreConfiguration = MobileDcCoreConfiguration.create(
    MobileDcCoreConfigurationBuilder()
        .withApplicationContext(this)
        .withWalletSecurityEventListener(object : WalletSecurityEventListener {
            override fun onSecurityIssueAppeared(event: EventSecurityIssueAppeared) {
                //eg. show security screen or toast with details from event object
                //all data collected by SDK will be removed
                //Clearing application data in context of SDK is recommended
            }

        })
        .withOptionalLogger(object : EventsLogger {
            override fun onEvent(eventId: Int) {
                eventsTrace.add(eventId)
            }
        })
        .withOptionalDeveloperOptions(DeveloperOptions().apply {
            allowDebug = false
            enableAdditionalSecurityChecks = true
            enableCodeObfuscationCheck = true
        })
)

MobileDcApiKotlin.setup(mobileDcCoreConfiguration)

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.

Asynchronous. Offline.

Checks Verestro Backend service source of push content.

Application should check senderId in RemoteMessage object (RemoteMessage::from method) before passing data to this method.

Deprecated, no longer required to use. Use simply method process() for push message providing.

Success callback with source of push.

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 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
        })
}

Asynchronous. Online.

Updates FCM Cloud Messaging registation token.

Method should be called when application receive new registration token from FCM service.

When updated application should still receive push notifications from Verestro Backend.

Application should always retry update FCM Registration token if method failed.

Success / failure callback.

//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
        })
}

Asynchronous. Online.

Updates Cloud Messaging registation token for selected token type (FCM).

Method should be called when application receive new registration token from FCM service.

When updated application should still receive push notifications from Verestro Backend.

Application should always retry update FCM Registration token if method failed.

Deprecated, use updateRegistrationToken.

Success / failure callback.

Asynchronous. Online.

Provides transaction history from Mobile DC backend with selected transactions filters.

Success callback with list of transactions history.

//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
            })
}

Asynchronous. Online.

Provides transaction details from Mobile DC backend for selected transactionId.

Success callback with transaction details.

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

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

Asynchronous. Online.

Stores attachment file in Mobile DC backend for selected transactionId.

Success callback.

//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
            })
}

Asynchronous. Online.

Provides new link to load attachment when existing one fails with 403 HTTP status.

Success callback with new attachment link and expiration date.

//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
        })
}

Asynchronous. Online.

Delete attachment associated with provided transaction.

Success callback/ Failure callback.

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
            })
}

Asynchronous. Online.

Updates single transaction data in Mobile DC backend by transactionId.

Success callback/ Failure callback.

Asynchronous. Online.

Updates category of the transaction. It is possible to set more than one category (sum of the amounts in categories has to be matched to the transaction amount).

Success callback/ Failure callback.

Asynchronous. Online.

Method returns user categories.

No input parameters.

Success callback with user categories details.

Asynchronous. Online.

Method returns monthly spending amount in target currency which has to be given balance currency. For scenario where someone was added manually transaction in different currency than balance or target currency is different, then this method will return error