# Technical Documentation # Technical Documentation UCP SDK Version 2.5.7 ## UCP SDK Introduction ### Basic abbreviations and definitions
**Field****Description**
CDCVMConsumer Device Cardholder Verification Method
CVMCardholder Verification Method
ContactlessTransactions 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
DSRPDigital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions
FCMFirebase Cloud Messaging
HCEHost Card Emulation
IBANBank Account Number
MCBPMastercard Cloud Based Payments
MDCMobile Data Core. Verestro core library.
MPAMobile Payment Application - an application that uses UCP SDK for payments
NFCNear Field Communication
One tapFlow in a contactless transaction, in which the consumer after authentication(using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data
PANPrimary account number. Know as a card number.
Payment InstrumentModel keeping all data considering entity used for payments
POSPoint Of Sale
QRCQR Code transactions - allows consumer generate QR code to present to a merchant, who then scans it to take payment
SUKSingle 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
TVCToken Verification Code
EWSExternal 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 MBRanged 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 validationValidationExceptionAdditional reason codes for ValidationException used in Mobile DC SDK
Backend exceptionBackendExceptionAdditional reason codes for BackendException used in Mobile DC SDK. **Note:** Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain)
SDK exceptionUcpSdkExceptionSomething 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\_ERRORError 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\_TOKENSpecified 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\_KILLEDOccurs 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**
idStringId of payment instrument. For card it is cardId, for IBAN sha256Hex. In the context of the External Wallet Server use tokenUniqueReference from MDES
paymentTokenIdStringId of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id
displayablePanDigitsStringToken last 4 digits which can be used to display
paymentInstrumentStatusPaymentInstrumentStatusEnum with status of payment instrument.
contactlessSupportedBooleanInformation if payment instrument supports contactless transactions.
dsrpSupportedBooleanInformation if the payment instrument supports DSRP transactions.
qrcSupportedBooleanInformation if the payment instrument supports QR transactions.
onDeviceCvmSupportedBooleanInformation about supporting CVM on device.
credentialsCountIntAmount of credentials that can be used for payments.
isDefaultForContactlessPayment BooleanInformation if payment instrument is default for contactless payments.
isDefaultForRemotePaymentBooleanInformation if payment instrument is default for remote payments.
additionalAuthenticationRequiredBoolean Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods
tokenLastFourDigitsString? Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
paymentInstrumentExpirationDateString? 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**
INACTIVEPayment instrument is not active, it can not be used for transactions. The activation process depends on integration. Read the product overview for more information.
ACTIVEPayment instrument is active and it can be used for transactions.
SUSPENDEDPayment instrument is suspended.
DELETEDPayment instrument is DELETED.
UNKNOWNPayment instrument status is unknown.
##### ##### AdditionalAuthenticationMethod
**Parameter****Type****Description**
idStringIdentifier of additional authentication method
nameStringMethod 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
valueStringValue depends on method name. Described below.
issuerParametersAuthMethodsIssuerParameters?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**
mdesAuthMethodsIssuerParametersMdes?Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token
vtsAuthMethodsIssuerParametersVts?Required for VTS Payment token
#### ##### AuthMethodsIssuerParametersMdes contains following fields:
**Parameter****Type****Description**
androidAuthMethodsIssuerParametersMdesAndroidPlain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device
iosAuthMethodsIssuerParametersMdesIosPlain AuthMethodsIssuerParametersMdesIos object. Required for IOS device
#### ##### AuthMethodsIssuerParametersMdesAndroid contains following fields:
**Parameter****Type****Description**
actionString?Name of the action to be performed
packageNameString?The package name of the issuer's mobile app
extraTextValueString?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**
deepLinkingUrlString?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.
extraTextValueString?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**
androidAuthMethodsIssuerParametersVtsAndroid?Plain AuthMethodsIssuerParametersVtsAndroid object. Required for Android devices
iosAuthMethodsIssuerParametersVtsIos?Plain AuthMethodsIssuerParametersVtsIos object. Required for IOS devices
##### AuthMethodsIssuerParametersVtsAndroid contains following fields:
**Parameter****Type****Description**
appIdString?Unique identifier for the application within the application store.
appUrlString?URL of the application in the application store.
intentUrlString?URL of banking app designed to respond to authentication code handling.
requestPayloadString?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**
appIdString?Unique identifier for the application within the application store.
appUrlString?URL of the application in the application store.
intentUrlString?URL of banking app designed to respond to authentication code handling.
requestPayloadString?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**
currencyCodeByteArrayCode of currency, that was used in transaction. Formatted in ISO 4271.
amountByteArrayTransaction amount in bytes. Can be formatted as Int in pennies.
transactionRangeContactlessTransactionRangeType of transaction range.
richTransactionTypeContactlessRichTransactionTypeRich transaction type.
merchantAndLocationByteArrayMerchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset.
**ContactlessTransactionRange**
**Value****Description**
LVTLow value transaction
HVTHigh value transaction
UNKNOWNUnknown
**ContactlessRichTransactionType**
**Value**
PURCHASE
REFUND
CASH
TRANSIT
PURCHASE\_WITH\_CASHBACK
UNKNOWN
##### DsrpTransactionInfo
**Parameter****Type****Descruption**
amountLongTransaction amount
currencyCodeIntCode of currency, that was used in transaction.
countryCodeIntCode of country.
issuerCryptogramTypeStringCryptogram type.
##### TransactionAbortReason
**Value****Description**
WALLET\_CANCEL\_REQUESTIndicates that the wallet has requested a transaction cancellation during payment.
CARD\_ERRORThis indicates that a problem has been detected in the MChipEngine processing. In some implementations, this can indicate badly formatted card profile data.
TERMINAL\_ERRORThis 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\_CARDSThere 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\_TIMEOUTThere 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**
currencyNumberIntCurrency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985.
currencyCodeString?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.
amountMinorLongThe monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235,
transactionRangeContactlessTransactionRangeType of transaction range.
richTransactionTypeContactlessRichTransactionTypeRich transaction type.
merchantAndLocationStringMerchant 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**
ValueDescription
LVTLow value transaction
HVTHigh value transaction
UNKNOWNUnknown
**ContactlessRichTransactionType**
ValueDescription
PURCHASE
REFUND
CASH
TRANSIT
PURCHASE\_WITH\_CASHBACK
UNKNOWN
WITHDRAWAL
ATM\_CONTACTLESS
##### Report
**Parameter****Type****Description**
nameStringAction name
descriptionStringAction details message.
isSuccessBooleanResult of action. True when action is finished successfully, false otherwise.
timestampLongTime when the action occurred.
errorMessageString?Detailed error message when isSuccess is false.
##### ContactlessAdvice
**Parameter****Description**
DECLINEDeclines 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\_REQUIREDAn 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.
PROCEEDTransaction can be processed.
##### ContactlessTransactionResult

**Important:** MPA should always refer to transaction results on the terminal.

**Value****Description****Is success on MPA side**
AUTHORIZE\_ONLINEThis 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\_OFFLINEThis 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\_TERMINALThe 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\_CARDThe 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\_REQUIREDIf 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**
ucpConfigurationUcpConfigurationUCP configuration provided in builder described below. Not empty.
**UcpConfigurationBuilder** contains the following methods:
**Metod****Parameter****Description****Validation conditions**
withApplicationApplicationApplication context.Not empty
withCvmModelWalletCvmModel (enum)Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE Not empty
withUserAuthModeWalletAuthMode (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
withUcpTransactionEventListenerUcpTransactionEventListener Global listener for actions during transaction processing Not empty
withTransactionAcceptanceEventListenerUcpTransactionAcceptanceEventListenerGlobal listener which allow application take final decision about transaction acceptance during transactionNot empty
withReplenishThresholdIntNumber of credentials below which replenish process will automatically begin Not empty
withMcbpPinningCertificatesList<String>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
withOptionalEventsReportsUcpEventReportListenerGlobal listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. Optional
withOptionalExternalWalletServerBooleanPrepares SDK for using external wallet server.Optional
withOptionalUcpMcbpHttpExecutorUcpMcbpHttpExecutor/DefaultUcpMcbpHttpExecutorGlobal 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
withOptionalUcpReProvisionEventListenerUcpReProvisionEventListenerGlobal listener for actions during reprovisioning.Optional
**UcpPaymentInstrumentEventListener** Contains callbacks for PaymentInstrument.
**Method name****Parameters****Description**
onProvisioningSuccesspaymentInstrument: PaymentInstrument Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below
onProvisioningFailureerrorMessage: String?, exception: Exception? Method called after provisioning failure. Try processing digitization again
onReplenishSuccesspaymentInstrument: 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
onReplenishFailurepaymentInstrument: 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
onPaymentInstrumentStatusChangednewStatus: PaymentInstrumentStatus paymentInstrumentId: String Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id
onNewTransactionnewTransaction: 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 nameParametersDescription
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
onAuthTimerUpdatedsecondsRemaining: IntCalled 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**
onReProvisionSuccesspaymentInstrument: PaymentInstrumentMethod called after reProvisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback.
onReProvisionFailurepaymentInstrument : PaymentInstrument errorMessage : String? exception : Exception? Method called after reProvisioning failure. Try again.
**UcpMcbpHttpExecutor**
Method name Parameters Description
execute ucpMcbpRequestType: UcpMcbpHttpExecutorRequestTypeucpMcbpHttpMethod: UcpMcbpHttpMethodurl: StringrequestData: AnyrequestProperties: Map<String, String> 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<String, String> 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**
paymentInstrumentIdStringId of PaymentInstrument to delete Not empty.
reasonCharArray?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**
checkEligibilityCheckEligibilityCheckEligibility object
CheckEligibility
**Parameter** **Type** **Description**
paymentInstrumentIdStringIdentifier of payment instrument
paymentInstrumentTypePaymentInstrumentTypePayment instrument type. One of: \[MASTERCARD\]
userLanguageStringUser language
userCountryStringUser country
**Output**

Success callback with CheckEligibilityResult.

CheckEligibilityResult
**Parameter** **Type** **Description**
termsAndConditionsAssetIdStringIdentifier 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**
ParameterTypeDescriptionValidation conditions
digitizationRequestDigitizationRequestPlain object of DigitizationRequest Not empty
DigitizationRequest object contains following fields:
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringIdentifier of payment instrument Not empty
paymentInstrumentTypePaymentInstrumentTypePayment instrument type. One of: \[MASTERCARD\] Not empty
securityCodeCharArray?Optional. The CVC2 for the card to be digitizedNot empty
#### **Output**

Success callback with DigitizationResult object

**Parameter****Type****Description**
digitizationResultDigitizationResultPlain object of DigitizationResult
DigitizationResult contains following fields.
**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentPlain object of PaymentInstrument
additionalAuthenticationMethodsList<AdditionalAuthenticationMethod>?All available additional authentication method
productConfigProductConfigPlain object of ProductConfig, contains Payment Token configuration
ProductConfig contains following fields.
**Parameter****Type****Description**
isCoBrandedBooleanWhether the product is co-branded
coBrandNameString?Name of the co-branded partner
foregroundColorStringForeground color, used to overlay text on top of the card image
backgroundColorStringBackground color, used to overlay text on top of the card image
labelColorString?Label color of the mobile wallet entry for the card
issuerNameStringName of the issuing bank
shortDescriptionStringA short description for this product
longDescriptionString?A long description for this product
custoremServiceUrlString?Customer service website of the issuing bank
customerServiceEmailString?Customer service email address of issuing bank
customerServicePhoneNumberString?Customer service phone number of the issuing bank
productConfigIssuerProductConfigIssuer?Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app
onlineBankingLoginUrlString?Login URL for the issuing bank's online banking website
termsAndConditionsUrlString?URL linking to the issuing bank's terms and conditions for this product
privacyPolicyUrlString?URL linking to the issuing bank's privacy policy for this product
issuerProductConfigCodeString?Freeform identifier for this product configuration as assigned by the issuer
contactNameString?Name of the issuing bank
bankAppNameString?Name of banking application for display
bankAppAddressString?The package name for the destination mobile application
unsupportedPresentationTypesString?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
unsupportedCardVerificationTypesString?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)
issuerFlagsList<ProductConfigIssuerFlags>?List of plain ProductConfigIssuerFlags object. Contains issuer flags
brandLogoAssetIdStringThe Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID
issuerLogoAssetIdStringThe logo of the issuing bank. Provided as a Asset ID
coBrandLogoAssetIdString?The co-brand logo (if any) for this product. Provided as an Asset ID
cardBackgroundCombinedAssetIdString?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
cardBackgroundAssetIdString?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
iconAssetIdStringThe icon representing the primary brand(s) associated with this product. Provided as an Asset ID
ProductConfigIssuer contains following fields.
**Parameter****Type****Description**
openIssuerAndroidIntentProductConfigOpenIssuerAndroidIntent?AndroidIntent object can be used to open the issuer mobile app
activateWithIssuerAndroidIntentProductConfigActivateWithIssuerAndroidIntent?AndroidIntent object can be used to open the issuer mobile app
openIssuerIOSDeepLinkingUrlProductConfigOpenIssuerIOSDeepLinkingUrl?IOSDeepLinkingUrl object can be used to open the issuer mobile app
activateWithIssuerIOSDeepLinkingUrlProductConfigActivateWithIssuerIOSDeepLinkingUrl?IOSDeepLinkingUrl object can be used to open the issuer mobile app
ProductConfigOpenIssuerAndroidIntent contains following fields.
**Parameter****Type****Description**
actionStringThe name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent
packageNameStringThe 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
extraTextValueStringContains 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**
actionStringThe name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent
packageNameStringThe 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
extraTextValueStringContains 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**
deepLinkinUrlStringThe 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
extraTextValueStringContains 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**
deepLinkingUrlStringThe 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
extraTextValueStringContains 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**
deviceBindingBooleanDevice binding
cardholderVerificationBooleanWhether the issuer participating in step-up flow
trustedBeneficiaryEnrollmentBooleanWhether this is a trusted beneficiary enrollment
delegateAuthenticationSupportedStringWhether 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**
paymentInstrumentIdStringIdentifier of payment instrument Not empty.
userLanguageStringLanguage preference selected by the consumer. Formatted as an ISO-639-1 two letter language code Not empty.
securityCodeCharArray?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**
getAdditionalAuthenticationMethodsGetAdditionalAuthenticationMethodsPlain object of GetAdditionalAuthenticationMethods Not empty
Fields of GetAdditionalAuthenticationMethods object:
**Parameter****Type****Description**
paymentInstrumentIdStringIdentifier of payment instrument
#### **Output**

Success callback with AdditionalAuthenticationMethods object.

**Parameter****Type****Description**
additionalAuthenticationMethodsAdditionalAuthenticationMethodsObject carrying list of AdditionalAuthenticationMethod
AdditionalAuthenticationMethods contains following value:
**Parameter****Type****Description**
additionalAuthenticationMethodsList<AdditionalAuthenticationMethod>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**
ParameterTypeDescription
paymentInstrumentIdStringIdentifier of payment instrument
authenticationCodeStringAuthentication 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**
paymentInstrumentIdStringIdentifier of payment instrument
authenticationMethodIdStringId 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**
ParameterTypeDescriptionValidation conditions
refreshBooleanRefresh all PaymentInstrument objects state with remote UCP server (network and user session required)
**Output**

Success callback with list of PaymentInstrument objects.

**Parameter****Type****Description**
paymentInstrumentsList<PaymentInstrument>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**
ParameterTypeDescriptionValidation conditions
paymentInstrumentIdStringId of instrument to retrieveNot empty
refreshBooleanRefresh selected PaymentInstrument state with remote UCP server (network required)
**Output**

Success callback with PaymentInstument object.

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentRetrieved 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**
signedAccountInfoStringSigned 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.
fcmRegistrationTokenCharArrayFCM Cloud messaging registration token Not empty.
languageCodeStringLanguage preference selected by the consumer. Formatted as an ISO-639-1 two letter language code Not empty.
**AccountInfo:**
**Parameter****Type****Description****Validation conditions**
userIdStringExternal user id Not empty.
ibanStringBank Account NumberNot empty.
countryCodeStringThe 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) cloudDigitizationSuccessBooleanCloud Token Digitization Details
resultCloudDigitizationResultCloud 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**
signedIbanInfoStringSigned 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**
ibanIdStringIban 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**
plainTvcPlainTvc?Plain PlainTvc object
encryptedTvcCharArray?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**
accountNumberCharArrayPrimary Account Number for the transaction – this is the Token PAN
dynamicExpiryDateCharArrayDynamic expiration date for the token. Expressed in YYMM format
dynamicCVCCharArrayDynamic 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**
signedIbanInfoStringSigned 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**
ibanIdStringIban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* Not empty.
userIdStringExternal user id given by the clientNot empty.
**Output**

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

**Parameter****Type****Description**
plainPaymentDataPlainPaymentData?Plain PlainPaymentData object
encryptedPaymentDataString?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**
accountNumberStringPrimary Account Number for the transaction – this is the Token PAN
applicationExpiryDateString?Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format
panSequenceNumberString?Rrquired only for UCAF. Application PAN sequence number for the Token
track2EquivalentString?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
ucafCryptogramString?Required only for UCAF. UCAF cryptogram
dynamicExpiryDateString?Dynamic expiration date for the token. Expressed in YYMM format
dynamicCVCString?Dynamic CVC

Failure callback when PaymentData cannot be created.

**Sample** Sample generation of *signedIbanInfo* (see [Data signing and encryption](https://wiki.verestro.com/display/UCP/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**
refreshBooleanRefresh all PaymentInstrument objects state with remote UCP server (network required)
**Output**

Success callback with list of PaymentInstrument objects

**Parameter****Type****Description**
paymentInstrumentsList<PaymentInstrument>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**
paymentInstrumentIdStringId of instrument to retrieve.Not empty
refreshBooleanRefresh selected PaymentInstrument state with remote UCP server (network required)
**Output**

Success callback with PaymentInstument object

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentRetrieved 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**
ParameterTypeDescriptionValidation conditions
paymentInstrumentIdStringId of PaymentInstrument to delete Not empty.
reasonCharArray?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**
paymentInstrumentIdStringPayment 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**
paymentInstrumentPaymentInstrumentDefault 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**
paymentInstrumentIdStringPayment 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**
paymentInstrumentPaymentInstrumentDefault 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**
paymentInstrumentdStringPayment 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**
paymentInstrumentIdStringPayment instrument identity Not empty
pinCharArray?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**
contextContextApplication context, can be provided from HostApduService Not empty
apduByteArrayAPDU command from HostApduService::processCommandApdu method parameter Not empty
extrasBundle?Extras object from HostApduService::processCom mandApdu method parameter
**Output**

Apdu result - method called synchronous without callback

**Parameter.****Type****Description**
apduByteArrayAPDU 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**
paymentInstrumentIdStringId 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**
requestAuthenticationCodeForPaymentRequestAuthenticationCodeForPaymentPlain RequestAuthenticationCodeForPayment object Not empty
RequestAuthenticationCodeForPayment object contains following fields
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringIdentifier of payment instrument Not empty
authenticationRequestIdStringAuthentication request id up to 64 alphanumeric characters long. A new id should be used for each instance than an account holder needs to be authenticatedNot 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**
ParameterTypeDescriptionValidation conditions
validateAuthenticationCodeForPaymentValidateAuthenticationCodeForPaymentPlain ValidateAuthenticationCodeForPayment object Not empty
ValidateAuthenticationCodeForPayment object contains following fields
ParameterTypeDescriptionValidation conditions
paymentInstrumentIdStringIdentifier of payment instrument Not empty
authenticationRequestIdStringAuthentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested.Not empty
authenticationCodeStringAuthentication Code to authenticate the account holderNot empty
**Output**

Success callback with ValidateAuthenticationCodeForPaymentResult object.

ValidateAuthenticationCodeForPaymentResult object contains following field
**Parameter****Type****Description**
signedAuthenticationProcessDataStringSigned AuthenticationProcessData per RFC 7519
AuthenticationProcessData model
**Parameter****Type****Description**
authenticationRequestIdStringAuthentication 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**
paymentInstrumentIdStringPayment instrument identity Not empty
dsrpTransactionInfoDsrpTransactionInfo
**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**
processDsrpTransactionProcessDsrpTransactionPlain ProcessDsrpTransaction object Not empty
ProcessDsrpTranasction object contains following fields
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringIdentifier of payment instrument Not empty
dsrpTransactionInfoDsrpTransactionInfoPlain DsrpTransactionInfo objectNot empty
DsrpTransactionInfo object contains following fields
**Parameter****Type****Description****Validation conditions**
amountLongA long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 Not empty
currencyCodeIntA 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
countryCodeIntA 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000.Not empty
issuerCryptogramTypeStringValue 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**
transactionResultStringString 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**
pushDataMap<String, String>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 MCBP. 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](https://wiki.verestro.com/display/UCP/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**
encryptedPayloadStringData 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**
MTF502118574555
PRODUCTION993764297204
### prepareRegistrationData

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentAppInstanceIdStringIdentifier for the specific Mobile Payment App instanceNot empty
paymentAppProviderIdStringGlobally unique identifier for the Wallet Provider, as assigned by MDESNot empty
publicKeyCertificateStringCMS-D public key certificate in pem formatNot empty
mobilePinCharArray?Mobile PIN used to payment confirmation
**Output**

Success callback with PrepareRegistrationResponse object.

**Parameter****Type****Description**
publicKeyCertificateFingerprintStringCMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded))
encryptedRgkStringEncrypted randomly-generated 128-bit AES key.
deviceInfoEwsDeviceInfoDevice info.
deviceFingerprintStringUnique device fingerprint.
encryptedPinString?Encrypted pin (if passed in input).
EwsDeviceInfo model:
**Parameter****Type****Description**
deviceNameStringDevice model name.
formFactorStringThe form factor of the target provisioned device.
storageTechnologyStringThe architecture or technology used for token storage.
osNameStringThe name of the operating system of the target provisioned device.
osVersionStringThe version of the operating system of the target provisioned device.
nfcCapableBooleanWhether 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**
mobileKeysetIdStringIdentifies the Mobile Keys used for this remote management session Not empty
ewsMobileKeysEwsMobileKeysContains the mobile keys used to secure the communication during subsequent remote management sessions Not empty
remoteManagementUrlStringThe 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**
transportKeyStringThe Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES
macKeyStringThe Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES
dataEncryptionKeyStringThe 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**
paymentInstrumentIdStringId 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**
paymentInstrumentIdStringId 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**
paymentInstrumentIdStringId of paymentInstrument to get. Not empty.
**Output**

Success callback with PaymentInstrument object.

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentRetrieved 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**
paymentInstrumentsList<PaymentInstrument>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**
pinCharArrayPIN to encrypt.Not empty.
**Output**

Success callback with encrypted mobile PIN.

**Parameter****Type****Description**
encryptedMobilePinStringHex 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**
paymentInstrumentIdStringId 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**
assetIdStringId of assets to retriveNot empty
**Output**

Success callback with list of Assets objects.

**Parameter****Type****Description**
ucpAssetUcpAssetPlain UcpAsset object
UcpAsset object contains following field
**Parameter****Type****Description**
contentList<UcpAssetContent>Plain list of UcpAssetContent objects
UcpAssetContent contains following fields.
**Parameter****Type****Description**
dataStringThe data for this asset. Base64-encoded data, given in the format as specified in type.
typeStringThe data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf.
widthLong?For image assets, the width of this image. Specified in pixels.
heightLong?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
# Technical Documentation MDC SDK The Mobile DC SDK is a core module dedicated to the management of users, devices, and cards in the Verestro system. To learn more about Mobile DC SDK follow: [Link to Mobile DC SDK technical documentation](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/technical-documentation-mdc-sdk "User Lifecycle & Card Management API & SDK") # Technical documentation UCP External API Technical Documentation UCP External API @swagger="https://services.upaidtest.pl/ucp/doc.yaml/external"