Technical Documentation VCP SDK

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


		//if the sync time takes too long, add filters to match the repository with specific modules as below
		content {
    		includeGroupByRegex "pl.upaid.*"
    		includeGroup "com.mastercard"
		}
	}
}

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

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

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

<service
	android:name=".WalletHceService"
	android:exported="true"
	android:permission="android.permission.BIND_NFC_SERVICE">
		
		<intent-filter>
			<action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />		
		</intent-filter>
		
		<meta-data
			android:name="android.nfc.cardemulation.host_apdu_service"
			android:resource="@xml/hce_apdu_service" />
 </service>

<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
	android:apduServiceBanner="@drawable/hce_logo"
	android:description="@string/hce_service_description"
	android:requireDeviceUnlock="false">
	<!-- If the requireDeviceUnlock is set to false, on some phones you can pay if the screen is not awake, 
    but on most devices the screen must be awake to make a payment. -->
	
	<aid-group
    	    android:category="payment"
    	    android:description="@string/aid_description">

		<!-- Following is a PPSE AID. You must always include this AID in order for payments to work-->

	 	<aid-filter android:name="325041592E5359532E4444463031" />

		<!-- Following AID list is specific to the application requirements.
	       If your application supports the type of card that these AID represents,
	       you must include those AID in your configuration file -->

		<aid-filter android:name="A0000000041010" /> <!-- Mastercard DEBIT/CREDIT -->
	    <aid-filter android:name="A0000000042203" /> <!-- Mastercard US DEBIT/CREDIT -->
	    <aid-filter android:name="A0000000043060" /> <!-- Maestro DEBIT -->
	    <aid-filter android:name="A0000000049100" /> <!-- Private label AID-->
	</aid-group>
</host-apdu-service>

fun isSystemDefault(): Boolean {
	val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
    return cardEmulation.isDefaultServiceForCategory(
        WalletHceService::class.java,
        CardEmulation.CATEGORY_PAYMENT
    )
}

fun requestForSystemDefault() {
    val intent = Intent().apply {
        action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
        putExtra("component", WalletHceService::class.java)
        putExtra("category", CardEmulation.CATEGORY_PAYMENT)
    }
    context.startActivity(intent)
}

fun registerAsOnTopHceApplication() {
	val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
    cardEmulation.setPreferredService(
        activity, ComponentName(activity, WalletHceService::class.java)
    )
}


fun unregisterFromOnTopHceApplication() {
	val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
    cardEmulation.unsetPreferredService(activity)
}

Synchronous. Offline.
Contains all the necessary data to configure SDK.
Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method.

Requires MobileDC setup() already finished

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.

Important: Before calling VCP SDK setup you must call setup from Mobile DC SDK.

Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment and loading first aplication screen.

// UcpTransactionEventListener comments

class BankingAppUcpTransactionEventListener : UcpTransactionEventListener {

    override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) {
        //authorization is required for transaction, open payment screen with authorization
        //show PaymentInstrument and ContactlessTransactionData available in event object

        showPaymentScreen(event.paymentInstrument, event.transactionData)
    }


    override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) {
        //authorization is required for transaction, open payment screen with authorization
        //show PaymentInstrument and DSRP transaction information available in event object

        showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo)
    }

    override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) {
        //check if user is on payment screen and update timer
        //when timer is 0, application should close payment with failure
        
		//deprcated, disabled by default, read method description how to enable
    }

    override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) {
        //looks like payment is aborted, can provide result to payment screen 
        //and show user what is abort reason
    }

    override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) {
        //payment completed, provide result to payment information
        //REMEMBER Transaction is processed on terminal and this is where 
        //you will see final transaction result
    }

    override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) {
        //something went wrong during transaction, provide result to user
    }

    override fun onTransactionStopped() {
        //deprecated, not used anymore, 
    }
    
    override fun onContactlessPaymentStarted() {
        //Payment started or resumed after callback onAuthReqiredForContactless
        //Best place for checking if user is authenticated for payment and call
        //setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected
    }
}

class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener {

    override fun onNewTransaction(event: EventNewTransaction) {
        //information about new transaction processed by issuer
    }

    override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
        //status of payment instrument was changed, refresh list, inform user about new status
    }

    override fun onProvisioningFailure(event: EventProvisioningFailure) {
        //provisioning failed, try again
    }

    override fun onProvisioningSuccess(event: EventProvisioningSuccess) {
        //provisioning success, wait for status and replenish changes until user can pay 
        //or provide activation method when required
    }

    override fun onReplenishFailure(event: EventReplenishFailure) {
        //transaction credentials replenish failed
    }

    override fun onReplenishSuccess(event: EventReplenishSuccess) {
        //transaction credentials replenish success
    }
}

class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener {

    //Sample implementation of transaction acceptance listener
    
	//For the scanario when authentication is required on issuer side for every transaction 
    //field even.isUserAuthenticated must be always true, otherwise 
    //ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned

    override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice {

        val isScreenUnlocked = isScreenUnlocked()
        val isScreenProtectedByKeyguard = isScreenUnlocked()

        val isLvtTransaction =
            event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT

        //discard all Transit transaction
        if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) {
            return ContactlessAdvice.DECLINE
        }

        //allow for transaction when user is authenticated for payment and screen unlocked
        if (event.isUserAuthenticated && isScreenUnlocked) {
            return ContactlessAdvice.PROCEED
        }

        //allow for LVT transaction on unlocked screen when protected and don't require authentication
        if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) {
            return ContactlessAdvice.PROCEED
        }

        // ...
        // much more cases

        //require authentication anyway
        return ContactlessAdvice.AUTHENTICATION_REQUIRED
    }
}

class BankReportEventListener : UcpEventReportsListener {

    override fun onNewReport(report: Report) {
       //may be used for debugging SDK or gathering reports on client's app or backend
  	}
}

//Use UcpMcbpHTtpExecutor as supertype if you want to replace connection
class BankUcpMcbpHttpExecutor : UcpMcbpHttpExecutor {
 
    override fun execute(
        ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
        ucpMcbpHttpMethod: UcpMcbpHttpMethod,
        url: String,
        requestData: Any,
        requestProperties: Map<String, String>
    ): UcpMcbpHttpResponse {
 
 
        //additional action before request
 
 
        //invoke connect by custom connector
        return when (ucpMcbpRequestType) {
            UcpMcbpHttpExecutorRequestType.REQUEST_SESSION -> {
                executeRequestSession(ucpMcbpHttpMethod, url, requestData as UcpMcbpRequestSessionRequestData, 
                requestProperties)
            }
            UcpMcbpHttpExecutorRequestType.PROVISION -> {
                executeProvision(ucpMcbpHttpMethod, url, requestData as UcpMcbpProvisionRequestData, 
                requestProperties)
            }
            UcpMcbpHttpExecutorRequestType.REPLENISH -> {
                executeReplenish(ucpMcbpHttpMethod, url, requestData as UcpMcbpReplenishRequestData, 
                requestProperties)
            }
            UcpMcbpHttpExecutorRequestType.NOTIFY_PROVISIONING_RESULT -> {
                executeNotifyProvisioningResult(ucpMcbpHttpMethod, url, 
                requestData as UcpMcbpNotifyProvisioningResultRequestData, requestProperties)
            }
            UcpMcbpHttpExecutorRequestType.CHANGE_MOBILE_PIN -> {
                executeChangeMobilePin(ucpMcbpHttpMethod, url, 
                requestData as UcpMcbpChangeMobilePinRequestData, requestProperties)
            }
            UcpMcbpHttpExecutorRequestType.DELETE -> {
                executeDelete(ucpMcbpHttpMethod, url, requestData as UcpMcbpDeleteRequestData, 
                requestProperties)
            }
        }
    }
}

//Use DefaultUcpMcbpHTtpExecutor as supertype if you want to only add some action before connection
class BankDefaultUcpMcbpHttpExecutor : DefaultUcpMcbpHttpExecutor() {
    override fun execute(
        ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
        ucpMcbpHttpMethod: UcpMcbpHttpMethod,
        url: String,
        requestData: Any,
        requestProperties: Map<String, String>
    ): UcpMcbpHttpResponse {
 
        //additional action before request
 
        return super.execute(
            ucpMcbpRequestType,
            ucpMcbpHttpMethod,
            url,
            requestData,
            requestProperties
        )
    }
}

class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() {
     override fun onReProvisionSuccess(event: EventReProvisionSuccess) {
     	//reProvisioning success, wait for status and replenish changes until user can pay 
  	}
 	
	override fun onReProvisionFailure(event: EventReProvisionFailure) {
       //reProvisioning failed, try again.
  	}
}

fun setup(
    application: Application,
    walletCvmModel: WalletCvmModel,
    walletAuthUserMode: WalletAuthUserMode,
    mcbpPinningCertificates: List<String>,
    replenishThreshold: Int
) {

    val ucpConfiguration = UcpConfiguration.create(
        UcpConfigurationBuilder()
            .withApplication(application)
            .withCvmModel(walletCvmModel)
            .withUserAuthMode(walletAuthUserMode)
            .withUcpTransactionEventListener(BankingAppUcpTransactionEventListener())
            .withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener())
            .withMcbpPinningCertificates(mcbpPinningCertificates)
            .withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener())
            .withReplenishThreshold(replenishThreshold)
			.withOptionalEventsReports(BankReportEventListener())
    		.withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor())
			//if you want to only add additional action before connection use below implementation
			//.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor())
			.withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener())
            //if you want to change standard transaction configuration use configuration below
            .withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration())
    )

    UcpApiKotlin().setup(ucpConfiguration)
}

Synchronous. Offline.
Method for resetting SDK to uninitialized state.
NOTE: According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. Please kill application process after using this method. Trying using any facade method without stopping application process will cause throwing UcpSdkException.
To avoid closing application use restart() methods.

fun reset() {
    UcpApiKotlin().reset()

	//Terminating JVM according to MC SDK Sample Application
    Runtime.getRuntime().exit(0);
}

Synchronous. Offline.

Method for resetting SDK to uninitialized state.

Replaces reset() method which requires killing application process.

When restart finishes with error, application should repeat action.

NOTE: SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again.

Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods.

Failure callback when something went wrong during restart. Application should repeat action.

UcpApiKotlin().restart({
    //restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods
}, {
    //some error occured, please repeat action
})

Asynchronous. Online.|
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with onPaymentInstrumentStatusChanged.

Success / failure callback

fun delete(paymentInstrumentId: String, reason: CharArray?) {
    ucpApi.cardsService
            .delete(paymentInstrumentId, reason,
                    {
                        //PaymentInstrument delete requested
                        //wait for confirmation from onPaymentInstrumentStatusChanged
                    },
                    { throwable ->
                        //Something went wrong, check excetpion with documentation
                    }
            )
}

Asynchronous. Online.
Check eligibility required to process digitize.

Success callback with CheckEligibilityResult.

Failure callback

private fun checkEligibility(
    paymentInstrumentId: String,
    paymentInstrumentType: PaymentInstrumentType,
    userLanguage: String,
    userCountry: String
) {

    ucpApi.cardsService
        .checkEligibility(
            CheckEligibility(
                paymentInstrumentId,
                paymentInstrumentType,
                userLanguage,
                userCountry
            ),
            { checkEligibilityResult ->
                //Handle result
            },
            { throwable ->
                //Something went wrong, check exception with documentation
            }
        )
}

Asynchronous. Online.
Use only when checkEligibility method is used.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.

Success callback with DigitizationResult object

Failure callback

fun digitizeCard(digitizationRequest: DigitizationRequest) {

    ucpApi.cardsService
            .digitize( digitizationRequest,
                    { digitizationResult ->
                        //digitization success, provisioning is in progress
                        //application should listen to push message and provide content to UCP
                        //refresh you payment instrument list form Cards::getPaymentInstruments
                        //new PaymentInstrument should be visible with INACTIVE state

                        //when push processed wait for onProvisioningSuccess or Failure callback
                        //and status change
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.

Success / failure callback

fun digitizeCard(
        paymentInstrumentId: String,
        languageCode: String,
        securityCode: CharArray) {

    ucpApi.cardsService
            .digitize(paymentInstrumentId, languageCode, securityCode,
                    {
                        //digitization success, provisioning is in progress
                        //application should listen to push message and provide content to UCP
                        //refresh you payment instrument list form Cards::getPaymentInstruments
                        //new PaymentInstrument should be visible with INACTIVE state

                        //when push processed wait for onProvisioningSuccess or Failure callback
                        //and status change
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Retrieves additional user authentication methods.

Success callback with AdditionalAuthenticationMethods object.

Failure callback.

private fun getAdditionalAuthenticationMethods() {
    val getAdditionalAuthenticationMethod =
        GetAdditionalAuthenticationMethods("paymentInstrumentId")

    ucpApi
        .cardsService
        .getAdditionalAuthenticationMethods(
            getAdditionalAuthenticationMethod,
            { additionalAuthenticationMethods ->
                //Handle result
            },
            { throwable ->
                //Something went wrong, check exception with documentation
            })
}

Asynchronous. Online.
Submit authentication code when additional user authentication is required.

Success callback/failure callback.

private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) {

    ucpApi.cardsService
        .submitAuthenticationValue(
            SubmitAuthenticationValue(
                paymentInstrumentId,
                authenticationCode
            ),
            {
                //Handle success
            },
            { throwable ->
                //Something went wrong, check exception with documentation
            }
        )
}

Asynchronous. Online.
Submit authentication method when additional user authentication is required.

Success callback/failure callback.

private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) {

    ucpApi.cardsService
        .submitAuthenticationMethod(
            SubmitAuthenticationMethod(
                paymentInstrumentId,
                authenticationMethodId
            ),
            {
                //Handle success
            },
            { throwable ->
                //Something went wrong, check exception with documentation
            }
        )
}

Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to increase UX.
Use remote way when possible to keep your payment instruments always up to date.

Success callback with list of PaymentInstrument objects.

Failure callback.

fun getAllPaymentInstrument(refresh: Boolean) {
    ucpApi.cardsService
            .getAllPaymentInstruments( refresh,
                    { paymentInstruments ->
                        //List of PaymentInstrument from local or remote storage
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online/Offline.
Deprecated - use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date.

Success callback with PaymentInstument object.

Failure callback.

fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
    ucpApi.cardsService
            .getPaymentInstrument(paymentInstrumentId, refresh,
                    { paymentInstrument ->
                        //PaymentInstrument from local or remote storage
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Registers user and device if already not registered in VCP backend. Creates payment token in VCP backend.
Expect push after successfull finish and then proceed using process method in Cloud Messaging domain.

Success callback. Called when device token digitization finished with success .Result contains IbanDigitizationResult object.

Note: Cloud token digitization fail doesn't affect on success/failure callback.

Failure callback. Called when device token digitization finished with failure.

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

fun digitizeIban(
        signedAccountInfo: String,
        fcmRegistrationToken: CharArray,
        languageCode: String) {

    ucpApi.ibansService
            .digitize(signedAccountInfo, fcmRegistrationToken, languageCode,
                    { ibanDigitizationResult ->

                        //Device token digitization finished with success
                        //wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success

                        val cloudDigitizationResult = ibanDigitizationResult.result

                        //check status of Cloud Token
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Provides Transaction Verification Code required to process cloud payments.

Success callback with Tvc object or encrypted Tvc object as String.

Failure callback when TVC cannot be created.

class SignedIbanInfo {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
            .build();

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

fun createTvc(signedIbanInfo: String) {
    ucpApi.ibansService
            .createTVC(signedIbanInfo, { tvc ->
                //result object could contains encrypted TVC
                val encryptedTvc: String? = tvc.encryptedTvc

                //or decrypted(plain) TVC object with parameters described in documentation
                val plainTvc = tvc.plainTvc
            }, { throwable ->
                //Something went wrong, check exception with documentation
            })
}

Asynchronous. Online.
This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form.

Success callback with PaymentData object or encrypted payment data object as String.

Failure callback when PaymentData cannot be created.

class SignedIbanInfo {
    fun generate() {
        val claims = JWTClaimsSet.Builder()
            .claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
			.claim("userId", "123")
            .build();

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

fun createPaymentData(signedIbanInfo: String) {
    ucpApi.ibansService
            .createPaymentData(signedIbanInfo, { paymentData ->
                //result object could contains encrypted PaymentData
                val encryptedPaymentData: String? = paymentData.encryptedPaymentData

                //or decrypted(plain) PaymentData object with parameters described in documentation
                val plainPaymentData = paymentData.plainPaymentData
            }, { throwable ->
                //Something went wrong, check exception with documentation
            })
}

Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date.

Success callback with list of PaymentInstrument objects

Failure callback

fun getAllPaymentInstrument(refresh: Boolean) {
    ucpApi.ibansService
            .getAllPaymentInstruments( refresh,
                    { paymentInstruments ->
                        //List of PaymentInstrument from local or remote storage
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online/Offline.
Use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. 

Success callback with PaymentInstument object

Failure callback

fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
    ucpApi.ibansService
            .getPaymentInstrument(paymentInstrumentId, refresh,
                    { paymentInstrument ->
                        //PaymentInstrument from local or remote storage
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with onPaymentInstrumentStatusChanged.

Success / failure callback

fun delete(paymentInstrumentId: String, reason: CharArray?) {
    ucpApi.ibansService
            .delete(paymentInstrumentId, reason,
                    {
                        //PaymentInstrument delete requested
                        //wait for confirmation from onPaymentInstrumentStatusChanged
                    },
                    { throwable ->
                        //Something went wrong, check excetpion with documentation
                    }
            )
}

Asynchronous. Offline.
Sets payment instrument as default for contactless payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically after linking with PoS terminal.
Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default.

Success / failure callback

fun setDefaultForContactless(paymentInstrument: PaymentInstrument) {

    if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) {
        //make sure selected PaymentInstrument can be seta as default
        return
    }

    val paymentInstrumentId = paymentInstrument.id

    ucpApi.paymentService
            .setDefaultForContactless(paymentInstrumentId, {
                //success
            }, { throwable ->
                //Something went wrong, check exception with documentation
            })
}

Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.

Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.

No input parameters

Success callback with id new default PaymentInstrument

Failure callback.

fun getDefaultForContactless() {
    ucpApi.paymentService
            .getDefaultForContactless({ paymentInstrument ->
                // use PaymentInstrument
            }, { throwable ->
                when (throwable) {
                    is DefaultPaymentInstrumentNotFoundException -> {
                        //there is no default PaymentInstrument
                    }
                    else -> {
                        //check another exception with documentation
                    }
                }
            })
}

Asynchronous. Offline.
Sets payment instrument as default for DSRP payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically to remote payments.

Success / failure callback

fun setDefaultForRemote(paymentInstrument: PaymentInstrument) {

    if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
            && !paymentInstrument.dsrpSupported) {
        
        //make sure selected PaymentInstrument can be set as default
        return
    }

    val paymentInstrumentId = paymentInstrument.id

    ucpApi.paymentService
            .setDefaultForRemote(paymentInstrumentId, {
                //success
            }, { throwable ->
                //Something went wrong, check exception with documentation
            })
}

Asynchronous. Offline.
Provides default PaymentInstrument for remote payments.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.

No input parameters

Success callback with id new default PaymentInstrument

Failure callback.

fun getDefaultForRemote() {
    ucpApi.paymentService
            .getDefaultForRemote({ paymentInstrument ->
                // use PaymentInstrument
            }, { throwable ->
                when (throwable) {
                    is DefaultPaymentInstrumentNotFoundException -> {
                        //there is no default PaymentInstrument
                    }
                    else -> {
                        //check another exception with documentation
                    }
                }
            })
}

Asynchronous. Offline.
Sets payment instrument as primary for next incoming contactless payment.

Success / failure callback

Note: This is only sample payment scenation

//sample scenario of starting payment with authentication before payment

fun startPayment(paymentInstrument: PaymentInstrument) {

    //checking conditions before payment
    val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
    val isContactlessSupported = paymentInstrument.contactlessSupported
    val hasTransactionCredentials = paymentInstrument.credentialsCount > 0

    if (!isActive || !isContactlessSupported || !hasTransactionCredentials) {
        //PaymentInstrument doesn't meet requirements for payment
        return
    }
    
    //selecting PaymentInstrument to payment
    ucpApi.paymentService
            .selectForPayment(paymentInstrument.id, {
                //selection success

                //request user authentication when 
                //... authentication presented

                //use setUserAuthenticatedForPayment method

            }, { throwable ->
                //something went wrong, check exception with documentation
            })
}

Asynchronous. Offline.
Sets user as authenticated to payment with provided payment instrument.
Authentication will expiry automatically after transaction time configured in payment instrument profile.

Authentication clearing depends on authentication timer configuration in UcpTransactionConfiguration:enableTransactionAuthenticationTimer.
By default timer is disabled and authentication is cancelled when user perform transaction and SDK send callback onContactlessPaymentCompleted/Aborted/Incident from UcpTransactionEventListener.
When timer is enabled authentication is cleared when auth timer finishes - it could casue problems when user start to pay just before timer finish. Authentication could be cleared by SDK during payement.

If application call setUserAuthenticatedForPayment without contactless payment context and authentication timer is disabled, authentication is never cleared by SDK. To clear authentication use abortUserAuthenticationForPayment.

UcpTransactionEventListener:onContactlessPaymentStarted is recommended place for payment authentication.

Note: User can be authenticated based on conditions like screen unlock.  Method must be called before payment in method UcpTransactionEventListener:onContactlessPaymentStarted()
Make sure that authentication on this step is done securely. Transaction information is not available on this step.

Success / failure callback

private fun setUserAuthenticatedForPayment(
    paymentInstrument: PaymentInstrument,
    pinProvidedByUser: CharArray
) {
    ucpApi
        .paymentService
        .setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser,
            {
                //user authentication provided
                //start one tap payment or continue two tap with 2nd tap to terminal after authentication
                //listen for auth timer changes
                //user abortUserAuthentication method when transaction cancelled by user
            }, { throwable ->
                //some error, check exception
            })
}

override fun onContactlessPaymentStarted() {

    //check internal conditions
    //like user performed authentication, is logged in application, is device unlocked etc
    val isUserAuthenticated = true

    //check if use selected any token for payment and select it in UCP SDK
    //otherwise default token will be used
    if (getSelectedPaymentInstrumentId() != null) {

        ucpApi
            .paymentService
            .selectForPayment(
                paymentInstrumentId = getSelectedPaymentInstrumentId(),
                success = {
                    //token will be used for actual payment
                    //call setUserAuthenticatedForPayment here - sample below in "else" block
                },
                failure = { throwable ->
                    //something went wrong, check throwable with documentation
                }
            )
    } else {

        if (isUserAuthenticated) {
            ucpApi
                .paymentService
                .setUserAuthenticatedForPayment(
                    paymentInstrumentId = getSelectedPaymentInstrumentId(),
                    pin = null, //or pin if MobilePin is used
                    success = 
                        //user authenticated in SDK
                    }, failure = {
                        //authentication failure, check exception
                    }
                )
        }
    }
}

Asynchronous. Offline.

Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped.

No input parameters

Success / failure callback

fun abortUserAuthenticationForPayment() {
    ucpApi
            .paymentService
            .abortUserAuthenticationForPayment(
                    {
                        //user authentication aborted
                        //listen for auth timer changes
                    },
                    { throwable ->
                        //some error, check exception
                    })
}

Synchronous. Offline.
Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS.
Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method.

Apdu result - method called synchronous without callback

//WalletHceService must be registerd in AndroidManifest as nfc service 
class WalletHceService : HostApduService() {

	//...
    //private val ucpApi = ..

    override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
        return ucpApi 
            .paymentService
            .processHceApduCommand(this, commandApdu, extras)
    }
	//..
}

Asynchronous. Online.
Method for manually replenishing payment credentials.
Application will receive push notification and notified about replenish process with global callback described in setup chapter. 

Success / failure callback

fun replenishCredentials(paymentInstrumentId: String) {
    ucpApi.paymentService
            .replenishCredentials(paymentInstrumentId,
                    {
                        //request for credentials replenish finished with success
                        //wait for push notification and pass to valid module
                        //when push processed application will be informed about replenish success/failure
                        //read chapter with setup for more information
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    })
}

Asynchronous. Offline.
Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile.
Default auth time is provided by card profile.

No input parameters

Success / failure callback

Asynchronous. Online.
Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated.

Success callback/failure callback.

fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) {
    ucpApi.paymentService
            .requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
                    { 
                        //Requesting Authentication Code went successfully.
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid.

Success callback with ValidateAuthenticationCodeForPaymentResult object.

fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) {
    ucpApi.paymentService
            .validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment,
                    { validateAuthenticationCodeForPaymentResult ->
                        //ValidateAuthenticationCodeForPaymentResult plain object, 
                        //contains data to validate on backend
						val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult
                        		.signedAuthenticationProcessData
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

class SignedAuthenticationProcessData {
    fun verifyAndGetAuthenticationRequestID() {
        val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600);
        val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId")        
        // ...
    }
}

Asynchronous. Online.

Success callback with cryptogram for payment

Failure callback

Asynchronous. Offline.
Method dedicated for starting DSRP transaction.
Every DSRP transaction has to be authenticated before processing.
Depending on implementation payment can be process with OTP authentication or device level authentication.

Success callback with ProcessDsrpTransactionResult object.

// After Merchant App delivers DSRP data application should authenticate user with device level authentication 
// and next execute setUserAuthenticationForPayment().

// Values for DsrpTransactionInfo delivered by Merchant APP 

val dsrpTransactionInfo: DsrpTransactionInfo = 
	DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction = 
	ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)

private fun setUserAuthenticatedForPayment(
    paymentInstrumentId: String,
    pinProvidedByUser: CharArray
) {
    ucpApi
        .paymentService
        .setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
            {
                //After succesfully authentication for payment MPA should execute processDsrpTransaction()
            }, { throwable ->
                //some error, check exception
            })
}

fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
    ucpApi.paymentService
            .processDsrpTransaction( processDsrpTransaction,
                    { processDsrpTranasctionResult ->
                        //DSRP transaction result with details went successfully result 
                        //should be delivered to Merchant APP
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

// After Merchant App delivers DSRP data user should request authentication 
// code for payment with selected paymentInstrument.

// Values for DsrpTransactionInfo delivered by Merchant APP 

val dsrpTransactionInfo: DsrpTransactionInfo = 
		DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction = 
		ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)

val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment = 
		RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId)
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) {
   		ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
                    {
                        //When requesting went successfully User will get authentication code. 
						//In next step authentication code should be passed to MPA and application 
                        //should validate this code with validateAuthenticationCode() method
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

val validateAuthenticationCode: ValidateAuthenticationCode = 
	ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser)
fun validateAuthenticationCode(validateAuthenticationCode) {
    ucpApi.paymentService
            .validateAuthenticationCode( validateAuthenticationCode,
                    { validateAuthenticationCodeResulty ->
                        //ValidateAuthenticationCodeResult plain object
                        val signedAuthenticationProcessData = validateAuthenticationCodeResulty
                        		.signedAuthenticationProcessData

						//If validation went successfully MPA should show authentication view, 
                        //and after valid authentication MPA should execute setUserAuthenticatedForPayment()
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

private fun setUserAuthenticatedForPayment(
    paymentInstrumentId: String,
    pinProvidedByUser: CharArray
) {
    ucpApi
        .paymentService
        .setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
            {
                //After succesfully authentication for payment MPA should execute processDsrpTransaction()
            }, { throwable ->
                //some error, check exception
            })
}

fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
    ucpApi.paymentService
            .processDsrpTransaction( processDsrpTransaction,
                    { processDsrpTransactionResult ->
	                    //DSRP transaction result with details went successfully result 
                        //should be delivered to Merchant APP
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Processes data sent by VCP backend (push notification data).
Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method.
Method can throw InvalidPushException in case of invalid push content passed to it.
Refer Mobile DC documentation how to handle push.

Deprecated in 2.6.7, use MobileDC:CloudMessaging:process() instead.

Success / failure callback. When request fails try again

//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 Mobile DC
        }, {
            //some error
        })
}

Asynchronous. Online.
Processes data sent by MCBP.
Application should check senderId in RemoteMessage object before passing data to VCP SDK.
Basic configuration for push processing from External Wallet Server: External Wallet Server domain.
Method can throw InvalidPushException in case of invalid push content passed to it.

Note: External Wallet Server Registration process mus be finished before push processing.

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 based on senderId
    if (isMastercardSenderId(senderId)) {

        val mastercardPayload: String = readMastercardPushContent(pushData)

        ucpApi
            .cloudMessagingService
            .processMcbpNotificationData(mastercardPayload, {
                //push processed in Mcbp
            }, {
                //some error
            })
        
    } else {
        //proceed push from another source
    }
}

Asynchronous. Offline.
Method for preparing data used for activation.
Should be used before calling register method.

Success callback with PrepareRegistrationResponse object.

Failure callback

fun prepareRegistrationData(
        paymentAppInstanceId: String,
        paymentAppProviderId: String,
        publicKeyCertificate: String,
        mobilePin: CharArray?) {

    ucpApi
            .ewsService
            .prepareRegistrationData(paymentAppInstanceId,
                    paymentAppProviderId,
                    publicKeyCertificate,
                    mobilePin,
                    { prepareRegistrationResponse ->
                        //Prepared data for registration including encryptedMobilePin if mobilePin is used
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Method used for registration new Mobile Payment App instance with MDES for use.

Success / failure callback

fun register(
        mobileKeysetId: String,
        ewsMobileKeys: EwsMobileKeys,
        remoteManagementUrl: String) {

    ucpApi
            .ewsService
            .register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl,
                    {
                        //Device registration success 
                        //application should listen to push messages and UcpPaymentInstrumentEventListener callbacks
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation  
                    }
            )
}

Asynchronous. Online.
Method to activate PaymentInstrument.
Should be used only on PaymentInstrumens which PaymentInstrumentStatus is SUSPENDED or INACTIVE.
Changes PaymentInstrumentStatus to ACTIVE, calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available.
Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card.

Success / failure callback

fun activate(paymentInstrumentId: String) {
    ucpApi
		.ewsService
        .activate(paymentInstrumentId,
		{
         	//Changes PaymentInstrumentStatus to ACTIVE, set card as default for payment if another 
            //is not already setted Performing replenish, 
            //application should listen to push message with information about replenish success/failure 
        }, 
		{ throwable ->
        	//Something went wrong, check exception with documentation
        }
	)
}

Asynchronous. Offline.
Method for suspending paymentInstrument.
Changes PaymentInstrumentStatus to SUSPENDED.
Use activate method to allow payments again.

Success / failure callback

fun suspend(paymentInstrumentId: String) {
    	ucpApi
			.ewsService
            .suspend(paymentInstrumentId,
			{
           		 //Changes PaymentInstrumentStatus to SUSPENDED.
            }, 
			{ throwable ->
            	 //Something went wrong, check exception with documentation
            }
	)
}

Asynchronous. Offline.
Method for getting single PaymentInstrument from local storage object based on id.

Success callback with PaymentInstrument object.

Failure callback.

fun getPaymentInstrument(paymentInstrumentId: String) {
    ucpApi.ewsService
            .getPaymentInstrument(paymentInstrumentId,
                    { paymentInstrument ->
                        //PaymentInstrument from local storage
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Offline.
Method for getting all payment instruments from local storage.

No input parameters

Success callback with list of PaymentInstrument objects.

Failure callback.

fun getAllPaymentInstrument() {
    ucpApi.ewsService
            .getAllPaymentInstruments(
                    { paymentInstruments ->
                        //List of PaymentInstrument from local storage
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Offline.|
Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged.

Success callback with encrypted mobile PIN.

Failure callback.

fun getEncryptedPin(pin: CharArray) {
    ucpApi
            .ewsService
            .getEncryptedPin(pin, { encryptedPin ->
                //call to Wallet Server with new created encrypted mobile PIN
                //when updated call onMobilePinChanged method
            }, {
                //Something went wrong, check exception with documentation
            })
}

Asynchronous. Online.
Method for informing SDK about mobilePin change.
Should be used when mobilePin changed.
The result of action is deletion of existing transaction credentials and replenish.

No input parameters

Success / failure callback

fun reactOnMobilePinChanged() {
    ucpApi
        .ewsService
        .onMobilePinChanged(
            {
				// Informing SDK about changing mobile pin processed succesfully.
				// SDK should delete and next replenish transaction credentials. 
				// Listen for UcpPaymentInstrumentEventListener events
            }, { throwable ->
				// Something went wrong, check exception with documentation.
            })
}

Asynchronous. Online.
Method to removing PaymentInstrument.
Removed transaction credentials and PaymentInstrument from local storage and in MDES.
When success PaymentInstrument will be no longer available in getPaymentInstrument and getPaymentInstruments methods.

Success / failure callback

fun delete(paymentInstrumentId: String) {
    ucpApi
            .ewsService
            .delete(paymentInstrumentId,
                    {
                        //Selected Payment instrument is removed
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}

Asynchronous. Online.
Method for getting all assets for selected assetId.

Success callback with list of Assets objects.

Failure callback

fun getAsset(assetId: String) {
    ucpApi.assetsService
            .getAssets( assetId,
                    { ucpAsset ->
                        //List of assets of selected assetId
						val ucpAssetContentList = ucpAsset.content
                    },
                    { throwable ->
                        //Something went wrong, check exception with documentation
                    }
            )
}