# Technical Documentation VCP SDK ## VCP SDK Introduction ### Basic abbreviations and definitions
**Field****Description**
CDCVMConsumer Device Cardholder Verification Method
CVMCardholder Verification Method
ContactlessTransactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to VCP SDK. HCE support is required for contactless transactions
DSRPDigital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions
FCMFirebase Cloud Messaging
HCEHost Card Emulation
IBANBank Account Number
MCBPMastercard Cloud Based Payments
MDCMobile Data Core. Verestro core library.
MPAMobile Payment Application - an application that uses VCP SDK for payments
NFCNear Field Communication
One tapFlow in a contactless transaction, in which the consumer after authentication(using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data
PANPrimary account number. Know as a card number.
Payment InstrumentModel keeping all data considering entity used for payments
POSPoint Of Sale
QRCQR Code transactions - allows consumer generate QR code to present to a merchant, who then scans it to take payment
SUKSingle Use Key - unique credential used for single transaction
Two tap Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates(using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data
TVCToken Verification Code
EWSExternal Wallet Server
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" } } } ```
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}' } ```
**For debug version:**
``` dependencies{ implementation 'pl.upaid.module:ucpsdk:{version}-debug' } ```
**Min SDK Version** The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.
``` ```
SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it. #### ### 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****Notes**
APK~37 MB
Bundle~7 MBRanged size depends on the ABI of the device. SDK contains native libraries used by different ABI. By using a bundle only the necessary version of the native library will be downloaded to a device.
**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 validationValidationExceptionAdditional reason codes for ValidationException used in Mobile DC SDK
Backend exceptionBackendExceptionAdditional reason codes for BackendException used in Mobile DC SDK. **Note:** Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain)
SDK exceptionUcpSdkExceptionSomething went wrong on the SDK side, check the table below with possible reasons
Process related-As every process is different some methods could throw a specified exception Types of possible exceptions are described in the method description
Additional BackendException reason codes:
**Reason****Description**
INTERNAL\_ERRORError occurred on server
VALIDATION\_ERROR Client sent invalid data
CRYPTOGRAPHY\_ERROR Error occurred during cryptography operation
PAYMENT\_CARD\_PREDIGITIZE\_ERROR Predigitize of payment card failed
PAYMENT\_IBAN\_PREDIGITIZE\_ERROR Predigitize of payment IBAN failed
PAYMENT\_CARD\_DIGITIZE\_ERROR Digitize of payment card failed
PAYMENT\_IBAN\_DIGITIZE\_ERROR Digitize of payment IBAN failed
PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED Predigitize for payment card must be executed
PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED Predigitize for payment IBAN must be executed
CLIENT\_UNAUTHORIZED Client of the API is unauthorized
USER\_UNAUTHORIZED User is unauthorized
CANT\_FIND\_USER Cannot find user
CANT\_FIND\_DEVICE Cannot find device
CANT\_FIND\_IBAN Cannot find payment IBAN
CANT\_FIND\_CARD Cannot find payment card
CANT\_FIND\_PAYMENT\_TOKEN Cannot find payment token
OPERATION\_NOT\_SUPPORTED Requested operation is not supported
OPERATION\_NOT\_ALLOWED Requested operation is not allowed
DEVICE\_TEMPORARILY\_LOCKED Device is temporarily locked
DEVICE\_PERMANENTLY\_LOCKED Device is permanently locked
INVALID\_PAN The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly
MISSING\_EXPIRY\_DATE The expiry date is required for this product but was missing
PAN\_INELIGIBLE The PAN is not in an approved account range for TSP
DEVICE\_INELIGIBLE The device is not supported for use
PAN\_INELIGIBLE\_FOR\_DEVICE The PAN is not allowed to be provisioned to the device because of Issuer rules
IBAN\_INELIGIBLE The financial account does not have an associated account range in TSP
PARALLEL\_REQUESTS\_ATTEMPTS Action is already processing. Please try again after the time included in headers
INVALID\_JWS\_TOKENSpecified JWS token is invalid
Additional ValidationException reason codes:
**Reason****Description**
INVALID\_SECURITY\_CODE Security code is empty
INVALID\_LANGUAGE\_CODE Language code is empty
INVALID\_PAYMENT\_INSTRUMENT\_ID Payment instrument id is empty
UcpSdkException reason codes:
**Reason****Description**
PUSH\_INVALID\_SOURCE Relates to push processing process. Push message should be consumed in another module
PUSH\_INVALID\_PUSH\_CONTENT Cannot process push message. The message is invalid or some process failed
PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND Cannot find default PaymentInstrument
PAYMENT\_INSTRUMENT\_NOT\_FOUND Selected PaymentInstrument cannot be found, is not digitized or active
APPLICATION\_PROCESS\_NOT\_KILLEDOccurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process
#### #### Facade The facade is an entry point to communication with 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**
idStringId of payment instrument. For card it is cardId, for IBAN sha256Hex. In the context of the External Wallet Server use tokenUniqueReference from MDES
paymentTokenIdStringId of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id
displayablePanDigitsStringToken last 4 digits which can be used to display
paymentInstrumentStatusPaymentInstrumentStatusEnum with status of payment instrument.
contactlessSupportedBooleanInformation if payment instrument supports contactless transactions.
dsrpSupportedBooleanInformation if the payment instrument supports DSRP transactions.
qrcSupportedBooleanInformation if the payment instrument supports QR transactions.
onDeviceCvmSupportedBooleanInformation about supporting CVM on device.
credentialsCountIntAmount of credentials that can be used for payments.
isDefaultForContactlessPayment BooleanInformation if payment instrument is default for contactless payments.
isDefaultForRemotePaymentBooleanInformation if payment instrument is default for remote payments.
additionalAuthenticationRequiredBoolean Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods
tokenLastFourDigitsString? Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
paymentInstrumentExpirationDateString? Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately).
paymentInstrumentLastFourDigits String? Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
productConfig ProductConfig? Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately).
provisioningStatus String Current state of provisioning process. One of: IN\_PROGRESS - in case of waiting for *onProvisioningSuccess*(), SUCCESS - when token is provisioned.
paymentTokenExpirationDateString?Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled.
### ##### PaymentInstrumentStatus
**Field****Description**
INACTIVEPayment instrument is not active, it can not be used for transactions. The activation process depends on integration. Read the product overview for more information.
ACTIVEPayment instrument is active and it can be used for transactions.
SUSPENDEDPayment instrument is suspended.
DELETEDPayment instrument is DELETED.
UNKNOWNPayment instrument status is unknown.
##### ##### AdditionalAuthenticationMethod
**Parameter****Type****Description**
idStringIdentifier of additional authentication method
nameStringMethod name. One of: OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER
valueStringValue depends on method name. Described below.
issuerParametersAuthMethodsIssuerParameters?Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION
#### ##### Additional authentication method values:
**Method****Value****Description**
`OTP_TO_CARDHOLDER_NUMBER`Masked phone number Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number.
`OTP_TO_CARDHOLDER_EMAIL`Masked email Email to Account holder’s email address. The value will be the Account holder’s masked email address.
`CARDHOLDER_TO_CALL_CUSTOMER_SERVICE`Phone number Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service.
`CARDHOLDER_TO_VISIT_WEBSITE`Website URL Account holder to visit a website. The value will be the website URL.
`CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION`Application name (Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS.
`ISSUER_TO_CALL_CARDHOLDER_NUMBER`Masked phone number Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number.
#### ##### AuthMethodsIssuerParameters contains the following fields:
**Parameter****Type****Description**
mdesAuthMethodsIssuerParametersMdes?Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token
vtsAuthMethodsIssuerParametersVts?Required for VTS Payment token
#### ##### AuthMethodsIssuerParametersMdes contains following fields:
**Parameter****Type****Description**
androidAuthMethodsIssuerParametersMdesAndroidPlain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device
iosAuthMethodsIssuerParametersMdesIosPlain AuthMethodsIssuerParametersMdesIos object. Required for IOS device
#### ##### AuthMethodsIssuerParametersMdesAndroid contains following fields:
**Parameter****Type****Description**
actionString?Name of the action to be performed
packageNameString?The package name of the issuer's mobile app
extraTextValueString?Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app
##### AuthMethodsIssuerParametersMdesIos contains following fields:
**Parameter****Type****Description**
deepLinkingUrlString?The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app.
extraTextValueString?Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app.
##### AuthMethodsIssuerParametersVts contains following fields:
**Parameter****Type****Description**
androidAuthMethodsIssuerParametersVtsAndroid?Plain AuthMethodsIssuerParametersVtsAndroid object. Required for Android devices
iosAuthMethodsIssuerParametersVtsIos?Plain AuthMethodsIssuerParametersVtsIos object. Required for IOS devices
##### AuthMethodsIssuerParametersVtsAndroid contains following fields:
**Parameter****Type****Description**
appIdString?Unique identifier for the application within the application store.
appUrlString?URL of the application in the application store.
intentUrlString?URL of banking app designed to respond to authentication code handling.
requestPayloadString?The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers.
##### AuthMethodsIssuerParametersVtsIos contains following fields:
**Parameter****Type****Description**
appIdString?Unique identifier for the application within the application store.
appUrlString?URL of the application in the application store.
intentUrlString?URL of banking app designed to respond to authentication code handling.
requestPayloadString?The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers.
##### ##### ContactlessTransactionInformation
**Parameter****Type****Description**
currencyCodeByteArrayCode of currency, that was used in transaction. Formatted in ISO 4271.
amountByteArrayTransaction amount in bytes. Can be formatted as Int in pennies.
transactionRangeContactlessTransactionRangeType of transaction range.
richTransactionTypeContactlessRichTransactionTypeRich transaction type.
merchantAndLocationByteArrayMerchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset.
**ContactlessTransactionRange**
**Value****Description**
LVTLow value transaction
HVTHigh value transaction
UNKNOWNUnknown
**ContactlessRichTransactionType**
**Value**
PURCHASE
REFUND
CASH
TRANSIT
PURCHASE\_WITH\_CASHBACK
UNKNOWN
##### DsrpTransactionInfo
**Parameter****Type****Descruption**
amountLongTransaction amount
currencyCodeIntCode of currency, that was used in transaction.
countryCodeIntCode of country.
issuerCryptogramTypeStringCryptogram type.
##### TransactionAbortReason
**Value****Description**
WALLET\_CANCEL\_REQUESTIndicates that the wallet has requested a transaction cancellation during payment.
CARD\_ERRORThis indicates that a problem has been detected in the MChipEngine processing. In some implementations, this can indicate badly formatted card profile data.
TERMINAL\_ERRORThis indicates incorrect terminal behavior.
NO\_TRANSACTION\_CREDENTIALS There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility.
NO\_CARDSThere is no active PaymentInstrument to start payment. Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event).
TERMINAL\_INACTIVITY\_TIMEOUTThere is a problem with communication between the terminal and payment device. For example, the terminal could abort communication with the mobile device for a long period of time and then trigger a timeout. Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal. The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment. **Note:** When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again. **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.
##### 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**
currencyNumberIntCurrency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985.
currencyCodeString?Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN Could be null as the terminal provides only the currencyNumber and a valid code could be not found.
amountMinorLongThe monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235,
transactionRangeContactlessTransactionRangeType of transaction range.
richTransactionTypeContactlessRichTransactionTypeRich transaction type.
merchantAndLocationStringMerchant and location data from terminal. **Deprecated** - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data.
**ContactlessTransactionRange**
ValueDescription
LVTLow value transaction
HVTHigh value transaction
UNKNOWNUnknown
**ContactlessRichTransactionType**
ValueDescription
PURCHASE
REFUND
CASH
TRANSIT
PURCHASE\_WITH\_CASHBACK
UNKNOWN
WITHDRAWAL
ATM\_CONTACTLESS
##### Report
**Parameter****Type****Description**
nameStringAction name
descriptionStringAction details message.
isSuccessBooleanResult of action. True when action is finished successfully, false otherwise.
timestampLongTime when the action occurred.
errorMessageString?Detailed error message when isSuccess is false.
##### ContactlessAdvice
**Parameter****Description**
DECLINEDeclines a processing transaction. When provided by SDK in *getFinalDecisionForTransaction* wallet should not overrule a DECLINE. If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response.
AUTHENTICATION\_REQUIREDAn user authentication is required for transaction processing, which could be overruled on the MPA side. When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the *onAuthRequiredForContactless* method.
PROCEEDTransaction can be processed.
##### ContactlessTransactionResult

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

**Value****Description****Is success on MPA side**
AUTHORIZE\_ONLINEThis indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization. The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal. Should be treated as transaction success on the MPA side. Yes
AUTHENTICATE\_OFFLINEThis indicates that the POS requested a decline (AAC) with a CDA signature. SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature. Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization. Should be treated as transaction success on the MPA side. Yes
DECLINE\_BY\_TERMINALThe POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request. Paying on the terminal with offline-only network connectivity can also return this callback. Application Cryptogram was generated with genuine credentials. Should be treated as transaction success on the MPA side. Yes
DECLINE\_BY\_CARDThe digitized card has declined the transaction. A non-exhaustive list of possible reasons may be: - Context mismatch between first and second tap - Terminal is offline-only - Terminal is a transit gate, and transit transactions are not allowed by the card profile - Transaction is international, while the card profile is domestic-only No
WALLET\_ACTION\_REQUIREDIf the *getFinalDecisionForTransaction* returns an AUTHENTICATION\_REQUIRED status then this result will be returned. The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap. If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place. No
#### #### External libraries The SDK uses several external Apache 2.0 libraries: - com.nimbusds:nimbus-jose-jwt - commons-codec:commons-codec - com.fasterxml.jackson.core:jackson-core - com.fasterxml.jackson.core:jackson-annotations - com.fasterxml.jackson.core:jackson-databind - com.fasterxml.jackson.module:jackson-module-kotlin - io.insert-koin:koin-android - io.reactivex.rxjava2:rxjava - io.reactivex.rxjava2:rxandroid - com.squareup.retrofit2:adapter-rxjava2 - com.squareup.retrofit2:retrofit - com.squareup.retrofit2:converter - com.squareup.okhttp3:logging - com.squareup.okhttp3:okhttp - com.google.zxing:core - net.sf.flexjson:flexjson ## 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**
ucpConfigurationUcpConfigurationVCP configuration provided in builder described below. Not empty.
**UcpConfigurationBuilder** contains the following methods:
**Metod****Parameter****Description****Validation conditions**
withApplicationApplicationApplication context.Not empty
withCvmModelWalletCvmModel (enum)Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE Not empty
withUserAuthModeWalletAuthMode (enum)User authentication mode: WALLET\_PIN, CUSTOM, NONE Contact Verestro to select proper configuration Not empty
withUcpPaymentInstrument EventListener UcpPaymentInstrument EventListener Global listener for actions on PaymentInstrument. Not empty
withUcpTransaction EventListenerUcpTransactionEventListener Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing Not empty
withTransactionAcceptance EventListenerUcpTransactionAcceptance EventListenerGlobal listener which allow application take final decision about transaction acceptance during transactionNot empty
withReplenishThresholdIntNumber of credentials below which replenish process will automatically begin Not empty
withMcbpPinningCertificatesList<String>List of public key certificates in PEM format. Pass list with empty String if *withOptionalUcpMcbpHttpExecutor* mentioned below is used with custom HTTP communication. Not empty List
withOptionalEventsReportsUcpEventReportListenerGlobal listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. Optional
withOptional ExternalWalletServerBooleanPrepares SDK for using external wallet server.Optional
withOptional UcpMcbpHttpExecutorUcpMcbpHttpExecutor/ DefaultUcpMcbpHttpExecutorGlobal listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor.Optional
withOptional UcpReProvisionEventListenerUcpReProvisionEventListenerGlobal 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
withOptionalWalletMcbpHttpExecutorBooleanPrepares SDK for processing CMS-D HTTP requests with Wallet Server proxy. Optional
**UcpPaymentInstrumentEventListener** Contains callbacks for PaymentInstrument.
**Method name****Parameters****Description**
onProvisioning SuccesspaymentInstrument: PaymentInstrument Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below
onProvisioning FailureerrorMessage: String?, exception: Exception? Method called after provisioning failure. Try processing digitization again
onReplenish SuccesspaymentInstrument: 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 FailurepaymentInstrument: 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 StatusChangednewStatus: PaymentInstrument Status paymentInstrumentId: String Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id
onNewTransactionnewTransaction: NewTransaction Provides online result with details of transaction processed in 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 nameParametersDescription
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 UpdatedsecondsRemaining: IntCalled 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 Called when transaction is completed with information about transaction and result. ContactlessTransactionInformation is deprecated in version 2.2.4.
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**
onReProvisionSuccesspaymentInstrument: PaymentInstrumentMethod called after reProvisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback.
onReProvisionFailurepaymentInstrument : PaymentInstrument errorMessage : String? exception : Exception? Method called after reProvisioning failure. Try again.
**UcpMcbpHttpExecutor**
Method name Parameters Description
execute ucpMcbpRequestType: 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 } ``` **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()) ) 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**
paymentInstrumentIdStringId of PaymentInstrument to delete Not empty.
reasonCharArray?Optional reason of deletion
**Output**

Success / failure callback

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

Asynchronous. Online. Check eligibility required to process digitize.

**Input**
**Parameter****Type****Description**
checkEligibilityCheckEligibilityCheckEligibility object
CheckEligibility
**Parameter** **Type** **Description**
paymentInstrumentIdStringIdentifier of payment instrument
paymentInstrumentTypePaymentInstrumentTypePayment instrument type. One of: \[MASTERCARD\]
userLanguageStringUser language
userCountryStringUser country
**Output**

Success callback with CheckEligibilityResult.

CheckEligibilityResult
**Parameter** **Type** **Description**
termsAndConditionsAssetIdStringIdentifier of Terms and Conditions asset

Failure callback

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

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

#### **Input**
ParameterTypeDescriptionValidation conditions
digitizationRequestDigitizationRequestPlain object of DigitizationRequest Not empty
DigitizationRequest object contains following fields:
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringIdentifier of payment instrument Not empty
paymentInstrumentTypePaymentInstrumentTypePayment instrument type. One of: \[MASTERCARD\] Not empty
securityCodeCharArray?Optional. The CVC2 for the card to be digitized
externalPaymentTokenIdString?Optional. Unique external identifier of Payment Token
#### **Output**

Success callback with DigitizationResult object

**Parameter****Type****Description**
digitizationResultDigitizationResultPlain object of DigitizationResult
DigitizationResult contains following fields.
**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentPlain object of PaymentInstrument
additionalAuthenticationMethodsList<AdditionalAuthenticationMethod>?All available additional authentication method
productConfigProductConfigPlain object of ProductConfig, contains Payment Token configuration
externalPaymentTokenIdString?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**
isCoBrandedBooleanWhether the product is co-branded
coBrandNameString?Name of the co-branded partner
foregroundColorStringForeground color, used to overlay text on top of the card image
backgroundColorStringBackground color, used to overlay text on top of the card image
labelColorString?Label color of the mobile wallet entry for the card
issuerNameStringName of the issuing bank
shortDescriptionStringA short description for this product
longDescriptionString?A long description for this product
custoremServiceUrlString?Customer service website of the issuing bank
customerServiceEmailString?Customer service email address of issuing bank
customerServicePhoneNumberString?Customer service phone number of the issuing bank
productConfigIssuerProductConfigIssuer?Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app
onlineBankingLoginUrlString?Login URL for the issuing bank's online banking website
termsAndConditionsUrlString?URL linking to the issuing bank's terms and conditions for this product
privacyPolicyUrlString?URL linking to the issuing bank's privacy policy for this product
issuerProductConfigCodeString?Freeform identifier for this product configuration as assigned by the issuer
contactNameString?Name of the issuing bank
bankAppNameString?Name of banking application for display
bankAppAddressString?The package name for the destination mobile application
unsupportedPresentationTypesString?The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request
unsupportedCardVerificationTypesString?The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address)
issuerFlagsList<ProductConfigIssuerFlags>?List of plain ProductConfigIssuerFlags object. Contains issuer flags
brandLogoAssetIdStringThe Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID
issuerLogoAssetIdStringThe logo of the issuing bank. Provided as a Asset ID
coBrandLogoAssetIdString?The co-brand logo (if any) for this product. Provided as an Asset ID
cardBackgroundCombinedAssetIdString?The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID
cardBackgroundAssetIdString?The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID
iconAssetIdStringThe icon representing the primary brand(s) associated with this product. Provided as an Asset ID
ProductConfigIssuer contains following fields.
**Parameter****Type****Description**
openIssuerAndroidIntentProductConfigOpenIssuerAndroidIntent?AndroidIntent object can be used to open the issuer mobile app
activateWithIssuerAndroidIntentProductConfigActivateWithIssuerAndroidIntent?AndroidIntent object can be used to open the issuer mobile app
openIssuerIOSDeepLinkingUrlProductConfigOpenIssuerIOSDeepLinkingUrl?IOSDeepLinkingUrl object can be used to open the issuer mobile app
activateWithIssuerIOSDeepLinkingUrlProductConfigActivateWithIssuerIOSDeepLinkingUrl?IOSDeepLinkingUrl object can be used to open the issuer mobile app
ProductConfigOpenIssuerAndroidIntent contains following fields.
**Parameter****Type****Description**
actionStringThe name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent
packageNameStringThe package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app
extraTextValueStringContains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object
ProductConfigActivateWithIssuerAndroidIntent contains following fields.
**Parameter****Type****Description**
actionStringThe name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent
packageNameStringThe package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app
extraTextValueStringContains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object
ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.
**Parameter****Type****Description**
deepLinkinUrlStringThe deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app
extraTextValueStringContains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object
ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.
**Parameter****Type****Description**
deepLinkingUrlStringThe deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app
extraTextValueStringContains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object
ProductConfigIssuerFlags contains following fields.
**Parameter****Type****Description**
deviceBindingBooleanDevice binding
cardholderVerificationBooleanWhether the issuer participating in step-up flow
trustedBeneficiaryEnrollmentBooleanWhether this is a trusted beneficiary enrollment
delegateAuthenticationSupportedStringWhether issuer supports delegated authentication

Failure callback

Sample
``` fun digitizeCard(digitizationRequest: DigitizationRequest) { ucpApi.cardsService .digitize( digitizationRequest, { digitizationResult -> //digitization success, provisioning is in progress //application should listen to push message and provide content to UCP //refresh you payment instrument list form Cards::getPaymentInstruments //new PaymentInstrument should be visible with INACTIVE state //when push processed wait for onProvisioningSuccess or Failure callback //and status change }, { throwable -> //Something went wrong, check exception with documentation } ) } ```
### ### digitize (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**
paymentInstrumentIdStringIdentifier of payment instrument Not empty.
userLanguageStringLanguage preference selected by the consumer. Formatted as an ISO-639-1 two letter language code Not empty.
securityCodeCharArray?Optional. The CVC2 for the card to be digitized
#### **Output**

Success / failure callback

##### **Sample**
``` fun digitizeCard( paymentInstrumentId: String, languageCode: String, securityCode: CharArray) { ucpApi.cardsService .digitize(paymentInstrumentId, languageCode, securityCode, { //digitization success, provisioning is in progress //application should listen to push message and provide content to UCP //refresh you payment instrument list form Cards::getPaymentInstruments //new PaymentInstrument should be visible with INACTIVE state //when push processed wait for onProvisioningSuccess or Failure callback //and status change }, { throwable -> //Something went wrong, check exception with documentation } ) } ```
### 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**
ParameterTypeDescriptionValidation conditions
digitizationGreenPathDigitizationGreenPathPlain object of DigitizationGreenPath Not empty
DigitizationGreenPath contains following fields.
**Parameter****Type****Description**
paymentInstrumentIdStringIdentifier of payment instrument
paymentInstrumentTypePaymentInstrumentTypePayment instrument type. One of: \[MASTERCARD\]
securityCodeCharArray?Optional. The CVC2 for the card to be digitized
userLanguageStringUser language
userCountryStringUser country
externalPaymentTokenIdString?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**
getAdditionalAuthenticationMethodsGetAdditionalAuthenticationMethodsPlain object of GetAdditionalAuthenticationMethods Not empty
Fields of GetAdditionalAuthenticationMethods object:
**Parameter****Type****Description**
paymentInstrumentIdStringIdentifier of payment instrument
#### **Output**

Success callback with AdditionalAuthenticationMethods object.

**Parameter****Type****Description**
additionalAuthenticationMethodsAdditionalAuthenticationMethodsObject carrying list of AdditionalAuthenticationMethod
AdditionalAuthenticationMethods contains following value:
**Parameter****Type****Description**
additionalAuthenticationMethodsList<AdditionalAuthenticationMethod>List of AdditionalAuthenticationMethod objects

Failure callback.

**Sample**
``` private fun getAdditionalAuthenticationMethods() { val getAdditionalAuthenticationMethod = GetAdditionalAuthenticationMethods("paymentInstrumentId") ucpApi .cardsService .getAdditionalAuthenticationMethods( getAdditionalAuthenticationMethod, { additionalAuthenticationMethods -> //Handle result }, { throwable -> //Something went wrong, check exception with documentation }) } ```
### submitTokenAuthenticationValue

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

**Input**
ParameterTypeDescription
paymentInstrumentIdStringIdentifier of payment instrument
authenticationCodeStringAuthentication code
#### **Output**

Success callback/failure callback.

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

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

**Input**
**Parameter****Type****Description**
paymentInstrumentIdStringIdentifier of payment instrument
authenticationMethodIdStringId of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true.
#### **Output**

Success callback/failure callback.

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

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

**Input**
ParameterTypeDescriptionValidation conditions
refreshBooleanRefresh all PaymentInstrument objects state with remote VCP server (network and user session required)
**Output**

Success callback with list of PaymentInstrument objects.

**Parameter****Type****Description**
paymentInstrumentsList<PaymentInstrument>List of retrieved payment instruments from local or remote storage

Failure callback.

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

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

**Input**
ParameterTypeDescriptionValidation conditions
paymentInstrumentIdStringId of instrument to retrieveNot empty
refreshBooleanRefresh selected PaymentInstrument state with remote VCP server (network required)
**Output**

Success callback with PaymentInstument object.

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentRetrieved payment instrument

Failure callback.

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

Asynchronous. Online. Registers user and device if already not registered in 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**
signedAccountInfoStringSigned AccountInfo per RFC 7519 Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation Not empty.
fcmRegistrationTokenCharArrayFCM Cloud messaging registration token Not empty.
languageCodeStringLanguage preference selected by the consumer. Formatted as an ISO-639-1 two letter language code Not empty.
**AccountInfo:**
**Parameter****Type****Description****Validation conditions**
userIdStringExternal user id Not empty.
ibanStringBank Account NumberNot empty.
countryCodeStringThe country of the financial account Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 Not empty.
**Output**

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

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

IbanDigitizationResult contains following fields:
**Parameter****Type****Description**
(DEPRECATED) cloudDigitizationSuccessBooleanCloud Token Digitization Details
resultCloudDigitizationResultCloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN

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

**Sample** Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
``` class SignedAccountInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("userId", "externalUserId") .claim("iban", "IN15HIND23467433866365") .claim("countryCode", "IND") .build() val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey) // ... } ```
``` fun digitizeIban( signedAccountInfo: String, fcmRegistrationToken: CharArray, languageCode: String) { ucpApi.ibansService .digitize(signedAccountInfo, fcmRegistrationToken, languageCode, { ibanDigitizationResult -> //Device token digitization finished with success //wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success val cloudDigitizationResult = ibanDigitizationResult.result //check status of Cloud Token }, { throwable -> //Something went wrong, check exception with documentation } ) } ```
### ### createTVC

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

**Input**
**Parameter****Type****Description****Validation conditions**
signedIbanInfoStringSigned IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation Not empty.
IbanInfo
**Parameter****Type****Description****Validation conditions**
ibanIdStringIban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* Not empty.
**Output**

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

**Parameter****Type****Description**
plainTvcPlainTvc?Plain PlainTvc object
encryptedTvcCharArray?Encrypted PlainTvc object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation
PlainTvc object contains following fields.
**Parameter****Type****Description**
accountNumberCharArrayPrimary Account Number for the transaction – this is the Token PAN
dynamicExpiryDateCharArrayDynamic expiration date for the token. Expressed in YYMM format
dynamicCVCCharArrayDynamic CVC

Failure callback when TVC cannot be created.

**Sample** Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
``` class SignedIbanInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b") .build(); val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ```
``` fun createTvc(signedIbanInfo: String) { ucpApi.ibansService .createTVC(signedIbanInfo, { tvc -> //result object could contains encrypted TVC val encryptedTvc: String? = tvc.encryptedTvc //or decrypted(plain) TVC object with parameters described in documentation val plainTvc = tvc.plainTvc }, { throwable -> //Something went wrong, check exception with documentation }) } ```
### createPaymentData

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

**Input**
**Parameter****Type****Description****Validation conditions**
signedIbanInfoStringSigned IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation Not empty.
IbanInfo
**Parameter****Type****Description****Validation conditions**
ibanIdStringIban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* Not empty.
userIdStringExternal user id given by the clientNot empty.
**Output**

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

**Parameter****Type****Description**
plainPaymentDataPlainPaymentData?Plain PlainPaymentData object
encryptedPaymentDataString?Encrypted PlainPaymentData object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation
PlainPaymentData object contains following fields.
**Parameter****Type****Description**
accountNumberStringPrimary Account Number for the transaction – this is the Token PAN
applicationExpiryDateString?Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format
panSequenceNumberString?Rrquired only for UCAF. Application PAN sequence number for the Token
track2EquivalentString?Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed
ucafCryptogramString?Required only for UCAF. UCAF cryptogram
dynamicExpiryDateString?Dynamic expiration date for the token. Expressed in YYMM format
dynamicCVCString?Dynamic CVC

Failure callback when PaymentData cannot be created.

**Sample** Sample generation of *signedIbanInfo* (see [Data signing and encryption](https://wiki.verestro.com/display/UCP/Data+signing+and+encryption) chapter in Mobile DC documentation)
``` class SignedIbanInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b") .claim("userId", "123") .build(); val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ```
``` fun createPaymentData(signedIbanInfo: String) { ucpApi.ibansService .createPaymentData(signedIbanInfo, { paymentData -> //result object could contains encrypted PaymentData val encryptedPaymentData: String? = paymentData.encryptedPaymentData //or decrypted(plain) PaymentData object with parameters described in documentation val plainPaymentData = paymentData.plainPaymentData }, { throwable -> //Something went wrong, check exception with documentation }) } ```
### getAllPaymentInstruments

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

**Input**
**Parameter****Type****Description****Validation conditions**
refreshBooleanRefresh all PaymentInstrument objects state with remote VCP server (network required)
**Output**

Success callback with list of PaymentInstrument objects

**Parameter****Type****Description**
paymentInstrumentsList<PaymentInstrument>List of retrieved payment instruments

Failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringId of instrument to retrieve.Not empty
refreshBooleanRefresh selected PaymentInstrument state with remote VCP server (network required)
**Output**

Success callback with PaymentInstument object

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentRetrieved payment instrument

Failure callback

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

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

**Input**
ParameterTypeDescriptionValidation conditions
paymentInstrumentIdStringId of PaymentInstrument to delete Not empty.
reasonCharArray?Optional reason of deletion
**Output**

Success / failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringPayment instrument identity Not empty
**Output**

Success / failure callback

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

Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.

Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.

**Input**

No input parameters

**Output**

Success callback with id new default PaymentInstrument

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentDefault Payment instrument

Failure callback.

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringPayment instrument identity Not empty
**Output**

Success / failure callback

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

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

**Input**

No input parameters

**Output**

Success callback with id new default PaymentInstrument

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentDefault Payment instrument

Failure callback.

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentdStringPayment instrument identity Not empty
**Output**

Success / failure callback

**Sample**

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

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

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

Authentication 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**
paymentInstrumentIdStringPayment instrument identity Not empty
pinCharArray?PIN or null for CUSTOM WalletAuthUserMode
**Output**

Success / failure callback

**Sample** Basic user authentication usage below, call when user is authenticated.
``` private fun setUserAuthenticatedForPayment( paymentInstrument: PaymentInstrument, pinProvidedByUser: CharArray ) { ucpApi .paymentService .setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser, { //user authentication provided //start one tap payment or continue two tap with 2nd tap to terminal after authentication //listen for auth timer changes //user abortUserAuthentication method when transaction cancelled by user }, { throwable -> //some error, check exception }) } ```
Optional authentication before making transaction based on custom conditions.
``` 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**
contextContextApplication context, can be provided from HostApduService Not empty
apduByteArrayAPDU command from HostApduService::processCommandApdu method parameter Not empty
extrasBundle?Extras object from HostApduService::processCom mandApdu method parameter
**Output**

Apdu result - method called synchronous without callback

**Parameter.****Type****Description**
apduByteArrayAPDU command to return in implementation of overridden processCommandApdu method
**Sample (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**
paymentInstrumentIdStringId of paymentInstrument that needs it credentials replenished Not empty
**Output**

Success / failure callback

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

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

**Input**

No input parameters

**Output**

Success / failure callback

### requestAuthenticationCodeForPayment

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

**Input**
**Parameter****Type****Description****Validation conditions**
requestAuthenticationCodeForPaymentRequestAuthenticationCodeForPaymentPlain RequestAuthenticationCodeForPayment object Not empty
RequestAuthenticationCodeForPayment object contains following fields
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringIdentifier of payment instrument Not empty
authenticationRequestIdStringAuthentication request id up to 64 alphanumeric characters long. A new id should be used for each instance than an account holder needs to be authenticatedNot empty
**Output**

Success callback/failure callback.

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

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

**Input**
ParameterTypeDescriptionValidation conditions
validateAuthenticationCodeForPaymentValidateAuthenticationCodeForPaymentPlain ValidateAuthenticationCodeForPayment object Not empty
ValidateAuthenticationCodeForPayment object contains following fields
ParameterTypeDescriptionValidation conditions
paymentInstrumentIdStringIdentifier of payment instrument Not empty
authenticationRequestIdStringAuthentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested.Not empty
authenticationCodeStringAuthentication Code to authenticate the account holderNot empty
**Output**

Success callback with ValidateAuthenticationCodeForPaymentResult object.

ValidateAuthenticationCodeForPaymentResult object contains following field
**Parameter****Type****Description**
signedAuthenticationProcessDataStringSigned AuthenticationProcessData per RFC 7519
AuthenticationProcessData model
**Parameter****Type****Description**
authenticationRequestIdStringAuthentication request id
**Sample**
``` fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) { ucpApi.paymentService .validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment, { validateAuthenticationCodeForPaymentResult -> //ValidateAuthenticationCodeForPaymentResult plain object, //contains data to validate on backend val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult .signedAuthenticationProcessData }, { throwable -> //Something went wrong, check exception with documentation } ) } ```
Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)
``` class SignedAuthenticationProcessData { fun verifyAndGetAuthenticationRequestID() { val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600); val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId") // ... } } ```
### processDsrpTransaction(deprecated)

Asynchronous. Online.

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringPayment instrument identity Not empty
dsrpTransactionInfoDsrpTransactionInfo
**Output**

Success callback with cryptogram for payment

Failure callback

### processDsrpTransaction

Asynchronous. 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**
processDsrpTransactionProcessDsrpTransactionPlain ProcessDsrpTransaction object Not empty
ProcessDsrpTranasction object contains following fields
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringIdentifier of payment instrument Not empty
dsrpTransactionInfoDsrpTransactionInfoPlain DsrpTransactionInfo objectNot empty
DsrpTransactionInfo object contains following fields
**Parameter****Type****Description****Validation conditions**
amountMinorLongA long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 Not empty
currencyCodeStringA 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
countryCodeString?A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000.
issuer Cryptogram TypeDsrpIssuer Cryptogram TypeEnum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used.Not empty
unpredictable NumberLong 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 DataByteArrayA 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 NumberInt An integer value specifying the PAN Sequence Number (PSN) of the card used.
cryptogramTypeDsrpIssuer Cryptogram TypeEnum 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\_INPUTInvalid input data.
DSRP\_UNEXPECTED\_DATA Provided data is valid in context of validation, but doesn't mee
DSRP\_AUTHENTICATION\_REQUIREDAuthentication is not provided for DSRP payment. Authenticate and process DSRP transaction again.
DSRP\_TOKEN\_INACTIVE Token used for DSRP is inactive.
DSRP\_NO\_TRANSACTION\_CREDENTIALSThere is no transaction credentials to procees DSRP payment
DSRP\_NOT\_SUPPORTED\_BY\_CARDDSRP 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**
pushDataMap<String, String>Data received from notification service in object RemoteMessage object Not empty
**Output**

Success / failure callback. When request fails try again

**Sample**
``` //FirebaseMessagingService class from Firebase override fun onMessageReceived(remoteMessage: RemoteMessage) { super.onMessageReceived(remoteMessage) val senderId: String = remoteMessage.from val pushData = remoteMessage.data //check push source only when push source is uPaid sender Id if (isUpaidSenderId(senderId)) { //checking push source and passing to proper uPaid module mobileDcApi .cloudMessagingService .getSource(pushData, { source -> when (source) { "UCP" -> processUcpPush(pushData) } }, { //some error }) } else { //proceed push from another source } } private fun processUcpPush(pushData: Map) { ucpApi .cloudMessagingService .process(pushData, { //push processed in Mobile DC }, { //some error }) } ```
### processMcbpNotificationData

Asynchronous. 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**
encryptedPayloadStringData received from notification service in object RemoteMessage object Not empty
**Output**

Success / failure callback

``` //FirebaseMessagingService class from Firebase override fun onMessageReceived(remoteMessage: RemoteMessage) { super.onMessageReceived(remoteMessage) val senderId: String? = remoteMessage.from val pushData = remoteMessage.data //check push source based on senderId if (isMastercardSenderId(senderId)) { val mastercardPayload: String = readMastercardPushContent(pushData) ucpApi .cloudMessagingService .processMcbpNotificationData(mastercardPayload, { //push processed in Mcbp }, { //some error }) } else { //proceed push from another source } } ```
## External Wallet Server domain Chapter contains method for SDK when External Wallet Server is used. Usage of method requires additional configuration with external API. Basic MDES cloud messaging configuration:
**Environment****FCM Sender Id**
MTF502118574555
PRODUCTION993764297204
### prepareRegistrationData

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

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

Success callback with PrepareRegistrationResponse object.

**Parameter****Type****Description**
publicKeyCertificateFingerprintStringCMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded))
encryptedRgkStringEncrypted randomly-generated 128-bit AES key.
deviceInfoEwsDeviceInfoDevice info.
deviceFingerprintStringUnique device fingerprint.
encryptedPinString?Encrypted pin (if passed in input).
EwsDeviceInfo model:
**Parameter****Type****Description**
deviceNameStringDevice model name.
formFactorStringThe form factor of the target provisioned device.
storageTechnologyStringThe architecture or technology used for token storage.
osNameStringThe name of the operating system of the target provisioned device.
osVersionStringThe version of the operating system of the target provisioned device.
nfcCapableBooleanWhether the target provisioned device has NFC capability.

Failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
mobileKeysetIdStringIdentifies the Mobile Keys used for this remote management session Not empty
ewsMobileKeysEwsMobileKeysContains the mobile keys used to secure the communication during subsequent remote management sessions Not empty
remoteManagementUrlStringThe URL endpoint for subsequent remote management sessions The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions Not empty
EwsMobileKeys
**Parameter****Type****Description**
transportKeyStringThe Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES
macKeyStringThe Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES
dataEncryptionKeyStringThe Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES
**Output**

Success / failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringId of paymentInstrument to activate.Not empty.
**Output**

Success / failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringId of paymentInstrument to suspend.Not empty.
**Output**

Success / failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringId of paymentInstrument to get. Not empty.
**Output**

Success callback with PaymentInstrument object.

**Parameter****Type****Description**
paymentInstrumentPaymentInstrumentRetrieved paymentInstrument

Failure callback.

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

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

**Input**
No input parameters
**Output**

Success callback with list of PaymentInstrument objects.

**Parameter****Type****Description**
paymentInstrumentsList<PaymentInstrument>List of retrieved payment instruments from local storage

Failure callback.

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
pinCharArrayPIN to encrypt.Not empty.
**Output**

Success callback with encrypted mobile PIN.

**Parameter****Type****Description**
encryptedMobilePinStringHex encoded encrypted mobile PIN.

Failure callback.

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

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

**Input**
No input parameters
**Output**

Success / failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
paymentInstrumentIdStringId of paymentInstrument to delete.Not empty.
**Output**

Success / failure callback

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

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

**Input**
**Parameter****Type****Description****Validation conditions**
assetIdStringId of assets to retriveNot empty
**Output**

Success callback with list of Assets objects.

**Parameter****Type****Description**
ucpAssetUcpAssetPlain UcpAsset object
UcpAsset object contains following field
**Parameter****Type****Description**
contentList<UcpAssetContent>Plain list of UcpAssetContent objects
UcpAssetContent contains following fields.
**Parameter****Type****Description**
dataStringThe data for this asset. Base64-encoded data, given in the format as specified in type.
typeStringThe data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf.
widthLong?For image assets, the width of this image. Specified in pixels.
heightLong?For image assets, the width of this image. Specified in pixels.

Failure callback

**Sample**
``` fun getAsset(assetId: String) { ucpApi.assetsService .getAssets( assetId, { ucpAsset -> //List of assets of selected assetId val ucpAssetContentList = ucpAsset.content }, { throwable -> //Something went wrong, check exception with documentation } ) } ```
## DOCUMENT CHANGELOG Version 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