| **Component** | **Description** |
| MPA | Android Mobile Payment Application provides frontend interface to the user and uses part of Verestro Wallet SDK which is responsible for payments using HCE. |
| Verestro Wallet Server | Provides the backend services to support Mobile Payment Application via Verestro Wallet SDK and is responsible for managing users, devices, cards, Payment Tokens and communication with MDES. Wallet Server acts as Token Requestor on behalf of Issuer in context of digitization. |
| Verestro Wallet SDK | Provides all functionalities needed for MPA to perform all needed operations related to MCBP. |
| MDES | Token Service Provider which supports digitization(transforming the card into Payment Token) and is responsible for management, generation and provisioning of transaction credentials into mobile devices to enable simpler and more secure digital payment experience. |
| Remote Notification Service | Wallet Server communicates with the MPA also using Remote Notification Service. For Android is used Firebase Cloud Messaging. |
| Issuer | Issuer is responsible for card issuing, accepting authorization digitization requests and accepting transactions which uses token. |
| **Field** | **Description** |
|---|---|
| CDCVM | Consumer Device Cardholder Verification Method |
| CVM | Cardholder Verification Method |
| Contactless | Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to UCP SDK. HCE support is required for contactless transactions |
| DSRP | Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions |
| FCM | Firebase Cloud Messaging |
| HCE | Host Card Emulation |
| IBAN | Bank Account Number |
| MCBP | Mastercard Cloud Based Payments |
| MDC | Mobile Data Core. Verestro core library. |
| MPA | Mobile Payment Application - an application that uses UCP SDK for payments |
| NFC | Near Field Communication |
| One tap | Flow in a contactless transaction, in which the consumer after authentication(using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data |
| PAN | Primary account number. Know as a card number. |
| Payment Instrument | Model keeping all data considering entity used for payments |
| POS | Point Of Sale |
| QRC | QR Code transactions - allows consumer generate QR code to present to a merchant, who then scans it to take payment |
| SUK | Single Use Key - unique credential used for single transaction |
| Two tap | Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates(using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data |
| TVC | Token Verification Code |
| EWS | External Wallet Server |
| ```
repositories{
maven {
credentials {
username " |
| ``` dependencies{ implementation 'pl.upaid.module:ucpsdk:{version}' } ``` |
| ``` dependencies{ implementation 'pl.upaid.module:ucpsdk:{version}-debug' } ``` |
| ```
|
| **Format** | **Size** | **Notes** |
|---|---|---|
| APK | ~15,8 MB | |
| Bundle | ~3,4 MB - ~4.5 MB | Ranged size depends on the ABI of the device. SDK contains native libraries used by different ABI. By using a bundle only the necessary version of the native library will be downloaded to a device. |
| **Exception type** | **Exception class** | **Description** |
|---|---|---|
| SDK validation | ValidationException | Additional reason codes for ValidationException used in Mobile DC SDK |
| Backend exception | BackendException | Additional reason codes for BackendException used in Mobile DC SDK. **Note:** Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain) |
| SDK exception | UcpSdkException | Something went wrong on the SDK side, check the table below with possible reasons |
| Process related | - | As every process is different some methods could throw a specified exception Types of possible exceptions are described in the method description |
| **Reason** | **Description** |
|---|---|
| INTERNAL\_ERROR | Error occurred on server |
| VALIDATION\_ERROR | Client sent invalid data |
| CRYPTOGRAPHY\_ERROR | Error occurred during cryptography operation |
| PAYMENT\_CARD\_PREDIGITIZE\_ERROR | Predigitize of payment card failed |
| PAYMENT\_IBAN\_PREDIGITIZE\_ERROR | Predigitize of payment IBAN failed |
| PAYMENT\_CARD\_DIGITIZE\_ERROR | Digitize of payment card failed |
| PAYMENT\_IBAN\_DIGITIZE\_ERROR | Digitize of payment IBAN failed |
| PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED | Predigitize for payment card must be executed |
| PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED | Predigitize for payment IBAN must be executed |
| CLIENT\_UNAUTHORIZED | Client of the API is unauthorized |
| USER\_UNAUTHORIZED | User is unauthorized |
| CANT\_FIND\_USER | Cannot find user |
| CANT\_FIND\_DEVICE | Cannot find device |
| CANT\_FIND\_IBAN | Cannot find payment IBAN |
| CANT\_FIND\_CARD | Cannot find payment card |
| CANT\_FIND\_PAYMENT\_TOKEN | Cannot find payment token |
| OPERATION\_NOT\_SUPPORTED | Requested operation is not supported |
| OPERATION\_NOT\_ALLOWED | Requested operation is not allowed |
| DEVICE\_TEMPORARILY\_LOCKED | Device is temporarily locked |
| DEVICE\_PERMANENTLY\_LOCKED | Device is permanently locked |
| INVALID\_PAN | The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly |
| MISSING\_EXPIRY\_DATE | The expiry date is required for this product but was missing |
| PAN\_INELIGIBLE | The PAN is not in an approved account range for TSP |
| DEVICE\_INELIGIBLE | The device is not supported for use |
| PAN\_INELIGIBLE\_FOR\_DEVICE | The PAN is not allowed to be provisioned to the device because of Issuer rules |
| IBAN\_INELIGIBLE | The financial account does not have an associated account range in TSP |
| PARALLEL\_REQUESTS\_ATTEMPTS | Action is already processing. Please try again after the time included in headers |
| INVALID\_JWS\_TOKEN | Specified JWS token is invalid |
| **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 |
| **Reason** | **Description** |
|---|---|
| PUSH\_INVALID\_SOURCE | Relates to push processing process. Push message should be consumed in another module |
| PUSH\_INVALID\_PUSH\_CONTENT | Cannot process push message. The message is invalid or some process failed |
| PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND | Cannot find default PaymentInstrument |
| PAYMENT\_INSTRUMENT\_NOT\_FOUND | Selected PaymentInstrument cannot be found, is not digitized or active |
| APPLICATION\_PROCESS\_NOT\_KILLED | Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process |
| ```
|
| ```
|
| ``` fun isSystemDefault(): Boolean { val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context)) return cardEmulation.isDefaultServiceForCategory( WalletHceService::class.java, CardEmulation.CATEGORY_PAYMENT ) } ``` |
| ``` fun requestForSystemDefault() { val intent = Intent().apply { action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT" putExtra("component", WalletHceService::class.java) putExtra("category", CardEmulation.CATEGORY_PAYMENT) } context.startActivity(intent) } ``` |
| ``` fun registerAsOnTopHceApplication() { val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context)) cardEmulation.setPreferredService( activity, ComponentName(activity, WalletHceService::class.java) ) } fun unregisterFromOnTopHceApplication() { val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context)) cardEmulation.unsetPreferredService(activity) } ``` |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| id | String | Id of payment instrument. For card it is cardId, for IBAN sha256Hex. In the context of the External Wallet Server use tokenUniqueReference from MDES |
| paymentTokenId | String | Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id |
| displayablePanDigits | String | Token last 4 digits which can be used to display |
| paymentInstrumentStatus | PaymentInstrumentStatus | Enum with status of payment instrument. |
| contactlessSupported | Boolean | Information if payment instrument supports contactless transactions. |
| dsrpSupported | Boolean | Information if the payment instrument supports DSRP transactions. |
| qrcSupported | Boolean | Information if the payment instrument supports QR transactions. |
| onDeviceCvmSupported | Boolean | Information about supporting CVM on device. |
| credentialsCount | Int | Amount of credentials that can be used for payments. |
| isDefaultForContactlessPayment | Boolean | Information if payment instrument is default for contactless payments. |
| isDefaultForRemotePayment | Boolean | Information if payment instrument is default for remote payments. |
| additionalAuthenticationRequired | Boolean | Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods |
| tokenLastFourDigits | String? | Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentExpirationDate | String? | Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentLastFourDigits | String? | Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| productConfig | ProductConfig? | Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| **Field** | **Description** |
|---|---|
| INACTIVE | Payment instrument is not active, it can not be used for transactions. The activation process depends on integration. Read the product overview for more information. |
| ACTIVE | Payment instrument is active and it can be used for transactions. |
| SUSPENDED | Payment instrument is suspended. |
| DELETED | Payment instrument is DELETED. |
| UNKNOWN | Payment instrument status is unknown. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| id | String | Identifier of additional authentication method |
| name | String | Method name. One of: OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER |
| value | String | Value depends on method name. Described below. |
| issuerParameters | AuthMethodsIssuerParameters? | Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION |
| **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. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| mdes | AuthMethodsIssuerParametersMdes? | Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token |
| vts | AuthMethodsIssuerParametersVts? | Required for VTS Payment token |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| android | AuthMethodsIssuerParametersMdesAndroid | Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device |
| ios | AuthMethodsIssuerParametersMdesIos | Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| action | String? | Name of the action to be performed |
| packageName | String? | The package name of the issuer's mobile app |
| extraTextValue | String? | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| deepLinkingUrl | String? | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. |
| extraTextValue | String? | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| android | AuthMethodsIssuerParametersVtsAndroid? | Plain AuthMethodsIssuerParametersVtsAndroid object. Required for Android devices |
| ios | AuthMethodsIssuerParametersVtsIos? | Plain AuthMethodsIssuerParametersVtsIos object. Required for IOS devices |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa. This field is opaque to wallet providers. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| currencyCode | ByteArray | Code of currency, that was used in transaction. Formatted in ISO 4271. |
| amount | ByteArray | Transaction amount in bytes. Can be formatted as Int in pennies. |
| transactionRange | ContactlessTransactionRange | Type of transaction range. |
| richTransactionType | ContactlessRichTransactionType | Rich transaction type. |
| merchantAndLocation | ByteArray | Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset. |
| **Value** | **Description** |
|---|---|
| LVT | Low value transaction |
| HVT | High value transaction |
| UNKNOWN | Unknown |
| **Value** |
|---|
| PURCHASE |
| REFUND |
| CASH |
| TRANSIT |
| PURCHASE\_WITH\_CASHBACK |
| UNKNOWN |
| **Parameter** | **Type** | **Descruption** |
|---|---|---|
| amount | Long | Transaction amount |
| currencyCode | Int | |
| countryCode | Int | Code of country. |
| issuerCryptogramType | String | Cryptogram type. |
| **Value** | **Description** |
|---|---|
| WALLET\_CANCEL\_REQUEST | Indicates that the wallet has requested a transaction cancellation during payment. |
| CARD\_ERROR | This indicates that a problem has been detected in the MChipEngine processing. In some implementations, this can indicate badly formatted card profile data. |
| TERMINAL\_ERROR | This indicates incorrect terminal behavior. |
| NO\_TRANSACTION\_CREDENTIALS | There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility. |
| NO\_CARDS | There is no active PaymentInstrument to start payment. Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). |
| TERMINAL\_INACTIVITY\_TIMEOUT | There is a problem with communication between the terminal and payment device. For example, the terminal could abort communication with the mobile device for a long period of time and then trigger a timeout. Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal. The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment. **Note:** When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again. |
| **Field** | **Type** | **Description** |
|---|---|---|
| clientTransactionId | String? | Identifier of transaction in TSP |
| type | String | The transaction type. One of: \[UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER\] |
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, and `BHD -1.345' will return -1345 |
| currency | String | 3-digit ISO 4217 currency code |
| timestamp | String | The date/time when the transaction occurred. In ISO 8601 extended format |
| merchantName | String? | The merchant (``doing business as'') name |
| merchantPostalCode | String? | The postal code of the merchant |
| transactionCountryCode | String? | The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1 |
| comboCardAccountType | String? | An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: \[UNKNOWN, CREDIT, DEBIT\] |
| issuerResponseInformation | String? | Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: \[UNKNOWN, INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION\] |
| status | String | The authorization status of the transaction. One of: \[AUTHORIZED, DECLINED, CLEARED, REVERSED\] |
| paymentTokenId | String | Identifier of payment token in UCP |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| currencyNumber | Int | Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. |
| currencyCode | String? | Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN Could be null as the terminal provides only the currencyNumber and a valid code could be not found. |
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, |
| transactionRange | ContactlessTransactionRange | Type of transaction range. |
| richTransactionType | ContactlessRichTransactionType | Rich transaction type. |
| merchantAndLocation | String | Merchant and location data from terminal. **Deprecated** - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data. |
| Value | Description |
|---|---|
| LVT | Low value transaction |
| HVT | High value transaction |
| UNKNOWN | Unknown |
| Value | Description |
|---|---|
| PURCHASE | |
| REFUND | |
| CASH | |
| TRANSIT | |
| PURCHASE\_WITH\_CASHBACK | |
| UNKNOWN | |
| WITHDRAWAL | |
| ATM\_CONTACTLESS |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| name | String | Action name |
| description | String | Action details message. |
| isSuccess | Boolean | Result of action. True when action is finished successfully, false otherwise. |
| timestamp | Long | Time when the action occurred. |
| errorMessage | String? | Detailed error message when isSuccess is false. |
| **Parameter** | **Description** |
|---|---|
| DECLINE | Declines a processing transaction. When provided by SDK in *getFinalDecisionForTransaction* wallet should not overrule a DECLINE. If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response. |
| AUTHENTICATION\_REQUIRED | An user authentication is required for transaction processing, which could be overruled on the MPA side. When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the *onAuthRequiredForContactless* method. |
| PROCEED | Transaction can be processed. |
**Important:** MPA should always refer to transaction results on the terminal.
| **Value** | **Description** | **Is success on MPA side** |
|---|---|---|
| AUTHORIZE\_ONLINE | This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization. The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal. Should be treated as transaction success on the MPA side. | Yes |
| AUTHENTICATE\_OFFLINE | This indicates that the POS requested a decline (AAC) with a CDA signature. SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature. Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization. Should be treated as transaction success on the MPA side. | Yes |
| DECLINE\_BY\_TERMINAL | The POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request. Paying on the terminal with offline-only network connectivity can also return this callback. Application Cryptogram was generated with genuine credentials. Should be treated as transaction success on the MPA side. | Yes |
| DECLINE\_BY\_CARD | The digitized card has declined the transaction. A non-exhaustive list of possible reasons may be: - Context mismatch between first and second tap - Terminal is offline-only - Terminal is a transit gate, and transit transactions are not allowed by the card profile - Transaction is international, while the card profile is domestic-only | No |
| WALLET\_ACTION\_REQUIRED | If the *getFinalDecisionForTransaction* returns an AUTHENTICATION\_REQUIRED status then this result will be returned. The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap. If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place. | No |
Synchronous. Offline. Contains all the necessary data to configure SDK. Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method. **Important:** Before calling UCP SDK setup you must call setup from Mobile DC SDK. Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| ucpConfiguration | UcpConfiguration | UCP configuration provided in builder described below. | Not empty. |
| **Metod** | **Parameter** | **Description** | **Validation conditions** |
|---|---|---|---|
| withApplication | Application | Application context. | Not empty |
| withCvmModel | WalletCvmModel (enum) | Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE | Not empty |
| withUserAuthMode | WalletAuthMode (enum) | User authentication mode: WALLET\_PIN, CUSTOM, NONE Contact Verestro to select proper configuration | Not empty |
| withUcpPaymentInstrumentEventListener | UcpPaymentInstrumentEventListener | Global listener for actions on PaymentInstrument. | Not empty |
| withUcpTransactionEventListener | UcpTransactionEventListener | Global listener for actions during transaction processing | Not empty |
| withTransactionAcceptanceEventListener | UcpTransactionAcceptanceEventListener | Global listener which allow application take final decision about transaction acceptance during transaction | Not empty |
| withReplenishThreshold | Int | Number of credentials below which replenish process will automatically begin | Not empty |
| withMcbpPinningCertificates | List<String> | List of public key certificates in PEM format. Pass list with empty String if *withOptionalUcpMcbpHttpExecutor*mentioned below is used with custom HTTP communication. | Not empty List |
| withOptionalEventsReports | UcpEventReportListener | Global listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. | Optional |
| withOptionalExternalWalletServer | Boolean | Prepares SDK for using external wallet server. | Optional |
| withOptionalUcpMcbpHttpExecutor | UcpMcbpHttpExecutor/DefaultUcpMcbpHttpExecutor | Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. | Optional |
| withOptionalUcpReProvisionEventListener | UcpReProvisionEventListener | Global listener for actions during reprovisioning. | Optional |
| **Method name** | **Parameters** | **Description** |
|---|---|---|
| onProvisioningSuccess | paymentInstrument: PaymentInstrument | Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below |
| onProvisioningFailure | errorMessage: String?, exception: Exception? | Method called after provisioning failure. Try processing digitization again |
| onReplenishSuccess | paymentInstrument: PaymentInstrument numberOfTransactionCredentials: Int | Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials. Depending on flow is called after activation process and when requested by SDK based on *replenishThreshold* configuration. **Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
| onReplenishFailure | paymentInstrument: PaymentInstrument, errorMessage: String?, exception: Exception? | Method called after replenish failure with PaymentInstrument **Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
| onPaymentInstrumentStatusChanged | newStatus: PaymentInstrumentStatus paymentInstrumentId: String | Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id |
| onNewTransaction | newTransaction: NewTransaction | Provides online result with details of transaction processed in UCP Works only when application is online |
**Important:** It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| Method name | Parameters | Description |
|---|---|---|
| onAuthRequiredForContactless | paymentInstrument: PaymentInstrument, transactionInformation: | Called when user authentication is required during contactless transaction ContactlessTransactionInformation is deprecated in version 2.2.4. |
| onAuthRequiredForDsrp | paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo | Called when user authentication is required during Dsrp transaction |
| onAuthTimerUpdated | secondsRemaining: Int | Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration |
| onContactlessPaymentCompleted | paymentInstrument: PaymentInstrument
transactionInformation: | Called when transaction is completed with information about transaction and result. ContactlessTransactionInformation is deprecated in version 2.2.4. |
| onContactlessPaymentIncident | paymentInstrument: PaymentInstrument, exception: Exception | Called when something went wrong during transaction and Mastercard marked transaction as incident |
| onContactlessPaymentAborted | paymentInstrument: PaymentInstrument?, abortReason: TransactionAbortReason, exception: Exception | Called when transaction is aborted during payment from some reason described in method parameter PaymentInstrument could be null if abortReason = TransactionAbortReason.NO\_CARDS is returned. |
| onTransactionStopped | Method called on transaction stopped by SDK |
**Important:** It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| **Method name** | **Parameters** | **Description** |
|---|---|---|
| getFinalDecisionForTransaction | isUserAuthenticated : Boolean
recommendedAdvice : ContactlessAdvice
trasactionInformation : | 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. |
| **Method name** | **Parameters** | **Description** |
|---|---|---|
| onNewReport | report: Report | Return logs related to token management. |
| **Method Name** | **Parameters** | **Description** |
|---|---|---|
| onReProvisionSuccess | paymentInstrument: PaymentInstrument | Method called after reProvisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback. |
| onReProvisionFailure | paymentInstrument : PaymentInstrument errorMessage : String? exception : Exception? | Method called after reProvisioning failure. Try again. |
| Method name | Parameters | Description |
|---|---|---|
| execute | ucpMcbpRequestType: UcpMcbpHttpExecutorRequestTypeucpMcbpHttpMethod: UcpMcbpHttpMethodurl: StringrequestData: AnyrequestProperties: Map<String, String> | Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION, NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE. ``` |
| 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. ``` |
| ``` // UcpTransactionEventListener comments class BankingAppUcpTransactionEventListener : UcpTransactionEventListener { override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) { //authorization is required for transaction, open payment screen with authorization //show PaymentInstrument and ContactlessTransactionData available in event object showPaymentScreen(event.paymentInstrument, event.transactionData) } override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) { //authorization is required for transaction, open payment screen with authorization //show PaymentInstrument and DSRP transaction information available in event object showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo) } override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) { //check if user is on payment screen and update timer //when timer is 0, application should close payment with failure } override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) { //looks like payment is aborted, can provide result to payment screen //and show user what is abort reason } override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) { //payment completed, provide result to payment information //REMEMBER Transaction is processed on terminal and this is where //you will see final transaction result } override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) { //something went wrong during transaction, provide result to user } override fun onTransactionStopped() { //transaction is stopped by SDK, inform user and try again } } ``` |
| ``` class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener { override fun onNewTransaction(event: EventNewTransaction) { //information about new transaction processed by issuer } override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) { //status of payment instrument was changed, refresh list, inform user about new status } override fun onProvisioningFailure(event: EventProvisioningFailure) { //provisioning failed, try again } override fun onProvisioningSuccess(event: EventProvisioningSuccess) { //provisioning success, wait for status and replenish changes until user can pay //or provide activation method when required } override fun onReplenishFailure(event: EventReplenishFailure) { //transaction credentials replenish failed } override fun onReplenishSuccess(event: EventReplenishSuccess) { //transaction credentials replenish success } } ``` |
| ``` class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener { //Sample implementation of transaction acceptance listener override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice { val isScreenUnlocked = isScreenUnlocked() val isScreenProtectedByKeyguard = isScreenUnlocked() val isLvtTransaction = event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT //discard all Transit transaction if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) { return ContactlessAdvice.DECLINE } //allow for transaction when user is authenticated for payment and screen unlocked if (event.isUserAuthenticated && isScreenUnlocked) { return ContactlessAdvice.PROCEED } //allow for LVT transaction on unlocked screen when protected and don't require authentication if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) { return ContactlessAdvice.PROCEED } // ... // much more cases //require authentication anyway return ContactlessAdvice.AUTHENTICATION_REQUIRED } } ``` |
| ``` class BankReportEventListener : UcpEventReportsListener { override fun onNewReport(report: Report) { //print log for debugging, etc. } } ``` |
| ```
//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 |
| ```
//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 |
| ``` class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() { override fun onReProvisionSuccess(event: EventReProvisionSuccess) { //reProvisioning success, wait for status and replenish changes until user can pay } override fun onReProvisionFailure(event: EventReProvisionFailure) { //reProvisioning failed, try again. } } ``` |
| ```
fun setup(
application: Application,
walletCvmModel: WalletCvmModel,
walletAuthUserMode: WalletAuthUserMode,
mcbpPinningCertificates: List |
Synchronous. Offline. Method for resetting SDK to uninitialized state. **NOTE:** According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. **Please kill application process after using this method**. Trying using any facade method without stopping application process will cause throwing UcpSdkException. To avoid closing application use restart() methods. |
| ``` fun reset() { UcpApiKotlin().reset() //Terminating JVM according to MC SDK Sample Application Runtime.getRuntime().exit(0); } ``` |
| Synchronous. Offline. Method for resetting SDK to uninitialized state. Replaces reset() method which requires killing application process. When restart finishes with error, application should repeat action. **NOTE:** SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again. |
Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods. Failure callback when something went wrong during restart. Application should repeat action. |
| ``` UcpApiKotlin().restart({ //restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods }, { //some error occured, please repeat action }) ``` |
Asynchronous. Online.| Method allows delete PaymentInstument from UCP. Payment token will be removed remote and local storage. Result of action will be notified with *onPaymentInstrumentStatusChanged*. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Id of PaymentInstrument to delete | Not empty. |
| reason | CharArray? | Optional reason of deletion |
Success / failure callback |
| ``` fun delete(paymentInstrumentId: String, reason: CharArray?) { ucpApi.cardsService .delete(paymentInstrumentId, reason, { //PaymentInstrument delete requested //wait for confirmation from onPaymentInstrumentStatusChanged }, { throwable -> //Something went wrong, check excetpion with documentation } ) } ``` |
Asynchronous. Online. Check eligibility required to process digitize. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| checkEligibility | CheckEligibility | CheckEligibility object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD\] |
| userLanguage | String | User language |
| userCountry | String | User country |
Success callback with CheckEligibilityResult. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| termsAndConditionsAssetId | String | Identifier of Terms and Conditions asset |
Failure callback |
| ``` private fun checkEligibility( paymentInstrumentId: String, paymentInstrumentType: PaymentInstrumentType, userLanguage: String, userCountry: String ) { ucpApi.cardsService .checkEligibility( CheckEligibility( paymentInstrumentId, paymentInstrumentType, userLanguage, userCountry ), { checkEligibilityResult -> //Handle result }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Use only when *checkEligibility* method is used. Creates payment token in UCP backend. Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| Parameter | Type | Description | Validation conditions |
|---|---|---|---|
| digitizationRequest | DigitizationRequest | Plain object of DigitizationRequest | Not empty |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD\] | Not empty |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized | Not empty |
Success callback with DigitizationResult object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| digitizationResult | DigitizationResult | Plain object of DigitizationResult |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrument | PaymentInstrument | Plain object of PaymentInstrument |
| additionalAuthenticationMethods | List<AdditionalAuthenticationMethod>? | All available additional authentication method |
| productConfig | ProductConfig | Plain object of ProductConfig, contains Payment Token configuration |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| isCoBranded | Boolean | Whether the product is co-branded |
| coBrandName | String? | Name of the co-branded partner |
| foregroundColor | String | Foreground color, used to overlay text on top of the card image |
| backgroundColor | String | Background color, used to overlay text on top of the card image |
| labelColor | String? | Label color of the mobile wallet entry for the card |
| issuerName | String | Name of the issuing bank |
| shortDescription | String | A short description for this product |
| longDescription | String? | A long description for this product |
| custoremServiceUrl | String? | Customer service website of the issuing bank |
| customerServiceEmail | String? | Customer service email address of issuing bank |
| customerServicePhoneNumber | String? | Customer service phone number of the issuing bank |
| productConfigIssuer | ProductConfigIssuer? | Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app |
| onlineBankingLoginUrl | String? | Login URL for the issuing bank's online banking website |
| termsAndConditionsUrl | String? | URL linking to the issuing bank's terms and conditions for this product |
| privacyPolicyUrl | String? | URL linking to the issuing bank's privacy policy for this product |
| issuerProductConfigCode | String? | Freeform identifier for this product configuration as assigned by the issuer |
| contactName | String? | Name of the issuing bank |
| bankAppName | String? | Name of banking application for display |
| bankAppAddress | String? | The package name for the destination mobile application |
| unsupportedPresentationTypes | String? | The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request |
| unsupportedCardVerificationTypes | String? | The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) |
| issuerFlags | List<ProductConfigIssuerFlags>? | List of plain ProductConfigIssuerFlags object. Contains issuer flags |
| brandLogoAssetId | String | The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID |
| issuerLogoAssetId | String | The logo of the issuing bank. Provided as a Asset ID |
| coBrandLogoAssetId | String? | The co-brand logo (if any) for this product. Provided as an Asset ID |
| cardBackgroundCombinedAssetId | String? | The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID |
| cardBackgroundAssetId | String? | The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID |
| iconAssetId | String | The icon representing the primary brand(s) associated with this product. Provided as an Asset ID |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| openIssuerAndroidIntent | ProductConfigOpenIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| activateWithIssuerAndroidIntent | ProductConfigActivateWithIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| openIssuerIOSDeepLinkingUrl | ProductConfigOpenIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| activateWithIssuerIOSDeepLinkingUrl | ProductConfigActivateWithIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| deepLinkinUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| deepLinkingUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| deviceBinding | Boolean | Device binding |
| cardholderVerification | Boolean | Whether the issuer participating in step-up flow |
| trustedBeneficiaryEnrollment | Boolean | Whether this is a trusted beneficiary enrollment |
| delegateAuthenticationSupported | String | Whether issuer supports delegated authentication |
Failure callback |
| ``` fun digitizeCard(digitizationRequest: DigitizationRequest) { ucpApi.cardsService .digitize( digitizationRequest, { digitizationResult -> //digitization success, provisioning is in progress //application should listen to push message and provide content to UCP //refresh you payment instrument list form Cards::getPaymentInstruments //new PaymentInstrument should be visible with INACTIVE state //when push processed wait for onProvisioningSuccess or Failure callback //and status change }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Creates payment token in UCP backend. Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument | Not empty. |
| userLanguage | String | Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code | Not empty. |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized |
Success / failure callback |
| ``` fun digitizeCard( paymentInstrumentId: String, languageCode: String, securityCode: CharArray) { ucpApi.cardsService .digitize(paymentInstrumentId, languageCode, securityCode, { //digitization success, provisioning is in progress //application should listen to push message and provide content to UCP //refresh you payment instrument list form Cards::getPaymentInstruments //new PaymentInstrument should be visible with INACTIVE state //when push processed wait for onProvisioningSuccess or Failure callback //and status change }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Retrieves additional user authentication methods. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| getAdditionalAuthenticationMethods | GetAdditionalAuthenticationMethods | Plain object of GetAdditionalAuthenticationMethods | Not empty |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument |
Success callback with AdditionalAuthenticationMethods object. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| additionalAuthenticationMethods | AdditionalAuthenticationMethods | Object carrying list of AdditionalAuthenticationMethod |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| additionalAuthenticationMethods | List<AdditionalAuthenticationMethod> | List of AdditionalAuthenticationMethod objects |
Failure callback. |
| ``` private fun getAdditionalAuthenticationMethods() { val getAdditionalAuthenticationMethod = GetAdditionalAuthenticationMethods("paymentInstrumentId") ucpApi .cardsService .getAdditionalAuthenticationMethods( getAdditionalAuthenticationMethod, { additionalAuthenticationMethods -> //Handle result }, { throwable -> //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Online. Submit authentication code when additional user authentication is required. |
| Parameter | Type | Description |
|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument |
| authenticationCode | String | Authentication code |
Success callback/failure callback. |
| ``` private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) { ucpApi.cardsService .submitAuthenticationValue( SubmitAuthenticationValue( paymentInstrumentId, authenticationCode ), { //Handle success }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Submit authentication method when additional user authentication is required. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument |
| authenticationMethodId | String | Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. |
Success callback/failure callback. |
| ``` private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) { ucpApi.cardsService .submitAuthenticationMethod( SubmitAuthenticationMethod( paymentInstrumentId, authenticationMethodId ), { //Handle success }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online/Offline. Method for getting all payment instruments from local or remote storage. Local storage is always instant available and should be used to increase UX. Use remote way when possible to keep your payment instruments always up to date. |
| Parameter | Type | Description | Validation conditions |
|---|---|---|---|
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote UCP server (network and user session required) |
Success callback with list of PaymentInstrument objects. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments from local or remote storage |
Failure callback. |
| ``` fun getAllPaymentInstrument(refresh: Boolean) { ucpApi.cardsService .getAllPaymentInstruments( refresh, { paymentInstruments -> //List of PaymentInstrument from local or remote storage }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online/Offline. Deprecated - use getAllPaymentInstruments instead. Method for getting single PaymentInstrument from local or remote storage object based on id. Local storage is always instant available and should be used to incerese UX. Use remote way when possible to keep your payment instruments always up to date. |
| Parameter | Type | Description | Validation conditions |
|---|---|---|---|
| paymentInstrumentId | String | Id of instrument to retrieve | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote UCP server (network required) |
Success callback with PaymentInstument object. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
Failure callback. |
| ``` fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) { ucpApi.cardsService .getPaymentInstrument(paymentInstrumentId, refresh, { paymentInstrument -> //PaymentInstrument from local or remote storage }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Registers user and device if already not registered in UCP backend. Creates payment token in UCP backend. Expect push after successfull finish and then proceed using process method in Cloud Messaging domain. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| signedAccountInfo | String | Signed AccountInfo per RFC 7519 Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
| fcmRegistrationToken | CharArray | FCM Cloud messaging registration token | Not empty. |
| languageCode | String | Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code | Not empty. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| userId | String | External user id | Not empty. |
| iban | String | Bank Account Number | Not empty. |
| countryCode | String | The country of the financial account Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 | Not empty. |
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. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| (DEPRECATED) cloudDigitizationSuccess | Boolean | Cloud Token Digitization Details |
| result | CloudDigitizationResult | Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN |
Failure callback. Called when **device token** digitization finished with failure. |
| ``` class SignedAccountInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("userId", "externalUserId") .claim("iban", "IN15HIND23467433866365") .claim("countryCode", "IND") .build() val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey) // ... } ``` |
| ``` fun digitizeIban( signedAccountInfo: String, fcmRegistrationToken: CharArray, languageCode: String) { ucpApi.ibansService .digitize(signedAccountInfo, fcmRegistrationToken, languageCode, { ibanDigitizationResult -> //Device token digitization finished with success //wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success val cloudDigitizationResult = ibanDigitizationResult.result //check status of Cloud Token }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Provides Transaction Verification Code required to process cloud payments. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| signedIbanInfo | String | Signed IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* | Not empty. |
Success callback with Tvc object or encrypted Tvc object as String. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| plainTvc | PlainTvc? | Plain PlainTvc object |
| encryptedTvc | CharArray? | Encrypted PlainTvc object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| accountNumber | CharArray | Primary Account Number for the transaction – this is the Token PAN |
| dynamicExpiryDate | CharArray | Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC | CharArray | Dynamic CVC |
Failure callback when TVC cannot be created. |
| ``` class SignedIbanInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b") .build(); val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ``` |
| ``` fun createTvc(signedIbanInfo: String) { ucpApi.ibansService .createTVC(signedIbanInfo, { tvc -> //result object could contains encrypted TVC val encryptedTvc: String? = tvc.encryptedTvc //or decrypted(plain) TVC object with parameters described in documentation val plainTvc = tvc.plainTvc }, { throwable -> //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Online. This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| signedIbanInfo | String | Signed IbanInfo per RFC 7519 Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* | Not empty. |
| userId | String | External user id given by the client | Not empty. |
Success callback with PaymentData object or encrypted payment data object as String. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| plainPaymentData | PlainPaymentData? | Plain PlainPaymentData object |
| encryptedPaymentData | String? | Encrypted PlainPaymentData object per RFC 7516 Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| accountNumber | String | Primary Account Number for the transaction – this is the Token PAN |
| applicationExpiryDate | String? | Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format |
| panSequenceNumber | String? | Rrquired only for UCAF. Application PAN sequence number for the Token |
| track2Equivalent | String? | Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed |
| ucafCryptogram | String? | Required only for UCAF. UCAF cryptogram |
| dynamicExpiryDate | String? | Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC | String? | Dynamic CVC |
Failure callback when PaymentData cannot be created. |
| ``` class SignedIbanInfo { fun generate() { val claims = JWTClaimsSet.Builder() .claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b") .claim("userId", "123") .build(); val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey); // ... } } ``` |
| ``` fun createPaymentData(signedIbanInfo: String) { ucpApi.ibansService .createPaymentData(signedIbanInfo, { paymentData -> //result object could contains encrypted PaymentData val encryptedPaymentData: String? = paymentData.encryptedPaymentData //or decrypted(plain) PaymentData object with parameters described in documentation val plainPaymentData = paymentData.plainPaymentData }, { throwable -> //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Online/Offline. Method for getting all payment instruments from local or remote storage. Local storage is always instant available and should be used to incerese UX. Use remote way when possible to keep your payment instruments always up to date. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote UCP server (network required) |
Success callback with list of PaymentInstrument objects |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments |
Failure callback |
| ``` fun getAllPaymentInstrument(refresh: Boolean) { ucpApi.ibansService .getAllPaymentInstruments( refresh, { paymentInstruments -> //List of PaymentInstrument from local or remote storage }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online/Offline. Use *getAllPaymentInstruments* instead. Method for getting single PaymentInstrument from local or remote storage object based on id. Local storage is always instant available and should be used to incerese UX. Use remote way when possible to keep your payment instruments always up to date. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Id of instrument to retrieve. | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote UCP server (network required) |
Success callback with PaymentInstument object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
Failure callback |
| ``` fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) { ucpApi.ibansService .getPaymentInstrument(paymentInstrumentId, refresh, { paymentInstrument -> //PaymentInstrument from local or remote storage }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Method allows delete PaymentInstument from UCP. Payment token will be removed remote and local storage. Result of action will be notified with *onPaymentInstrumentStatusChanged*. |
| Parameter | Type | Description | Validation conditions |
|---|---|---|---|
| paymentInstrumentId | String | Id of PaymentInstrument to delete | Not empty. |
| reason | CharArray? | Optional reason of deletion |
Success / failure callback |
| ``` fun delete(paymentInstrumentId: String, reason: CharArray?) { ucpApi.ibansService .delete(paymentInstrumentId, reason, { //PaymentInstrument delete requested //wait for confirmation from onPaymentInstrumentStatusChanged }, { throwable -> //Something went wrong, check excetpion with documentation } ) } ``` |
Asynchronous. Offline. Sets payment instrument as default for contactless payment. Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment. Default payment instrument will be used automatically after linking with PoS terminal. Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Payment instrument identity | Not empty |
Success / failure callback |
| ``` fun setDefaultForContactless(paymentInstrument: PaymentInstrument) { if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) { //make sure selected PaymentInstrument can be seta as default return } val paymentInstrumentId = paymentInstrument.id ucpApi.paymentService .setDefaultForContactless(paymentInstrumentId, { //success }, { throwable -> //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Offline.Provides default PaymentInstrument for contactless payment. Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
No input parameters |
Success callback with id new default PaymentInstrument |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrument | PaymentInstrument | Default Payment instrument |
Failure callback. |
| ``` fun getDefaultForContactless() { ucpApi.paymentService .getDefaultForContactless({ paymentInstrument -> // use PaymentInstrument }, { throwable -> when (throwable) { is DefaultPaymentInstrumentNotFoundException -> { //there is no default PaymentInstrument } else -> { //check another exception with documentation } } }) } ``` |
Asynchronous. Offline. Sets payment instrument as default for DSRP payment. Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment. Default payment instrument will be used automatically to remote payments. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Payment instrument identity | Not empty |
Success / failure callback |
| ``` fun setDefaultForRemote(paymentInstrument: PaymentInstrument) { if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE && !paymentInstrument.dsrpSupported) { //make sure selected PaymentInstrument can be set as default return } val paymentInstrumentId = paymentInstrument.id ucpApi.paymentService .setDefaultForRemote(paymentInstrumentId, { //success }, { throwable -> //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Offline. Provides default PaymentInstrument for remote payments. Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
No input parameters |
Success callback with id new default PaymentInstrument |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrument | PaymentInstrument | Default Payment instrument |
Failure callback. |
| ``` fun getDefaultForRemote() { ucpApi.paymentService .getDefaultForRemote({ paymentInstrument -> // use PaymentInstrument }, { throwable -> when (throwable) { is DefaultPaymentInstrumentNotFoundException -> { //there is no default PaymentInstrument } else -> { //check another exception with documentation } } }) } ``` |
Asynchronous. Offline. Sets payment instrument as primary for next incoming contactless payment. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentd | String | Payment instrument identity | Not empty |
Success / failure callback |
**Note:** This is only sample payment scenation |
| ``` //sample scenario of starting payment with authentication before payment fun startPayment(paymentInstrument: PaymentInstrument) { //checking conditions before payment val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE val isContactlessSupported = paymentInstrument.contactlessSupported val hasTransactionCredentials = paymentInstrument.credentialsCount > 0 if (!isActive || !isContactlessSupported || !hasTransactionCredentials) { //PaymentInstrument doesn't meet requirements for payment return } //selecting PaymentInstrument to payment ucpApi.paymentService .selectForPayment(paymentInstrument.id, { //selection success //request user authentication when //... authentication presented //use setUserAuthenticatedForPayment method }, { throwable -> //something went wrong, check exception with documentation }) } ``` |
Asynchronous. Offline. Sets user as authenticated to payment with provided payment instrument. Authentication will expiry automatically after transaction time configured in payment instrument profile. **Note:** User can be authenticated based on conditions like screen unlock. Method must be called before payment in declared *HostApduService* (sample below). Make sure that authentication on this step is done securely. Transaction information are not available in this scenario. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Payment instrument identity | Not empty |
| pin | CharArray? | PIN or null for CUSTOM WalletAuthUserMode |
Success / failure callback |
| ``` private fun setUserAuthenticatedForPayment( paymentInstrument: PaymentInstrument, pinProvidedByUser: CharArray ) { ucpApi .paymentService .setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser, { //user authentication provided //start one tap payment or continue two tap with 2nd tap to terminal after authentication //listen for auth timer changes //user abortUserAuthentication method when transaction cancelled by user }, { throwable -> //some error, check exception }) } ``` |
| ``` class WalletHceService : HostApduService() { // ... private var authenticationAlreadyProcessed = false override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? { Logs.d("**** processCommandApdu") //check conditions like screen unlock etc val isUserAuthenticated = true //make sure that user already not trying to pay another way. //f.e. user selected PaymentInstrument (paymentService::selectForPayment) // or/and is already authenticated with setUserAuthenticatedForPayment method val shouldAllowToSuchFlow = true if (shouldAllowToSuchFlow && !authenticationAlreadyProcessed && isUserAuthenticated) { ucpApi .paymentService .setUserAuthenticatedForPayment( getSelectedPaymentInstrumentId(), null, //or pin { //user authenticated //make sure authentication is done only one time, clear it in onDeactivate method authenticationAlreadyProcessed = true }, { //authentication failure, check exception } ) } return ucpApi .paymentService .processHceApduCommand(this, commandApdu, extras) } override fun onDeactivated(reason: Int) { //clear flag for next transaction authenticationAlreadyProcessed = false return ucpApi .paymentService .handleHceApduDeactivationEvent(reason) } // more code implementation } ``` |
Asynchronous. Offline. Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped. |
| No input parameters |
Success / failure callback |
| ``` fun abortUserAuthenticationForPayment() { ucpApi .paymentService .abortUserAuthenticationForPayment( { //user authentication aborted //listen for auth timer changes }, { throwable -> //some error, check exception }) } ``` |
Synchronous. Offline. Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS. Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| context | Context | Application context, can be provided from HostApduService | Not empty |
| apdu | ByteArray | APDU command from HostApduService::processCommandApdu method parameter | Not empty |
| extras | Bundle? | Extras object from HostApduService::processCom mandApdu method parameter |
Apdu result - method called synchronous without callback |
| **Parameter.** | **Type** | **Description** |
|---|---|---|
| apdu | ByteArray | APDU command to return in implementation of overridden processCommandApdu method |
| ``` //WalletHceService must be registerd in AndroidManifest as nfc service class WalletHceService : HostApduService() { //... //private val ucpApi = .. override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? { return ucpApi .paymentService .processHceApduCommand(this, commandApdu, extras) } //.. } ``` |
Asynchronous. Online. Method for manually replenishing payment credentials. Application will receive push notification and notified about replenish process with global callback described in *setup*chapter. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Id of paymentInstrument that needs it credentials replenished | Not empty |
Success / failure callback |
| ``` fun replenishCredentials(paymentInstrumentId: String) { ucpApi.paymentService .replenishCredentials(paymentInstrumentId, { //request for credentials replenish finished with success //wait for push notification and pass to valid module //when push processed application will be informed about replenish success/failure //read chapter with setup for more information }, { throwable -> //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Offline. Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile. Default auth time is provided by card profile. |
No input parameters |
Success / failure callback |
Asynchronous. Online. Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| requestAuthenticationCodeForPayment | RequestAuthenticationCodeForPayment | Plain RequestAuthenticationCodeForPayment object | Not empty |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| authenticationRequestId | String | Authentication request id up to 64 alphanumeric characters long. A new id should be used for each instance than an account holder needs to be authenticated | Not empty |
Success callback/failure callback. |
| ``` fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) { ucpApi.paymentService .requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment, { //Requesting Authentication Code went successfully. }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid. |
| Parameter | Type | Description | Validation conditions |
|---|---|---|---|
| validateAuthenticationCodeForPayment | ValidateAuthenticationCodeForPayment | Plain ValidateAuthenticationCodeForPayment object | Not empty |
| Parameter | Type | Description | Validation conditions |
|---|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| authenticationRequestId | String | Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. | Not empty |
| authenticationCode | String | Authentication Code to authenticate the account holder | Not empty |
Success callback with ValidateAuthenticationCodeForPaymentResult object. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| signedAuthenticationProcessData | String | Signed AuthenticationProcessData per RFC 7519 |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| authenticationRequestId | String | Authentication request id |
| ``` fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) { ucpApi.paymentService .validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment, { validateAuthenticationCodeForPaymentResult -> //ValidateAuthenticationCodeForPaymentResult plain object, //contains data to validate on backend val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult .signedAuthenticationProcessData }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
| ``` class SignedAuthenticationProcessData { fun verifyAndGetAuthenticationRequestID() { val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600); val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId") // ... } } ``` |
Asynchronous. Online. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Payment instrument identity | Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo |
Success callback with cryptogram for payment |
Failure callback |
Asynchronous. Online. Method dedicated for starting DSRP transaction. Every DSRP transaction has to be authenticated. Depending on implementation payment can be process with OTP authentication or device level authentication. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| processDsrpTransaction | ProcessDsrpTransaction | Plain ProcessDsrpTransaction object | Not empty |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | Plain DsrpTransactionInfo object | Not empty |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| amount | Long | A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 | Not empty |
| currencyCode | Int | A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. | Not empty |
| countryCode | Int | A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. | Not empty |
| issuerCryptogramType | String | Value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. | Not empty |
Success callback with ProcessDsrpTransactionResult object. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| transactionResult | String | String contains information regarding weather the request was successful, and if so, further information about the transaction state. |
| ``` // After Merchant App delivers DSRP data application should authenticate user with device level authentication // and next execute setUserAuthenticationForPayment(). // Values for DsrpTransactionInfo delivered by Merchant APP val dsrpTransactionInfo: DsrpTransactionInfo = DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType) val processDsrpTransaction: ProcessDsrpTransaction = ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo) private fun setUserAuthenticatedForPayment( paymentInstrumentId: String, pinProvidedByUser: CharArray ) { ucpApi .paymentService .setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser, { //After succesfully authentication for payment MPA should execute processDsrpTransaction() }, { throwable -> //some error, check exception }) } fun processDsrpTransaction(processDsrpTransaction) { ucpApi.paymentService .processDsrpTransaction( processDsrpTransactionResult, { val transactionResult = processDsrpTranasctionResult.transactionResult //Information if DSRP transaction went successfully result //should be delivered to Merchant APP }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
| ``` // After Merchant App delivers DSRP data user should request authentication // code for payment with selected paymentInstrument. // Values for DsrpTransactionInfo delivered by Merchant APP val dsrpTransactionInfo: DsrpTransactionInfo = DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType) val processDsrpTransaction: ProcessDsrpTransaction = ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo) val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment = RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId) fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) { ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment, { //When requesting went successfully User will get authentication code. //In next step authentication code should be passed to MPA and application //should validate this code with validateAuthenticationCode() method }, { throwable -> //Something went wrong, check exception with documentation } ) } val validateAuthenticationCode: ValidateAuthenticationCode = ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser) fun validateAuthenticationCode(validateAuthenticationCode) { ucpApi.paymentService .validateAuthenticationCode( validateAuthenticationCode, { validateAuthenticationCodeResulty -> //ValidateAuthenticationCodeResult plain object val signedAuthenticationProcessData = validateAuthenticationCodeResulty .signedAuthenticationProcessData //If validation went successfully MPA should show authentication view, //and after valid authentication MPA should execute setUserAuthenticatedForPayment() }, { throwable -> //Something went wrong, check exception with documentation } ) } private fun setUserAuthenticatedForPayment( paymentInstrumentId: String, pinProvidedByUser: CharArray ) { ucpApi .paymentService .setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser, { //After succesfully authentication for payment MPA should execute processDsrpTransaction() }, { throwable -> //some error, check exception }) } fun processDsrpTransaction(processDsrpTransaction) { ucpApi.paymentService .processDsrpTransaction( processDsrpTransactionResult, { val transactionResult = processDsrpTranasctionResult.transactionResult //Information if DSRP transaction went successfully result //should be delivered to Merchant APP }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Processes data sent by UCP backend (push notification data). Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method. Method can throw InvalidPushException in case of invalid push content passed to it. Refer Mobile DC documentation how to handle push. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| pushData | Map<String, String> | Data received from notification service in object RemoteMessage object | Not empty |
Success / failure callback. When request fails try again |
| ```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map |
Asynchronous. Online. Processes data sent by MCBP. Application should check senderId in RemoteMessage object before passing data to UCP SDK. Basic configuration for push processing from External Wallet Server: [External Wallet Server domain](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain). Method can throw InvalidPushException in case of invalid push content passed to it. **Note:** External Wallet Server Registration process mus be finished before push processing. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| encryptedPayload | String | Data received from notification service in object RemoteMessage object | Not empty |
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 } } ``` |
| **Environment** | **FCM Sender Id** |
|---|---|
| MTF | 502118574555 |
| PRODUCTION | 993764297204 |
Asynchronous. Offline. Method for preparing data used for activation. Should be used before calling register method. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentAppInstanceId | String | Identifier for the specific Mobile Payment App instance | Not empty |
| paymentAppProviderId | String | Globally unique identifier for the Wallet Provider, as assigned by MDES | Not empty |
| publicKeyCertificate | String | CMS-D public key certificate in pem format | Not empty |
| mobilePin | CharArray? | Mobile PIN used to payment confirmation |
Success callback with PrepareRegistrationResponse object. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| publicKeyCertificateFingerprint | String | CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) |
| encryptedRgk | String | Encrypted randomly-generated 128-bit AES key. |
| deviceInfo | EwsDeviceInfo | Device info. |
| deviceFingerprint | String | Unique device fingerprint. |
| encryptedPin | String? | Encrypted pin (if passed in input). |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| deviceName | String | Device model name. |
| formFactor | String | The form factor of the target provisioned device. |
| storageTechnology | String | The architecture or technology used for token storage. |
| osName | String | The name of the operating system of the target provisioned device. |
| osVersion | String | The version of the operating system of the target provisioned device. |
| nfcCapable | Boolean | Whether the target provisioned device has NFC capability. |
Failure callback |
| ``` fun prepareRegistrationData( paymentAppInstanceId: String, paymentAppProviderId: String, publicKeyCertificate: String, mobilePin: CharArray?) { ucpApi .ewsService .prepareRegistrationData(paymentAppInstanceId, paymentAppProviderId, publicKeyCertificate, mobilePin, { prepareRegistrationResponse -> //Prepared data for registration including encryptedMobilePin if mobilePin is used }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Method used for registration new Mobile Payment App instance with MDES for use. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| mobileKeysetId | String | Identifies the Mobile Keys used for this remote management session | Not empty |
| ewsMobileKeys | EwsMobileKeys | Contains the mobile keys used to secure the communication during subsequent remote management sessions | Not empty |
| remoteManagementUrl | String | The URL endpoint for subsequent remote management sessions The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions | Not empty |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| transportKey | String | The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES |
| macKey | String | The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES |
| dataEncryptionKey | String | The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES |
Success / failure callback |
| ``` fun register( mobileKeysetId: String, ewsMobileKeys: EwsMobileKeys, remoteManagementUrl: String) { ucpApi .ewsService .register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl, { //Device registration success //application should listen to push messages and UcpPaymentInstrumentEventListener callbacks }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Method to activate PaymentInstrument. Should be used only on PaymentInstrumens which PaymentInstrumentStatus is SUSPENDED or INACTIVE. Changes PaymentInstrumentStatus to ACTIVE, calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available. Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Id of paymentInstrument to activate. | Not empty. |
Success / failure callback |
| ``` fun activate(paymentInstrumentId: String) { ucpApi .ewsService .activate(paymentInstrumentId, { //Changes PaymentInstrumentStatus to ACTIVE, set card as default for payment if another //is not already setted Performing replenish, //application should listen to push message with information about replenish success/failure }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Offline. Method for suspending paymentInstrument. Changes PaymentInstrumentStatus to SUSPENDED. Use activate method to allow payments again. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Id of paymentInstrument to suspend. | Not empty. |
Success / failure callback |
| ``` fun suspend(paymentInstrumentId: String) { ucpApi .ewsService .suspend(paymentInstrumentId, { //Changes PaymentInstrumentStatus to SUSPENDED. }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Offline. Method for getting single PaymentInstrument from local storage object based on id. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Id of paymentInstrument to get. | Not empty. |
Success callback with PaymentInstrument object. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstrument | PaymentInstrument | Retrieved paymentInstrument |
Failure callback. |
| ``` fun getPaymentInstrument(paymentInstrumentId: String) { ucpApi.ewsService .getPaymentInstrument(paymentInstrumentId, { paymentInstrument -> //PaymentInstrument from local storage }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Offline. Method for getting all payment instruments from local storage. |
| No input parameters |
Success callback with list of PaymentInstrument objects. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments from local storage |
Failure callback. |
| ``` fun getAllPaymentInstrument() { ucpApi.ewsService .getAllPaymentInstruments( { paymentInstruments -> //List of PaymentInstrument from local storage }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Offline.| Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| pin | CharArray | PIN to encrypt. | Not empty. |
Success callback with encrypted mobile PIN. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| encryptedMobilePin | String | Hex encoded encrypted mobile PIN. |
Failure callback. |
| ``` fun getEncryptedPin(pin: CharArray) { ucpApi .ewsService .getEncryptedPin(pin, { encryptedPin -> //call to Wallet Server with new created encrypted mobile PIN //when updated call onMobilePinChanged method }, { //Something went wrong, check exception with documentation }) } ``` |
Asynchronous. Online. Method for informing SDK about mobilePin change. Should be used when mobilePin changed. The result of action is deletion of existing transaction credentials and replenish. |
| No input parameters |
Success / failure callback |
| ``` fun reactOnMobilePinChanged() { ucpApi .ewsService .onMobilePinChanged( { // Informing SDK about changing mobile pin processed succesfully. // SDK should delete and next replenish transaction credentials. // Listen for UcpPaymentInstrumentEventListener events }, { throwable -> // Something went wrong, check exception with documentation. }) } ``` |
Asynchronous. Online. Method to removing PaymentInstrument. Removed transaction credentials and PaymentInstrument from local storage and in MDES. When success PaymentInstrument will be no longer available in *getPaymentInstrument* and *getPaymentInstruments*methods. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| paymentInstrumentId | String | Id of paymentInstrument to delete. | Not empty. |
Success / failure callback |
| ``` fun delete(paymentInstrumentId: String) { ucpApi .ewsService .delete(paymentInstrumentId, { //Selected Payment instrument is removed }, { throwable -> //Something went wrong, check exception with documentation } ) } ``` |
Asynchronous. Online. Method for getting all assets for selected assetId. |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|---|---|---|
| assetId | String | Id of assets to retrive | Not empty |
Success callback with list of Assets objects. |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| ucpAsset | UcpAsset | Plain UcpAsset object |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| content | List<UcpAssetContent> | Plain list of UcpAssetContent objects |
| **Parameter** | **Type** | **Description** |
|---|---|---|
| data | String | The data for this asset. Base64-encoded data, given in the format as specified in type. |
| type | String | The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. |
| width | Long? | For image assets, the width of this image. Specified in pixels. |
| height | Long? | For image assets, the width of this image. Specified in pixels. |
Failure callback |
| ``` 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 } ) } ``` |