# Technical Documentation VCP SDK ## VCP SDK Introduction ### Basic abbreviations and definitions

Field	Description
CDCVM	Consumer Device Cardholder Verification Method
CVM	Cardholder Verification Method
Contactless	Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to VCP SDK. HCE support is required for contactless transactions
DSRP	Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions
FCM	Firebase Cloud Messaging
HCE	Host Card Emulation
IBAN	Bank Account Number
MCBP	Mastercard Cloud Based Payments
MDC	Mobile Data Core. Verestro core library.
MPA	Mobile Payment Application - an application that uses VCP SDK for payments
NFC	Near Field Communication
One tap	Flow in a contactless transaction, in which the consumer after authentication(using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data
PAN	Primary account number. Know as a card number.
Payment Instrument	Model keeping all data considering entity used for payments
POS	Point Of Sale
QRC	QR Code transactions - allows consumer generate QR code to present to a merchant, who then scans it to take payment
SUK	Single Use Key - unique credential used for single transaction for Mastercard
LUK	Limited Use Key - payment credential for usage with Visa
Two tap	Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates(using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data
TVC	Token Verification Code
EWS	External Wallet Server
VCP	Verestro Cloud Payment

### What is VCP SDK? The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.payment ### How VCP 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) VCP 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" includeGroup "com.visa" //Only when Visa is used } } } ```

VCP 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}' //Use below code ONLY if using Visa //implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}' //def strictVtsVersionBeta = "6.4.1-sandbox" //def strictVtsVersionProduction = "6.4.1-production" //implementation 'com.visa:cbp' + strictVtsVersionBeta //implementation 'com.visa:cbp' + strictVtsVersionProduction } ```

**For debug version:**

``` dependencies{ implementation 'pl.upaid.module:ucpsdk:{version}-debug' //Use below code ONLY if using Visa //implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}-debug' //def strictVtsVersionBeta = "6.4.0-sandbox" //def strictVtsVersionProduction = "6.4.0-production" //implementation('com.visa:cbp') { // version { strictly strictVtsVersionBeta } //} } ```

**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. ### VCP SDK Application Signing requirements **Mastercard:** There is no requirement related to Application signing. **Visa:** Both sandbox (test) and production environment require APK signed with valid key. To add Application as Trusted in Visa services please provide Signing Key Certificate from chain in PEM format using below script: ``` keytool -exportcert -keystore your_apk_keystore.jks -alias your_keystore_key_alias -rfc -file certificate.pem ``` Output will be provided in *certificate.pem* file. Please provide an result to Verestro representative with related *applicationId* (package). **Note:** When using only Google Play signing key tests local tests related to Visa tokenization and payments will be not possible. ### VCP 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 increment	Notes
APK all architectures	~13,6 MB	Size compared to empty application. Size already include Mobile DC library size as it's required dependency.
APK Arm64	~2.8 MB	Size compared to empty application. Size already include Mobile DC library size as it's required dependency.

**VCP size already includes Mobile DC SDK size.** Additional information: - size from the table above is referred to release version; - size depends on configured proguard; ### VCP SDK Usage This chapter describes the structure and basic usage of VCP 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**: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.

Exception type	Exception class	Description
SDK validation	ValidationException	Additional reason codes for ValidationException used in Mobile DC SDK
Backend exception	BackendException	Additional reason codes for BackendException used in Mobile DC SDK. Note: Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain)
SDK exception	UcpSdkException	Something went wrong on the SDK side, check the table below with possible reasons
Process related	-	As every process is different some methods could throw a specified exception Types of possible exceptions are described in the method description

Additional BackendException reason codes:

Reason	Description
INTERNAL\_ERROR	Error occurred on server
VALIDATION\_ERROR	Client sent invalid data
CRYPTOGRAPHY\_ERROR	Error occurred during cryptography operation
PAYMENT\_CARD\_PREDIGITIZE\_ERROR	Predigitize of payment card failed
PAYMENT\_IBAN\_PREDIGITIZE\_ERROR	Predigitize of payment IBAN failed
PAYMENT\_CARD\_DIGITIZE\_ERROR	Digitize of payment card failed
PAYMENT\_IBAN\_DIGITIZE\_ERROR	Digitize of payment IBAN failed
PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED	Predigitize for payment card must be executed
PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED	Predigitize for payment IBAN must be executed
CLIENT\_UNAUTHORIZED	Client of the API is unauthorized
USER\_UNAUTHORIZED	User is unauthorized
CANT\_FIND\_USER	Cannot find user
CANT\_FIND\_DEVICE	Cannot find device
CANT\_FIND\_IBAN	Cannot find payment IBAN
CANT\_FIND\_CARD	Cannot find payment card
CANT\_FIND\_PAYMENT\_TOKEN	Cannot find payment token
OPERATION\_NOT\_SUPPORTED	Requested operation is not supported
OPERATION\_NOT\_ALLOWED	Requested operation is not allowed
DEVICE\_TEMPORARILY\_LOCKED	Device is temporarily locked
DEVICE\_PERMANENTLY\_LOCKED	Device is permanently locked
INVALID\_PAN	The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly
MISSING\_EXPIRY\_DATE	The expiry date is required for this product but was missing
PAN\_INELIGIBLE	The PAN is not in an approved account range for TSP
DEVICE\_INELIGIBLE	The device is not supported for use
PAN\_INELIGIBLE\_FOR\_DEVICE	The PAN is not allowed to be provisioned to the device because of Issuer rules
PAN\_ALREADY\_PROVISIONED	The PAN is already provisioned for this device
IBAN\_INELIGIBLE	The financial account does not have an associated account range in TSP
PARALLEL\_REQUESTS\_ATTEMPTS	Action is already processing. Please try again after the time included in headers
INVALID\_JWS\_TOKEN	Specified JWS token is invalid

Additional ValidationException reason codes:

Reason	Description
INVALID\_SECURITY\_CODE	Security code is empty
INVALID\_LANGUAGE\_CODE	Language code is empty
INVALID\_PAYMENT\_INSTRUMENT\_ID	Payment instrument id is empty

UcpSdkException reason codes:

Reason	Description
PUSH\_INVALID\_SOURCE	Relates to push processing process. Push message should be consumed in another module
PUSH\_INVALID\_PUSH\_CONTENT	Cannot process push message. The message is invalid or some process failed
PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND	Cannot find default PaymentInstrument
PAYMENT\_INSTRUMENT\_NOT\_FOUND	Selected PaymentInstrument cannot be found, is not digitized or active
APPLICATION\_PROCESS\_NOT\_KILLED	Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process

#### #### Facade The facade is an entry point to communication with VCP 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 VCP SDK provides three public APIs with the same functionalities, the APIs are: - UcpJavaApi for projects which use Java programming language. - UcpKotlinApi for projects which use Kotlin programming language. The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same. This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark). #### #### HceApduService registration To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service. Properly configured meta-data in service will also register an application as tap&pay ready. Exemplary service below:

```

Below listing of the default source file hce\_apud\_service.xml:

```

Check if the application is set as default for payment.

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

Request for set your application as default for payment - will show a dialog for the user to approve the changes.

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

If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.

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

#### #### Models ##### PaymentInstrument

Parameter	Type	Description
id	String	Id of payment instrument. For card it is cardId, for IBAN sha256Hex. In the context of the External Wallet Server use tokenUniqueReference from MDES
paymentTokenId	String	Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id
displayablePanDigits	String	Token last 4 digits which can be used to display
paymentInstrumentStatus	PaymentInstrumentStatus	Enum with status of payment instrument.
contactlessSupported	Boolean	Information if payment instrument supports contactless transactions.
dsrpSupported	Boolean	Information if the payment instrument supports DSRP transactions.
qrcSupported	Boolean	Information if the payment instrument supports QR transactions.
onDeviceCvmSupported	Boolean	Information about supporting CVM on device.
credentialsCount	Int	Amount of credentials that can be used for payments. Always 0 for Visa Cards.
isDefaultForContactlessPayment	Boolean	Information if payment instrument is default for contactless payments.
isDefaultForRemotePayment	Boolean	Information if payment instrument is default for remote payments.
additionalAuthenticationRequired	Boolean	Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods
tokenLastFourDigits	String?	Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
paymentInstrumentExpirationDate	String?	Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately).
paymentInstrumentLastFourDigits	String?	Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
productConfig	ProductConfig?	Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately).
provisioningStatus	String	Current state of provisioning process. One of: IN\_PROGRESS - in case of waiting for onProvisioningSuccess(), SUCCESS - when token is provisioned.
paymentTokenExpirationDate	String?	Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled.

### ##### PaymentInstrumentStatus

Field	Description
INACTIVE	Payment instrument is not active, it can not be used for transactions. The activation process depends on integration. Read the product overview for more information.
ACTIVE	Payment instrument is active and it can be used for transactions.
SUSPENDED	Payment instrument is suspended.
DELETED	Payment instrument is DELETED.
UNKNOWN	Payment instrument status is unknown.

##### ##### AdditionalAuthenticationMethod

Parameter	Type	Description
id	String	Identifier of additional authentication method
name	String	Method name. One of: OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER
value	String	Value depends on method name. Described below.
issuerParameters	AuthMethodsIssuerParameters?	Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION

#### ##### Additional authentication method values:

Method	Value	Description
`OTP_TO_CARDHOLDER_NUMBER`	Masked phone number	Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number.
`OTP_TO_CARDHOLDER_EMAIL`	Masked email	Email to Account holder’s email address. The value will be the Account holder’s masked email address.
`CARDHOLDER_TO_CALL_CUSTOMER_SERVICE`	Phone number	Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service.
`CARDHOLDER_TO_VISIT_WEBSITE`	Website URL	Account holder to visit a website. The value will be the website URL.
`CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION`	Application name	(Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS.
`ISSUER_TO_CALL_CARDHOLDER_NUMBER`	Masked phone number	Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number.

#### ##### AuthMethodsIssuerParameters contains the following fields:

Parameter	Type	Description
mdes	AuthMethodsIssuerParametersMdes?	Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token
vts	AuthMethodsIssuerParametersVts?	Required for VTS Payment token

#### ##### AuthMethodsIssuerParametersMdes contains following fields:

Parameter	Type	Description
android	AuthMethodsIssuerParametersMdesAndroid	Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device
ios	AuthMethodsIssuerParametersMdesIos	Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device

#### ##### AuthMethodsIssuerParametersMdesAndroid contains following fields:

Parameter	Type	Description
action	String?	Name of the action to be performed
packageName	String?	The package name of the issuer's mobile app
extraTextValue	String?	Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app

##### AuthMethodsIssuerParametersMdesIos contains following fields:

Parameter	Type	Description
deepLinkingUrl	String?	The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app.
extraTextValue	String?	Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app.

##### AuthMethodsIssuerParametersVts contains following fields:

Parameter	Type	Description
android	AuthMethodsIssuerParametersVtsAndroid?	Plain AuthMethodsIssuerParametersVtsAndroid object. Required for Android devices
ios	AuthMethodsIssuerParametersVtsIos?	Plain AuthMethodsIssuerParametersVtsIos object. Required for IOS devices

##### AuthMethodsIssuerParametersVtsAndroid contains following fields:

Parameter	Type	Description
appId	String?	Unique identifier for the application within the application store.
appUrl	String?	URL of the application in the application store.
intentUrl	String?	URL of banking app designed to respond to authentication code handling.
requestPayload	String?	The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers.

##### AuthMethodsIssuerParametersVtsIos contains following fields:

Parameter	Type	Description
appId	String?	Unique identifier for the application within the application store.
appUrl	String?	URL of the application in the application store.
intentUrl	String?	URL of banking app designed to respond to authentication code handling.
requestPayload	String?	The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers.

##### ##### ContactlessTransactionInformation

Parameter	Type	Description
currencyCode	ByteArray	Code of currency, that was used in transaction. Formatted in ISO 4271.
amount	ByteArray	Transaction amount in bytes. Can be formatted as Int in pennies.
transactionRange	ContactlessTransactionRange	Type of transaction range.
richTransactionType	ContactlessRichTransactionType	Rich transaction type.
merchantAndLocation	ByteArray	Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset.

**ContactlessTransactionRange**

Value	Description
LVT	Low value transaction
HVT	High value transaction
UNKNOWN	Unknown

**ContactlessRichTransactionType**

Value
PURCHASE
REFUND
CASH
TRANSIT
PURCHASE\_WITH\_CASHBACK
UNKNOWN

##### DsrpTransactionInfo

Parameter	Type	Descruption
amount	Long	Transaction amount
currencyCode	Int	Code of currency, that was used in transaction.
countryCode	Int	Code of country.
issuerCryptogramType	String	Cryptogram type.

##### TransactionAbortReason

Value	Description
WALLET\_CANCEL\_REQUEST	Indicates that the wallet has requested a transaction cancellation during payment.
CARD\_ERROR	This indicates that a problem has been detected in the MChipEngine processing. In some implementations, this can indicate badly formatted card profile data.
TERMINAL\_ERROR	This indicates incorrect terminal behavior.
NO\_TRANSACTION\_CREDENTIALS	There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility.
NO\_CARDS	There is no active PaymentInstrument to start payment. Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event).
TERMINAL\_INACTIVITY\_TIMEOUT	There is a problem with communication between the terminal and payment device. For example, the terminal could abort communication with the mobile device for a long period of time and then trigger a timeout. Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal. The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment. Note: When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again. Note: Deprecated in 2.6.7, no longer used due to time difference between connection lost and providing result to application. Replaced by CONNECTION\_LOST which works immediatelly.
CONNECTION\_LOST	Connection between terminal and device is lost and payment is terminated.
PAYMENT\_NOT\_ALLOWED	Payment is not allowed at this moment. Mastercard: Application should show error and user should retry payment. Visa: Visa requires online security services connection before performing payment on Android versions below 11. When connected internet connection is no more required until application close. During a Payment application should wait for UcpVtsPaymentAllowedListener::onPaymentAllowed()

##### 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 VCP

##### ContactlessTransactionData

Parameter	Type	Description
currencyNumber	Int	Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985.
currencyCode	String?	Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN Could be null as the terminal provides only the currencyNumber and a valid code could be not found.
amountMinor	Long	The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235,
transactionRange	ContactlessTransactionRange	Type of transaction range.
richTransactionType	ContactlessRichTransactionType	Rich transaction type.
merchantAndLocation	String	Merchant and location data from terminal. Deprecated - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data.

**ContactlessTransactionRange**

Value	Description
LVT	Low value transaction
HVT	High value transaction
UNKNOWN	Unknown

**ContactlessRichTransactionType**

Value	Description
PURCHASE
REFUND
CASH
TRANSIT
PURCHASE\_WITH\_CASHBACK
UNKNOWN
WITHDRAWAL
ATM\_CONTACTLESS

##### Report

Parameter	Type	Description
name	String	Action name
description	String	Action details message.
isSuccess	Boolean	Result of action. True when action is finished successfully, false otherwise.
timestamp	Long	Time when the action occurred.
errorMessage	String?	Detailed error message when isSuccess is false.

##### ContactlessAdvice

Parameter	Description
DECLINE	Declines a processing transaction. When provided by SDK in getFinalDecisionForTransaction wallet should not overrule a DECLINE. If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response.
AUTHENTICATION\_REQUIRED	An user authentication is required for transaction processing, which could be overruled on the MPA side. When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the onAuthRequiredForContactless method.
PROCEED	Transaction can be processed.

##### ContactlessTransactionResult

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

Value	Description	Is success on MPA side
AUTHORIZE\_ONLINE	This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization. The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal. Should be treated as transaction success on the MPA side.	Yes
AUTHENTICATE\_OFFLINE	This indicates that the POS requested a decline (AAC) with a CDA signature. SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature. Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization. Should be treated as transaction success on the MPA side.	Yes
DECLINE\_BY\_TERMINAL	The POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request. Paying on the terminal with offline-only network connectivity can also return this callback. Application Cryptogram was generated with genuine credentials. Should be treated as transaction success on the MPA side.	Yes
DECLINE\_BY\_CARD	The digitized card has declined the transaction. A non-exhaustive list of possible reasons may be: - Context mismatch between first and second tap - Terminal is offline-only - Terminal is a transit gate, and transit transactions are not allowed by the card profile - Transaction is international, while the card profile is domestic-only	No
WALLET\_ACTION\_REQUIRED	If the getFinalDecisionForTransaction returns an AUTHENTICATION\_REQUIRED status then this result will be returned. The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap. If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place.	No

#### #### External libraries The SDK uses several external Apache 2.0 libraries: - com.nimbusds:nimbus-jose-jwt - commons-codec:commons-codec - com.fasterxml.jackson.core:jackson-core - com.fasterxml.jackson.core:jackson-annotations - com.fasterxml.jackson.core:jackson-databind - com.fasterxml.jackson.module:jackson-module-kotlin - io.insert-koin:koin-android - io.reactivex.rxjava2:rxjava - io.reactivex.rxjava2:rxandroid - com.squareup.retrofit2:adapter-rxjava2 - com.squareup.retrofit2:retrofit - com.squareup.retrofit2:converter - com.squareup.okhttp3:logging - com.squareup.okhttp3:okhttp - com.google.zxing:core - net.sf.flexjson:flexjson ## VCP SDK Setup VCP SDK has to be configured every time when is used. Before VCP 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.

Requires MobileDC setup() already finished

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

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

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

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

**Input**

Parameter	Type	Description	Validation conditions
ucpConfiguration	UcpConfiguration	VCP configuration provided in builder described below.	Not empty.

**UcpConfigurationBuilder** contains the following methods:

Metod	Parameter	Description	Validation conditions
withApplication	Application	Application context.	Not empty
withCvmModel	WalletCvmModel (enum)	Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE	Not empty
withUserAuthMode	WalletAuthMode (enum)	User authentication mode: WALLET\_PIN, CUSTOM, NONE Contact Verestro to select proper configuration	Not empty
withUcpPaymentInstrument EventListener	UcpPaymentInstrument EventListener	Global listener for actions on PaymentInstrument.	Not empty
withUcpTransaction EventListener	UcpTransactionEventListener	Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing	Not empty
withTransactionAcceptance EventListener	UcpTransactionAcceptance EventListener	Global listener which allow application take final decision about transaction acceptance during transaction	Not empty
withReplenishThreshold	Int	Number of credentials below which replenish process will automatically begin	Not empty
withMcbpPinningCertificates	List<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
withOptionalEventsReports	UcpEventReportListener	Global listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug.	Optional
withOptional ExternalWalletServer		Prepares SDK for using external wallet server.	Optional
withOptional UcpMcbpHttpExecutor	UcpMcbpHttpExecutor/ DefaultUcpMcbpHttpExecutor	Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor.	Optional
withOptional UcpReProvisionEventListener	UcpReProvisionEventListener	Global listener for actions during reprovisioning.	Optional
withOptional UcpTransactionConfiguration	UcpTransactionConfiguration	Transaction configuration. Allow to enable deprecated authentication timer called when authentication is peformed. Timer is disabled by default, usage is not recomended.	Optional
withOptionalWallet McbpHttpExecutor		Prepares SDK for processing CMS-D HTTP requests with Wallet Server proxy.	Optional
withOptionalEnableVisaSDK		Enables Visa SDK usage, requires gradle dependencies configuration	Optional
withOptionalVtsPayment ReadyCallback	UcpVtsPaymentAllowedListener	Provides information if payment with Visa Token is allowed with callback onPaymentAllowed(). Application should wait for callback when Visa Card is used. Receiving callback requires enabled internet connection. Can be switched anytime and SDK will detect connection change. When connected internet connection is no more required until application close.	Optional

**UcpPaymentInstrumentEventListener** Contains callbacks for PaymentInstrument.

Method name	Parameters	Description
onProvisioning Success	paymentInstrument: PaymentInstrument	Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below
onProvisioning Failure	errorMessage: String?, exception: Exception?	Method called after provisioning failure. Try processing digitization again
onReplenish Success	paymentInstrument: PaymentInstrument numberOfTransactionCredentials: Int	Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials. Depending on flow is called after activation process and when requested by SDK based on replenishThreshold configuration. Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row
onReplenish Failure	paymentInstrument: PaymentInstrument, errorMessage: String?, exception: Exception?	Method called after replenish failure with PaymentInstrument Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row
onPayment Instrument StatusChanged	newStatus: PaymentInstrument Status paymentInstrumentId: String	Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id
onNewTransaction	newTransaction: NewTransaction	Provides online result with details of transaction processed in VCP Works only when application is online

**UcpTransactionEventListener** Callbacks related to transaction process.

**Important:** It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.

Method name	Parameters	Description
onAuthRequired ForContactless	paymentInstrument: PaymentInstrument, transactionInformation: ~~ContactlessTransactionInformation~~ transactionData: ContactlessTransactionData	Called when user authentication is required during contactless transaction ContactlessTransactionInformation is deprecated in version 2.2.4.
onAuthRequired ForDsrp	paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo	Called when user authentication is required during Dsrp transaction
onAuthTimer Updated	secondsRemaining: Int	Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration. Note: Deprecated and disabled by default in version 2.6.7. To enable use configuration avaialble in SDK setup::withOptionalUcpTransactionConfiguration.
onContactless PaymentStarted	\-	Called on very beginnging of every transaction start (SELECT\_PPSE APDU command). E.g. first tap to terminal or second tap if onAuthRequiredForContactless method was called. Locks communication until method is finished. Method duration directly impacts on transaction time.
onContactless Payment Completed	paymentInstrument: PaymentInstrument transactionInformation: ~~ContactlessTransactionInformation~~ transactionResult: ContactlessTransactionResult transactionData : ContactlessTransactionData, transactionId:String	Called when transaction is completed with information about transaction and result. ContactlessTransactionInformation is deprecated in version 2.2.4. transactionId - transaction identifier for Mastercard transactions, allow to match transaction with processed transaction notification from Mobile DC SDK: EventNewTransaction::clientTransactionId.
onContactless Payment Incident	paymentInstrument: PaymentInstrument, exception: Exception	Called when something went wrong during transaction and Mastercard marked transaction as incident
onContactless Payment Aborted	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. Note: SDK clears passed selected card with method selectForPayment() and authentication with setUserAuthenticatedForPayment()
onTransaction Stopped		Method called on transaction stopped by SDK. Deprecated in version 2.6.7, no longer used.

**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
getFinal Decision ForTransaction	isUserAuthenticated : Boolean recommendedAdvice : ContactlessAdvice trasactionInformation : ~~ContactlessTransactionInformation~~ transactionData : ContactlessTransactionData	Called on every transaction for the final decision about transaction processing An application can decide based on information about authentication, transaction details like amount, currency, and transaction types The method also provide recommended by MCBP advice based on transaction ContactlessTransactionInformation is deprecated in version 2.2.4.

**UcpEventReportsListener**

Method name	Parameters	Description
onNewReport	report: Report	Return logs related to token management.

**UcpReProvisionEventListener** Called when transaction is completed with information about transaction and result. ContactlessTransactionInformation is deprecated in version 2.2.4.

Method Name	Parameters	Description
onReProvisionSuccess	paymentInstrument: PaymentInstrument	Method called after reProvisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback.
onReProvisionFailure	paymentInstrument : PaymentInstrument errorMessage : String? exception : Exception?	Method called after reProvisioning failure. Try again.

**UcpMcbpHttpExecutor**

Method name	Parameters	Description
execute	ucpMcbpRequestType: 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 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. ```

**UcpTransactionConfiguration**

Parameter	Type	Description
enableTransaction AuthenticationTimer	Boolean	Allows to enable deprecated authentication timer. Timer is started along setUserAuthenticatedForPayment(), result is available in onAuthTimerUpdated().

**Callback samples:** **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 //deprcated, disabled by default, read method description how to enable } override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) { //looks like payment is aborted, can provide result to payment screen //and show user what is abort reason } override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) { //payment completed, provide result to payment information //REMEMBER Transaction is processed on terminal and this is where //you will see final transaction result } override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) { //something went wrong during transaction, provide result to user } override fun onTransactionStopped() { //deprecated, not used anymore, } override fun onContactlessPaymentStarted() { //Payment started or resumed after callback onAuthReqiredForContactless //Best place for checking if user is authenticated for payment and call //setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected } } ```

**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 //For the scanario when authentication is required on issuer side for every transaction //field even.isUserAuthenticated must be always true, otherwise //ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice { val isScreenUnlocked = isScreenUnlocked() val isScreenProtectedByKeyguard = isScreenUnlocked() val isLvtTransaction = event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT //discard all Transit transaction if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) { return ContactlessAdvice.DECLINE } //allow for transaction when user is authenticated for payment and screen unlocked if (event.isUserAuthenticated && isScreenUnlocked) { return ContactlessAdvice.PROCEED } //allow for LVT transaction on unlocked screen when protected and don't require authentication if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) { return ContactlessAdvice.PROCEED } // ... // much more cases //require authentication anyway return ContactlessAdvice.AUTHENTICATION_REQUIRED } } ```

**UcpEventReportsListener**

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

**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. } } ```

**UcpTransactionConfiguration** ``` class BankingAppUcpTransactionConfiguration : UcpTransactionConfiguration { override val enableTransactionAuthenticationTimer: Boolean = false } ``` **UcpVtsPaymentAllowedListener** ``` class BankingAppUcpVtsPaymentAllowedListener : UcpVtsPaymentAllowedListener { override fun onPaymentAllowed() { //when during a payment an status of PAYMENT_NOT_ALLOWED is received //Application UI should show transaction error and wait for onPaymentAllowed() callback //When received callback shouuld inform UI to process transaction again }} ``` **Sample VCP SDK setup implementation** Mobile DC setup() and VCP setup() method could be called on MainThread in Application:onCreate as blocking or another thread. When applicaiton has multiple dependencies there is possible to call both setup() methods on another thread (MobileDC setup() method must be already finished until VCP setup() is called). Important: In case of loading SDK on another thread and using contactless payments HostApduService must be used asynchronous way to prevet using SDK until loading is finished - check sample for method *PaymentService:processHceApduCommand*.

``` fun setup( application: Application, walletCvmModel: WalletCvmModel, walletAuthUserMode: WalletAuthUserMode, mcbpPinningCertificates: List, replenishThreshold: Int ) { val ucpConfiguration = UcpConfiguration.create( UcpConfigurationBuilder() .withApplication(application) .withCvmModel(walletCvmModel) .withUserAuthMode(walletAuthUserMode) //marked as deprecated - see description above .withUcpTransactionEventListener(BankingAppUcpTransactionEventListener()) .withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener()) .withMcbpPinningCertificates(mcbpPinningCertificates) .withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener()) .withReplenishThreshold(replenishThreshold) .withOptionalEventsReports(BankReportEventListener()) .withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor()) //if you want to only add additional action before connection use below implementation //.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor()) .withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener()) //if you want to change standard transaction configuration use configuration below .withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration()) //.withOptionalEnableVisaSDK() //optional when Visa is used //.withOptionalVtsPaymentReadyCallback(BankingAppUcpVtsPaymentAllowedListener()) //optional when Visa is used ) 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 VCP 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 VCP 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 VCP. Payment token will be removed remote and local storage. Result of action will be notified with *onPaymentInstrumentStatusChanged*.

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of PaymentInstrument to delete	Not empty.
reason	CharArray?	Optional reason of deletion

**Output**

Success / failure callback

**Sample**

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

### checkEligibility

Asynchronous. Online. Check eligibility required to process digitize.

**Input**

Parameter	Type	Description
checkEligibility	CheckEligibility	CheckEligibility object

CheckEligibility

Parameter	Type	Description
paymentInstrumentId	String	Identifier of payment instrument
paymentInstrumentType	PaymentInstrumentType	Payment instrument type. One of: \[MASTERCARD,VISA\]
userLanguage	String	User language
userCountry	String	User country

**Output**

Success callback with CheckEligibilityResult.

CheckEligibilityResult

Parameter	Type	Description
termsAndConditionsAssetId	String	Identifier of Terms and Conditions asset

Failure callback

**Sample**

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

### digitize

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

#### **Input**

Parameter	Type	Description	Validation conditions
digitizationRequest	DigitizationRequest	Plain object of DigitizationRequest	Not empty

DigitizationRequest object contains following fields:

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Identifier of payment instrument	Not empty
paymentInstrumentType	PaymentInstrumentType	Payment instrument type. One of: \[MASTERCARD,VISA\]	Not empty
securityCode	CharArray?	Optional. The CVC2 for the card to be digitized
externalPaymentTokenId	String?	Optional. Unique external identifier of Payment Token

#### **Output**

Success callback with DigitizationResult object

Parameter	Type	Description
digitizationResult	DigitizationResult	Plain object of DigitizationResult

DigitizationResult contains following fields.

Parameter	Type	Description
paymentInstrument	PaymentInstrument	Plain object of PaymentInstrument
additionalAuthenticationMethods	List<AdditionalAuthenticationMethod>?	All available additional authentication method
productConfig	ProductConfig	Plain object of ProductConfig, contains Payment Token configuration
externalPaymentTokenId	String?	Optional. External payment token id configured by the consumer. In case of identifier duplicate an random id is generated

ProductConfig contains following fields.

Parameter	Type	Description
isCoBranded	Boolean	Whether the product is co-branded
coBrandName	String?	Name of the co-branded partner
foregroundColor	String	Foreground color, used to overlay text on top of the card image
backgroundColor	String	Background color, used to overlay text on top of the card image
labelColor	String?	Label color of the mobile wallet entry for the card
issuerName	String	Name of the issuing bank
shortDescription	String	A short description for this product
longDescription	String?	A long description for this product
custoremServiceUrl	String?	Customer service website of the issuing bank
customerServiceEmail	String?	Customer service email address of issuing bank
customerServicePhoneNumber	String?	Customer service phone number of the issuing bank
productConfigIssuer	ProductConfigIssuer?	Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app
onlineBankingLoginUrl	String?	Login URL for the issuing bank's online banking website
termsAndConditionsUrl	String?	URL linking to the issuing bank's terms and conditions for this product
privacyPolicyUrl	String?	URL linking to the issuing bank's privacy policy for this product
issuerProductConfigCode	String?	Freeform identifier for this product configuration as assigned by the issuer
contactName	String?	Name of the issuing bank
bankAppName	String?	Name of banking application for display
bankAppAddress	String?	The package name for the destination mobile application
unsupportedPresentationTypes	String?	The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request
unsupportedCardVerificationTypes	String?	The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address)
issuerFlags	List<ProductConfigIssuerFlags>?	List of plain ProductConfigIssuerFlags object. Contains issuer flags
brandLogoAssetId	String	The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID
issuerLogoAssetId	String	The logo of the issuing bank. Provided as a Asset ID
coBrandLogoAssetId	String?	The co-brand logo (if any) for this product. Provided as an Asset ID
cardBackgroundCombinedAssetId	String?	The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID
cardBackgroundAssetId	String?	The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID
iconAssetId	String	The icon representing the primary brand(s) associated with this product. Provided as an Asset ID

ProductConfigIssuer contains following fields.

Parameter	Type	Description
openIssuerAndroidIntent	ProductConfigOpenIssuerAndroidIntent?	AndroidIntent object can be used to open the issuer mobile app
activateWithIssuerAndroidIntent	ProductConfigActivateWithIssuerAndroidIntent?	AndroidIntent object can be used to open the issuer mobile app
openIssuerIOSDeepLinkingUrl	ProductConfigOpenIssuerIOSDeepLinkingUrl?	IOSDeepLinkingUrl object can be used to open the issuer mobile app
activateWithIssuerIOSDeepLinkingUrl	ProductConfigActivateWithIssuerIOSDeepLinkingUrl?	IOSDeepLinkingUrl object can be used to open the issuer mobile app

ProductConfigOpenIssuerAndroidIntent contains following fields.

Parameter	Type	Description
action	String	The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent
packageName	String	The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app
extraTextValue	String	Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object

ProductConfigActivateWithIssuerAndroidIntent contains following fields.

Parameter	Type	Description
action	String	The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent
packageName	String	The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app
extraTextValue	String	Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object

ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.

Parameter	Type	Description
deepLinkinUrl	String	The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app
extraTextValue	String	Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object

ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.

Parameter	Type	Description
deepLinkingUrl	String	The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app
extraTextValue	String	Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object

ProductConfigIssuerFlags contains following fields.

Parameter	Type	Description
deviceBinding	Boolean	Device binding
cardholderVerification	Boolean	Whether the issuer participating in step-up flow
trustedBeneficiaryEnrollment	Boolean	Whether this is a trusted beneficiary enrollment
delegateAuthenticationSupported	String	Whether issuer supports delegated authentication

Failure callback

Sample

``` fun digitizeCard(digitizationRequest: DigitizationRequest) { ucpApi.cardsService .digitize( digitizationRequest, { digitizationResult -> //digitization success, provisioning is in progress //application should listen to push message and provide content to UCP //refresh you payment instrument list form Cards::getPaymentInstruments //new PaymentInstrument should be visible with INACTIVE state //when push processed wait for onProvisioningSuccess or Failure callback //and status change }, { throwable -> //Something went wrong, check exception with documentation } ) } ```

### ### digitize (deprecated)

Asynchronous. Online. Deprecated - use digitize(DigitizationGreenPath) instead. Creates payment token in VCP backend. Expect push after successful finish and then proceed using process method in Cloud Messaging domain.

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Identifier of payment instrument	Not empty.
userLanguage	String	Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code	Not empty.
securityCode	CharArray?	Optional. The CVC2 for the card to be digitized

#### **Output**

Success / failure callback

##### **Sample**

``` fun digitizeCard( paymentInstrumentId: String, languageCode: String, securityCode: CharArray) { ucpApi.cardsService .digitize(paymentInstrumentId, languageCode, securityCode, { //digitization success, provisioning is in progress //application should listen to push message and provide content to UCP //refresh you payment instrument list form Cards::getPaymentInstruments //new PaymentInstrument should be visible with INACTIVE state //when push processed wait for onProvisioningSuccess or Failure callback //and status change }, { throwable -> //Something went wrong, check exception with documentation } ) } ```

### digitize

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

**Input**

Parameter	Type	Description	Validation conditions
digitizationGreenPath	DigitizationGreenPath	Plain object of DigitizationGreenPath	Not empty

DigitizationGreenPath contains following fields.

Parameter	Type	Description
paymentInstrumentId	String	Identifier of payment instrument
paymentInstrumentType	PaymentInstrumentType	Payment instrument type. One of: \[MASTERCARD,VISA\]
securityCode	CharArray?	Optional. The CVC2 for the card to be digitized
userLanguage	String	User language
userCountry	String	User country
externalPaymentTokenId	String?	Optional. Unique external identifier of Payment Token

**Output**

Success / failure callback

##### **Sample** ``` fun digitizeCard(digitizationGreenPath: DigitizationGreenPath) { ucpApi.cardsService .digitize(digitizationGreenPath, { //digitization success, provisioning is in progress //application should listen to push message and provide content to UCP //refresh you payment instrument list form Cards::getPaymentInstruments //new PaymentInstrument should be visible with INACTIVE state //when push processed wait for onProvisioningSuccess or Failure callback //and status change }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` ### getAdditionalAuthenticationMethods

Asynchronous. Online. Retrieves additional user authentication methods.

**Input**

Parameter	Type	Description	Validation conditions
getAdditionalAuthenticationMethods	GetAdditionalAuthenticationMethods	Plain object of GetAdditionalAuthenticationMethods	Not empty

Fields of GetAdditionalAuthenticationMethods object:

Parameter	Type	Description
paymentInstrumentId	String	Identifier of payment instrument

#### **Output**

Success callback with AdditionalAuthenticationMethods object.

Parameter	Type	Description
additionalAuthenticationMethods	AdditionalAuthenticationMethods	Object carrying list of AdditionalAuthenticationMethod

AdditionalAuthenticationMethods contains following value:

Parameter	Type	Description
additionalAuthenticationMethods	List<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**

Parameter	Type	Description
paymentInstrumentId	String	Identifier of payment instrument
authenticationCode	String	Authentication code

#### **Output**

Success callback/failure callback.

##### **Sample**

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

### submitTokenAuthenticationMethod

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

**Input**

Parameter	Type	Description
paymentInstrumentId	String	Identifier of payment instrument
authenticationMethodId	String	Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true.

#### **Output**

Success callback/failure callback.

##### **Sample**

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

### getAllPaymentInstruments

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

**Input**

Parameter	Type	Description	Validation conditions
refresh	Boolean	Refresh all PaymentInstrument objects state with remote VCP server (network and user session required)

**Output**

Success callback with list of PaymentInstrument objects.

Parameter	Type	Description
paymentInstruments	List<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**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of instrument to retrieve	Not empty
refresh	Boolean	Refresh selected PaymentInstrument state with remote VCP server (network required)

**Output**

Success callback with PaymentInstument object.

Parameter	Type	Description
paymentInstrument	PaymentInstrument	Retrieved payment instrument

Failure callback.

**Sample**

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

## ## IBANs domain ### ### digitize

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

**Input**

Parameter	Type	Description	Validation conditions
signedAccountInfo	String	Signed AccountInfo per RFC 7519 Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation	Not empty.
fcmRegistrationToken	CharArray	FCM Cloud messaging registration token	Not empty.
languageCode	String	Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code	Not empty.

**AccountInfo:**

Parameter	Type	Description	Validation conditions
userId	String	External user id	Not empty.
iban	String	Bank Account Number	Not empty.
countryCode	String	The country of the financial account Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1	Not empty.

**Output**

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

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

IbanDigitizationResult contains following fields:

Parameter	Type	Description
(DEPRECATED) cloudDigitizationSuccess	Boolean	Cloud Token Digitization Details
result	CloudDigitizationResult	Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN

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

**Sample** Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)

``` class SignedAccountInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("userId", "externalUserId") .claim("iban", "IN15HIND23467433866365") .claim("countryCode", "IND") .build() val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey) // ... } ```

``` fun digitizeIban( signedAccountInfo: String, fcmRegistrationToken: CharArray, languageCode: String) { ucpApi.ibansService .digitize(signedAccountInfo, fcmRegistrationToken, languageCode, { ibanDigitizationResult -> //Device token digitization finished with success //wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success val cloudDigitizationResult = ibanDigitizationResult.result //check status of Cloud Token }, { throwable -> //Something went wrong, check exception with documentation } ) } ```

### ### createTVC

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

**Input**

Parameter	Type	Description	Validation conditions
signedIbanInfo	String	Signed IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation	Not empty.

IbanInfo

Parameter	Type	Description	Validation conditions
ibanId	String	Iban id returned in addUserWithIban methdod or sha256Hex(iban)	Not empty.

**Output**

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

Parameter	Type	Description
plainTvc	PlainTvc?	Plain PlainTvc object
encryptedTvc	CharArray?	Encrypted PlainTvc object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation

PlainTvc object contains following fields.

Parameter	Type	Description
accountNumber	CharArray	Primary Account Number for the transaction – this is the Token PAN
dynamicExpiryDate	CharArray	Dynamic expiration date for the token. Expressed in YYMM format
dynamicCVC	CharArray	Dynamic CVC

Failure callback when TVC cannot be created.

**Sample** Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)

``` class SignedIbanInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b") .build(); val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ```

``` fun createTvc(signedIbanInfo: String) { ucpApi.ibansService .createTVC(signedIbanInfo, { tvc -> //result object could contains encrypted TVC val encryptedTvc: String? = tvc.encryptedTvc //or decrypted(plain) TVC object with parameters described in documentation val plainTvc = tvc.plainTvc }, { throwable -> //Something went wrong, check exception with documentation }) } ```

### createPaymentData

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

**Input**

Parameter	Type	Description	Validation conditions
signedIbanInfo	String	Signed IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation	Not empty.

IbanInfo

Parameter	Type	Description	Validation conditions
ibanId	String	Iban id returned in addUserWithIban methdod or sha256Hex(iban)	Not empty.
userId	String	External user id given by the client	Not empty.

**Output**

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

Parameter	Type	Description
plainPaymentData	PlainPaymentData?	Plain PlainPaymentData object
encryptedPaymentData	String?	Encrypted PlainPaymentData object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation

PlainPaymentData object contains following fields.

Parameter	Type	Description
accountNumber	String	Primary Account Number for the transaction – this is the Token PAN
applicationExpiryDate	String?	Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format
panSequenceNumber	String?	Rrquired only for UCAF. Application PAN sequence number for the Token
track2Equivalent	String?	Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed
ucafCryptogram	String?	Required only for UCAF. UCAF cryptogram
dynamicExpiryDate	String?	Dynamic expiration date for the token. Expressed in YYMM format
dynamicCVC	String?	Dynamic CVC

Failure callback when PaymentData cannot be created.

**Sample** Sample generation of *signedIbanInfo* (see [Data signing and encryption](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
refresh	Boolean	Refresh all PaymentInstrument objects state with remote VCP server (network required)

**Output**

Success callback with list of PaymentInstrument objects

Parameter	Type	Description
paymentInstruments	List<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
paymentInstrumentId	String	Id of instrument to retrieve.	Not empty
refresh	Boolean	Refresh selected PaymentInstrument state with remote VCP server (network required)

**Output**

Success callback with PaymentInstument object

Parameter	Type	Description
paymentInstrument	PaymentInstrument	Retrieved payment instrument

Failure callback

**Sample**

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

### delete

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of PaymentInstrument to delete	Not empty.
reason	CharArray?	Optional reason of deletion

**Output**

Success / failure callback

**Sample**

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

## Payment domain ### setDefaultForContactless

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Payment instrument identity	Not empty

**Output**

Success / failure callback

**Sample**

``` fun setDefaultForContactless(paymentInstrument: PaymentInstrument) { if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) { //make sure selected PaymentInstrument can be seta as default return } val paymentInstrumentId = paymentInstrument.id ucpApi.paymentService .setDefaultForContactless(paymentInstrumentId, { //success }, { throwable -> //Something went wrong, check exception with documentation }) } ```

### ### getDefaultForContactless

Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.

Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.

**Input**

No input parameters

**Output**

Success callback with id new default PaymentInstrument

Parameter	Type	Description
paymentInstrument	PaymentInstrument	Default Payment instrument

Failure callback.

**Sample**

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

### setDefaultForRemote (deprecated)

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Payment instrument identity	Not empty

**Output**

Success / failure callback

**Sample**

``` fun setDefaultForRemote(paymentInstrument: PaymentInstrument) { if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE && !paymentInstrument.dsrpSupported) { //make sure selected PaymentInstrument can be set as default return } val paymentInstrumentId = paymentInstrument.id ucpApi.paymentService .setDefaultForRemote(paymentInstrumentId, { //success }, { throwable -> //Something went wrong, check exception with documentation }) } ```

### getDefaultForRemote (deprecated)

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

**Input**

No input parameters

**Output**

Success callback with id new default PaymentInstrument

Parameter	Type	Description
paymentInstrument	PaymentInstrument	Default Payment instrument

Failure callback.

**Sample**

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

### selectForPayment

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentd	String	Payment instrument identity	Not empty

**Output**

Success / failure callback

**Sample**

**Note:** This is only sample payment scenation

``` //sample scenario of starting payment with authentication before payment fun startPayment(paymentInstrument: PaymentInstrument) { //checking conditions before payment val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE val isContactlessSupported = paymentInstrument.contactlessSupported val hasTransactionCredentials = paymentInstrument.credentialsCount > 0 if (!isActive || !isContactlessSupported || !hasTransactionCredentials) { //PaymentInstrument doesn't meet requirements for payment return } //selecting PaymentInstrument to payment ucpApi.paymentService .selectForPayment(paymentInstrument.id, { //selection success //request user authentication when //... authentication presented //use setUserAuthenticatedForPayment method }, { throwable -> //something went wrong, check exception with documentation }) } ```

### setUserAuthenticatedForPayment

Asynchronous. Offline. Sets user as authenticated to payment with provided payment instrument.

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

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

*UcpTransactionEventListener:onContactlessPaymentStarted* is recommended place for payment authentication.

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Payment instrument identity	Not empty
pin	CharArray?	PIN or null for CUSTOM WalletAuthUserMode

**Output**

Success / failure callback

**Sample** Basic user authentication usage below, call when user is authenticated.

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

Optional authentication before making transaction based on custom conditions.

``` override fun onContactlessPaymentStarted() { //check internal conditions //like user performed authentication, is logged in application, is device unlocked etc val isUserAuthenticated = true //check if use selected any token for payment and select it in UCP SDK //otherwise default token will be used if (getSelectedPaymentInstrumentId() != null) { ucpApi .paymentService .selectForPayment( paymentInstrumentId = getSelectedPaymentInstrumentId(), success = { //token will be used for actual payment //call setUserAuthenticatedForPayment here - sample below in "else" block }, failure = { throwable -> //something went wrong, check throwable with documentation } ) } else { if (isUserAuthenticated) { ucpApi .paymentService .setUserAuthenticatedForPayment( paymentInstrumentId = getSelectedPaymentInstrumentId(), pin = null, //or pin if MobilePin is used success = //user authenticated in SDK }, failure = { //authentication failure, check exception } ) } } } ```

### abortUserAuthenticationForPayment

Asynchronous. Offline.

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

**Input**

No input parameters

**Output**

Success / failure callback

**Sample**

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

### processHceApduCommand

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

**Input**

Parameter	Type	Description	Validation conditions
context	Context	Application context, can be provided from HostApduService	Not empty
apdu	ByteArray	APDU command from HostApduService::processCommandApdu method parameter	Not empty
extras	Bundle?	Extras object from HostApduService::processCom mandApdu method parameter

**Output**

Apdu result - method called synchronous without callback

Parameter.	Type	Description
apdu	ByteArray	APDU command to return in implementation of overridden processCommandApdu method

**Sample (synchronized HostApduService)** Use this version if MobileDC:setup and UCP:setup() method is called in Application:onCreate on Main Thread.

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

**Sample (aynchronous HostApduService)** Use this version if SDK is called on another thread and HostApduService can receive APDU until VCP SDK is still in loading state. ``` //WalletHceService must be registerd in AndroidManifest as nfc service class WalletHceService : HostApduService() { //... //private val ucpApi = .. override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? { //UcpSdkStateApplicationSingleton is sample class which keep SDK state and allow to observe when SDK load is finished if (UcpSdkStateApplicationSingleton.isLoaded()) { val result = processCommandApduInUcpSdk(context, commandApdu, extras) sendResponseApdu(result) } else { sendResponseApdu(null) UcpSdkStateApplicationSingleton.listenForSdkReady( onSdkLoadListener = { val result = processCommandApduInUcpSdk(context, commandApdu, extras) sendResponseApdu(result) } ) } return null } override fun onDeactivated(reason: Int) { if (UcpSdkStateApplicationSingleton.isLoaded()) { return ucpApi .paymentService .handleHceApduDeactivationEvent(reason) } } private fun processCommandApduInUcpSdk( context: Context, commandApdu: ByteArray, extras: Bundle? ): ByteArray? { return ucpApi .paymentService .processHceApduCommand(context, commandApdu, extras) } } //sample objec which helps to listen SDK state object UcpSdkStateApplicationSingleton : UcpSdkState { //flag could be synchronized private var isLoaded = false private var onSdkLoadListener: (() -> Unit)? = null override fun listenForSdkReady(onSdkLoadListener: () -> Unit) { this.onSdkLoadListener = onSdkLoadListener if (isLoaded) this.onSdkLoadListener?.invoke() } //call when SDK loading thread is finished //setupMdc() -> setupUcp() -> UcpSdkStateApplicationSingleton.onUcpSdkLoaded() override fun onUcpSdkLoaded() { isLoaded = true onSdkLoadListener?.invoke() } override fun isLoaded(): Boolean { return isLoaded } } ``` ### replenishCredentials

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of paymentInstrument that needs it credentials replenished	Not empty

**Output**

Success / failure callback

**Sample**

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

### restartContactlessAuthTimer

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

**Input**

No input parameters

**Output**

Success / failure callback

### requestAuthenticationCodeForPayment

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

**Input**

Parameter	Type	Description	Validation conditions
requestAuthenticationCodeForPayment	RequestAuthenticationCodeForPayment	Plain RequestAuthenticationCodeForPayment object	Not empty

RequestAuthenticationCodeForPayment object contains following fields

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Identifier of payment instrument	Not empty
authenticationRequestId	String	Authentication request id up to 64 alphanumeric characters long. A new id should be used for each instance than an account holder needs to be authenticated	Not empty

**Output**

Success callback/failure callback.

**Sample**

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

### validateAuthenticationCodeForPayment

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

**Input**

Parameter	Type	Description	Validation conditions
validateAuthenticationCodeForPayment	ValidateAuthenticationCodeForPayment	Plain ValidateAuthenticationCodeForPayment object	Not empty

ValidateAuthenticationCodeForPayment object contains following fields

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Identifier of payment instrument	Not empty
authenticationRequestId	String	Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested.	Not empty
authenticationCode	String	Authentication Code to authenticate the account holder	Not empty

**Output**

Success callback with ValidateAuthenticationCodeForPaymentResult object.

ValidateAuthenticationCodeForPaymentResult object contains following field

Parameter	Type	Description
signedAuthenticationProcessData	String	Signed AuthenticationProcessData per RFC 7519

AuthenticationProcessData model

Parameter	Type	Description
authenticationRequestId	String	Authentication request id

**Sample**

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

Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)

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

### processDsrpTransaction(deprecated)

Asynchronous. Online.

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Payment instrument identity	Not empty
dsrpTransactionInfo	DsrpTransactionInfo

**Output**

Success callback with cryptogram for payment

Failure callback

### processDsrpTransaction

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

Parameter	Type	Description	Validation conditions
processDsrpTransaction	ProcessDsrpTransaction	Plain ProcessDsrpTransaction object	Not empty

ProcessDsrpTranasction object contains following fields

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Identifier of payment instrument	Not empty
dsrpTransactionInfo	DsrpTransactionInfo	Plain DsrpTransactionInfo object	Not empty

DsrpTransactionInfo object contains following fields

Parameter	Type	Description	Validation conditions
amountMinor	Long	A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900	Not empty
currencyCode	String	A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999.	Not empty
countryCode	String?	A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000.
issuer Cryptogram Type	DsrpIssuer Cryptogram Type	Enum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used.	Not empty
unpredictable Number	Long	A long representing the random number generated by the merchant or by the Payment Gateway. The maximum value is 4,294,967,295.	Not empty
transactionType	Dsrp Transaction Type	A type of financial transaction, one of: PURCHASE, CASH, PURCHASE\_WITH\_CASHBACK, REFUND	Not empty
transactionDate	Date?	A Date object indicating date of transaction.

**Output**

Success callback with ProcessDsrpTransactionResult object.

ProcessDsrpTransactionResult object contains following field

Parameter	Type	Description
transaction Cryptogram Data	ByteArray	A byte array containing a formatted response, either UCAF or a set of TLV data for the merchant to populate DE55 data.
pan	String	String containing the PAN of the card used.
panSequence Number	Int	An integer value specifying the PAN Sequence Number (PSN) of the card used.
cryptogramType	DsrpIssuer Cryptogram Type	Enum value as UCAF or DE55 depending on cryptogram data format is used.
track2Data	String	String containing the data elements of track 2 according to ISO/IEC 7813.
par	String	String representation of byte array of permanent account reference. A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens.
expirationDate	String	Date in ISO-8601 (YYYY-MM-DD) format indicating expiry date of the card.
transactionId	String	Hexed byte array containing a Transaction Identifier.

**Errors** DsrpPaymentException exception throwed on error in DSRP processing

DsrpPaymentException.reason	Description
DSRP\_INVALID\_INPUT	Invalid input data.
DSRP\_UNEXPECTED\_DATA	Provided data is valid in context of validation, but doesn't mee
DSRP\_AUTHENTICATION\_REQUIRED	Authentication is not provided for DSRP payment. Authenticate and process DSRP transaction again.
DSRP\_TOKEN\_INACTIVE	Token used for DSRP is inactive.
DSRP\_NO\_TRANSACTION\_CREDENTIALS	There is no transaction credentials to procees DSRP payment
DSRP\_NOT\_SUPPORTED\_BY\_CARD	DSRP is not suported by Card.
DSRP\_TRANSACTION\_DECLINED	Transaction is declined by Card.
DSRP\_INCOMPATIBLE\_PROFILE	Card profile is incomaptible with DSRP.
DSRP\_WRONG\_STATE	DSRP transaction is in wrong state.
DSRP\_INTERNAL\_ERROR	Unknowne error during DSRP processing.

**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 : ProcessDsrpTransaction) { ucpApi.paymentService .processDsrpTransaction( processDsrpTransaction, { processDsrpTranasctionResult -> //DSRP transaction result with details went successfully result //should be delivered to Merchant APP }, { throwable -> //Something went wrong, check exception with documentation } ) } ```

**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 : ProcessDsrpTransaction) { ucpApi.paymentService .processDsrpTransaction( processDsrpTransaction, { processDsrpTransactionResult -> //DSRP transaction result with details went successfully result //should be delivered to Merchant APP }, { throwable -> //Something went wrong, check exception with documentation } ) } ```

**Sample input and output DSRP data:** ```Java Input: amountMinor: 4321, countryCode: 840, currencyCode: 840, issuerCryptogramType: UCAF, transactionDate: Apr 25, 2023 09:41:05, //Date() toString() format transactionType: PURCHASE, unpredictableNumber: 29496729 Output: pan: 5204830959972699 track2Data: 5204830959972699D26052010000000000000 expirationDate: 2026-05-31 //YYYY-MM-DD par: 500170A4PEV2GLWPFD00N6H5AX2YB panSequenceNumber: 0 transactionId: df25a522a075680acbaa407fdc8a0348a321f77afa2f0231cd38f28e7ae691e2 cryptogramType: UCAF transactionCryptogramData: 414d506a6d4a474650306149414155427768575a47674144464b553d //in Hex ``` ## Cloud messaging domain ### process (deprecated in 2.6.7)

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

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

**Input**

Parameter	Type	Description	Validation conditions
pushData	Map<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. Offline. Processes data sent by MCBP. Application should check senderId in RemoteMessage object before passing data to VCP SDK. Basic configuration for push processing from External Wallet Server: [External Wallet Server domain](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
encryptedPayload	String	Data received from notification service in object RemoteMessage object	Not empty

**Output**

Success / failure callback

``` //FirebaseMessagingService class from Firebase override fun onMessageReceived(remoteMessage: RemoteMessage) { super.onMessageReceived(remoteMessage) val senderId: String? = remoteMessage.from val pushData = remoteMessage.data //check push source based on senderId if (isVerestroSenderId(senderId)) { val verestroPayload: String = readVerestrpPushContent(pushData) ucpApi .cloudMessagingService .processMcbpNotificationData(verestroPayload, { //push processed in VCP }, { //some error }) } else { //proceed push from another source } } ```

## External Wallet Server domain Chapter contains method for SDK when External Wallet Server is used. Usage of method requires additional configuration with external API. Basic MDES cloud messaging configuration:

Environment	FCM Sender Id
MTF	502118574555
PRODUCTION	993764297204

### prepareRegistrationData

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

**Input**

Parameter	Type	Description	Validation conditions
paymentAppInstanceId	String	Identifier for the specific Mobile Payment App instance	Not empty
paymentAppProviderId	String	Globally unique identifier for the Wallet Provider, as assigned by MDES	Not empty
publicKeyCertificate	String	CMS-D public key certificate in pem format	Not empty
mobilePin	CharArray?	Mobile PIN used to payment confirmation

**Output**

Success callback with PrepareRegistrationResponse object.

Parameter	Type	Description
publicKeyCertificateFingerprint	String	CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded))
encryptedRgk	String	Encrypted randomly-generated 128-bit AES key.
deviceInfo	EwsDeviceInfo	Device info.
deviceFingerprint	String	Unique device fingerprint.
encryptedPin	String?	Encrypted pin (if passed in input).

EwsDeviceInfo model:

Parameter	Type	Description
deviceName	String	Device model name.
formFactor	String	The form factor of the target provisioned device.
storageTechnology	String	The architecture or technology used for token storage.
osName	String	The name of the operating system of the target provisioned device.
osVersion	String	The version of the operating system of the target provisioned device.
nfcCapable	Boolean	Whether the target provisioned device has NFC capability.

Failure callback

**Sample**

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

### register

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

**Input**

Parameter	Type	Description	Validation conditions
mobileKeysetId	String	Identifies the Mobile Keys used for this remote management session	Not empty
ewsMobileKeys	EwsMobileKeys	Contains the mobile keys used to secure the communication during subsequent remote management sessions	Not empty
remoteManagementUrl	String	The URL endpoint for subsequent remote management sessions The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions	Not empty

EwsMobileKeys

Parameter	Type	Description
transportKey	String	The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES
macKey	String	The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES
dataEncryptionKey	String	The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES

**Output**

Success / failure callback

**Sample**

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

### activate

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of paymentInstrument to activate.	Not empty.

**Output**

Success / failure callback

**Sample**

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

### suspend

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of paymentInstrument to suspend.	Not empty.

**Output**

Success / failure callback

**Sample**

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

### getPaymentInstrument

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of paymentInstrument to get.	Not empty.

**Output**

Success callback with PaymentInstrument object.

Parameter	Type	Description
paymentInstrument	PaymentInstrument	Retrieved paymentInstrument

Failure callback.

**Sample**

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

### getAllPaymentInstruments

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

**Input**

No input parameters

**Output**

Success callback with list of PaymentInstrument objects.

Parameter	Type	Description
paymentInstruments	List<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
pin	CharArray	PIN to encrypt.	Not empty.

**Output**

Success callback with encrypted mobile PIN.

Parameter	Type	Description
encryptedMobilePin	String	Hex encoded encrypted mobile PIN.

Failure callback.

**Sample**

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

### onMobilePinChanged

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

**Input**

No input parameters

**Output**

Success / failure callback

**Sample**

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

### delete

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

**Input**

Parameter	Type	Description	Validation conditions
paymentInstrumentId	String	Id of paymentInstrument to delete.	Not empty.

**Output**

Success / failure callback

**Sample**

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

## Assets Domain ### getAsset

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

**Input**

Parameter	Type	Description	Validation conditions
assetId	String	Id of assets to retrive	Not empty

**Output**

Success callback with list of Assets objects.

Parameter	Type	Description
ucpAsset	UcpAsset	Plain UcpAsset object

UcpAsset object contains following field

Parameter	Type	Description
content	List<UcpAssetContent>	Plain list of UcpAssetContent objects

UcpAssetContent contains following fields.

Parameter	Type	Description
data	String	The data for this asset. Base64-encoded data, given in the format as specified in type.
type	String	The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf.
width	Long?	For image assets, the width of this image. Specified in pixels.
height	Long?	For image assets, the width of this image. Specified in pixels.

Failure callback

**Sample**

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

## DOCUMENT CHANGELOG Vesion 2.10.12 - **IMPORTANT: Mobile DC dependency can no longer be declared as saperate dependency in the same application when UCP is declared. MDC will be available as default.** - UCP is now built as a [fused library](https://developer.android.com/build/publish-library/fused-library) - Updated Mobile DC to 2.17.5 - Updated AGP to 9.0.1 - Updated Gradle to 9.3.1 Vesion 2.10.10 - Added new field for digitization: *formFactor* - Mobile DC updated to 2.17.3 Vesion 2.10.0 - Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes) - Security tools updated to newest version - Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22) - AGP updated to 8.11.1 - Mobile DC updated to 2.17.0 Version 2.9.10 - Added new parameter *transactionId* to method *onContactlessPaymentCompleted* for Mastercard transactions. New transaction identifier allow to match transaction with processed transaction notification *MobileDC::EventNewTransaction::clientTransactionId.* - Mobile DC updated to 2.16.12 Version 2.9.8 - **IMPORTANT: Security tools updated to newest version. Recommneded update when using version 2.9.x due to changes fixes in security tools.** - Visa SDK updated to 6.4.0 - Mobile DC updated to 2.16.10 Version 2.9.5 - Added MC *mtf* host name - Update Mobile DC to 2.16.5 Version 2.9.4 - **Important:** Apply security and functional certification changes related to intruduction new security tools. Changes in security thread management and working in background - Update Mobile DC to 2.16.4 Version 2.8.7 - Update Mobile DC to 2.15.8 Version 2.8.6 - Small fixes to 2.8.5 Version 2.8.5 - Update Proguard rules related to R8 changes Version 2.8.2 - Added new field "externalPaymentTokenId" in DigitizationGreenPath, DigitizationRequest and DigitizationResult models. - Added new optional configuration withOptionalWalletMcbpHttpExecutor - Marked configuration withUcpTransactionEventListener from UcpConfigurationBuilder as deprecated. Use MobileDcTransactionEventListener.optionalMobileDcTransactionEventListener from MDC SDK instead. Version 2.7.4 - Added new field "paymentTokenExpirationDate" in PaymentInstrument model. Version 2.7.3 - update MobileDC dependency to 2.15.3 Version 2.7.1 - update MobileDC dependency to 2.15.1 Version 2.7.0 - update MobileDC dependency to 2.15.0 Version 2.6.9.2 - update MobileDC dependency to 2.14.7.2 Version 2.6.9.1 - Hotfix possible OutOfMemoryException in MDC 2.14.7 - update MobileDC dependency to 2.14.7.1 Version 2.6.9 - don't use, could cause OOM Exception

- Updated Mobile DC dependency to 2.14.7. - Updated *processDsrpTransaction* method. Version 2.6.7

- Updated Mobile DC dependency to 2.14.6 - Added support for Mastercard India datacenter. - **important** Added new method to UcpTransactionEventListener - *onContactlessPaymentStarted()***.** Callback allows application to get event about new transaction and it's a best place for token selection and user authentication. Read more in Product Overview. - Due to adding new place for contactless payment authentiocation also updated code samples for *HostApduSevice* implementation and method *setUserAuthenthenticatedForPayment()* - **Important** CloudMessagingService:process became deprecated due to introducing delivery message from server service. Read more in Product Overview and Mobile DC specification. - **Important** Added new status *AbortReason:CONNECTION\_LOST* for *UcpTransactionEventListener:onContactlessPaymentAborted.* Status TERMINAL\_INACTIVITY\_TIMEOUT became deprecated. Change significally improves contactless payment UX. Method works immediatelly when connection between device and terminal is lost. - **Important** Aded new optional configuration for *UcpTransactionConfiguration* with field *enableTransactionAuthenticationTimer.* Timer is now disabled by default, previously was always enabled and could cause problems when authentication time leading to zero and user performs transaction. It could cause clearing user authentication during processing payment on terminal. Change is related to other payments optimizations and introducing *onContactlessPaymentStarted()* and new *AbortReason CONNECTION\_LOST.* Please align your code to new changes, enabling timer is not recommended.

Version 2.5.7

- Updated Mobile DC dependency to 2.13.7

Version 2.5.6

- Resolved Google Play Console Security warning - Updated Mobile DC dependency to 2.13.6

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.3 - Update internal libraries. **IMPORTANT** Read more in Mobile DC changelog for version 2.13.3 Version 2.5.2 - Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality 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.4.4 - Updated MDC SDK to 2.12.1 - fixed aggressive security process check - Updated documentation for TransactionAbortReason:TERMINAL\_INACTIVITY\_TIMEOUT model 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.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 VCP SDK without application kill. Method clears all VCP 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.3.22.2 - hotfix - 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.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.21 - Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration - Replenish process optimization Version 2.3.18 - Updated security libraries Version 2.3.17 - Fixed parsing merchantAndLocation field from ContactlessTransactionData. - Added EWS configuration parameter in setup. Version 2.3.13 - Added new parameter *result* to IbanDigitizationResult model - Parameter *cloudDigitizationSuccess* in IbanDigitizationResult is now deprecated Version 2.3.12 - Core module with update. - Added new reports to Wallet Server. 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.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.2 - Fixed SDK provisionning process on Google Pixel devices - Improved default Payment Instrument management - Updated security harmful process check mechanism 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.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.2.6 - Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure - Fixed problem with flow cutting on digitalization process 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.3 - Fixed setting default PaymentInstrument after activation - Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status Version 2.2.2 - Fixed dependencies conflicts - Consumer Proguard rules update - Certificate pinning implementation improvement Version 2.2.0 - Added new method in EWS Service - getEncryptedPin - SDK startup optimization 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.1.0 - Added new methods in External Wallet Server domain (activate, suspend, getPaymentInstrument, getPaymentInstruments, onMobilePinChanged) 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 1.0.1 - Created