Technical Documentation UCP SDK Version 2.5.7 UCP SDK Introduction Basic abbreviations and definitions Field Description CDCVM Consumer Device Cardholder Verification Method CVM Cardholder Verification Method Contactless Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to UCP SDK. HCE support is required for contactless transactions DSRP Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions FCM Firebase Cloud Messaging HCE Host Card Emulation IBAN Bank Account Number MCBP Mastercard Cloud Based Payments MDC Mobile Data Core. Verestro core library. MPA Mobile Payment Application - an application that uses UCP SDK for payments NFC Near Field Communication One tap Flow in a contactless transaction, in which the consumer after authentication(using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data  PAN Primary account number. Know as a card number.  Payment Instrument Model keeping all data considering entity used for payments POS Point Of Sale QRC QR Code transactions - allows consumer generate QR code to present to a merchant, who then scans it to take payment  SUK Single Use Key - unique credential used for single transaction  Two tap  Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates(using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data TVC Token Verification Code EWS External Wallet Server What is UCP SDK? The UCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of UCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to UCP SDK using the Mobile DC module.payment How UCP SDK works? Provides methods to manage digitization using main domains: IBANs Payment Cloud Messaging Cards External Wallet Server Depending on the selected payment instrument source (Card, Iban, External Wallet Server) UCP SDK allows to digitize it and provide methods for the payment process. Usage of the following domains depends on client requirements. Versioning and backward compatibility SDK version contains three digits. For example: 1.0.0. First version digit tracks compatibility-breaking changes in SDK public APIs. It is mandatory to update the application code to use SDK when this is incremented . Second version digit tracks new, not compatibility-breaking changes in public API of SDK. It is optional to update the application code when this digit is incremented. Third version digit tracks internal changes in SDK. No updates in application code are necessary to update to the version, which has this number incremented. Changes not breaking compatibility: Adding a new optional interface to SDK setup Adding a new method to any domain Adding a new ENUM value to input or output Adding a new field in the input or output model Technical overview SDK Basic configuration The minSdkVersion must be at least 23 (Android 6.0). The application must use AndroidX.  SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system. The username and password are provided by Verestro. repositories{ maven { credentials { username "" password "" } 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" } } } UCP SDK is available in two versions: debug and release. Debug version is ended with appendix "-debug" in version name. Samples below: For release version: dependencies{ implementation 'pl.upaid.module:ucpsdk:{version}' } For debug version: dependencies{ implementation 'pl.upaid.module:ucpsdk:{version}-debug' } Min SDK Version The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest. SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it. UCP SDK Size The size of SDK is dependent on its distribution system. The table below shows the size of the module for the ask and bundle file. Format Size Notes APK ~15,8 MB Bundle ~3,4 MB - ~4.5 MB Ranged size depends on the ABI of the device. SDK contains native libraries used by different ABI. By using a bundle only the necessary version of the native library will be downloaded to a device. UCP size already includes Mobile DC SDK size. Additional information: size from the table above is referred to release version; size depends on configured proguard; UCP SDK Usage This chapter describes the structure and basic usage of UCP SDK. Domains Every of the described facades is divided into domains with different responsibilities. Available domains: IBANs Payment Cloud Messaging Cards External Wallet Server Every domain contains domain-related methods. Error handling Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods. SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message. Note : UCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module. Exception type Exception class Description SDK validation ValidationException Additional reason codes for ValidationException used in Mobile DC SDK  Backend exception BackendException Additional reason codes for BackendException used in Mobile DC SDK. Note: Not applicable for External Wallet Server domain  SDK exception UcpSdkException Something went wrong on the SDK side, check the table below with possible reasons  Process related - As every process is different some methods could throw a specified exception Types of possible exceptions are described in the method description Additional BackendException reason codes: Reason Description INTERNAL_ERROR Error occurred on server VALIDATION_ERROR Client sent invalid data CRYPTOGRAPHY_ERROR Error occurred during cryptography operation PAYMENT_CARD_PREDIGITIZE_ERROR Predigitize of payment card failed PAYMENT_IBAN_PREDIGITIZE_ERROR Predigitize of payment IBAN failed PAYMENT_CARD_DIGITIZE_ERROR Digitize of payment card failed PAYMENT_IBAN_DIGITIZE_ERROR Digitize of payment IBAN failed PAYMENT_CARD_PREDIGITIZE_NOT_EXECUTED Predigitize for payment card must be executed PAYMENT_IBAN_PREDIGITIZE_NOT_EXECUTED Predigitize for payment IBAN must be executed CLIENT_UNAUTHORIZED Client of the API is unauthorized USER_UNAUTHORIZED User is unauthorized CANT_FIND_USER Cannot find user CANT_FIND_DEVICE Cannot find device CANT_FIND_IBAN Cannot find payment IBAN CANT_FIND_CARD Cannot find payment card CANT_FIND_PAYMENT_TOKEN Cannot find payment token OPERATION_NOT_SUPPORTED Requested operation is not supported OPERATION_NOT_ALLOWED Requested operation is not allowed DEVICE_TEMPORARILY_LOCKED Device is temporarily locked DEVICE_PERMANENTLY_LOCKED Device is permanently locked INVALID_PAN The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly MISSING_EXPIRY_DATE The expiry date is required for this product but was missing PAN_INELIGIBLE The PAN is not in an approved account range for TSP DEVICE_INELIGIBLE The device is not supported for use PAN_INELIGIBLE_FOR_DEVICE The PAN is not allowed to be provisioned to the device because of Issuer rules IBAN_INELIGIBLE The financial account does not have an associated account range in TSP PARALLEL_REQUESTS_ATTEMPTS Action is already processing. Please try again after the time included in headers  INVALID_JWS_TOKEN Specified JWS token is invalid Additional ValidationException reason codes: Reason Description INVALID_SECURITY_CODE Security code is empty INVALID_LANGUAGE_CODE Language code is empty INVALID_PAYMENT_INSTRUMENT_ID Payment instrument id is empty UcpSdkException reason codes: Reason Description PUSH_INVALID_SOURCE Relates to push processing process. Push message should be consumed in another module PUSH_INVALID_PUSH_CONTENT Cannot process push message. The message is invalid or some process failed PAYMENT_INSTRUMENT_DEFAULT_NOT_FOUND Cannot find default PaymentInstrument PAYMENT_INSTRUMENT_NOT_FOUND Selected PaymentInstrument cannot be found, is not digitized or active APPLICATION_PROCESS_NOT_KILLED Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process Facade The facade is an entry point to communication with UCP SDK. Contains SDK initialization method and domains which allows for payment instrument management. Method structure Please read Mobile DC Documentation for details. Multiple facade types UCP SDK provides three public APIs with the same functionalities, the APIs are: UcpJavaApi for projects which use Java programming language. UcpKotlinApi for projects which use Kotlin programming language. The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same. This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark). HceApduService registration To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service. Properly configured meta-data in service will also register an application as tap&pay ready. Exemplary service below: Below listing of the default source file hce_apud_service.xml:   Check if the application is set as default for payment. fun isSystemDefault(): Boolean { val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context)) return cardEmulation.isDefaultServiceForCategory( WalletHceService::class.java, CardEmulation.CATEGORY_PAYMENT ) } Request for set your application as default for payment - will show a dialog for the user to approve the changes. 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) } If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.  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) } Models PaymentInstrument Parameter Type Description id String Id of payment instrument. For card it is cardId, for IBAN sha256Hex. In the context of the External Wallet Server use tokenUniqueReference from MDES paymentTokenId String Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id  displayablePanDigits String Token last 4 digits which can be used to display paymentInstrumentStatus PaymentInstrumentStatus Enum with status of payment instrument.  contactlessSupported Boolean Information if payment instrument supports contactless transactions.  dsrpSupported Boolean Information if the payment instrument supports DSRP transactions.  qrcSupported Boolean Information if the payment instrument supports QR transactions.  onDeviceCvmSupported Boolean Information about supporting CVM on device.  credentialsCount Int Amount of credentials that can be used for payments.  isDefaultForContactlessPayment Boolean Information if payment instrument is default for contactless payments.  isDefaultForRemotePayment Boolean Information if payment instrument is default for remote payments.  additionalAuthenticationRequired Boolean Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods tokenLastFourDigits String? Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). paymentInstrumentExpirationDate String? Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately). paymentInstrumentLastFourDigits String? Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). productConfig ProductConfig? Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately). PaymentInstrumentStatus Field Description INACTIVE Payment instrument is not active , it can not be used for transactions. The activation process depends on integration. Read the product overview for more information. ACTIVE Payment instrument is active and it can be used for transactions. SUSPENDED Payment instrument is suspended. DELETED Payment instrument is DELETED. UNKNOWN Payment instrument status is unknown. AdditionalAuthenticationMethod Parameter Type Description id String Identifier of additional authentication method  name String Method name. One of: OTP_TO_CARDHOLDER_NUMBER, OTP_TO_CARDHOLDER_EMAIL, CARDHOLDER_TO_CALL_CUSTOMER_SERVICE, CARDHOLDER_TO_VISIT_WEBSITE, CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION, ISSUER_TO_CALL_CARDHOLDER_NUMBER  value String Value depends on method name. Described below.  issuerParameters AuthMethodsIssuerParameters? Non null if method is CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION Additional authentication method values: Method Value Description OTP_TO_CARDHOLDER_NUMBER Masked phone number  Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number. OTP_TO_CARDHOLDER_EMAIL Masked email  Email to Account holder’s email address. The value will be the Account holder’s masked email address. CARDHOLDER_TO_CALL_CUSTOMER_SERVICE Phone number  Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service. CARDHOLDER_TO_VISIT_WEBSITE Website URL Account holder to visit a website. The value will be the website URL. CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION Application name (Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS. ISSUER_TO_CALL_CARDHOLDER_NUMBER Masked phone number Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number. AuthMethodsIssuerParameters contains the following fields: Parameter Type Description mdes AuthMethodsIssuerParametersMdes? Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token vts AuthMethodsIssuerParametersVts? Required for VTS Payment token AuthMethodsIssuerParametersMdes contains following fields: Parameter Type Description android AuthMethodsIssuerParametersMdesAndroid Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device ios AuthMethodsIssuerParametersMdesIos Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device AuthMethodsIssuerParametersMdesAndroid contains following fields: Parameter Type Description action String? Name of the action to be performed packageName String? The package name of the issuer's mobile app extraTextValue String? Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app AuthMethodsIssuerParametersMdesIos contains following fields: Parameter Type Description deepLinkingUrl String? The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. extraTextValue String? Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. AuthMethodsIssuerParametersVts contains following fields: Parameter Type Description android AuthMethodsIssuerParametersVtsAndroid? Plain AuthMethodsIssuerParametersVtsAndroid object. Required for Android devices ios AuthMethodsIssuerParametersVtsIos? Plain AuthMethodsIssuerParametersVtsIos object. Required for IOS devices AuthMethodsIssuerParametersVtsAndroid contains following fields: Parameter Type Description appId String? Unique identifier for the application within the application store. appUrl String? URL of the application in the application store. intentUrl String? URL of banking app designed to respond to authentication code handling. requestPayload String? The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers. AuthMethodsIssuerParametersVtsIos contains following fields: Parameter Type Description appId String? Unique identifier for the application within the application store. appUrl String? URL of the application in the application store. intentUrl String? URL of banking app designed to respond to authentication code handling. requestPayload String? The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers. ContactlessTransactionInformation Parameter Type Description currencyCode ByteArray Code of currency, that was used in transaction. Formatted in ISO 4271. amount ByteArray Transaction amount in bytes. Can be formatted as Int in pennies. transactionRange ContactlessTransactionRange Type of transaction range. richTransactionType ContactlessRichTransactionType Rich transaction type. merchantAndLocation ByteArray Merchant and location data from terminal. Can be formatted as String, by using UTF_8 Charset. ContactlessTransactionRange Value Description LVT Low value transaction HVT High value transaction UNKNOWN Unknown ContactlessRichTransactionType Value PURCHASE REFUND CASH TRANSIT PURCHASE_WITH_CASHBACK UNKNOWN DsrpTransactionInfo Parameter Type Descruption amount Long Transaction amount currencyCode Int Code of currency, that was used in transaction. countryCode Int Code of country. issuerCryptogramType String Cryptogram type. TransactionAbortReason Value Description WALLET_CANCEL_REQUEST Indicates that the wallet has requested a transaction cancellation during payment. CARD_ERROR This indicates that a problem has been detected in the MChipEngine processing. In some implementations, this can indicate badly formatted card profile data. TERMINAL_ERROR This indicates incorrect terminal behavior.  NO_TRANSACTION_CREDENTIALS  There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility. NO_CARDS There is no active PaymentInstrument to start payment . Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). TERMINAL_INACTIVITY_TIMEOUT There is a problem with communication between the terminal and payment device. For example, the terminal could abort communication with the mobile device for a long period of time and then trigger a timeout. Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal. The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment. Note:  When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again. NewTransaction Field Type Description clientTransactionId String? Identifier of transaction in TSP type String The transaction type. One of: [UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM_WITHDRAWAL, CASH_DISBURSEMENT, ATM_DEPOSIT, ATM_TRANSFER] amountMinor Long The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, and `BHD -1.345' will return -1345 currency String 3-digit ISO 4217 currency code timestamp String The date/time when the transaction occurred. In ISO 8601 extended format merchantName String? The merchant (``doing business as'') name merchantPostalCode String? The postal code of the merchant transactionCountryCode String? The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1 comboCardAccountType String? An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: [UNKNOWN, CREDIT, DEBIT] issuerResponseInformation String? Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: [UNKNOWN, INVALID_CARD_NUMBER, FORMAT_ERROR, MAX_AMOUNT_EXCEEDED, EXPIRED_CARD, PIN_AUTHORIZATION_FAILED, TRANSACTION_NOT_PERMITTED, WITHDRAWL_AMOUNT_EXCEEDED, RESTRICTED_CARD, WITHDRAWL_COUNT_EXCEEDED, PIN_TRIES_NUMBER_EXCEEDED, INCORRECT_PIN, DUPLICATE_TRANSMISSION] status String The authorization status of the transaction. One of: [AUTHORIZED, DECLINED, CLEARED, REVERSED] paymentTokenId String Identifier of payment token in UCP ContactlessTransactionData Parameter Type Description currencyNumber Int Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. currencyCode String? Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN Could be null as the terminal provides only the currencyNumber and a valid code could be not found. amountMinor Long The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, transactionRange ContactlessTransactionRange Type of transaction range. richTransactionType ContactlessRichTransactionType Rich transaction type. merchantAndLocation String Merchant and location data from terminal. Deprecated - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data. ContactlessTransactionRange Value Description LVT Low value transaction HVT High value transaction UNKNOWN Unknown ContactlessRichTransactionType Value Description PURCHASE REFUND CASH TRANSIT PURCHASE_WITH_CASHBACK UNKNOWN WITHDRAWAL ATM_CONTACTLESS Report Parameter Type Description name String Action name description String Action details message. isSuccess Boolean Result of action. True when action is finished successfully, false otherwise. timestamp Long Time when the action occurred. errorMessage String? Detailed error message when isSuccess is false. ContactlessAdvice Parameter Description DECLINE Declines a processing transaction. When provided by SDK in getFinalDecisionForTransaction wallet should not overrule a DECLINE. If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response. AUTHENTICATION_REQUIRED An user authentication is required for transaction processing, which could be overruled on the MPA side. When the MPA decision is AUTHENTICATION_REQUIRED, SDK will ask for user authentication in the onAuthRequiredForContactless method. PROCEED Transaction can be processed. ContactlessTransactionResult Important: MPA should always refer to transaction results on the terminal. Value Description Is success on MPA side AUTHORIZE_ONLINE This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization. The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal. Should be treated as transaction success on the MPA side. Yes AUTHENTICATE_OFFLINE This indicates that the POS requested a decline (AAC) with a CDA signature. SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature. Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization. Should be treated as transaction success on the MPA side. Yes DECLINE_BY_TERMINAL The POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request. Paying on the terminal with offline-only network connectivity can also return this callback. Application Cryptogram was generated with genuine credentials. Should be treated as transaction success on the MPA side. Yes DECLINE_BY_CARD The digitized card has declined the transaction. A non-exhaustive list of possible reasons may be: Context mismatch between first and second tap Terminal is offline-only Terminal is a transit gate, and transit transactions are not allowed by the card profile Transaction is international, while the card profile is domestic-only No WALLET_ACTION_REQUIRED If the getFinalDecisionForTransaction returns an AUTHENTICATION_REQUIRED status then this result will be returned. The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap. If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place. No External libraries The SDK uses several external Apache 2.0 libraries: com.nimbusds:nimbus-jose-jwt commons-codec:commons-codec com.fasterxml.jackson.core:jackson-core com.fasterxml.jackson.core:jackson-annotations com.fasterxml.jackson.core:jackson-databind com.fasterxml.jackson.module:jackson-module-kotlin io.insert-koin:koin-android io.reactivex.rxjava2:rxjava io.reactivex.rxjava2:rxandroid com.squareup.retrofit2:adapter-rxjava2 com.squareup.retrofit2:retrofit com.squareup.retrofit2:converter com.squareup.okhttp3:logging com.squareup.okhttp3:okhttp com.google.zxing:core net.sf.flexjson:flexjson UCP SDK Setup UCP SDK has to be configured every time when is used. Before UCP SDK usage Mobile DC SDK should be already configured. setup 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. Important: Before calling UCP 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. Input Parameter Type Description Validation conditions ucpConfiguration UcpConfiguration UCP configuration provided in builder described below. Not empty. UcpConfigurationBuilder contains the following methods: Metod Parameter Description Validation conditions withApplication Application Application context. Not empty withCvmModel WalletCvmModel (enum) Customer Verification Method: CDCVM_ALWAYS, FLEXIBLE_CDCVM, CARD_LIKE Not empty withUserAuthMode WalletAuthMode (enum) User authentication mode: WALLET_PIN, CUSTOM, NONE Contact Verestro to select proper configuration Not empty withUcpPaymentInstrumentEventListener UcpPaymentInstrumentEventListener Global listener for actions on PaymentInstrument. Not empty withUcpTransactionEventListener UcpTransactionEventListener Global listener for actions during transaction processing Not empty withTransactionAcceptanceEventListener UcpTransactionAcceptanceEventListener Global listener which allow application take final decision about transaction acceptance during transaction Not empty withReplenishThreshold Int Number of credentials below which replenish process will automatically begin Not empty withMcbpPinningCertificates List List of public key certificates in PEM format. Pass list with empty String if withOptionalUcpMcbpHttpExecutor mentioned below is used with custom HTTP communication. Not empty List withOptionalEventsReports UcpEventReportListener Global listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. Optional withOptionalExternalWalletServer Boolean Prepares SDK for using external wallet server. Optional withOptionalUcpMcbpHttpExecutor UcpMcbpHttpExecutor/DefaultUcpMcbpHttpExecutor Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. Optional withOptionalUcpReProvisionEventListener UcpReProvisionEventListener Global listener for actions during reprovisioning. Optional UcpPaymentInstrumentEventListener Contains callbacks for PaymentInstrument. Method name Parameters Description onProvisioningSuccess paymentInstrument: PaymentInstrument Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below onProvisioningFailure errorMessage: String?, exception: Exception? Method called after provisioning failure. Try processing digitization again onReplenishSuccess paymentInstrument: PaymentInstrument numberOfTransactionCredentials: Int Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials. Depending on flow is called after activation process and when requested by SDK based on replenishThreshold configuration. Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row  onReplenishFailure paymentInstrument: PaymentInstrument, errorMessage: String?, exception: Exception? Method called after replenish failure with PaymentInstrument Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row onPaymentInstrumentStatusChanged newStatus: PaymentInstrumentStatus paymentInstrumentId: String Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id onNewTransaction newTransaction: NewTransaction Provides online result with details of transaction processed in UCP Works only when application is online UcpTransactionEventListener Callbacks related to transaction process. Important:  It's recommended to not do complex process in there callbacks. It could  significantly  affect on transaction processing time. Method name Parameters Description onAuthRequiredForContactless paymentInstrument: PaymentInstrument, transactionInformation:  ContactlessTransactionInformation transactionData: ContactlessTransactionData Called when user authentication is required during contactless transaction ContactlessTransactionInformation is deprecated in version 2.2.4. onAuthRequiredForDsrp paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo Called when user authentication is required during Dsrp transaction onAuthTimerUpdated secondsRemaining: Int Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration onContactlessPaymentCompleted paymentInstrument: PaymentInstrument transactionInformation: ContactlessTransactionInformation transactionResult: ContactlessTransactionResult transactionData : ContactlessTransactionData Called when transaction is completed with information about transaction and result. ContactlessTransactionInformation is deprecated in version 2.2.4. onContactlessPaymentIncident paymentInstrument: PaymentInstrument, exception: Exception Called when something went wrong during transaction and Mastercard marked transaction as incident onContactlessPaymentAborted paymentInstrument: PaymentInstrument?, abortReason: TransactionAbortReason, exception: Exception Called when transaction is aborted during payment from some reason described in method parameter PaymentInstrument could be null if abortReason = TransactionAbortReason.NO_CARDS is returned. onTransactionStopped Method called on transaction stopped by SDK UcpTransactionAcceptanceEventListener Callbacks related to transaction process. Important:  It's recommended to not do complex process in there callbacks. It could  significantly  affect on transaction processing time. Method name Parameters Description getFinalDecisionForTransaction isUserAuthenticated : Boolean recommendedAdvice : ContactlessAdvice trasactionInformation : ContactlessTransactionInformation transactionData : ContactlessTransactionData Called on every transaction for the final decision about transaction processing An application can decide based on information about authentication, transaction details like amount, currency, and transaction types The method also provide recommended by MCBP advice  based on  transaction ContactlessTransactionInformation is deprecated in version 2.2.4. UcpEventReportsListener Method name Parameters Description onNewReport report: Report Return logs related to token management. UcpReProvisionEventListener Called when transaction is completed with information about transaction and result. ContactlessTransactionInformation is deprecated in version 2.2.4. Method Name Parameters Description onReProvisionSuccess paymentInstrument: PaymentInstrument Method called after reProvisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback. onReProvisionFailure paymentInstrument : PaymentInstrument errorMessage : String? exception : Exception? Method called after reProvisioning failure. Try again. UcpMcbpHttpExecutor Method name Parameters Description execute ucpMcbpRequestType: UcpMcbpHttpExecutorRequestTypeucpMcbpHttpMethod: UcpMcbpHttpMethodurl: StringrequestData: AnyrequestProperties: Map Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse. requestData could be one of request data type: UcpMcbpRequestSessionRequestData, UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData, UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData. ucpMcbpHttpMethod could be one of: POST, GET. ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION, NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE. DefaultUcpMcbpHttpExecutor Method name Parameters Description execute ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType ucpMcbpHttpMethod: UcpMcbpHttpMethod url: String requestData: Any requestProperties: Map Called on every time if SDK want to connect to MasterCard and should return super.execute method. requestData could be one of request data type: UcpMcbpRequestSessionRequestData, UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData, UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData. ucpMcbpHttpMethod could be one of: POST, GET. ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION, NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE. Output No output. Sample UcpTransactionEventListener // 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 } 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() { //transaction is stopped by SDK, inform user and try again } } UcpPaymentInstrumentEventListener 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 } } UcpTransactionAcceptanceEventListener class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener { //Sample implementation of transaction acceptance listener 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 } } UcpEventReportsListener class BankReportEventListener : UcpEventReportsListener { override fun onNewReport(report: Report) { //print log for debugging, etc. } } UcpMcbpHttpExecutor //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 ): 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) } } } } DefaultUcpMcbpHttpExecutor //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 ): UcpMcbpHttpResponse { //additional action before request return super.execute( ucpMcbpRequestType, ucpMcbpHttpMethod, url, requestData, requestProperties ) } } UcpReProvisionEventListener 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. } } Sample UCP SDK setup implementation: fun setup( application: Application, walletCvmModel: WalletCvmModel, walletAuthUserMode: WalletAuthUserMode, mcbpPinningCertificates: List, 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()) ) UcpApiKotlin().setup(ucpConfiguration) } reset (DEPRECATED - use restart instead) 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. Input No input. Output No output. Sample Sample UCP SDK reset implementation: fun reset() { UcpApiKotlin().reset() //Terminating JVM according to MC SDK Sample Application Runtime.getRuntime().exit(0); } restart 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. Input No input. Output 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. Sample Sample UCP SDK reset implementation: 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 }) Cards domain delete Asynchronous. Online.| Method allows delete PaymentInstument from UCP. Payment token will be removed remote and local storage. Result of action will be notified with onPaymentInstrumentStatusChanged . Input Parameter Type Description Validation conditions paymentInstrumentId String Id of PaymentInstrument to delete Not empty. reason CharArray? Optional reason of deletion Output Success / failure callback Sample 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 } ) } checkEligibility Asynchronous. Online. Check eligibility required to process digitize. Input Parameter Type Description checkEligibility CheckEligibility CheckEligibility object CheckEligibility Parameter Type Description paymentInstrumentId String Identifier of payment instrument paymentInstrumentType PaymentInstrumentType Payment instrument type. One of: [MASTERCARD] userLanguage String User language userCountry String User country Output Success callback with CheckEligibilityResult. CheckEligibilityResult Parameter Type Description termsAndConditionsAssetId String Identifier of Terms and Conditions asset Failure callback Sample 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 } ) } digitize  Asynchronous. Online. Use only when checkEligibility method is used. Creates payment token in UCP backend. Expect push after successful finish and then proceed using process method in Cloud Messaging domain. Input Parameter Type Description Validation conditions digitizationRequest DigitizationRequest Plain object of DigitizationRequest Not empty DigitizationRequest object contains following fields: Parameter Type Description Validation conditions paymentInstrumentId String Identifier of payment instrument Not empty paymentInstrumentType PaymentInstrumentType Payment instrument type. One of: [MASTERCARD] Not empty securityCode CharArray? Optional. The CVC2 for the card to be digitized Not empty Output Success callback with DigitizationResult object Parameter Type Description digitizationResult DigitizationResult Plain object of DigitizationResult DigitizationResult contains following fields. Parameter Type Description paymentInstrument PaymentInstrument Plain object of PaymentInstrument additionalAuthenticationMethods List? All available additional authentication method productConfig ProductConfig Plain object of ProductConfig, contains Payment Token configuration ProductConfig contains following fields. Parameter Type Description isCoBranded Boolean Whether the product is co-branded coBrandName String? Name of the co-branded partner foregroundColor String Foreground color, used to overlay text on top of the card image backgroundColor String Background color, used to overlay text on top of the card image labelColor String? Label color of the mobile wallet entry for the card issuerName String Name of the issuing bank shortDescription String A short description for this product longDescription String? A long description for this product custoremServiceUrl String? Customer service website of the issuing bank customerServiceEmail String? Customer service email address of issuing bank customerServicePhoneNumber String? Customer service phone number of the issuing bank productConfigIssuer ProductConfigIssuer? Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app onlineBankingLoginUrl String? Login URL for the issuing bank's online banking website termsAndConditionsUrl String? URL linking to the issuing bank's terms and conditions for this product privacyPolicyUrl String? URL linking to the issuing bank's privacy policy for this product issuerProductConfigCode String? Freeform identifier for this product configuration as assigned by the issuer contactName String? Name of the issuing bank bankAppName String? Name of banking application for display bankAppAddress String? The package name for the destination mobile application unsupportedPresentationTypes String? The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request unsupportedCardVerificationTypes String? The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) issuerFlags List? List of plain ProductConfigIssuerFlags object. Contains issuer flags brandLogoAssetId String The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID issuerLogoAssetId String The logo of the issuing bank. Provided as a Asset ID coBrandLogoAssetId String? The co-brand logo (if any) for this product. Provided as an Asset ID cardBackgroundCombinedAssetId String? The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID cardBackgroundAssetId String? The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID iconAssetId String The icon representing the primary brand(s) associated with this product. Provided as an Asset ID ProductConfigIssuer contains following fields. Parameter Type Description openIssuerAndroidIntent ProductConfigOpenIssuerAndroidIntent? AndroidIntent object can be used to open the issuer mobile app activateWithIssuerAndroidIntent ProductConfigActivateWithIssuerAndroidIntent? AndroidIntent object can be used to open the issuer mobile app openIssuerIOSDeepLinkingUrl ProductConfigOpenIssuerIOSDeepLinkingUrl? IOSDeepLinkingUrl object can be used to open the issuer mobile app activateWithIssuerIOSDeepLinkingUrl ProductConfigActivateWithIssuerIOSDeepLinkingUrl? IOSDeepLinkingUrl object can be used to open the issuer mobile app ProductConfigOpenIssuerAndroidIntent contains following fields. Parameter Type Description action String The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent packageName String The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app extraTextValue String Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object ProductConfigActivateWithIssuerAndroidIntent contains following fields. Parameter Type Description action String The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent packageName String The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app extraTextValue String Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields. Parameter Type Description deepLinkinUrl String The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app extraTextValue String Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields. Parameter Type Description deepLinkingUrl String The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app extraTextValue String Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object ProductConfigIssuerFlags contains following fields. Parameter Type Description deviceBinding Boolean Device binding cardholderVerification Boolean Whether the issuer participating in step-up flow trustedBeneficiaryEnrollment Boolean Whether this is a trusted beneficiary enrollment delegateAuthenticationSupported String Whether issuer supports delegated authentication Failure callback Sample 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 } ) } digitize Asynchronous. Online. Creates payment token in UCP backend. Expect push after successful finish and then proceed using process method in Cloud Messaging domain. Input Parameter Type Description Validation conditions paymentInstrumentId String Identifier of payment instrument Not empty. userLanguage String Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code Not empty. securityCode CharArray? Optional. The CVC2 for the card to be digitized Output Success / failure callback Sample 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 } ) } getAdditionalAuthenticationMethods Asynchronous. Online. Retrieves additional user authentication methods. Input Parameter Type Description Validation conditions getAdditionalAuthenticationMethods GetAdditionalAuthenticationMethods Plain object of GetAdditionalAuthenticationMethods Not empty Fields of GetAdditionalAuthenticationMethods object: Parameter Type Description paymentInstrumentId String Identifier of payment instrument Output Success callback with AdditionalAuthenticationMethods object. Parameter Type Description additionalAuthenticationMethods AdditionalAuthenticationMethods Object carrying list of AdditionalAuthenticationMethod AdditionalAuthenticationMethods contains following value: Parameter Type Description additionalAuthenticationMethods List List of AdditionalAuthenticationMethod objects Failure callback. Sample private fun getAdditionalAuthenticationMethods() { val getAdditionalAuthenticationMethod = GetAdditionalAuthenticationMethods("paymentInstrumentId") ucpApi .cardsService .getAdditionalAuthenticationMethods( getAdditionalAuthenticationMethod, { additionalAuthenticationMethods -> //Handle result }, { throwable -> //Something went wrong, check exception with documentation }) } submitTokenAuthenticationValue Asynchronous. Online. Submit authentication code when additional user authentication is required. Input Parameter Type Description paymentInstrumentId String Identifier of payment instrument authenticationCode String Authentication code Output Success callback/failure callback. Sample private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) { ucpApi.cardsService .submitAuthenticationValue( SubmitAuthenticationValue( paymentInstrumentId, authenticationCode ), { //Handle success }, { throwable -> //Something went wrong, check exception with documentation } ) } submitTokenAuthenticationMethod Asynchronous. Online. Submit authentication method when additional user authentication is required. Input Parameter Type Description paymentInstrumentId String Identifier of payment instrument authenticationMethodId String Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. Output Success callback/failure callback. Sample private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) { ucpApi.cardsService .submitAuthenticationMethod( SubmitAuthenticationMethod( paymentInstrumentId, authenticationMethodId ), { //Handle success }, { throwable -> //Something went wrong, check exception with documentation } ) } getAllPaymentInstruments 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. Input Parameter Type Description Validation conditions refresh Boolean Refresh all PaymentInstrument objects state with remote UCP server (network and user session required) Output Success callback with list of PaymentInstrument objects. Parameter Type Description paymentInstruments List List of retrieved payment instruments from local or remote storage Failure callback. Sample 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 } ) } getPaymentInstrument (deprecated) 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. Input Parameter Type Description Validation conditions paymentInstrumentId String Id of instrument to retrieve Not empty refresh Boolean Refresh selected PaymentInstrument state with remote UCP server (network required) Output Success callback with PaymentInstument object. Parameter Type Description paymentInstrument PaymentInstrument Retrieved payment instrument Failure callback. Sample 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 } ) } IBANs domain digitize Asynchronous. Online. Registers user and device if already not registered in UCP backend. Creates payment token in UCP backend. Expect push after successfull finish and then proceed using process method in Cloud Messaging domain. Input Parameter Type Description Validation conditions signedAccountInfo String Signed AccountInfo per RFC 7519 Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation Not empty. fcmRegistrationToken CharArray FCM Cloud messaging registration token Not empty. languageCode String Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code Not empty. AccountInfo: Parameter Type Description Validation conditions userId String External user id Not empty. iban String Bank Account Number Not empty. countryCode String The country of the financial account Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 Not empty. Output 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. IbanDigitizationResult contains following fields: Parameter Type Description (DEPRECATED) cloudDigitizationSuccess Boolean Cloud Token Digitization Details result CloudDigitizationResult Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN Failure callback. Called when device token digitization finished with failure. Sample Sample generation of  signedAccountInfo  (see  Data signing and encryption  chapter in Mobile DC documentation) 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 } ) } createTVC Asynchronous. Online. Provides Transaction Verification Code required to process cloud payments. Input Parameter Type Description Validation conditions signedIbanInfo String Signed IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation Not empty. IbanInfo Parameter Type Description Validation conditions ibanId String Iban id returned in addUserWithIban methdod or sha256Hex(iban) Not empty. Output Success callback with Tvc object or encrypted Tvc object as String. Parameter Type Description plainTvc PlainTvc? Plain PlainTvc object encryptedTvc CharArray? Encrypted PlainTvc object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation PlainTvc object contains following fields. Parameter Type Description accountNumber CharArray Primary Account Number for the transaction – this is the Token PAN dynamicExpiryDate CharArray Dynamic expiration date for the token. Expressed in YYMM format dynamicCVC CharArray Dynamic CVC Failure callback when TVC cannot be created. Sample Sample generation of  signedIbanInfo  (see  Data signing and encryption  chapter in Mobile DC documentation) 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 }) } createPaymentData 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. Input Parameter Type Description Validation conditions signedIbanInfo String Signed IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation Not empty. IbanInfo Parameter Type Description Validation conditions ibanId String Iban id returned in addUserWithIban methdod or sha256Hex(iban) Not empty. userId String External user id given by the client Not empty. Output Success callback with PaymentData object or encrypted payment data object as String. Parameter Type Description plainPaymentData PlainPaymentData? Plain PlainPaymentData object encryptedPaymentData String? Encrypted PlainPaymentData object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation PlainPaymentData object contains following fields. Parameter Type Description accountNumber String Primary Account Number for the transaction – this is the Token PAN applicationExpiryDate String? Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format panSequenceNumber String? Rrquired only for UCAF. Application PAN sequence number for the Token track2Equivalent String? Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed ucafCryptogram String? Required only for UCAF. UCAF cryptogram dynamicExpiryDate String? Dynamic expiration date for the token. Expressed in YYMM format dynamicCVC String? Dynamic CVC Failure callback when PaymentData cannot be created. Sample Sample generation of  signedIbanInfo  (see  Data signing and encryption  chapter in Mobile DC documentation) 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 }) } getAllPaymentInstruments 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. Input Parameter Type Description Validation conditions refresh Boolean Refresh all PaymentInstrument objects state with remote UCP server (network required) Output Success callback with list of PaymentInstrument objects Parameter Type Description paymentInstruments List List of retrieved payment instruments Failure callback Sample 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 } ) } getPaymentInstrument(deprecated) 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.  Input Parameter Type Description Validation conditions paymentInstrumentId String Id of instrument to retrieve. Not empty refresh Boolean Refresh selected PaymentInstrument state with remote UCP server (network required) Output Success callback with PaymentInstument object Parameter Type Description paymentInstrument PaymentInstrument Retrieved payment instrument Failure callback Sample 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 } ) } delete Asynchronous. Online. Method allows delete PaymentInstument from UCP. Payment token will be removed remote and local storage. Result of action will be notified with onPaymentInstrumentStatusChanged . Input Parameter Type Description Validation conditions paymentInstrumentId String Id of PaymentInstrument to delete Not empty. reason CharArray? Optional reason of deletion Output Success / failure callback Sample 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 } ) } Payment domain setDefaultForContactless 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. Input Parameter Type Description Validation conditions paymentInstrumentId String Payment instrument identity Not empty Output Success / failure callback Sample 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 }) } getDefaultForContactless Asynchronous. Offline.Provides default PaymentInstrument for contactless payment. Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. Input No input parameters Output Success callback with id new default PaymentInstrument Parameter Type Description paymentInstrument PaymentInstrument Default Payment instrument Failure callback. Sample fun getDefaultForContactless() { ucpApi.paymentService .getDefaultForContactless({ paymentInstrument -> // use PaymentInstrument }, { throwable -> when (throwable) { is DefaultPaymentInstrumentNotFoundException -> { //there is no default PaymentInstrument } else -> { //check another exception with documentation } } }) } setDefaultForRemote (deprecated) 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. Input Parameter Type Description Validation conditions paymentInstrumentId String Payment instrument identity Not empty Output Success / failure callback Sample 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 }) } getDefaultForRemote (deprecated) Asynchronous. Offline. Provides default PaymentInstrument for remote payments. Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. Input No input parameters Output Success callback with id new default PaymentInstrument Parameter Type Description paymentInstrument PaymentInstrument Default Payment instrument Failure callback. Sample fun getDefaultForRemote() { ucpApi.paymentService .getDefaultForRemote({ paymentInstrument -> // use PaymentInstrument }, { throwable -> when (throwable) { is DefaultPaymentInstrumentNotFoundException -> { //there is no default PaymentInstrument } else -> { //check another exception with documentation } } }) } selectForPayment Asynchronous. Offline. Sets payment instrument as primary for next incoming contactless payment. Input Parameter Type Description Validation conditions paymentInstrumentd String Payment instrument identity Not empty Output Success / failure callback Sample 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 }) } setUserAuthenticatedForPayment Asynchronous. Offline. Sets user as authenticated to payment with provided payment instrument. Authentication will expiry automatically after transaction time configured in payment instrument profile. Note: User can be authenticated based on conditions like screen unlock.  Method must be called before payment in declared HostApduService (sample below). Make sure that authentication on this step is done securely. Transaction information are not available in this scenario. Input Parameter Type Description Validation conditions paymentInstrumentId String Payment instrument identity Not empty pin CharArray? PIN or null for CUSTOM WalletAuthUserMode Output Success / failure callback Sample Basic user authentication usage below, call when user is authenticated. 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 }) } Optional authentication before making transaction based on custom conditions. class WalletHceService : HostApduService() { // ... private var authenticationAlreadyProcessed = false override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? { Logs.d("**** processCommandApdu") //check conditions like screen unlock etc val isUserAuthenticated = true //make sure that user already not trying to pay another way. //f.e. user selected PaymentInstrument (paymentService::selectForPayment) // or/and is already authenticated with setUserAuthenticatedForPayment method val shouldAllowToSuchFlow = true if (shouldAllowToSuchFlow && !authenticationAlreadyProcessed && isUserAuthenticated) { ucpApi .paymentService .setUserAuthenticatedForPayment( getSelectedPaymentInstrumentId(), null, //or pin { //user authenticated //make sure authentication is done only one time, clear it in onDeactivate method authenticationAlreadyProcessed = true }, { //authentication failure, check exception } ) } return ucpApi .paymentService .processHceApduCommand(this, commandApdu, extras) } override fun onDeactivated(reason: Int) { //clear flag for next transaction authenticationAlreadyProcessed = false return ucpApi .paymentService .handleHceApduDeactivationEvent(reason) } // more code implementation } abortUserAuthenticationForPayment Asynchronous. Offline. Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped. Input No input parameters Output Success / failure callback Sample fun abortUserAuthenticationForPayment() { ucpApi .paymentService .abortUserAuthenticationForPayment( { //user authentication aborted //listen for auth timer changes }, { throwable -> //some error, check exception }) } processHceApduCommand 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. Input Parameter Type Description Validation conditions context Context Application context, can be provided from HostApduService Not empty apdu ByteArray APDU command from HostApduService::processCommandApdu method parameter Not empty extras Bundle? Extras object from HostApduService::processCom mandApdu method parameter Output Apdu result - method called synchronous without callback Parameter. Type Description apdu ByteArray APDU command to return in implementation of overridden processCommandApdu method Sample //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) } //.. } replenishCredentials 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.  Input Parameter Type Description Validation conditions paymentInstrumentId String Id of paymentInstrument that needs it credentials replenished Not empty Output Success / failure callback Sample 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 }) } restartContactlessAuthTimer 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. Input No input parameters Output Success / failure callback requestAuthenticationCodeForPayment 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. Input Parameter Type Description Validation conditions requestAuthenticationCodeForPayment RequestAuthenticationCodeForPayment Plain RequestAuthenticationCodeForPayment object Not empty RequestAuthenticationCodeForPayment object contains following fields Parameter Type Description Validation conditions paymentInstrumentId String Identifier of payment instrument Not empty authenticationRequestId String Authentication request id up to 64 alphanumeric characters long. A new id should be used for each instance than an account holder needs to be authenticated Not empty Output Success callback/failure callback. Sample fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) { ucpApi.paymentService .requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment, { //Requesting Authentication Code went successfully. }, { throwable -> //Something went wrong, check exception with documentation } ) } validateAuthenticationCodeForPayment 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. Input Parameter Type Description Validation conditions validateAuthenticationCodeForPayment ValidateAuthenticationCodeForPayment Plain ValidateAuthenticationCodeForPayment object Not empty ValidateAuthenticationCodeForPayment object contains following fields Parameter Type Description Validation conditions paymentInstrumentId String Identifier of payment instrument Not empty authenticationRequestId String Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. Not empty authenticationCode String Authentication Code to authenticate the account holder Not empty Output Success callback with ValidateAuthenticationCodeForPaymentResult object. ValidateAuthenticationCodeForPaymentResult object contains following field Parameter Type Description signedAuthenticationProcessData String Signed AuthenticationProcessData per RFC 7519 AuthenticationProcessData model Parameter Type Description authenticationRequestId String Authentication request id Sample 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 } ) } Sample verification of signedAuthenticationProcessData (see  Data signing and encryption  chapter in Mobile DC documentation) class SignedAuthenticationProcessData { fun verifyAndGetAuthenticationRequestID() { val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600); val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId") // ... } } processDsrpTransaction(deprecated) Asynchronous. Online. Input Parameter Type Description Validation conditions paymentInstrumentId String Payment instrument identity Not empty dsrpTransactionInfo DsrpTransactionInfo Output Success callback with cryptogram for payment Failure callback processDsrpTransaction Asynchronous. Online. Method dedicated for starting DSRP transaction. Every DSRP transaction has to be authenticated. Depending on implementation payment can be process with OTP authentication or device level authentication. Parameter Type Description Validation conditions processDsrpTransaction ProcessDsrpTransaction Plain ProcessDsrpTransaction object Not empty ProcessDsrpTranasction object contains following fields Parameter Type Description Validation conditions paymentInstrumentId String Identifier of payment instrument Not empty dsrpTransactionInfo DsrpTransactionInfo Plain DsrpTransactionInfo object Not empty DsrpTransactionInfo object contains following fields Parameter Type Description Validation conditions amount Long A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 Not empty currencyCode Int A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. Not empty countryCode Int A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. Not empty issuerCryptogramType String Value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. Not empty Output Success callback with ProcessDsrpTransactionResult object. ProcessDsrpTransactionResult object contains following field Parameter Type Description transactionResult String String contains information regarding weather the request was successful, and if so, further information about the transaction state. Sample DSRP transaction with device level authentication // 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) { ucpApi.paymentService .processDsrpTransaction( processDsrpTransactionResult, { val transactionResult = processDsrpTranasctionResult.transactionResult //Information if DSRP transaction went successfully result //should be delivered to Merchant APP }, { throwable -> //Something went wrong, check exception with documentation } ) } Sample DSRP transaction with OTP authentication // 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) { ucpApi.paymentService .processDsrpTransaction( processDsrpTransactionResult, { val transactionResult = processDsrpTranasctionResult.transactionResult //Information if DSRP transaction went successfully result //should be delivered to Merchant APP }, { throwable -> //Something went wrong, check exception with documentation } ) } Cloud messaging domain process Asynchronous. Online. Processes data sent by UCP 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. Input Parameter Type Description Validation conditions pushData Map Data received from notification service in object RemoteMessage object Not empty Output Success / failure callback. When request fails try again Sample //FirebaseMessagingService class from Firebase override fun onMessageReceived(remoteMessage: RemoteMessage) { super.onMessageReceived(remoteMessage) val senderId: String = remoteMessage.from val pushData = remoteMessage.data //check push source only when push source is uPaid sender Id if (isUpaidSenderId(senderId)) { //checking push source and passing to proper uPaid module mobileDcApi .cloudMessagingService .getSource(pushData, { source -> when (source) { "UCP" -> processUcpPush(pushData) } }, { //some error }) } else { //proceed push from another source } } private fun processUcpPush(pushData: Map) { ucpApi .cloudMessagingService .process(pushData, { //push processed in Mobile DC }, { //some error }) } processMcbpNotificationData Asynchronous. Online. Processes data sent by MC BP. Application should check senderId in RemoteMessage object before passing data to UCP 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. Input Parameter Type Description Validation conditions encryptedPayload String Data received from notification service in object RemoteMessage object Not empty Output 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 } } External Wallet Server domain Chapter contains method for SDK when External Wallet Server is used. Usage of method requires additional configuration with external API. Basic MDES  cloud messaging configuration: Environment FCM Sender Id MTF 502118574555 PRODUCTION 993764297204 prepareRegistrationData Asynchronous. Offline. Method for preparing data used for activation. Should be used before calling register method. Input Parameter Type Description Validation conditions paymentAppInstanceId String Identifier for the specific Mobile Payment App instance Not empty paymentAppProviderId String Globally unique identifier for the Wallet Provider, as assigned by MDES Not empty publicKeyCertificate String CMS-D public key certificate in pem format Not empty mobilePin CharArray? Mobile PIN used to payment confirmation Output Success callback with PrepareRegistrationResponse object. Parameter Type Description publicKeyCertificateFingerprint String CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) encryptedRgk String Encrypted randomly-generated 128-bit AES key. deviceInfo EwsDeviceInfo Device info. deviceFingerprint String Unique device fingerprint. encryptedPin String? Encrypted pin (if passed in input). EwsDeviceInfo  model: Parameter Type Description deviceName String Device model name. formFactor String The form factor of the target provisioned device. storageTechnology String The architecture or technology used for token storage. osName String The name of the operating system of the target provisioned device. osVersion String The version of the operating system of the target provisioned device. nfcCapable Boolean Whether the target provisioned device has NFC capability. Failure callback Sample 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 } ) } register Asynchronous. Online. Method used for registration new Mobile Payment App instance with MDES for use. Input Parameter Type Description Validation conditions mobileKeysetId String Identifies the Mobile Keys used for this remote management session Not empty ewsMobileKeys EwsMobileKeys Contains the mobile keys used to secure the communication during subsequent remote management sessions Not empty remoteManagementUrl String The URL endpoint for subsequent remote management sessions The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions Not empty EwsMobileKeys  model: Parameter Type Description transportKey String The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES macKey String The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES dataEncryptionKey String The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES Output Success / failure callback Sample 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 } ) } activate 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. Input Parameter Type Description Validation conditions paymentInstrumentId String Id of paymentInstrument to activate. Not empty. Output Success / failure callback Sample 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 } ) } suspend Asynchronous. Offline. Method for suspending paymentInstrument. Changes PaymentInstrumentStatus to SUSPENDED . Use activate method to allow payments again. Input Parameter Type Description Validation conditions paymentInstrumentId String Id of paymentInstrument to suspend. Not empty. Output Success / failure callback Sample fun suspend(paymentInstrumentId: String) { ucpApi .ewsService .suspend(paymentInstrumentId, { //Changes PaymentInstrumentStatus to SUSPENDED. }, { throwable -> //Something went wrong, check exception with documentation } ) } getPaymentInstrument Asynchronous. Offline. Method for getting single PaymentInstrument from local storage object based on id. Input Parameter Type Description Validation conditions paymentInstrumentId String Id of paymentInstrument to get. Not empty. Output Success callback with PaymentInstrument object. Parameter Type Description paymentInstrument PaymentInstrument Retrieved paymentInstrument Failure callback. Sample fun getPaymentInstrument(paymentInstrumentId: String) { ucpApi.ewsService .getPaymentInstrument(paymentInstrumentId, { paymentInstrument -> //PaymentInstrument from local storage }, { throwable -> //Something went wrong, check exception with documentation } ) } getAllPaymentInstruments Asynchronous. Offline. Method for getting all payment instruments from local storage. Input No input parameters Output Success callback with list of PaymentInstrument objects. Parameter Type Description paymentInstruments List List of retrieved payment instruments from local storage Failure callback. Sample fun getAllPaymentInstrument() { ucpApi.ewsService .getAllPaymentInstruments( { paymentInstruments -> //List of PaymentInstrument from local storage }, { throwable -> //Something went wrong, check exception with documentation } ) } getEncryptedPin Asynchronous. Offline.| Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged. Input Parameter Type Description Validation conditions pin CharArray PIN to encrypt. Not empty. Output Success callback with encrypted mobile PIN. Parameter Type Description encryptedMobilePin String Hex encoded encrypted mobile PIN. Failure callback. Sample 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 }) } onMobilePinChanged 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. Input No input parameters Output Success / failure callback Sample 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. }) } delete  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. Input Parameter Type Description Validation conditions paymentInstrumentId String Id of paymentInstrument to delete. Not empty. Output Success / failure callback Sample fun delete(paymentInstrumentId: String) { ucpApi .ewsService .delete(paymentInstrumentId, { //Selected Payment instrument is removed }, { throwable -> //Something went wrong, check exception with documentation } ) } Assets Domain getAsset Asynchronous. Online. Method for getting all assets for selected assetId. Input Parameter Type Description Validation conditions assetId String Id of assets to retrive Not empty Output Success callback with list of Assets objects. Parameter Type Description ucpAsset UcpAsset Plain UcpAsset object UcpAsset object contains following field Parameter Type Description content List Plain list of UcpAssetContent objects UcpAssetContent contains following fields. Parameter Type Description data String The data for this asset. Base64-encoded data, given in the format as specified in type. type String The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. width Long? For image assets, the width of this image. Specified in pixels. height Long? For image assets, the width of this image. Specified in pixels. Failure callback Sample 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 } ) } DOCUMENT CHANGELOG Version 1.0.1 Created Version 2.0.0 Changed approach to SDK setup Added UcpSdkException Added new reason codes to existing exceptions New methods in cards domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete New methods in ibans domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete New methods in cloud messaging domain: processMcbpNotificationData New methods in payment domain: abortUserAuthenticationForPayment, replenishCredentials, restartContactlessTimer New methods in external wallet server domain: prepareRegistrationData, register Version 2.1.0 Added new methods in External Wallet Server domain (activate, suspend, getPaymentInstrument, getPaymentInstruments, onMobilePinChanged) Version 2.1.1 Fixed dependencies for release version Added information about SDK size Added information about SDK integration on lower Android API level Version 2.2.0 Added new method in EWS Service - getEncryptedPin SDK startup optimization Version 2.2.2 Fixed dependencies conflicts Consumer Proguard rules update Certificate pinning implementation improvement Version 2.2.3 Fixed setting default PaymentInstrument after activation Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status Version 2.2.4 Added new enum state TransactionAbortReason.NO_CARDS. Callback onContactlessPaymentAborted is now called when no card is available for payment. Added new model ContactlessTransactionData with better formatting terminal data. New object is added for events EventGetFinalDecision, EventAuthRequiredForContactless, EventContactlessPaymentCompleted. ContactlessTransactionInformation is now deprecated. Version 2.2.6 Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure Fixed problem with flow cutting on digitalization process Version 2.2.7 Added reset functionality. Addded method in Ibans service createPaymentDat. Method createTVC iban service is now deprecated. Added global listener for most important internal SDK actions related to token managem Version 2.3.1 Added  delete  method in External Wallet Server domain Added more detailed descriptions for methods from External Wallet Server domain Added more information about models related to payment processing Version 2.3.2 Fixed SDK provisionning process on Google Pixel devices Improved default Payment Instrument management Updated security harmful process check mechanism Version 2.3.8 Improved facade exception throwing, now contains more details about error. Removing whitespaces from merchantAndLocation in ContectlessTransactionData model Updated security harmful process check mechanism Added MCBP cloud messaging queue handling to prevent processing errors Version 2.3.11 Added new method in Payment Service: processDsrpTransaction Added new method in User Service: resendOtp Added new paremeter in createPaymentData IbanInfo model: userId Improved default PaymentInstrument management Fixed clearing SDK state when unpairing device (MobileDC unPair method) Version 2.3.12 Core module with update. Added new reports to Wallet Server. Version 2.3.13 Added new parameter  result  to IbanDigitizationResult model Parameter  cloudDigitizationSuccess  in IbanDigitizationResult is now deprecated Version 2.3.17 Fixed parsing merchantAndLocation field from ContactlessTransactionData. Added EWS configuration parameter in setup. Version 2.3.18 Updated security libraries Version 2.3.21 Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration Replenish process optimization Version 2.3.22 Improved internal SDK logs reporting Using androidX in end project is necessary now Improved automatic replenish credentials process Added handling ReDigititzation process in SDK. Use withOptionalReProvisionEventListener method in SDK setup method to observe PaymentInstrument changes Version 2.3.22.2 Added more validation for input parameters for External Wallet Server service Added data verification before accessing data in CMS-D processes Improved catching exceptions for MCBP processes Improved flow for reset() method - added protection agains processing messaging after SDK reset() Changed algorithm for calculating publicKeyCertificateFingerprint in PrepareRegistrationDataResponse. From hex(sha1(certificate.publicKey.encoded)) to hex(sha1(certificate.encoded)) Added support for multiple calling setUserAuthenticatedForPayment() method Version 2.3.24 Added new state for TransactionAbortReason::TERMINAL_INACTIVITY_TIMEOUT. Previously status was part of TransactionAbortReason::TERMINAL_ERROR and produces contactless payment aborted handling problems.  Status is used in onContactlessPaymentAborted callback. Application can ignore this state and do not perform any action. Added method on UcpApi for SDK restart(). Unlike reset() new method is asynchronous and allows to usage UCP SDK without application kill. Method clears all UCP SDK data and restarts to initial state. Introduced new approach to handling security issue. When application will call any SDK method after security issue reporting, UcpSkdExpcetion with SECURITY_EVENT_OCCURRED will be returned. Previously APPLICATION_PROCESS_NOT_KILLED was returned. Change doesn't impact  onSecurityIssue callback. Added Assets Domain and getAsset() method. Added verification of input parameters in token profile and transaction credentials replenish. Added more details in callbacks onProvisioningFailure and onReplenishFailure about errors in token related operations. Version 2.4.3 IMPORTANT Update security tools after EMV Security Evaluation - refer to Mobile DC technical documentation version changelog (version 2.12.0) Update Gradle and R8 tools Handled authentication flow for ContactlessRichTransactionType REFUND. SDK requires authentication if not provided. Improved description for ContactlesssTransactionResult model in documentation. Added new ContactlessRichTransactionType: WITHDRAWAL and ATM_CONTACTLESS Version 2.4.4 Updated MDC SDK to 2.12.1 - fixed aggressive security process check Updated documentation for TransactionAbortReason:TERMINAL_INACTIVITY_TIMEOUT model Version 2.5.1 Methods marked as deprecated: reset (use restart instead) getPaymentInstrument (use getAllPaymentInstruments instead) setDefaultForRemote (usage is redundant) getDefaultForRemote (usage is redundant) processDsrpTransaction(use new processDsrpTransaction method with  ProcessDsrpTransaction  added model) Added new methods related to OTP authentication code: requestAuthenticationCodeForPayment  validateAuthenticationCodeForPayment Added new methods for supporting yellow-path token activation: checkEligibility digitize (new version with support for checkEligibility usage) submitTokenAuthenticationMethod submitTokenAuthenticationValue getAdditionalAuthenticationMethods Fixed getPaymentInstrument method (case invalid error when session expired error occurred). Updated Kotlin version to 1.5.31 and Koin to 2.1.6. Removed unused permissions  ACCESS_FINE_LOCATION  and  com.google.android.c2dm.permission.RECEIVE . Added logs for all facade methods  (available in SDK debug version). Version 2.5.2 Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality Version 2.5.3 Update internal libraries.  IMPORTANT  Read more in Mobile DC changelog for version 2.13.3 Version 2.5.5 Wrap in try-catch block callbacks from SDK setup() method to prevent breaking process in SDK. Read more in setup () method description. Version 2.5.6 Resolved Google Play Console Security warning Updated Mobile DC dependency to 2.13.6 Version 2.5.7 Updated Mobile DC dependency to 2.13.7