# Token Requestor / Issuer wallet
NFC Issuer Wallet with Mobile SDK. Mastercard MCBP 2.1 SDK and Visa VTS SDK.
Due to the rename UCP and VCP are used interchangeably.
# Article
You can find more knowledge about products on this site.
# Issuer Wallet and Apple Pay / Google Pay - Differences
As we have implemented more than 50 contactless and tokenization projects for banks, fintechs and other payment institutions, let me share a quick view on key differences between various types of contactless payment technologies.
##### X-Pays
If you are a card issuer in today's world, you usually need to implement **Apple Pay** and **Google Pay** to let your users benefit from various payment activities on mobile phones. We think it is obligatory in today's world for standard card use cases. The power of Apple and Google is so strong that avoiding these platforms really impacts your customers.
In general, implementation of these technologies is not difficult. If you use our [**Token Management Platform**](https://developer.verestro.com/books/token-management-platform), implementation time can be reduced to weeks. Additionally, you have to sign contracts with Apple and Google. In the case of Apple, they charge additional fees for registering a card at Apple Pay. In the case of Google, they collect all transactions of your users to earn money on advertisement and data management. These are key disadvantages. In both cases you have to follow their requirements and changes, but if you cooperate with certified providers, you do not have problems with this, as a processor can solve these problems on your behalf.
Both Google and Apple solutions enable contactless, inApp and eCommerce payments on their browsers. The non-contactless payment transactions are an important part of these projects. You should focus not only on contactless payments.
It is worth mentioning that implementation of tokenization usually gives you access to other **X-Pays** like Fitbit Pay, Garmin Pay or others. They are much smaller companies and we treat them as nice-to-have in card issuing projects today.
##### Issuer Wallet SDK
Before Apple Pay and Google Pay appeared, both **Mastercard** and **VISA** invented other ways of contactless payments on mobile phones. They were called differently, but today they are mainly called Issuer Wallets. In such cases you do not sign contracts with Apple or Google, but you implement technology (both mobile SDKs and backend) that allows you to go live with contactless payments on mobile without signing contracts with Apple or Google. Actually it was possible for Android only, but recently (2023/2024) Apple allowed non-Apple Pay contactless payments on iPhones in the European Union.
In such cases you need to get and certify SDKs and backend components to go live with **contactless payments**. Such developments usually take 12-24 months and the software must be kept updated all the time, so it is actually better that you try to use a certified partner for this activity to avoid on-going development costs just for your project. From a contactless use case perspective, transactions work in a very similar way to X-Pays, but you have more flexibility. On Android, for example, you can implement a contactless payment just after unlocking the phone screen. You can - but do not have to - ask for additional authentication. You are also sure that data of your users and their transactions will not be shared with external entities (Apple and Google) for their benefit.
A big advantage of the Issuer Wallet SDK is that it can work not only on Android phones - for example, we have live implementations on Huawei devices. This detail has an important business impact on your users.
In today's world, working with Apple or Google is obligatory in our opinion, but we strongly recommend implementing Issuer Wallets at the same time, as it will give you more flexibility and business security in the long run. The costs and processes do not differ a lot, but the additional benefits of an issuer wallet such as flexibility, more devices, lower transaction costs make it worth implementing.
Read more: [**Push Provisioning to Google Pay and Apple Pay**](https://developer.verestro.com/books/knowledge-center/page/push-provisioning-step-by-step)
Thanks for reading.
# NFC on iPhone/iOS
#### What happened?
As part of an agreement between the European Union and Apple, Apple has decided to open access to its NFC module to 3rd party developers. It allows the creation of solutions for contactless payments (HCE), an alternative to Apple Pay.
This article aims to explain the challenges and opportunities related to this technology.
#### How it works?
- **NFC payments.** Users of participating third-party banking or wallet apps can initiate NFC transactions from within the app with compatible NFC terminals.
- **Default app settings.** Users can choose any eligible app as their default contactless payments app which will enable the app to support Field detect and Double-click features.
- **Field detect.** The default contactless payments app automatically launches when the user places the device in the presence of a compatible NFC terminal and after user authentication (if the iPhone is locked).
- **Double-click.** The default contactless payments app automatically launches when the user double-clicks the side button (for Face ID devices) or the Home button (for Touch ID) and after user authentication (if the iPhone is locked).
- **Payment support for non-default apps.** Eligible apps running in the foreground can prevent the system default contactless app from launching and interfering with the payment.
#### What are the differences compared to Android?
Since 2013 Android allows implementing alternatives to Google's own Google Pay, and there are already a few mature solutions on the market. [Apple's NFC API](https://developer.apple.com/documentation/corenfc) offers very similar capabilities from both a technical and user experience perspective. However, there are a few differences:
- **Not possible to directly ask a user to set your application as the default NFC payment app** - on Android, when users open your app, they can be presented with a dialog window that asks them if they want to use your app, as the default NFC payment app. Apple's documentation doesn't seem to hint at such a functionality.
- **Apple needs to give you special entitlement to access the NFC module** - without Apple's approval, it's not possible to include NFC payments into your app. This entitlement can be requested here: [https://developer.apple.com/contact/request/hce-payments-entitlement/](https://developer.apple.com/contact/request/hce-payments-entitlement/)
- **Security certification** - every app enabling NFC payments needs the EMVCo certification. As NFC on the Apple platform is a new thing, it's still not clear how exactly security certification will look like, however due to fundamental differences between Android and iOS we can expect slight differences.
#### What are the differences compared to Apple Pay?
Apple's API allows 3dr party developers to implement most of the functionality offered by Apple Pay. Two slight differences are:
- Power Reserve Mode - Apple Pay allows payments with the default card for some time after the iPhone battery is depleted.
- Express Transit Mode - allows to pay for public transport tickets in a few areas with compatible cards, without unlocking the iPhone. Full list of locations is [available here](https://support.apple.com/en-us/118625).
#### Will it work outside the EU?
Companies registered in the European Economic Area can offer this functionality to customers based in EEA. The table below shows various combinations of companies wanting to offer HCE payments in their App and customers, and the expected outcome according to Apple's requirements.
|
| **Company developing App established & licensed for payments in EEA**
| **Company developing App not present in EEA or not licensed for payments in EEA**
|
| **EEA citizen, transacting in EEA country**
| ✅HCE available
| ❌HCE not Available
|
| **EEA citizen, transacting outside EEA (traveling)**
| ✅HCE available | ❌HCE not Available |
| **non-EEA citizen, transacting in EEA country (traveling)**
| ❌HCE not Available | ❌HCE not Available |
| **non-EEA citizen, transacting outside EEA country** | ❌HCE not Available | ❌HCE not Available |
# On-device tokenization in India
Payment law in India required a few years ago that server based card-on-file systems are not allowed. Instead, there is a necessity to store user data on-device to perform transactions.
This is an interesting topic that impacted a lot of local players like big merchants, Cred, Phonepe or Amazon so let me describe it in some details because maybe it will be implemented in a few years in other countries as well.
Requirement for storing tokens in a secure way on customer devices forces us to implement and certify secure SDK in which payment token data will be saved. It is a similar concept to standard HCE (Host Card Emulation) implementation for mobile NFC payments. While registering to a merchant or wallet system, the user adds a payment card, performs tokenization with approval (One-Time-Passwords) of the issuing bank and the token connected with his card is stored in this wallet / SDK.
Once we have a secure place of storing the user's token on his mobile phone we can use this token for multiple purposes:
1. NFC / contactless payments - the user uses his phone to perform transactions on a contactless acceptance network. Token and payment keys are transferred through the contactless interface to the payment terminal and acquirer for authorization.
2. inApp - the user chooses products and adds them to the basket in the merchant app, clicks that he wants to pay with a particular wallet or payment brand and confirms the transaction in a wallet app. The token is taken from an SDK, transferred to the cooperating acquirer in the form of a DSRP message (Dynamic Secured Remote Payment) and processed in standard way
3. web purchase - the user chooses products and adds them to the basket on the merchant website, clicks that he/she wants to pay with a particular wallet or payment brand and receives a push notification in his/her mobile app to finalize the transaction. As above, the token is taken from an SDK, transferred to the cooperating acquirer in the form of a DSRP message (Dynamic Secured Remote Payment) and processed in standard way. There could be a possibility to store the token inside the browser of the user on his laptop / PC but this requires more discussion with Mastercard and VISA.
To enable these use cases, several implementation points needs to be considered:
- types of devices - an inApp and web purchase can work on all devices (iOS and Android) but NFC is enabled on Android only. Apple is blocking the NFC access outside of the European Union today.
- VISA vs Mastercard - do you need a solution working for both schemes? Are there any local certification requirements?
- Issuers - are banks ready to connect to your new X-Pay wallet? Which banks are enabled on local markets?
- local on-soil requirements - is there a need to store data in the country? What are the legal impacts?
This is an interesting development and area of work. We are live with a few partners and are happy to work with new ones. Please contact us if you are interested.
Thanks for reading.
# Introduction
**Token Requestor Service** is an end-to-end solution designed to enable **Issuer Wallets** for secure and flexible **NFC payments** on both Android and iOS platforms.
Tailored for banks, fintechs, and other financial institutions, this solution empowers you to build a seamless and scalable digital payment ecosystem directly within your **Mobile Banking** or **Payment App**.
## Core Components of the Solution
The Token Requestor Service is a set of components that together deliver a comprehensive and highly customizable payment experience:
**Android SDK**
A certified and highly configurable library for managing token lifecycle and NFC transactions. Fully compliant with [**EMVCo standards**](https://www.emvco.com/approved-registered/approved-products/?action=search_products&approved_product_expiration_date=2020-08-31&px_search=&emvco_product_sbmp%5B0%5D=mobile-app-sdk&sort=approved_product_expiration_date&sort_order=ASC), the SDK supports integration into existing applications and ensures secure and smooth payment flows.
**iOS SDK**
Enabling in-app token-based payments based on Apple's **HCE Transactions for Apps**. The solution allows you to create a **standalone wallet on iOS**, fully independent from Apple Pay.
**Huawei Wearables SDK**
A dedicated SDK enabling tokenized **NFC payments on Huawei smartwatches**, compatible with both Android and iOS smartphone.
**Server Component**
A backend system integrated with **Mastercard’s MDES**, **Visa’s VTS**, and a range of proprietary **Verestro services**, managing card digitization, provisioning, and lifecycle events.
## Key Capabilities
**Full control over card, user, and token lifecycles**
Manage how cards are issued, provisioned, and revoked within your own ecosystem.
**Support for Huawei smartwatches**
Tokenized payments can be enabled on [Huawei wearable devices](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/watch-integration) for both Android and iOS. Notably, **payments via Huawei smartwatches are also available when paired with iPhones, even outside the EEA**.
**Certified and secure**
Built in compliance with global standards, including **EMVCo certification**, ensuring maximum security and interoperability.
**Customizable user experience**
As an Issuer Wallet solution, you retain full flexibility over the UX, allowing seamless integration of additional products and services into your app.
## Easy Integration and Deployment
Whether you're looking to add tokenized payments to an existing mobile application or launch a brand-new digital wallet, integration is simple.
**We provide:**
- A complete SDK package (Android and iOS)
- Backend server components
- Technical integration support
- Optionally, fully developed white-label applications
## Ready to Get Started?
Launching tokenized NFC payments has never been easier. Simply:
1. **Open a project with MDES or VTS**
2. **Integrate our SDKs**
3. **Expand the services you offer to your customers**
We provide full documentation, fast onboarding, and professional support throughout the process.
👉 [**Explore documentation**](https://developer.verestro.com/books/token-requestor-issuer-wallet)
**MDES** and **VTS** integration as token requestor. Issuer wallet or SDK integrated into mobile banking application. Available on all Android phones (including Huawei) and all countries. Enables mobile contactless transactions using NFC interface.
**API**
MDES (Mastercard Digital Enablement Service) and VTS (Visa Token Service)
**Readiness**
Live
**SDK available**
Yes
**White label solution available**
Yes
**Certification**
Yes, full security and functional certification
**Implementation time**
3 months from contracting
[  ](https://developer.verestro.com/attachments/50)
## Architecture
[  ](https://developer.verestro.com/uploads/images/gallery/2026-03/issuer-wallet-2.jpg)
# Overview
Verestro Cloud Payments is a solution developed to facilitate adopting cloud-based payments for the Customers. VCP provides functionalities for User identification and verification, Payment Instruments digitization and User data management. Cloud payments enables a card to be digitized into a wallet application on a mobile device and used for payment without the need for a Secure Element (SE) or a Trusted Execution Environment (TEE) to protect the card's sensitive assets, such as the keys needed for calculating the Application Cryptogram. Master Keys for the digitized card are kept securely on remote servers (for plastic in the chip), hence the term 'cloud-based payment,' and a limited number of keys (where each key can only be used to perform a single transaction) are downloaded to the application.
## Solution Components
**Server components**
• Wallet Server - backend component,
• Wallet Admin Panel - frontend component
**Mobile components**
• Wallet SDK - Android and iOS libraries,
• Wearable SDK - libraries for payments with Huawei Smartwatches
[  ](https://developer.verestro.com/attachments/61)
### **MCBP Key Components**
| **Component** | **Description** |
| MPA | Mobile Payment Application (for Android and iOS Smartphones) provides frontend interface to the user and uses part of Verestro Wallet SDK which is responsible for payments using HCE. In case of wearable payments, MPA acts as companion app. |
| 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. |
## Description
### **Wallet Types**
VCP supports following wallet types which can be used in the implementation:
- **OPEN** - user registers itself in the application and provides data like PAN etc.,
- **CLOSED** - user data are passed automatically from Customer servers without User interaction to Wallet Server.
### **Implementation Models**
Verestro provides two different implementation models for products: **integrated** and **standalone** version.
**Integrated**
In this model Customer is owner of MPA. Verestro provides Wallet SDK and Wallet Server. Customer is responsible for direct User authentication and passes the result of the authentication to Wallet SDK. Online operations which need to be performed by User using Wallet Server require valid session on Wallet Server. To obtain user online session with Wallet Server, Customer needs to pass Trusted Identity.
**Standalone**
In this model Verestro provides MPA, Wallet SDK and Wallet Server. Furthermore, Verestro manages direct user authentication.
[  ](https://developer.verestro.com/attachments/51)
### **Server Components**
Server components are applications which need to be deployed on remote server to make possible to connect them by network.
#### **Deployment Models**
Verestro offers two deployment models of server components: **On-premise** and **SaaS**.
**On-premise**
Server components also can be deployed on Customer infrastructure. Applications are designed to be deployed using [Kubernetes](https://kubernetes.io/) as system for automating deployment, scaling, and management of containerized applications. For more details please contact Verestro representative.
**SaaS**
Server components are designed to be deployed in SaaS model. In this case everything is deployed and configured on Verestro side. Verestro is responsible for maintaining infrastructure, deploying applications and monitoring.
[  ](https://developer.verestro.com/attachments/58)
#### **Wallet Admin Panel**
Web frontend application which is dedicated for back office to manage all User data.
### **Mobile Components**
#### **Wallet SDK**
Verestro provides Software Development Kit (SDK) called Wallet SDK which can be used in Mobile Payment Application. As a company, Verestro provides many products which can be used in single application. For that reason Wallet SDK is divided into separated modules which covers different functionalities. There are two main modules dedicated for Verestro Cloud Payments: **MDC SDK** and **VCP SDK**.
**MDC SDK** is core Verestro module responsible for user data management: authentication, payment cards management - since these are main functionalities used in every product. VCP SDK is dedicated for performing digitization and payments using Payment Token. In payment context VCP SDK wraps Mastercard Cloud Based Payment SDK.
#### **Wearables SDK**
Product supports contactless payments using Huawei smartwatches. There are multiple SDKs to be implemented both - on smartphone and wearable device. Smartphone app serves as companion app in this process. Wearable payments are fully compliant with smartphone-only solution, and act alongside it. Wearables SDK is extension, but uses wallet SDK even if smartphone payments are not necessary in project.
#### **Requirements**
**Important!** Wallet SDK has some mandatory requirements to make it work:
- device cannot be rooted,
- Android OS image (ROM) should be genuine in version 6.0 (Marshmallow) or above,
- devices cannot have enabled debugging.
There are also some **not mandatory** requirements, but Customer needs to be aware of them to maintain functionalities:
- NFC module necessary for HCE payments,
- lock screen necessary for locally-verified user authentication.
#### **Security**
Wallet SDK was developed according to security requirements included in Security Guide MCBP SDK for Android. However Wallet SDK cannot guarantee full MPA protection and MPA must provide additional layer of security to protect user interface (mainly when PAN is manually entered in the application) and data processing within application. More detailed information can be found in *Wallet SDK API.* Moreover all sensitive data are passed as chars or bytes arrays. Wallet SDK copies the arrays and clears that copies just after processing. MPA should clear provided sensitive data immediately after passing them to Wallet SDK.
**Security Checks and Data Clearing**
On Wallet SDK side are performed security checks which includes static code analysis protection and dynamic analysis protection. Security checks consists of:
- root access detection,
- hooking protection,
- debugging protection,
- custom ROM protection,
- data tampering protection,
- man in the middle protection.
Security checks are performed periodically, if Wallet SDK detects any of above things all data hold by Wallet SDK will be cleared and security report will be sent to Wallet Server. MPA will be informed about such detection.
**Communication with Wallet Server**
Communication from genuine applications which are installed on genuine devices is accepted by the Wallet Server. Wallet SDK at the very beginning performs authentication of application and device to Wallet Server. This authentication may take advantage of Google Play Integrity which is a 3rd-party trusted side in whole authentication. Google Play Integrity verifies device and sign information about device and application. Signed data from Play Integrity are sent to the Wallet Server. Wallet Server verifies data and allow or does not allow for further communication. Application is verified according preconfigured application certificate digest used for signing application.
**Important!** There is a limit of requests to Google Play Integrity API: 10 000 per day. If Customer predicts that there will be more installations per day then this limit needs to be increased during Google Project Setup.
Wallet SDK communicates with Wallet Server using TLS 1.2. Wallet SDK performs public key certificate pinning when it tries to establish connection with Wallet Server (similar with connection to MDES). Certificates for the pinning needs to be provided to SDK. Sensitive information are additionally encrypted and/or signed.
**Versioning**
Wallet SDK uses semantic versioning. It means that every release has own version which is MAJOR.MINOR.PATCH, where:
- MAJOR version increases when SDK has incompatible API changes,
- MINOR version increases when new functionality is added in a backwards compatible manner,
- PATCH version increases when new backwards compatible bug fixes are introduced.
MAJOR versions are supported 6 months and Customer needs to migrate to new version if they want to maintain support.
#### **Remote Notification Service**
Wallet SDK is responsible for remote notification processing. However MPA is responsible for obtaining FCM registration token, handling FCM token update and receiving remote notifications. Before passing remote notification to SDK, MPA needs to verify if given message is dedicated for SDK by checking sender Id. Sender Id is configured during onboarding. Verestro will create new FCM project and provide data needed to obtain FCM token for given project. Due to observing some issues with FCM token refresh notification from FCM service, additional check of new token availability is recommended (e.g. on application start). See more in *Wallet SDK API.*
#### **Access**
Wallet SDK is stored as artifacts in maven repository. Access there is provided during onboarding by Verestro representative.
### **Configuration**
Whole product has configuration which needs to be fulfilled. This configuration also consists of data which are set in MDES. More details are described in *Wallet Configuration*.
### **User Experience for Contactless Transactions**
MDES offers a few options for customers for defining user experience for contactless transactions. Final option is the choice of CDCVM type (Mobile PIN, Locally-verified CDCVM) and CVM model (Always, Flexible, Card-like).
#### **CDCVM Types**
There are two types of Consumer Device Cardholder Verification Method (CDCVM) which are supported by MDES.
##### **Mobile PIN CDCVM**
A PIN value (4–8 digits) that the cardholder enters on the mobile device and that is validated online by MDES during the transaction authorization process. Since Locally-verified is mostly preferable option, Mobile PIN is out of scope.
##### **Locally-verified CDCVM**
A CDCVM entered on and validated by the consumer's mobile device, for example system device PIN, pattern, password or biometric methods (such as fingerprint, iris or facial recognition). Swipe (slide to unlock) is not a valid cardholder verification method and must not be supported. These methods are commonly associated with a device unlock process and are validated on the cardholder's mobile device. The payment component embedded in the Mobile Payment Application will use the outcome of this authentication process. A Locally-verified CDCVM applies to all the payment tokens of a given Mobile Payment Application instance ("Wallet-level"). In some parts of system this type is also named as Custom.
### **CVM Models**
For two CDCVM types customer can apply different user experience CVM Models.
#### **Always CVM**
In this model the card profiles supplied to the SDK are configured to indicate that the mobile device supports on-device cardholder authentication. When transactions are performed on a POS supporting CDCVM, the POS will delegate cardholder authentication to the mobile device the terminal will not request an Online PIN on the terminal. In POS which does not support CDCVM cardholder authentication is required using Online PIN. This model requires the cardholder's mobile device to authenticate the cardholder for all transactions (LVT, HVT, Transit). CDCVM can be performed using either a Mobile PIN or a Locally-verified CDCVM. MPA is expected to decline any transaction for which cardholder authentication is not performed or is unsuccessful.
Below are presented sample diagrams which show how the transactions can look like:
*Always LVT, HVT - single tap*
[  ](https://developer.verestro.com/attachments/52)
*Always LVT, HVT - double tap*
[  ](https://developer.verestro.com/attachments/54)
#### **Flexible CVM**
In this model the card profile also indicates that the mobile device supports on device cardholder authentication Mobile PIN or Locally-verified CDCVM. However rather than applying authentication for every transaction the MPA defines flexible criteria such as allowing multiple transactions between each authentication. This criteria are often named as Lost & Stolen options or velocity checks. For transit transactions cardholder authentication is not expected.
Below are presented sample diagrams which show how the transactions can look like:
*Flexible LVT*
[  ](https://developer.verestro.com/attachments/56)
*Flexible HVT - single tap*
[  ](https://developer.verestro.com/attachments/57)
*Flexible HVT, LVT with Velocity counters - double tap*
[  ](https://developer.verestro.com/attachments/60)
#### **Card-like CVM**
In this model the card profiles supplied to the SDK are configured to indicate that the mobile wallet is not capable of supporting on device cardholder verification. This means that when transactions are performed with a Point of Sale (POS) terminal, the POS will treat the transaction in the same way as a card transaction. Typically this means that low value transactions (LVTs) will be processed without additional user authentication and if supported, high value transactions will require an online PIN to be provided on POS. This model is put here just for general information, however it is not preferred for issuer wallets.
Below are presented sample diagrams which show how the transactions can look like:
*Card like LVT*
[  ](https://developer.verestro.com/attachments/55)
*Card like HVT*
[  ](https://developer.verestro.com/attachments/53)
#### **Lost & Stolen Options**
The Lost & Stolen options are dedicated to control performing transactions allowed before requiring cardholder authentication. This limits fraud risk if the cardholder's mobile device is lost or stolen. Lost & Stolen options can be applied only for Flexible CDCVM. These options also are known as velocity check counters. Wallet SDK provides interface which is invoked during transaction. Transaction information like range, rich transaction type, amount are provided within this interface. MPA can implement various checks to support velocity check counters using transaction information. MPA for example can count LVT transactions and allow only some predefined number of LVT transactions without cardholder authentication.
#### **Transit Transactions**
Transit transactions are transactions with given Merchant Category Code performed e.g. on traffic gates like: underground. It is up to Customer if wants to enable such transactions or not (option selected during MDES onboarding). Transit transactions are enabled in every CVM model, however for Always CDCVM needs to be performed for every transaction, for Card-Like and Flexible CDCVM can be skipped.
### **Tokenization/Digitization**
Tokenization is a process which enable to replace sensitive data, e.g. card number, with another string of characters - a secure payment token - as a result of which card data remains inaccessible. Payment tokens are assigned to a given device of the card owner, which means that an unauthorized person, even if he obtains the token data, will not be able to use them via another device. It is also secured inside the SDK. As a result of the tokenization process, the customer comes into possession of Transaction Credentials in a mobile application on his device.
[  ](https://developer.verestro.com/attachments/62)
#### **Digitization decisions**
Green
**APPROVED**
Approve the digitization request without further cardholder interaction.
Yellow
**REQUIRE\_ADDITIONAL\_AUTHENTICATION**
Approve the digitization request but seek additional cardholder authentication.
Red
**DECLINED**
Decline the digitization.
**One-Step Digitization**
Simplified process for implementations requiring no additional authentication. Expects **APPROVED** or **DECLINED** outcome only.
**Multi-Step Digitization**
Includes eligibility checking, terms & conditions display, and digitization. May result in **APPROVED**, **DECLINED**, or **REQUIRE\_ADDITIONAL\_AUTHENTICATION** outcome.
**Automatic**
After every transaction, Wallet SDK checks if the number of transaction credentials has fallen below a preconfigured threshold. If so, replenishment is triggered automatically.
**Initial**
Occurs directly after successful token activation without requiring any MPA action.
**Manual**
Allows explicit user-initiated credential refresh when automatic processes fail, particularly when internet connectivity is limited.
**Issuer integration with MDES.**
**Completing BPMS/ICG file - configuration for issuers in MDES:**
• PAN ranges allowed for digitization,
• channel for the authorization cards for the digitization: predigitization API/ISO 8583 messages,
• digitization path,
**Completing PCG file - configuration for token requestors (wallet configuration):**
• parameters for connection,
• transactions user experience,
**Exchanging certificates:**
• connection,
• external wrapping key,
• payload encryption to mdes,
• tav,
**Adopt LC API to pass users and cards into wallet server and manage them later**
**Integrate SDK into issuer application**
**Implement signing user identity to authenticate user on wallet server via SDK**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant Issuer
MPA -> SDK: 1. UCP:Cards#checkEligibility(paymentInstrumentId=verestroCardId, locale)
activate MPA
activate SDK
SDK -> SDK: 2. isDeviceRegisteredForPayment
alt isDeviceRegisteredForPayment=false
SDK -> WS: 3. getPkCertificate
activate WS
WS -> MDES: 4. getPkCertificate
activate MDES
MDES --> WS: 5. response(pkCertificate)
WS --> SDK: 6. response(pkCertificate)
SDK -> SDK: 7. prepareDataForRegistration(pkCertificate)
SDK -> WS: 8. registerDeviceForPayment (paymentDeviceInfo, userSessionToken)
WS -> MDES: 9. registerMobilePaymentApplication (paymentDeviceInfo)
MDES --> WS: 10. response(mobileKeys, remoteManagementUrl)
WS --> SDK: 11. response(mobileKeys, remoteManagementUrl)
end
SDK -> WS: 12. checkEligibility(paymentInstrumentId,userSessionToken)
WS -> MDES: 13. checkEligibility(card)
MDES -->WS: 14. response(termsAndConditionsAssetId, eligibilityReceipt)
WS --> SDK: 15. response(termsAndConditionsAssetId, digitizationRef)
SDK --> MPA: 16. result(termsAndConditionsAssetId)
MPA -> SDK: 17. UCP:getAsset(termsAndConditionsAssetId)
SDK -> WS: 18. getAsset(termsAndConditionsAssetId)
WS -> MDES: 19. getAsset(termsAndConditionsAssetId)
MDES --> WS: 20. response(content)
deactivate MDES
WS --> SDK: 21. response(content)
deactivate WS
SDK --> MPA: 22. result
deactivate SDK
MPA -> User: 23. show T&C
deactivate MPA
User -> MPA: 24. accept
activate MPA
MPA -> SDK: 25. UCP:Cards#digitize(paymentInstrumentId, cvc?)
activate SDK
SDK -> WS: 26. digitize(digitizationRef, cvc?, userSessionToken)
activate WS
WS ->MDES: 27. digitize(eligibilityReceipt, cvc?)
activate MDES
MDES --> WS: 28. response(additionalAuthenticationRequired, authenticationMethods?, tokenInfo, productConfig)
deactivate MDES
WS --> SDK: 29. response(additionalAuthenticationRequired, authenticationMethods?, tokenInfo, productConfig)
deactivate WS
SDK --> MPA: 30. result
deactivate SDK
MPA -> User: 31. please wait
deactivate MPA
note over SDK, WS #1C1E3F: See Card digitization outcome Approved or Decline or Require Additional Authentication diagram
@enduml
##### Card Digitazation Outcomes
There are following digitization outcomes which should be handled differently:
- APPROVED
- DECLINED
- REQUIRE\_ADDITIONAL\_AUTHENTICATION
##### APPROVED
This digitization outcome always refers to green path digitization decision. When digitization is APPROVED then profile provisioning(See Profile Provisioning) starts automatically. According to MDES architecture just after digitization Payment Token is in INACTIVE state even though does not require additional User authentication. Due that fact new flag was introduced which informs which Payment Token exactly needs to be additionally authenticated. After successful provisioning token is activated and then SDK will perform Transaction Credentials - Initial Replenishment.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
group APPROVED
MDES --> WS : 1. responseFromDigitization(APPROVED, cardDigitizationData)
activate MDES
activate WS
opt
WS ->>Issuer: 2. send Payment Token Event
end
WS --> SDK : 3. response(digitizatonData, paymentToken)
deactivate WS
activate SDK
SDK --> MPA : 4. result
activate MPA
MPA --> User : 5. result
deactivate MPA
... Profile Provisioning ...
note over MPA, MDES #1C1E3F: See Profile Provisioning diagram
... MDES Token Activation ...
SDK -> MDES: 6. notifyProvisioningResult
MDES -> MDES: 7. createTokenMapping
MDES -> WS: 8. notifyTokenUpdated(Active)
deactivate MDES
activate WS
opt
WS ->>Issuer: 9. send Payment Token Event
end
WS -> SDK: 10. deliverMessage(paymentTokenActive)
NOTE LEFT: See: Handle Message From Server
deactivate WS
SDK -> SDK: 11. updateTokenStatus
SDK -> MPA: 12. onPaymentInstrumentStatusChanged(id, status)
deactivate MPA
deactivate SDK
... Initial Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
end
@enduml
##### DECLINE
This digitization outcome refers to red digitization decision.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
group APPROVED
MDES --> WS : 1. responseFromDigitization(DECLINED)
activate MDES
deactivate MDES
activate WS
WS --> SDK : 2. response(error)
deactivate WS
activate SDK
SDK --> MPA : 3. result
deactivate SDK
activate MPA
MPA --> User : 4 result
deactivate MPA
@enduml
##### REQUIRE\_ADDITIONAL\_AUTHENTICATION
This digitization outcome always refers to yellow path digitization decision. When digitization is REQUIRE\_ADDITIONAL\_AUTHENTICATION then profile provisioning(See Profile Provisioning) starts automatically but remain INACTIVE until the User is authenticated(see Card Digitization Activation). Flag *additionalAuthenticationRequired* informs if additional user authentication is needed or not.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
group REQUIRE\_ADDITIONAL\_AUTHENTICATION
MDES --> WS : 1. responseFromDigitization(response(additionalAuthenticationRequired=true, authenticationMethods?, tokenInfo, productConfig))
activate MDES
deactivate MDES
activate WS
opt
WS ->> Issuer: 2. send Payment Token event
end
WS --> SDK : 3. response(response(additionalAuthenticationRequired=true, authenticationMethods?, tokenInfo, productConfig))
deactivate WS
activate SDK
SDK --> MPA : 4. result
deactivate SDK
activate MPA
MPA --> User : 5. result
deactivate MPA
... Profile Provisioning ...
note over MPA, MDES #1C1E3F: See Profile Provisioning diagram
... Card Digitization Activation ...
note over MPA, MDES #1C1E3F: See Card Digitization Activation diagram
end
@enduml
##### Card Digitization Activation
This process is applicable only if digitization has infomation that additional authentication is required. During this process User can choose one of the additional authentication methods. If user-entered authentication code is chosen then MDES will send authentication code which later should be provided by User for submission. Once user enters correct authentication code, Payment Token is activated by MDES asynchronously. After activation Wallet Server is notified that Payment Token is activated and this information is passed to Wallet SDK. After Payment Token activation, Wallet SDK start Transaction Credentials - Initial Replenishment.
NOTE: Submit authentication value is allowed only if provisioning is finished.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
alt Just after digitization
MDES --> WS : 1. responseFromDigitization(additionalAuthenticationRequired=true, \\rauthenticationMethods?, tokenInfo,productConfig)
activate MDES
activate WS
WS --> SDK : 2. response(additionalAuthenticationRequired=true, \\rauthenticationMethods?, tokenInfo, productConfig)
activate SDK
SDK --> MPA: 3. result(authenticationMethods)
activate MPA
else Activation not finished after digitization
User -> MPA: 4. activate token
MPA -> SDK: 5. UCP::getAdditionalAuthenticationMethods(paymentInstrumentId)
SDK -> WS: 6. getAuthenticationMethods(cardId, userSessionToken)
WS --> SDK: 7. response(authenticationMethods)
SDK --> MPA: 8. result(authenticationMethods)
end
MPA --> User: 9. show authentication methods
User -> MPA: 10. select authentication method
MPA -> SDK: 11. UCP::submitTokenAuthenticationMethod(authenticationMethod)
deactivate MPA
SDK -> WS: 12. submitTokenAuthenticationMethod(authenticationMethod, userSessionToken)
deactivate SDK
WS -> MDES: 13. submitAuthenticationMethod(authenticationMethod)
deactivate WS
MDES -> Issuer: 14. deliverAuthCode(authCode)
deactivate MDES
activate Issuer
Issuer -> User: 15. deliver authCode
deactivate Issuer
alt Provisioning finished - onProvisioningSuccess(paymentInstrumentId) was called
User -> MPA: 16. enter authCode
NOTE LEFT: User should have possibility to enter code\\n only when provisioning finished
activate MPA
MPA -> SDK: 17. UCP::submitTokenAuthenticationValue(authCode)
activate SDK
SDK -> WS: 18. submitTokenAuthenticationValue(authCode, userSessionToken)
activate WS
WS -> WS: 19. checkProvisioningStatus
WS -> MDES: 20. submitAuthenticationValue(authCode)
activate MDES
MDES -> MDES: 21. verify authCode
MDES --> WS: 22. response
WS --> SDK: 23. response
deactivate WS
SDK --> MPA: 24. response
deactivate SDK
deactivate MPA
MDES -> MDES: 25. createTokenMapping
MDES -> WS: 26. notifyTokenUpdated(Active)
deactivate MDES
activate WS
opt
WS ->>Issuer: 27. send Payment Token event
end
WS -> SDK: 28. deliverMessage(paymentTokenActive)
NOTE LEFT: See: Handle Message From Server
deactivate WS
SDK -> SDK: 29. updateTokenStatus
SDK -> MPA: 30. onPaymentInstrumentStatusChanged(id, status)
deactivate MPA
deactivate SDK
end
... Initial Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
@enduml
#### Handle Message From Server
In whole system there are processes where server needs to send messages to the device. Wallet Server has separate component which is responsible for sending messages to the device. This component uses different channels for message delivery. There are two channels: SSE(Server Sent Events) and RNS(Remote Notification Service). When message is ready for delivery, Wallet Server uses both channels to deliver such message. In first versions of Wallet Server only RNS was used, however sometimes messages were not delivered and to improve delivery new SSE channel was introduced. This channel helps in processes which start from the device and device expects message from the server. Moreover device checks messages which are still not delivered on actions where such messages are expected. Below diagram describes how delivery message process works and how needs to be handled on MPA side.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant "MPA" as MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "RNS" as RNS
opt
SDK -> WS: 1. callActionAfterWhichMessageIsExpected
WS --> SDK: 2. response
SDK -> WS: 3. openSSEConnection
end
WS -> WS: messageReadyForDelivery
opt If device has opened connection
WS -> SDK: 4. deliverUsingSSE
end
WS -> RNS: 5. deliverMessage
RNS --> WS: 6. response
RNS -> MPA: 7. deliverMessage
MPA -> MPA: 8. checkWalletSenderId
MPA-> SDK: 9. MDC:CloudMessage#process(pushData)
SDK -> SDK: 10. deduplicateMessage
SDK -> WS: 11. acknowledgeMessage
WS --> SDK: 12. response
SDK -> SDK: 13. processMessage
...Obtain pending messages...
MPA -> SDK: 14. someActionWhereMessageMayBeStillPending
SDK -> SDK: 15. doAction
SDK ->> WS: 16. getPendingMessages
WS --> SDK: 17. response
SDK -> SDK: do actions from 10 to 13
@enduml
#### Update RNS Token
Wallet Server is responsible for sending push notifications to the Wallet SDK. For that reason RNS token is passed to Wallet Server during pairing device or in some cases is obtained by SDK from MPA whenere is needed. However this token can be . MPA will be notified when token is being updated and then needs to obtain new RNS token and update via Wallet SDK on Wallet Server. Retrieving push notifications and RNS tokens is responsibility of the MPA.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Remote Notification Service" as RNS
activate RNS
RNS -> MPA: 1. onTokenRefresh
deactivate RNS
activate MPA
MPA -> MPA: 2. obtainNewToken(walletFirebase)
MPA -> SDK: 3. MDC::updateRegistrationToken(newRNSToken)
activate SDK
SDK -> WS: 4. updateRNSToken(deviceInstallationId, newRNSToken)
activate WS
WS -> WS: 5. updateRNSToken
WS --> SDK: 6. response
deactivate WS
SDK --> MPA: 7. result
deactivate SDK
deactivate MPA
deactivate RNS
@enduml
#### Profile Provisioning
During this process digitized card profile is delivered to the device. This process is triggered automatically after successful digitization where outcome is APPROVED or REQUIRE\_ADDITIONAL\_AUTHENTICATION. It is not possible to retry provisioning itself. To retry provisioning, previous token needs to be deleted and new digitization called hence when SDK reports that provisioning has failed then given token is automatically deleted and User can perform digitization once again. During process there is few point of failures and provisioning can be not finished at all. In this scenario Payment Tokens which are not provisioned for long period of time are delete by Wallet Server (see Removing Not Provisioned Tokens). From User perspective it can be good approach to treat digitization and provisioning as one process and inform User about steps(if User has to wait long time without any information then can treat this as some failure). From MPA perspective can be also good approach to wait for provisioning status as long as User stays on view dedicated to it. If User wants to cancel the process because provisioning status is not available for long period of time it is recommended to delete Payment Token(see Delete Payment Token via SDK) once User click cancel or back. Thanks to deletion, new digitization can be called and User does not have to wait until Payment Token is deleted by Wallet Server due to lack of provisioning.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
MDES->WS: 1. sendRemoteNotificationMessage(mdesRemoteMessage)
activate MDES
deactivate MDES
activate WS
WS-> SDK: 2. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK-> MDES: 3. provision
activate MDES
MDES --> SDK: 4. response(cardProfile)
SDK-> MDES: 5. notify provisioning result
MDES --> SDK: 6. response
deactivate MDES
SDK -> SDK: 7. store card profile
SDK -> WS: 8. confirmProvisioningStatus(SUCCESS/FAILURE)
activate WS
alt FAILURE
WS -> MDES: 9. deleteToken
activate MDES
MDES --> WS: 10. response
deactivate MDES
WS --> SDK: 11. response
SDK -> SDK: 12. deleteToken
SDK -> MPA: 13. onProvisioningFailure
activate MPA
MPA -> User: 14. please try again
deactivate MPA
else SUCCESS
WS --> SDK: 15. response
deactivate WS
SDK -> MPA: 16. onProvisioningSuccess(paymentInstrument)
deactivate SDK
activate MPA
MPA -> User: 17. card digitized successfully
deactivate MPA
end
@enduml
#### Getting Asset
Every field which's name consists of *assetId* is an identifier to some static asset. This asset can be:
- Card art
- Mastercard brand logos
- Issuers's logos
- Terms and Conditions
There are different types of assets and multiple formats may be supported. For example a single image may be supported in various file formats or variant sizes and most appropriate format to use for a particular device.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "MDES" as MDES
MPA -> SDK: 1. UCP::getAsset(assetId)
activate SDK
SDK -> WS: 2. getAsset(assetId)
activate WS
WS -> MDES: 3. getAsset(assetId)
activate MDES
MDES --> WS: 4. response(content)
deactivate MDES
WS --> SDK: 5. response(content)
deactivate WS
SDK --> MPA: 6. result(content)
deactivate SDK
@enduml
#### Transaction Credentials Replenishment
Transaction Credentials are unique per transactions keys that are used to calculate cryptograms in transactions. Each set of credentials is linked with a unique Application Transaction Counter (ATC). Each set of credentials can only be used for one transaction. There is a limit (set on MDES onboarding) of transaction credentials stored on device.
##### Transaction Credentials - Automatic Replenishment
After every transaction Wallet SDK checks if number of transaction credentials is below, . If yes then SDK will call replenish. During replenish process transaction credentials are being delivered to mobile
##### Transaction Credentials - Initial Replenishment
Initial replenishment is process which starts directly after successful token activation. Wallet SDK is notified by Wallet Server using push notification or refreshing payment instruments. A.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
WS -> SDK: 1. notifyTokenUpdated(Active)
activate WS
deactivate WS
activate SDK
alt Request session if required
SDK-> MDES: 2. requestSession
activate MDES
MDES--> SDK: 3. response
MDES-> WS: 4. sendRemoteNotificationMessage(mdesRemoteMessage)
deactivate MDES
activate WS
WS-> SDK: 5. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK-> MDES: 6. replenish
activate MDES
MDES-> MDES: 7. checkIfPaymentTokenIsActive
MDES-->SDK: 8. response(transactionCredentials)
deactivate MDES
SDK -> MPA: 9. onReplenishSuccess(paymentInstrument)
deactivate SDK
@enduml
##### Transaction Credentials - Manual Replenishment
There are scenarios when automatic replenish is not possible and after some number of transactions, transaction credentials number will decrease to 0. In such case MPA should handle NO\_TRANSACTION\_CREDENTIALS error from transaction listener, show user proper alert and call replenish method manually. MPA can also check number of transaction credentials at any other time.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
MPA -> SDK: 1. UCP::replenishCredentials(paymentInstrumentId)
activate MPA
deactivate MPA
activate SDK
alt Request session if required
SDK-> MDES: 2. requestSession
activate MDES
MDES--> SDK: 3. response
MDES-> WS: 4. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS-> SDK: 5. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK-> MDES: 6. replenish
activate MDES
MDES-> MDES: 7. checkIfPaymentTokenIsActive
MDES-->SDK: 8. response(transactionCredentials)
deactivate MDES
SDK -> MPA: 9. onReplenishSuccess(paymentInstrument)
deactivate SDK
@enduml
#### Transacting
Wallet SDK provides functionalities to make contactless payments (using HCE) and e-commerce payments.
##### Contactless Transaction
CDCVM and on how transaction is started, user experience is different and MPA should interact with Wallet SDK in different way. The final decision about transaction processing belongs to MPA. Wallet SDK provides transaction information and based on that and User authentication, MPA can advise to proceed, decline or require authentication(if User should be authenticated but was not). For contactless transaction Wallet SDK provides result of transaction. This result is only from the communication between and Terminal. Transaction Processing with is done separately (see Transaction Processing). Also after every contactless transaction, Transaction Credentials Replenishment is performed automatically by SDK if needed(see Transaction Credentials - Automatic Replenishment).
NOTE: The way of authentication depends on MPA. For transaction User may also choose specific card. If no card is chosen, SDK will use the one which is set as default for contactless payments. Whenever user is authenticated or chose card for payment MPA should pass this information when *onContactlessPaymentStarted* is called.
As was described above, the final decision(PROCEED, DECLINE, AUTHENTICATION\_REQUIRED) for given transaction is taken on MPA side based on transaction information and User authentication. Because of that reason there could be different scenarios which may occur and transaction experience will be single or double tap.
Sample scenarios:
- User can be already authenticated and if MPA will not decline transaction then will be processed as single tap,
- velocity check counters can be applied and even if User was not authenticated MPA can decide to proceed transaction without authentication, taking decision based on transaction information,
- User was not authenticated but MPA recognised transaction as authentication needed. MPA returns AUTHENTICATION\_REQUIRED decision and and SDK informs MPA that authentication is needed.
**Contactless Transaction with MasterCard Token**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "HostApduService" as HAS
participant "Wallet SDK" as SDK
participant Terminal as TER
opt User selects particular card for payment
MPA -> User: 1. showCards
activate MPA
User -> MPA: 2. selectCard
deactivate MPA
end
User -> MPA: 3. pay
User -> TER : 4. contactless 1st tap
activate TER
loop
TER -> HAS: 5. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 6. UCP::Pay#processHceApduCommand(apdu, extras)
activate SDK
group Select PPSE
SDK -> MPA: 7. onContactlessPaymentStarted()
activate MPA
MPA -> MPA: 8. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 9. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 10. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 11. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
deactivate MPA
end
end
group Generate AC command
SDK -> MPA: 12. getFinalDecisionForTransaction(isUserAuthenticated,recommendedAdvice, trxInfo)
activate MPA
MPA -> MPA: 13. checkTrxAndAuthentication
MPA --> SDK: 14. result(advice)
deactivate MPA
end
SDK --> HAS: 15. responseApdu
HAS --> TER: 16. responseApdu
deactivate HAS
end
alt advice=AUTHENTICATION\_REQUIRED
SDK -> MPA: 17. onAuthRequiredForContactless(paymentInstrument, trxInfo)
activate MPA
MPA -> User: 18. show authentication view with trx info
User -> MPA: 19. authenticate
User -> TER: 20. contactless 2nd tap
loop
TER -> HAS: 21. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 22. UCP::Pay#processHceApduCommand(apdu, extras)
group Select PPSE
SDK -> MPA: 23. onContactlessPaymentStarted()
MPA -> MPA: 24. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 25. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 26. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 27. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
end
end
group Generate AC command
SDK -> MPA: 28. getFinalDecisionForTransaction(isUserAuthenticated=true,recommendedAdvice, trxInfo)
MPA -> MPA: 29. checkTrxAndAuthentication
MPA --> SDK: 30. result(PROCEED)
end
SDK --> HAS: 31. responseApdu
HAS --> TER: 32. responseApdu
deactivate HAS
deactivate TER
end
end
SDK -> MPA: 33. onContactlessPaymentCompleted(paymentInstrument, trxInfo, trxResult)
deactivate SDK
MPA -> User: 34. show trx info view
deactivate MPA
...Transaction Processing ...
note over HAS #1C1E3F: See Transaction Processing diagram
...Transaction Credentials Automatic Replenishment ...
note over HAS #1C1E3F: See Transaction Credentials Automatic Replenishment diagram
@enduml
**Contactless Transaction with Visa Token**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "HostApduService" as HAS
participant "Wallet SDK" as SDK
participant Terminal as TER
participant "VTS Backend" as VTS
User -> MPA: tap&pay on Terminal or launch MPA
MPA -> SDK: initialize MDC SDK & UCP SDK
... VTS SDK initialization ...
SDK -> SDK: VTS#initialize
alt Android >= 11
SDK -> SDK: VTS#VerifyApps offline
alt VTS#VerifyApps success
SDK -> SDK: VTS#enableOfflinePayments()
SDK -> MPA: onPaymentAllowed
else VTS#VerifyApps failure
...All Visa card payments will finish with failure ...
end
else Android < 11
SDK -> VTS: VTS#DPELogin online
alt VTS#DPELogin success
VTS -> SDK: response(dpeLoginSession)
SDK -> MPA: onPaymentAllowed
else VTS#DPELogin failure
... all Visa card payments will finish with failure ...
end
end
opt User selects particular card for payment
MPA -> User: 1. showCards
activate MPA
User -> MPA: 2. selectCard
deactivate MPA
end
User -> MPA: 3. pay
User -> TER : 4. contactless 1st tap
activate TER
loop
TER -> HAS: 5. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 6. UCP::Pay#processHceApduCommand(apdu, extras)
SDK -> SDK: Recognize Visa Card and verify if Payment Allowed\\nBreaks
alt Payment using Visa Card and VTS not allow to payment
SDK --> MPA: onContactlessPaymentAborted(PAYMENT\_NOT\_ALLOWED)\\nMPA must wait for onPaymentAllowed callback
destroy MPA
end
activate SDK
group Select PPSE
SDK -> MPA: 7. onContactlessPaymentStarted()
activate MPA
MPA -> MPA: 8. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 9. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 10. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 11. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
deactivate MPA
end
end
group Generate AC command
SDK -> MPA: 12. getFinalDecisionForTransaction(isUserAuthenticated,recommendedAdvice, trxInfo)
activate MPA
MPA -> MPA: 13. checkTrxAndAuthentication
MPA --> SDK: 14. result(advice)
deactivate MPA
end
SDK --> HAS: 15. responseApdu
HAS --> TER: 16. responseApdu
deactivate HAS
end
alt advice=AUTHENTICATION\_REQUIRED
SDK -> MPA: 17. onAuthRequiredForContactless(paymentInstrument, trxInfo)
activate MPA
MPA -> User: 18. show authentication view with trx info
User -> MPA: 19. authenticate
User -> TER: 20. contactless 2nd tap
loop
TER -> HAS: 21. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 22. UCP::Pay#processHceApduCommand(apdu, extras)
group Select PPSE
SDK -> MPA: 23. onContactlessPaymentStarted()
MPA -> MPA: 24. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 25. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 26. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 27. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
end
end
group Generate AC command
SDK -> MPA: 28. getFinalDecisionForTransaction(isUserAuthenticated=true,recommendedAdvice, trxInfo)
MPA -> MPA: 29. checkTrxAndAuthentication
MPA --> SDK: 30. result(PROCEED)
end
SDK --> HAS: 31. responseApdu
HAS --> TER: 32. responseApdu
deactivate HAS
deactivate TER
end
end
SDK -> MPA: 33. onContactlessPaymentCompleted(paymentInstrument, trxInfo, trxResult)
deactivate SDK
MPA -> User: 34. show trx info view
deactivate MPA
...Transaction Processing ...
note over HAS #1C1E3F: See Transaction Processing diagram
...Transaction Credentials Automatic Replenishment ...
note over HAS #1C1E3F: See Transaction Credentials Automatic Replenishment diagram
@enduml
##### E-commerce transaction
E-commerce transaction can be processed using DSRP. Every DSRP transaction has to be authenticated. Depending on implementation e-commerce payment can be preceded with one time password authentication or just device level authentication.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
box "Consumer mobile android device" #white
participant "Merchant App" as MerchantApp
participant MPA
participant "Wallet SDK" as SDK
end box
participant Merchant
participant "Wallet Server" as WS
participant MDES
participant Issuer
participant "Payment Gateway" as PG
User -> MerchantApp: 1. pay
activate MerchantApp
MerchantApp -> Merchant: 2. startTransaction
activate Merchant
Merchant --> MerchantApp: 3. response(transactionId,\\r unpredictableNumber)
deactivate Merchant
MerchantApp -> MPA: 4. getDsrpData(transactionId, trxInfo)
deactivate MerchantApp
activate MPA
alt One Time Password
MPA -> User: 5. select payment instrument
User -> MPA: 6. payment instrument
MPA -> SDK: 7. UCP::requestAuthCodeForPayment(transactionId \\ras authenticationRequestId)
activate SDK
SDK -> WS: 8. requestAuthenticationCodeForPayment(authenticationRequestId)
activate WS
WS -> MDES: 9. requestAuthenticationCodeForPayment(authenticationRequestId)
activate MDES
MDES -> Issuer: 10. sendAuthenticationCode
activate Issuer
Issuer --> MDES: 11. response
MDES --> WS: 12. response
deactivate MDES
WS --> SDK: 13. response
deactivate WS
SDK --> MPA: 14. result
Issuer -> User: 15. sendAuthenticationCode(authenticationCode)
deactivate Issuer
User -> MPA: 16. provide authentication code
MPA -> SDK: 17. UCP::validateAuthenticationCodeForPayment(authenticationCode,\\r transactionId)
SDK -> WS: 18. validateAuthenticationCodeForPayment(authenticationCode,\\r authenticationRequestId)
WS -> MDES: 19. authenticate(authenticationCode,\\r authenticationRequestId)
MDES --> WS: 20. response
deactivate MDES
WS -> WS: 21. createDigitalSignature(authenticationRequestId)
WS --> SDK: 22. response(digitlSignature)
SDK --> MPA: 23. result(digitalSignature)
else Device Level Auth
MPA -> User: 24. show authentication view
User -> MPA: 25. authenticate
end
MPA -> SDK: 26. UCP::setUserAuthenticatedForPayment(id, pin?)
MPA -> SDK: 27. UCP::processDsrpTransaction(id, trxInfo)
SDK --> MPA: 28. result(dsrpData)
MPA --> MerchantApp: 29. result(dsrpData)
activate MerchantApp
MerchantApp -> MerchantApp: 30. encryptPaymentDataForTransit(dsrpData)
MerchantApp -> Merchant: 31. finishTransaction(encryptedPaymentData, \\rdigitalSignature?, transactionId)
activate Merchant
opt
Merchant -> Merchant: 32. validateSignature
note right: this check is needed to proof that given transactionId\\n\\r was preceded with OTP
end
Merchant -> PG: 33. processPayment(pan, exp, cryptogram)
activate PG
PG --> Merchant: 34. response
Merchant --> MerchantApp: 35. response
MerchantApp -> User: 36. show result
deactivate PG
deactivate Merchant
deactivate MerchantApp
@enduml
##### Transaction Processing
Transaction Processing starts after contactless communication between terminal and MPA in case of contactless payment or after payment gateway transaction authorization initiation in case of e-commerce payment. After authorization MDES notifies Wallet Server about the result of the authorization and sends transaction information. Transaction information is sent to MPA.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Terminal/PG" as TER
participant "Payment Network" as PN
participant MDES
participant Issuer
TER -> PN: 1. authorizeTransaction(tokenPAN, cryptogram)
activate PN
activate TER
PN -> MDES: 2. detokenize
activate MDES
MDES -> MDES: 3. lookup token mapping
MDES --> PN: 4. response(PAN)
deactivate MDES
PN -> Issuer: 5. authorize(PAN)
activate Issuer
Issuer --> PN: 6. response
deactivate Issuer
PN --> TER: 7. response
deactivate TER
PN -> MDES: 8. storeTransactionDetails
deactivate PN
activate MDES
MDES -> WS: 9. pushTransactionDetails
deactivate MDES
activate WS
alt store transaction enabled
WS -> WS: 10. storeTransaction
end
opt
WS ->>Issuer: 11. send transaction event
end
WS -> SDK: 12. deliverMessage(trxInfo)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> MPA: 13. onNewTransaction(trxDetails)
deactivate SDK
activate MPA
MPA -> User: 14. showSystemNotification(trxDetails)
deactivate MPA
@enduml
#### Setting Defaults for Payment
SDK manages default Payment Instrument for contactless payments. After digitization, if there is no default Payment Instrument, SDK sets digitized Payment Instrument after activation as default. In case where there are more than one active Payment Instruments and current default Payment Instrument is deleted or suspended, the SDK will set first active Payment Instrument as default. Default Payment Instrument can be changed at any time. Only active Payment Instrument can be set as default.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
MPA->User: 1. payment instrument list
activate MPA
User->MPA: 2. choose default for contactless payment)
MPA->SDK: 3. UCP::setDefaultForContactless(paymentInstrumentId)
activate SDK
SDK-> SDK: 4. storeDefault
SDK-->MPA: 5. result
deactivate MPA
deactivate SDK
@enduml
#### Login On Wallet Server
User data are protected by User session token which is issued by Wallet Server after providing authentication factor. Authentication factor is provided first in pairing device and then session is created. Since session has limited period of validity, it needs to be refreshed using login on Wallet Server methods.
Login on Wallet Server using Trusted Identity
. During login process Wallet Server checks if given device still exists, if not then responds with CANT\_FIND\_DEVICE status which is interpreted on SDK side as given device is deleted and all local data stored on SDK side are cleared.
Since MDC 2.14.5 for devices which are already paired, Wallet SDK will try to asynchronously register device in new delivery message service. To make it possible *CloudMessagingRegistrationProvider* needs to be implemented and provided within setup.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as Issuer
MPA -> SDK: 1. invoke API
activate MPA
activate SDK
SDK -> WS: 2. invoke API
activate WS
WS --> SDK: 3. response(USER\_UNATHORIZED)
deactivate WS
SDK --> MPA: 4. result(USER\_UNATHORIZED)
MPA->User: 5. show authenticate view
User->MPA: 6. put authentication data
MPA->Issuer: 7. authenticate
activate Issuer
Issuer -> Issuer: 8. generateTrustedIdentity - signed user id
Issuer --> MPA: 9. response(trustedIdentity)
deactivate Issuer
MPA-> SDK: 10. MDC::loginByTrustedIdentity(trustedIdentity)
SDK-> WS: 11. loginByTrustedIdentity(trustedIdentity)
alt Device not registered in new delivery message service
SDK -> MPA: 12. CloudMessagingRegistrationProvider::getRegistrationToken
SDK ->> WS: 13. registerDeviceForNewMessageDelivery(cloudMessageToken)
WS --> SDK: 14. response
end
activate WS
WS -> WS: 15. check if device exists
alt device exists
WS-> WS: 16. verify trusted identity
WS --> SDK: 17. response(userSessionToken)
SDK -> SDK: 18. store(userSessionToken)
SDK-->MPA: 19. result
MPA -> SDK: 20. invoke API
else device not exists
WS --> SDK: 21. response(CANT\_FIND\_DEVICE)
deactivate WS
SDK -> SDK: 22. clearAllLocalData
SDK --> MPA: 23. result(CANT\_FIND\_DEVICE)
deactivate MPA
deactivate SDK
... Pair device ...
note over MPA, WS #1C1E3F: See Pairing Device diagram
MPA -> SDK: 24. invoke API
end
@enduml
#### Getting Cards
When cards are already placed on Wallet Server, then they can be displayed to User in the application. Cards have identifiers which can be used e.g. for digitization.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
MPA->SDK: 1. MDC::getAllCards
activate MPA
activate SDK
SDK -> WS: 2. getAllCards(userSessionToken)
WS --> SDK: 3. response(userCards)
deactivate WS
SDK --> MPA: 4. result(cardList)
deactivate SDK
deactivate MPA
@enduml
#### Getting Payment Intruments
After digitization process, payment instrument is stored in VCP SDK module of Wallet SDK. Payment instrument in context of VCP SDK is digitized card and contains i:
- id (specified id which helps MPA to identify payment instrument which was digitized from MPA),
- status,
- transaction credentials count,
- paymentTokenId etc. .
MPA can get information about all Payment Instruments from the Wallet SDK at any time. Payment instruments will be retrieved only from local storage that is part of SDK. Payment Tokens for Payment Instruments can be refreshed/pulled from Wallet Server on demand. This scenario should be considered only when User e.g. makes swipe to refresh.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as IS
MPA->SDK: 1. UCP::getAllPaymentInstruments(refresh)
activate MPA
alt refresh = true
activate SDK
SDK -> WS: 2. getAllPaymentTokens(userSessionToken)
activate WS
WS -> SDK: 3. response(devicePaymentTokens)
deactivate WS
SDK -> SDK: 4. updateLocalStorage
end
SDK --> MPA: 5. result(paymentInstrumentList)
deactivate SDK
deactivate MPA
@enduml
#### Getting Transaction History
. Transactions are returned in corresponding parts for better user experience. If next part is available then response from previous part contain information needed for requesting next part. MPA should check if next part is not empty and then make another request.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
loop next != null
MPA->SDK: 1. MDC::getTransactionsHistory(filters, next?)
activate MPA
activate SDK
SDK -> WS: 2. getTransactionHistory(filters, next?, userSessionToken, ...)
activate WS
WS -> SDK: 3. response(transactionHistoryList, next?)
deactivate WS
SDK --> MPA: 4. result(transactionHistoryList, next?)
deactivate SDK
deactivate MPA
end
@enduml
#### Payment Token Lifecycle Management via SDK
Payment Token lifecycle management can be done via SDK.
##### Delete Payment Token via SDK
Payment Token can be deleted using SDK.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant Issuer
User -> MPA: 1. Delete payment token
activate MPA
MPA -> SDK: 2. UCP::delete(paymentInstrumentId, reason)
deactivate MPA
activate SDK
SDK -> WS: 3. deletePaymentToken(userSessionToken, paymentTokenId, reason)
activate WS
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
deactivate MDES
WS --> SDK: 7. response
opt
WS ->> Issuer: 8. send Payment Token event
end
deactivate WS
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
MPA --> User: 17. show update view
deactivate MPA
@enduml
#### Errors Reporting
#### Device Unpairing
Unpairing device clears all modules data and report that fact only if possible to server. If server receives this signal then removes all device data including provisioned Payment Tokens. If not then data are cleared locally only - similar like during app uninstallation. This can be used for scenario when MPA does not want to use SDK at all or for scenario when MPA supports switching between users accounts on the same installation. If MPA detects that new User is trying to log into application in case when previous had digitized cards, immediately should clear all data from previous, since SDK stores data in context of one User only.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
MPA -> SDK: 1. MDC::unpairDevice
activate MPA
activate SDK
opt
SDK -> WS: 2. unpairDevice
activate WS
WS --> SDK: 3. response
deactivate WS
end
SDK -> SDK: 4. clearAllData
SDK --> MPA: 5. result
deactivate SDK
deactivate MPA
@enduml
#### MDES Initiated
This section describes use cases which are initiated from MDES.
##### Re-digitization
Re-digitization process can be triggered by MDES for several use cases:
**Token Expiry**
One month before token expiry MDES will request for redigitization.
**Attribute Change**
Issuer may perform an attribute change at the BIN account-range level impacting theri MDES enabled ranges. Some device tokens may need to have their data refreshed to match the new attributes.
**BIN Account-Range Split**
Issuer may perform a BIN account-range split. Some existing tokens may need to be updated to ensure that they are linked to the correct funding BIN account ranges internally.
**PAN Update in Different Account Range**
Issuer may update existing PAN with new Pan in a different BIN account range.
For above cases:
- token unique reference remains the same
- token expiration date is extended by three years from the date of redigitization
After successful redigitization process transaction credentials replenishment is called in case where Payment Token is active.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
MDES -> WS: 1. notifyTokenUpdated(redigitize=true)
activate MDES
activate WS
WS -> MDES: 2. redigitize
MDES --> WS: 3. response
WS --> MDES: 4. response
deactivate MDES
deactivate WS
MDES->WS: 5. sendRemoteNotificationMessage(mdesRemoteMessage)
activate MDES
deactivate MDES
activate WS
WS-> SDK: 6. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK-> MDES: 7. provision(redigitize=true)
activate MDES
MDES --> SDK: 8. response(cardProfile)
SDK-> MDES: 9. notify provisioning result(redigitize=true)
MDES --> SDK: 10. response
SDK -> WS: 11. confirmReProvisioningStatus(SUCCESS/FAILURE)
alt FAILURE
WS -> WS: 12. markRedigitizationAsFailed
note left: redigitization process will be retried after some period of time
SDK -> MPA: 13. onReProvisioningFailure(paymentInstrument)
else SUCCESS
SDK -> SDK: 14. clearTransactionCredentials
SDK -> MPA: 15. onReProvisioningSuccess(paymentInstrument)
deactivate SDK
MDES -> WS: 16. notifyTokenUpdated(redigitized=false)
deactivate MDES
activate WS
opt
WS ->> Issuer: 17. send Payment Token event
end
WS -> SDK: 18. deliverMessage(PAYMENT\_TOKEN\_INFO\_CHANGE(redigitized=true))
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: 19. replenish
... Automatic Replenishment ...
note over SDK, MDES #1C1E3F: Just after reprovisioning transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
end
@enduml
#### Wallet Server Initiated
Since important processes are asynchronous in MDES and there are many point of failures, wallet server provides additional functionalities to resolve some failure scenarios by running some operations on own side.
##### Removing Not Provisioned Tokens
Wallet Server checks periodically DEVICE Payment Tokens and verify if provisioning is completed. These Payment Tokens which have provisioning status in progress for long period of time are deleted automatically and from User perspective process needs to be started again. By default this period is set to 1 hour but can be modified.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
WS -> WS: 1. find not provisioned payment tokens for a\\r long period of time
activate WS
loop Not provisioned payment tokens for a long period of time
WS -> MDES: 2. Delete token
activate MDES
MDES -> MDES: 3. Delete token mapping
MDES --> WS: 4. response
deactivate MDES
opt
WS ->> Issuer: 5. send Payment Token event
end
WS -> SDK: 6. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
alt Request session if required
SDK -> MDES: 7. request session
activate MDES
MDES --> SDK: 8. response
MDES -> WS: 9. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 10. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 11. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 12. response
deactivate MDES
SDK -> SDK: 13. Delete transaction credentials, card profile
SDK -> MPA: 14. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
#### Wallet Server Admin API Initiated
This section describes use cases which are initiated from Wallet Server Admin Panel.
##### Admin Card Deletion
During this process all data related to given card are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
participant Issuer
AP -> WS: 1. deleteCard(cardId)
activate WS
activate AP
WS -> WS: 2. deleteCard
WS --> AP: 3. response
deactivate AP
loop All Payment Tokens for card
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
deactivate MDES
opt
WS ->>Issuer: 7. send Payment Token event
end
WS -> SDK: 8. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
##### Admin Device Deletion
During this process all data related to given device are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deleteDevice(deviceInstallationId)
activate AP
activate WS
WS --> AP: 2. response
deactivate AP
loop All Payment Tokens for given device
WS -> MDES: 3. delete token
activate MDES
MDES --> WS: 4. response
deactivate WS
deactivate MDES
end
@enduml
##### Admin Token Deletion
Payment Token can be deleted via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deletePaymentToken(paymentTokenId)
activate AP
activate WS
WS -> MDES: 2. Delete token
activate MDES
MDES -> MDES: 3. Delete token mapping
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->> Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenDeleted)
deactivate WS
activate SDK
NOTE LEFT: See: Handle Message From Server
deactivate MDES
alt Request session if required
SDK -> MDES: 8. request session
activate MDES
MDES --> SDK: 9. response
MDES -> WS: 10. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 11. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 12. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 13. response
deactivate MDES
SDK -> SDK: 14. Delete transaction credentials, card profile
SDK -> MPA: 15. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
MPA --> User: 16. show update view
deactivate MPA
@enduml
##### Admin Token Suspension
Payment Token can be suspended via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
participant Issuer
AP -> WS: 1. suspendToken(paymentTokenId)
activate WS
activate AP
WS -> MDES: 2. suspend token
activate MDES
MDES -> MDES: 3. Suspend token
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->> Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenSuspend)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: 8. suspend
SDK -> MPA: 9. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
deactivate MPA
@enduml
##### Admin Token Unsuspension
Payment Token can be unsuspended via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. unsuspendToken(paymentTokenId)
activate WS
activate AP
WS -> MDES: 2. unsuspend token
activate MDES
MDES -> MDES: 3. Unsuspend token
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->>Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenUnsuspend)
deactivate WS
activate SDK
SDK -> SDK: 8. activate
SDK -> MPA: 9. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
deactivate MPA
... Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials replenishment is performed by SDK\\r. See Transaction Credentials Automatic Replenishment diagram
@enduml
##### Admin User Deletion
During this process all data related to given User are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deleteUser(userId)
activate AP
activate WS
WS -> WS: 2. delete cards, devices
WS --> AP: 3. response
deactivate AP
loop All Payment Tokens for given User
WS -> MDES: 4. delete token
activate MDES
MDES --> WS: 5. response
deactivate WS
deactivate MDES
end
@enduml
#### Summary of Changes
This section describes changes introduced in next version based on time
##### Version 2.0
- Base version of the document describing VCP Solution for cards
##### Version 2.1
- Introduced *onContactlessPaymentStarted* in Contactless Transaction use case
- Added new use case: Handle Message From Server
- Introduced provider for *cloudMessageRegistrationToken* in Login On Wallet Server use case
- Updated all use cases with new way of message delivery from server
- Added sending Payment Token event when token is created or updated
# Use Cases (MDES&VTS)
###
This section describes use cases which can be initiated using Wallet Server LC API. Customers to manage Users and cards data on Wallet Server.
#### User with Card Registration
User with Card Registration is process when user and cards are transferred to Wallet Server to make possible use them in different processes (e.g. digitization) later in the application. Registration needs to be done as the first step
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant Issuer
Issuer -> WS: 1. addUserWithCard(userData, cardData)
activate Issuer
activate WS
WS --> Issuer: 2. response(cardId)
deactivate WS
Issuer -> Issuer: 3. storeCardId
deactivate Issuer
@enduml
#### Card Reissuing
Since plastic cards have expiration date, Issuers may want to reissue them. In most cases PAN remains the same and only expiration date is extended.
**TSP MDES**
It is worth to mention that MDES does not check PAN expiry date for transactions performed with Payment Token. MDES offers API for Issuers where is possibility to update expiration date or even whole PAN for already provisioned Payment Tokens. In context of integration there are a few options:
- Issuer has own processor which is integrated with Customer Service MDES API and there is a possibility to update PAN or expiration date. Then reissuing is done only on processor side. Wallet Server will be notified by MDES about the change.
- Issuer uses Verestro Token Management Platform and reissuing is possible using LC API.
- Issuer uses only Wallet Server which acts as Token Requestor and there is no possibility to update PAN or expiration date for given Payment Token. Issuer needs to delete previous card and add new one. Users need to make digitization again.
All options needs to be considered individually and discussed with Verestro representative.
**TSP VTS**
//todo
#### User Deletion
During this process all data related to given User are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant Issuer
participant "TSP" as TSP
Issuer -> WS: 1. deleteUser(userId)
activate Issuer
activate WS
WS -> WS: 2. delete cards, devices
WS --> Issuer: 3. response
deactivate Issuer
loop All Payment Tokens for given User
WS -> TSP: 4. delete token
activate TSP
TSP --> WS: 5. response
opt
WS ->> Issuer: 6. send Payment Token event
end
deactivate WS
deactivate TSP
end
@enduml
#### Card Deletion
During card deletion process all data related to given card are deleted. Payment Tokens are deleted asynchronously.
**TSP MDES**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
Issuer -> WS: 1. deleteCard(cardId)
activate WS
activate Issuer
WS -> WS: 2. deleteCard
WS --> Issuer: 3. response
deactivate Issuer
loop All Payment Tokens for card
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
opt
WS ->> Issuer: 7. send Payment Token event
end
deactivate MDES
WS -> SDK: 8. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
deactivate MPA
activate SDK
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
deactivate MPA
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
**TSP VTS**
@startuml
autonumber
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "VTS" as TSP
participant Issuer
Issuer -> WS: deleteCard(cardId)
activate WS
activate Issuer
WS -> WS: deleteCard
WS --> Issuer: response
deactivate Issuer
loop All Payment Tokens for card
WS -> TSP: delete token
activate TSP
TSP -> TSP: delete token mapping
TSP --> WS: response
deactivate TSP
opt
WS ->> Issuer: send Payment Token event
end
WS -> SDK: deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: delete transaction credentials, card profile
SDK -> MPA: onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
@enduml
### Wallet SDK Initiated
#### Wallet SDK Setup
Setup of Wallet SDK (both modules VCP SDK and MDC SDK) is main step which needs to be made at very beginning. During setup main configuration should be provided. Moreover there is some configuration which is related with HCE payments: MPA should be registered as default application for payment (Tap & Pay) and also should implement HostApduService to emulate an NFC card inside an Android service component. Please find more details in *Wallet SDK API* document.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant MPA
participant "Wallet SDK" as SDK
MPA -> SDK: 1. MDC:setup(configuration)
activate MPA
activate SDK
SDK --> MPA: 2. result
MPA -> SDK: 3. UCP:setup(configuration)
SDK --> MPA: 4. result
deactivate MPA
deactivate SDK
@enduml
#### Pair Device on Wallet Server
This section describes pairing device process. Device pairing is process which authenticates device in context of given user. During this process device data and keys used in communication are exchanged with Wallet Server. To make possible device pairing, user needs to be already registered on the Wallet Server. Every device is identified by unique identifier. After every pairing device request, Wallet Server gives unique installation identifier. It means that particular installation of the application installed on particular device belongs to given User. Different Users can use same device for separate installations. If any active installation on given device already exists during pairing device, Wallet Server will delete and create new installation in context of new user. Only one active installation is possible on particular device. Device pairing is the first process which should be done after user registration. Pairing device should be done only once for individual installation.
##### Pair Device By Trusted Identity
In the integrated model, [Trusted Identity](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/trusted-identity) is used to proof User authenticity. User is firstly authenticated on the Customer side. Trusted Identity should be generated on Issuer backend side and pass via Wallet SDK, since mobile environment is treated as unsecure. Algorithm of generating Trusted Identity is placed in Wallet SDK API specification.
Access to User data stored on Wallet Server is possible only when session is established. After paring device session is automatically generated for particular User.
If previously on given device was installation which had Payment Tokens, during pairing these Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as Issuer
participant "MDES" as MDES
MPA->Issuer: 1. authenticate
activate MPA
activate Issuer
Issuer->Issuer: 2. generateTrustedIdentity - signed user id
Issuer--> MPA: 3. response(trustedIdentity)
deactivate Issuer
MPA -> MPA: 4. obtainRNSToken(walletFirebase)
MPA-> SDK: 5. MDC:pairDeviceByTrustedIdentity\\r(trustedIdentity, rnsRegistrationToken)
activate SDK
SDK -> SDK: 6. isDevicePaired
alt isDevicePaired=true
SDK --> MPA: 7. result
else isDevicePaired=false
SDK-> WS: 8. pairDeviceByTrustedIdentity\\r(trustedIdentity, rnsRegistrationToken, deviceInfo)
activate WS
WS-> WS: 9. verify trusted identity
alt isActiveInstallationOnGivenDevice
WS -> WS: 10. deleteActiveInstallation
WS -> MDES: 11. deleteDeviceTokens
activate MDES
deactivate MDES
note left: asynchronous
end
WS -> WS: 12. createNewDeviceInstallationRecordForUser
WS --> SDK: 13. response\\r (userSessionToken, installationId)
deactivate WS
SDK -> SDK: 14. store userSessionToken
SDK-->MPA: 15. result
deactivate MPA
deactivate SDK
end
@enduml
#### Card Digitization
Card digitization is process which allows to transform plastic card into . To perform digitization, card data should be placed already on Wallet Server and device should be already paired. Card digitization process uses Wallet Server identifier of the card. There are two ways of performing card digitization. Usage of the API's depends on needs in given implementation.
##### Card Digitization Ways
Depending on implementation card can be digitized in different way using different approach. There are following ways of card digitization:
- one step - which is the simplest way of card digitization and should be used in project implementation where card can be just digitized without any additional staff like additional User authentication or showing T&C or showing card art from TSP,
- multi step - which should be used when digitization will require additional User authentication, showing T&C or showing card art from TSP.
##### Card Digitization Ways - One Step
One step digitization is dedicated for implementations where there is no additional User authentication and . Mostly it should be used in Issuer applications where NFC payments is added as a new functionality without additional staff which is used in dedicated wallets. Only transaction outcomes APPROVED(see APPROVED) or DECLINE(see DECLINE) are expected in this type of digitization.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant "MPA" as MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
MPA -> SDK: 1. UCP:Cards#digitize\\r(paymentInstrumentId=verestroCardId, userLanguageCode, securityCode?)
activate MPA
activate SDK
SDK -> SDK: 2. isDeviceRegisteredForPayment
alt isDeviceRegisteredForPayment=false
SDK -> WS: 3. getPkCertificate
activate WS
WS -> MDES: 4. getPkCertificate
activate MDES
MDES --> WS: 5. response(pkCertificate)
WS --> SDK: 6. response(pkCertificate)
SDK -> SDK: 7. prepareDataForRegistration(pkCertificate)
SDK -> WS: 8. registerDeviceForPayment\\r (paymentDeviceInfo, userSessionToken)
WS -> MDES: 9. registerMobilePaymentApplication\\r (paymentDeviceInfo)
MDES --> WS: 10. response(mobileKeys,\\r remoteManagementUrl)
WS --> SDK: 11. response(mobileKeys,\\r remoteManagementUrl)
end
SDK -> SDK: 12. isPaymentInstrumentDigitized
alt isPaymentInstrumentDigitized=true
SDK --> MPA: 13. result
else isPaymentInstrumentDigitized=false
SDK -> WS: 14. digitizeCard\\r (cardId, userSessionToken)
WS -> MDES: 15. checkEligibility(cardData, paymentAppId,\\r paymentAppInstanceId)
MDES --> WS: 16. response (eligibilityReceipt)
WS -> MDES: 17. digitize(eligibilityReceipt)
MDES --> WS: 18. response
deactivate MDES
WS --> SDK: 19. response(paymentTokenInfo)
deactivate WS
SDK --> MPA: 20. result
deactivate SDK
deactivate MPA
end
deactivate SDK
deactivate MPA
note over SDK, WS #1C1E3F: See Card digitization outcome Approved or Decline diagram
@enduml
##### Card Digitization Ways - Multi step
Multi step digitization should be used in implementations where terms and are displayed before every digitization, additional user authentication is needed or card art need to be used from TSP. Multi step digitization consists of following steps:
- checking card eligibility
- showing T&C
- digitizing card
Digitization may finished with different outcomes(see Card Digitization Outcomes).
**TSP MDES**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant Issuer
MPA -> SDK: 1. UCP:Cards#checkEligibility(paymentInstrumentId=verestroCardId, locale)
activate MPA
activate SDK
SDK -> SDK: 2. isDeviceRegisteredForPayment
alt isDeviceRegisteredForPayment=false
SDK -> WS: 3. getPkCertificate
activate WS
WS -> MDES: 4. getPkCertificate
activate MDES
MDES --> WS: 5. response(pkCertificate)
WS --> SDK: 6. response(pkCertificate)
SDK -> SDK: 7. prepareDataForRegistration(pkCertificate)
SDK -> WS: 8. registerDeviceForPayment (paymentDeviceInfo, userSessionToken)
WS -> MDES: 9. registerMobilePaymentApplication (paymentDeviceInfo)
MDES --> WS: 10. response(mobileKeys, remoteManagementUrl)
WS --> SDK: 11. response(mobileKeys, remoteManagementUrl)
end
SDK -> WS: 12. checkEligibility(paymentInstrumentId,userSessionToken)
WS -> MDES: 13. checkEligibility(card)
MDES -->WS: 14. response(termsAndConditionsAssetId, eligibilityReceipt)
WS --> SDK: 15. response(termsAndConditionsAssetId, digitizationRef)
SDK --> MPA: 16. result(termsAndConditionsAssetId)
MPA -> SDK: 17. UCP:getAsset(termsAndConditionsAssetId)
SDK -> WS: 18. getAsset(termsAndConditionsAssetId)
WS -> MDES: 19. getAsset(termsAndConditionsAssetId)
MDES --> WS: 20. response(content)
deactivate MDES
WS --> SDK: 21. response(content)
deactivate WS
SDK --> MPA: 22. result
deactivate SDK
MPA -> User: 23. show T&C
deactivate MPA
User -> MPA: 24. accept
activate MPA
MPA -> SDK: 25. UCP:Cards#digitize(paymentInstrumentId, cvc?)
activate SDK
SDK -> WS: 26. digitize(digitizationRef, cvc?, userSessionToken)
activate WS
WS ->MDES: 27. digitize(eligibilityReceipt, cvc?)
activate MDES
MDES --> WS: 28. response(additionalAuthenticationRequired, authenticationMethods?, tokenInfo, productConfig)
deactivate MDES
WS --> SDK: 29. response(additionalAuthenticationRequired, authenticationMethods?, tokenInfo, productConfig)
deactivate WS
SDK --> MPA: 30. result
deactivate SDK
MPA -> User: 31. please wait
deactivate MPA
note over SDK, WS #1C1E3F: See Card digitization outcome Approved or Decline or Require Additional Authentication diagram
@enduml
**TSP VTS**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant VTS
participant Issuer
MPA -> SDK: UCP:Cards#checkEligibility(paymentInstrumentId=verestroCardId, \\nuserLanguageCode, userCountryCode, securityCode?)
activate MPA
activate SDK
SDK -> SDK: isDeviceEnrolledInVts()
alt isDeviceEnrolled=false
SDK -> WS: getDeviceData(uniqueDeviceId)
activate WS
WS --> SDK: response(deviceData)
deactivate WS
SDK -> SDK: create vtsEnrollDeviceRequest & vtsEnrollDpeDeviceRequest
SDK -> WS: enroll(uniqueDeviceId, vtsEnrollDeviceRequest, dpeEnrollDeviceRequest, userSessionToken)
activate WS
WS -> VTS: enrollDevice(vtsEnrollDeviceRequest)
activate VTS
VTS --> WS: response(vtsEnrollDeviceResponse)
WS -> VTS: enrollDevice(vtsDpeEnrollDeviceRequest)
VTS --> WS: response(vtsDpeEnrollDeviceResponse)
WS --> SDK: response(vtsEnrollDeviceDpeResponse)
deactivate WS
deactivate VTS
SDK -> SDK: processEnrollDasResponse(vtsEnrollDeviceDpeResponse)
SDK -> VTS: Async::initialize with DPE Service
activate VTS
VTS --> SDK: Async::DPE login complete
deactivate VTS
end
SDK -> WS: getPkCertificate
activate WS
WS --> SDK: response(pkCertificate)
SDK -> WS: enrollPan(paymentInstrumentId=verestroCardId, \\nuserLanguageCode, userCountryCode, securityCode?, userSessionToken)
WS -> VTS: panEnrollments(card, cvv2)
activate VTS
VTS --> WS: response(vPanEnrollmentId, termsAndConditionsAssetId)
deactivate VTS
WS --> SDK: response(termsAndConditionsAssetId, digitizationRef)
deactivate WS
SDK --> MPA: result(termsAndConditionsAssetId)
alt termsAndConditionsAssetId != null
MPA -> SDK: UCP:getAsset(termsAndConditionsAssetId)
SDK -> WS: getAsset(termsAndConditionsAssetId)
activate WS
WS -> VTS: getContent(termsAndConditionsAssetId)
activate VTS
VTS --> WS: response(content)
deactivate VTS
WS --> SDK: response(content)
deactivate WS
SDK --> MPA: result
deactivate SDK
MPA -> User: show T&C
User -> MPA: accept
deactivate MPA
end
MPA -> SDK: UCP:Cards#digitize(paymentInstrumentId, securityCode?)
activate MPA
activate SDK
SDK -> WS: provision(digitizationRef, securityCode?, userSessionToken)
WS -> VTS: panEnrollments(vPanEnrollmentId, cvv2?)
activate VTS
VTS --> WS: response(vtsProvisioningResponse, vProvisionedTokenId,\\nstepUpRequest presets?, tokenInfo, productConfig)
deactivate VTS
WS --> SDK: response(vtsProvisioningResponse, \\nadditionalAuthenticationRequired, \\nauthenticationMethods?,\\ntokenInfo, productConfig)
SDK --> MPA: result
deactivate WS
deactivate SDK
deactivate MPA
note over MPA, WS #1C1E3F: See Card digitization outcome Approved or Decline or Require Additional Authentication diagram
@enduml
##### Card Digitazation Outcomes
There are following digitization outcomes which should be handled differently:
- APPROVED
- DECLINED
- REQUIRE\_ADDITIONAL\_AUTHENTICATION
##### APPROVED
This digitization outcome always refers to green path digitization decision. When digitization is APPROVED then profile provisioning(See Profile Provisioning) starts automatically.
**TSP MDES**
According to MDES architecture just after digitization Payment Token is in INACTIVE state even though does not require additional User authentication. Due that fact new flag (additionalAuthenticationRequired) was introduced which informs which Payment Token exactly needs to be additionally authenticated. After successful provisioning token is activated and then SDK will perform Transaction Credentials - Initial Replenishment.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
group APPROVED
MDES --> WS : 1. responseFromDigitization(APPROVED, cardDigitizationData)
activate MDES
activate WS
opt
WS ->>Issuer: 2. send Payment Token Event
end
WS --> SDK : 3. response(digitizatonData, paymentToken)
deactivate WS
activate SDK
SDK --> MPA : 4. result
activate MPA
MPA --> User : 5. result
deactivate MPA
... Profile Provisioning ...
note over MPA, MDES #1C1E3F: See Profile Provisioning diagram
... MDES Token Activation ...
SDK -> MDES: 6. notifyProvisioningResult
MDES -> MDES: 7. createTokenMapping
MDES -> WS: 8. notifyTokenUpdated(Active)
deactivate MDES
activate WS
opt
WS ->>Issuer: 9. send Payment Token Event
end
WS -> SDK: 10. deliverMessage(paymentTokenActive)
NOTE LEFT: See: Handle Message From Server
deactivate WS
SDK -> SDK: 11. updateTokenStatus
SDK -> MPA: 12. onPaymentInstrumentStatusChanged(id, status)
deactivate MPA
deactivate SDK
... Initial Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
end
@enduml
**TSP VTS** VTS Payment token just after digitization is in ACTIVE state and contains transaction credentials making Token ready to use.
@startuml
autonumber
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "VTS" as VTS
participant Issuer
group APPROVED
VTS --> WS: response from Provision(tokenStatus=ACTIVE)
activate WS
opt
WS ->> Issuer: send Payment Token event
end
WS --> SDK: response from Provision(\\ntokenStatus=ACTIVE\\nadditionalAuthenticationRequired=false)
deactivate WS
... Profile Provisioning ...
note over MPA, VTS #1C1E3F: See Profile Provisioning diagram
... Card Digitization Activation ...
SDK -> MPA: onPaymentInstrumentStatusChanged(id, status)
deactivate MPA
end
@enduml
##### DECLINE
This digitization outcome refers to red digitization decision.
**TSP MDES**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
group APPROVED
MDES --> WS : 1. responseFromDigitization(DECLINED)
activate MDES
deactivate MDES
activate WS
WS --> SDK : 2. response(error)
deactivate WS
activate SDK
SDK --> MPA : 3. result
deactivate SDK
activate MPA
MPA --> User : 4 result
deactivate MPA
@enduml
**TSP VTS**
@startuml
autonumber
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "VTS" as VTS
participant Issuer
VTS --> WS: response from Provision(DECLINE)
activate WS
opt
WS ->> Issuer: send Payment Token event
end
WS --> SDK: response(error)
deactivate WS
activate SDK
SDK -> MPA: error
deactivate SDK
activate MPA
MPA -> User: error
deactivate MPA
deactivate User
@enduml
##### REQUIRE\_ADDITIONAL\_AUTHENTICATION
This digitization outcome always refers to yellow path digitization decision. When digitization is REQUIRE\_ADDITIONAL\_AUTHENTICATION then profile provisioning(See Profile Provisioning) starts automatically but remain INACTIVE until the User is authenticated(see Card Digitization Activation). Flag *additionalAuthenticationRequired* informs if additional user authentication is needed or not.
**TSP MDES**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
group REQUIRE\_ADDITIONAL\_AUTHENTICATION
MDES --> WS : 1. responseFromDigitization(response(additionalAuthenticationRequired=true, authenticationMethods?, tokenInfo, productConfig))
activate MDES
deactivate MDES
activate WS
opt
WS ->> Issuer: 2. send Payment Token event
end
WS --> SDK : 3. response(response(additionalAuthenticationRequired=true, authenticationMethods?, tokenInfo, productConfig))
deactivate WS
activate SDK
SDK --> MPA : 4. result
deactivate SDK
activate MPA
MPA --> User : 5. result
deactivate MPA
... Profile Provisioning ...
note over MPA, MDES #1C1E3F: See Profile Provisioning diagram
... Card Digitization Activation ...
note over MPA, MDES #1C1E3F: See Card Digitization Activation diagram
end
@enduml
**TSP VTS**
@startuml
autonumber
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "VTS Backend" as VTS
participant Issuer
group REQUIRE\_ADDITIONAL\_AUTHENTICATION
VTS --> WS: response from Provision(tokenStatus=INACTIVE, stepUpRequest presents)
activate WS
opt
WS ->> Issuer: send Payment Token event
end
WS --> SDK: response from Provision(tokenStatus=INACTIVE,\\nadditionalAuthenticationRequired=true,\\nauthenticationMethods)
deactivate WS
deactivate MPA
... Profile Provisioning ...
note over MPA, VTS #1C1E3F: See Profile Provisioning diagram
... Card Digitization Activation ...
note over MPA, VTS #1C1E3F: See Card Digitization Activation diagram
end
@enduml
##### Card Digitization Activation
This process is applicable only if digitization has infomation that additional authentication is required. During this process User can choose one of the additional authentication methods. If user-entered authentication code is chosen then TSP will send authentication code which later should be provided by User for submission. Once user enters correct authentication code, Payment Token is activated by TSP asynchronously. After activation Wallet Server is notified that Payment Token is activated and this information is passed to Wallet SDK. After Payment Token activation, Wallet SDK start Transaction Credentials - Initial Replenishment.
**TSP MDES**
NOTE: Submit authentication value is allowed only if provisioning is finished.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
alt Just after digitization
MDES --> WS : 1. responseFromDigitization(additionalAuthenticationRequired=true, \\rauthenticationMethods?, tokenInfo,productConfig)
activate MDES
activate WS
WS --> SDK : 2. response(additionalAuthenticationRequired=true, \\rauthenticationMethods?, tokenInfo, productConfig)
activate SDK
SDK --> MPA: 3. result(authenticationMethods)
activate MPA
else Activation not finished after digitization
User -> MPA: 4. activate token
MPA -> SDK: 5. UCP::getAdditionalAuthenticationMethods(paymentInstrumentId)
SDK -> WS: 6. getAuthenticationMethods(cardId, userSessionToken)
WS --> SDK: 7. response(authenticationMethods)
SDK --> MPA: 8. result(authenticationMethods)
end
MPA --> User: 9. show authentication methods
User -> MPA: 10. select authentication method
MPA -> SDK: 11. UCP::submitTokenAuthenticationMethod(authenticationMethod)
deactivate MPA
SDK -> WS: 12. submitTokenAuthenticationMethod(authenticationMethod, userSessionToken)
deactivate SDK
WS -> MDES: 13. submitAuthenticationMethod(authenticationMethod)
deactivate WS
MDES -> Issuer: 14. deliverAuthCode(authCode)
deactivate MDES
activate Issuer
Issuer -> User: 15. deliver authCode
deactivate Issuer
alt Provisioning finished - onProvisioningSuccess(paymentInstrumentId) was called
User -> MPA: 16. enter authCode
NOTE LEFT: User should have possibility to enter code\\n only when provisioning finished
activate MPA
MPA -> SDK: 17. UCP::submitTokenAuthenticationValue(authCode)
activate SDK
SDK -> WS: 18. submitTokenAuthenticationValue(authCode, userSessionToken)
activate WS
WS -> WS: 19. checkProvisioningStatus
WS -> MDES: 20. submitAuthenticationValue(authCode)
activate MDES
MDES -> MDES: 21. verify authCode
MDES --> WS: 22. response
WS --> SDK: 23. response
deactivate WS
SDK --> MPA: 24. response
deactivate SDK
deactivate MPA
MDES -> MDES: 25. createTokenMapping
MDES -> WS: 26. notifyTokenUpdated(Active)
deactivate MDES
activate WS
opt
WS ->>Issuer: 27. send Payment Token event
end
WS -> SDK: 28. deliverMessage(paymentTokenActive)
NOTE LEFT: See: Handle Message From Server
deactivate WS
SDK -> SDK: 29. updateTokenStatus
SDK -> MPA: 30. onPaymentInstrumentStatusChanged(id, status)
deactivate MPA
deactivate SDK
end
... Initial Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
@enduml
**TSP VTS**
@startuml
autonumber
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "VTS" as VTS
participant Issuer
alt Just after digitization
VTS --> WS: response from Provision(tokenStatus=INACTIVE,\\nstepUpRequest presents)
activate VTS
activate WS
WS --> SDK: response from Provision(\\ntokenStatus=INACTIVE\\nadditionalAuthenticationRequired=true\\nadditionalAuthenticationMethods)
activate SDK
SDK --> MPA: result(authenticationMethods)
activate MPA
else Activation not finished after digitization
User -> MPA: activate token
MPA -> SDK: UCP::getAdditionalAuthenticationMethods(\\r GetAdditionalAuthenticationMethods)
SDK -> WS: getAuthenticationMethods(paymentTokenId)
WS --> SDK: response(authenticationMethods)
SDK --> MPA: result(authenticationMethods)
end
MPA --> User: show authenticationMethods
User -> MPA: select authentication method
MPA -> SDK: UCP::submitAuthenticationMethod(SubmitAuthenticationMethod)
deactivate MPA
SDK -> WS: submitAuthenticationMethod(\\r paymentTokenId, authenticationMethodId)
deactivate SDK
WS -> VTS: stepUpRequest(id)
deactivate WS
VTS -> Issuer: deliverAuthCode(authCode)
deactivate VTS
activate Issuer
Issuer -> User: deliver authCode
deactivate Issuer
alt Provisioning finished
User -> MPA: enter authentication code
NOTE LEFT: User should have possibility to enter code\\n only when provisioning finished
activate MPA
MPA -> SDK: UCP::submitAuthenticationValue(SubmitAuthenticationValue)
deactivate MPA
activate SDK
SDK -> WS: submitAuthenticationValue(\\r paymentTokenId, authenticationCode)
activate WS
WS -> WS: checkProvisioningStatus
WS -> VTS: validate OTP(authenticationCode)
activate VTS
VTS -> VTS: verify OTP
VTS --> WS: response
WS --> SDK: response
deactivate WS
SDK --> MPA: result
deactivate SDK
activate MPA
MPA -> User: show: please wait
deactivate MPA
VTS -> VTS: createTokenMapping
VTS -> WS: token status updated(Active)
deactivate VTS
activate WS
opt
WS ->> Issuer: send Payment Token event
end
WS -> SDK: deliverMessage(paymentTokenActive)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: updateTokenStatus(ACTIVE)
SDK -> MPA: onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
activate MPA
MPA -> User: show: card activated
deactivate MPA
end
... Initial Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials initial replenishment is performed by SDK.\\rSee Transaction Credentials Initial Replenishment diagram
@enduml
#### Handle Message From Server
In whole system there are processes where server needs to send messages to the device. Wallet Server has separate component which is responsible for sending messages to the device. This component uses different channels for message delivery. There are two channels: SSE(Server Sent Events) and RNS(Remote Notification Service). When message is ready for delivery, Wallet Server uses both channels to deliver such message. In first versions of Wallet Server only RNS was used, however sometimes messages were not delivered and to improve delivery new SSE channel was introduced. This channel helps in processes which start from the device and device expects message from the server. Moreover device checks messages which are still not delivered on actions where such messages are expected. Below diagram describes how delivery message process works and how needs to be handled on MPA side.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant "MPA" as MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "RNS" as RNS
opt
SDK -> WS: 1. callActionAfterWhichMessageIsExpected
WS --> SDK: 2. response
SDK -> WS: 3. openSSEConnection
end
WS -> WS: messageReadyForDelivery
opt If device has opened connection
WS -> SDK: 4. deliverUsingSSE
end
WS -> RNS: 5. deliverMessage
RNS --> WS: 6. response
RNS -> MPA: 7. deliverMessage
MPA -> MPA: 8. checkWalletSenderId
MPA-> SDK: 9. MDC:CloudMessage#process(pushData)
SDK -> SDK: 10. deduplicateMessage
SDK -> WS: 11. acknowledgeMessage
WS --> SDK: 12. response
SDK -> SDK: 13. processMessage
...Obtain pending messages...
MPA -> SDK: 14. someActionWhereMessageMayBeStillPending
SDK -> SDK: 15. doAction
SDK ->> WS: 16. getPendingMessages
WS --> SDK: 17. response
SDK -> SDK: do actions from 10 to 13
@enduml
#### Update RNS Token
Wallet Server is responsible for sending push notifications to the Wallet SDK. For that reason RNS token is passed to Wallet Server during pairing device or in some cases is obtained by SDK from MPA whenere is needed. However this token can be . MPA will be notified when token is being updated and then needs to obtain new RNS token and update via Wallet SDK on Wallet Server. Retrieving push notifications and RNS tokens is responsibility of the MPA.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Remote Notification Service" as RNS
activate RNS
RNS -> MPA: 1. onTokenRefresh
deactivate RNS
activate MPA
MPA -> MPA: 2. obtainNewToken(walletFirebase)
MPA -> SDK: 3. MDC::updateRegistrationToken(newRNSToken)
activate SDK
SDK -> WS: 4. updateRNSToken(deviceInstallationId, newRNSToken)
activate WS
WS -> WS: 5. updateRNSToken
WS --> SDK: 6. response
deactivate WS
SDK --> MPA: 7. result
deactivate SDK
deactivate MPA
deactivate RNS
@enduml
#### Profile Provisioning
During this process digitized card profile is delivered to the device. This process is triggered automatically after successful digitization where outcome is APPROVED or REQUIRE\_ADDITIONAL\_AUTHENTICATION. It is not possible to retry provisioning itself. To retry provisioning, previous token needs to be deleted and new digitization called hence when SDK reports that provisioning has failed then given token is automatically deleted and User can perform digitization once again. During process there is few point of failures and provisioning can be not finished at all. In this scenario Payment Tokens which are not provisioned for long period of time are delete by Wallet Server (see Removing Not Provisioned Tokens). From User perspective it can be good approach to treat digitization and provisioning as one process and inform User about steps(if User has to wait more then 1minute from digitzation without any information then can treat this as some failure). From MPA perspective can be also good approach to wait for provisioning status as long as User stays on view dedicated to it. If User wants to cancel the process because provisioning status is not available for long period of time it is recommended to delete Payment Token(see Delete Payment Token via SDK) once User click cancel or back. Thanks to deletion, new digitization can be called and User does not have to wait until Payment Token is deleted by Wallet Server due to lack of provisioning.
**TSP MDES**
Provisioning process is asynchronosus, after digitization profile is provided to Wallet SDK using different channel. Application should wait for 1minute for provisionig success or failure callback.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
MDES->WS: 1. sendRemoteNotificationMessage(mdesRemoteMessage)
activate MDES
deactivate MDES
activate WS
WS-> SDK: 2. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK-> MDES: 3. provision
activate MDES
MDES --> SDK: 4. response(cardProfile)
SDK-> MDES: 5. notify provisioning result
MDES --> SDK: 6. response
deactivate MDES
SDK -> SDK: 7. store card profile
SDK -> WS: 8. confirmProvisioningStatus(SUCCESS/FAILURE)
activate WS
alt FAILURE
WS -> MDES: 9. deleteToken
activate MDES
MDES --> WS: 10. response
deactivate MDES
WS --> SDK: 11. response
SDK -> SDK: 12. deleteToken
SDK -> MPA: 13. onProvisioningFailure
activate MPA
MPA -> User: 14. please try again
deactivate MPA
else SUCCESS
WS --> SDK: 15. response
deactivate WS
SDK -> MPA: 16. onProvisioningSuccess(paymentInstrument)
deactivate SDK
activate MPA
MPA -> User: 17. card digitized successfully
deactivate MPA
end
@enduml
**TSP VTS**
Provisioning process is part of digitiaztion and called internally after performing cad digitization on Wallet Server. After digitization profile is saved internally, but requires internal communication with 20s timeout. Application should wait or onProvisioningSuccess or onProvisioningFailure.
#### Getting Asset
Every field which's name consists of *assetId* is an identifier to some static asset. This asset can be:
- Card art
- Mastercard brand logos
- Issuers's logos
- Terms and Conditions
There are different types of assets and multiple formats may be supported. For example a single image may be supported in various file formats or variant sizes and most appropriate format to use for a particular device.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "TSP" as TSP
MPA -> SDK: 1. UCP::getAsset(assetId)
activate SDK
SDK -> WS: 2. getAsset(assetId)
activate WS
WS -> TSP: 3. get(assetId)
activate TSP
TSP --> WS: 4. response(content)
deactivate TSP
WS --> SDK: 5. response(content)
deactivate WS
SDK --> MPA: 6. result(content)
deactivate SDK
@enduml
#### Transaction Credentials Replenishment
Transaction Credentials are unique per transactions keys that are used to calculate cryptograms in transactions. Each set of credentials is linked with a unique Application Transaction Counter (ATC). Each set of credentials can only be used for one transaction. There is a limit (set on MDES onboarding) of transaction credentials stored on device.
##### Transaction Credentials - Automatic Replenishment
After every transaction Wallet SDK checks if number of transaction credentials is below, . If yes then SDK will call replenish. During replenish process transaction credentials are being delivered to mobile
##### Transaction Credentials - Initial Replenishment
**TSP MDES**
Initial replenishment is process which starts directly after successful token activation. Wallet SDK is notified by Wallet Server using push notification or refreshing payment instruments. A.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
WS -> SDK: 1. notifyTokenUpdated(Active)
activate WS
deactivate WS
activate SDK
alt Request session if required
SDK-> MDES: 2. requestSession
activate MDES
MDES--> SDK: 3. response
MDES-> WS: 4. sendRemoteNotificationMessage(mdesRemoteMessage)
deactivate MDES
activate WS
WS-> SDK: 5. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK-> MDES: 6. replenish
activate MDES
MDES-> MDES: 7. checkIfPaymentTokenIsActive
MDES-->SDK: 8. response(transactionCredentials)
deactivate MDES
SDK -> MPA: 9. onReplenishSuccess(paymentInstrument)
deactivate SDK
@enduml
**TSP VTS**
VTS Initiali Transaction Credentials Replenishement process depends on token Status after provisioning.
\* For ACTIVE state replenishment process is not called and LUK is saved immediatelly along Token Profile
\* For INACTIVE process is called directly after Token Activation
//todo diagram
##### Transaction Credentials - Manual Replenishment
**TSP MDES**
There are scenarios when automatic replenish is not possible and after some number of transactions, transaction credentials number will decrease to 0. In such case MPA should handle NO\_TRANSACTION\_CREDENTIALS error from transaction listener, show user proper alert and call replenish method manually. MPA can also check number of transaction credentials at any other time.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
MPA -> SDK: 1. UCP::replenishCredentials(paymentInstrumentId)
activate MPA
deactivate MPA
activate SDK
alt Request session if required
SDK-> MDES: 2. requestSession
activate MDES
MDES--> SDK: 3. response
MDES-> WS: 4. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS-> SDK: 5. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK-> MDES: 6. replenish
activate MDES
MDES-> MDES: 7. checkIfPaymentTokenIsActive
MDES-->SDK: 8. response(transactionCredentials)
deactivate MDES
SDK -> MPA: 9. onReplenishSuccess(paymentInstrument)
deactivate SDK
@enduml
**TSP VTS**
VTS uses LUK mechnism which allows to perform transaction after reaching max credentials usage (depends on Issuer configuration, usually 5). Then VTS allow to process up to next 5 transactions until returning DECLINE.
Verestro SDK along VTS performs LUK Credentials replenishement automatically when internet connection is available.
//todo verifivation with Visa if Mechanism starts automatically when User enable internet connection or requires start Application.
#### Transacting
Wallet SDK provides functionalities to make contactless payments (using HCE) and e-commerce payments.
##### Contactless Transaction
CDCVM and on how transaction is started, user experience is different and MPA should interact with Wallet SDK in different way. The final decision about transaction processing belongs to MPA. Wallet SDK provides transaction information and based on that and User authentication, MPA can advise to proceed, decline or require authentication(if User should be authenticated but was not). For contactless transaction Wallet SDK provides result of transaction. This result is only from the communication between and Terminal. Transaction Processing with is done separately (see Transaction Processing). Also after every contactless transaction, Transaction Credentials Replenishment is performed automatically by SDK if needed(see Transaction Credentials - Automatic Replenishment).
NOTE: The way of authentication depends on MPA. For transaction User may also choose specific card. If no card is chosen, SDK will use the one which is set as default for contactless payments. Whenever user is authenticated or chose card for payment MPA should pass this information when *onContactlessPaymentStarted* is called.
As was described above, the final decision(PROCEED, DECLINE, AUTHENTICATION\_REQUIRED) for given transaction is taken on MPA side based on transaction information and User authentication. Because of that reason there could be different scenarios which may occur and transaction experience will be single or double tap.
Sample scenarios:
- User can be already authenticated and if MPA will not decline transaction then will be processed as single tap,
- velocity check counters can be applied and even if User was not authenticated MPA can decide to proceed transaction without authentication, taking decision based on transaction information,
- User was not authenticated but MPA recognised transaction as authentication needed. MPA returns AUTHENTICATION\_REQUIRED decision and and SDK informs MPA that authentication is needed.
**TSP MDES**
All transactions can be performed offline from the MPA perspective.
In case of lack transaction credentials an transaction will be stopped by Wallet SDK and user requested to replenish credentials.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "HostApduService" as HAS
participant "Wallet SDK" as SDK
participant Terminal as TER
opt User selects particular card for payment
MPA -> User: 1. showCards
activate MPA
User -> MPA: 2. selectCard
deactivate MPA
end
User -> MPA: 3. pay
User -> TER : 4. contactless 1st tap
activate TER
loop
TER -> HAS: 5. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 6. UCP::Pay#processHceApduCommand(apdu, extras)
activate SDK
group Select PPSE
SDK -> MPA: 7. onContactlessPaymentStarted()
activate MPA
MPA -> MPA: 8. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 9. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 10. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 11. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
deactivate MPA
end
end
group Generate AC command
SDK -> MPA: 12. getFinalDecisionForTransaction(isUserAuthenticated,recommendedAdvice, trxInfo)
activate MPA
MPA -> MPA: 13. checkTrxAndAuthentication
MPA --> SDK: 14. result(advice)
deactivate MPA
end
SDK --> HAS: 15. responseApdu
HAS --> TER: 16. responseApdu
deactivate HAS
end
alt advice=AUTHENTICATION\_REQUIRED
SDK -> MPA: 17. onAuthRequiredForContactless(paymentInstrument, trxInfo)
activate MPA
MPA -> User: 18. show authentication view with trx info
User -> MPA: 19. authenticate
User -> TER: 20. contactless 2nd tap
loop
TER -> HAS: 21. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 22. UCP::Pay#processHceApduCommand(apdu, extras)
group Select PPSE
SDK -> MPA: 23. onContactlessPaymentStarted()
MPA -> MPA: 24. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 25. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 26. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 27. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
end
end
group Generate AC command
SDK -> MPA: 28. getFinalDecisionForTransaction(isUserAuthenticated=true,recommendedAdvice, trxInfo)
MPA -> MPA: 29. checkTrxAndAuthentication
MPA --> SDK: 30. result(PROCEED)
end
SDK --> HAS: 31. responseApdu
HAS --> TER: 32. responseApdu
deactivate HAS
deactivate TER
end
end
SDK -> MPA: 33. onContactlessPaymentCompleted(paymentInstrument, trxInfo, trxResult)
deactivate SDK
MPA -> User: 34. show trx info view
deactivate MPA
...Transaction Processing ...
note over HAS #1C1E3F: See Transaction Processing diagram
...Transaction Credentials Automatic Replenishment ...
note over HAS #1C1E3F: See Transaction Credentials Automatic Replenishment diagram
@enduml
**TSP VTS**
Using MPA in offline mode for perfoming transaction depends on Android Version. Starting from Android 11(API Level 30) payment can be possible without internet connection. For Android version 8-10 VTS SDK performs intenally HTTP request to Visa Security Services and obtain secure session. It's done once until application closed (by User or System).
Visa uses LUK (Limited Use Key) as transaction credential. During project onboarding Wallet Provider configures credentials threshold and Issuer defines their threshold. Usually values 5 and 10. It means replenish is called after 5 payments, byt Issuer allows to pay up to 10 payments without replenish credentials. Additionally LUK expires after 27 days from replenishement.
For offline transacion (eg transit) VTS SDK uses ODA certificated which is valid for 2months.
@startuml
autonumber
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "HostApduService" as HAS
participant "Wallet SDK" as SDK
participant Terminal as TER
participant VTS as VTS
User -> MPA: tap&pay on Terminal or launch MPA
activate User
deactivate User
alt Verestro SDK not initialized
... Verestro SDK initialization ...
MPA -> SDK: initialize MDC SDK & UCP SDK
activate SDK
deactivate SDK
... VTS SDK initialization ...
SDK -> SDK: VTS#initialize
activate SDK
alt Android >= 11
SDK -> SDK: VTS#VerifyApps offline
alt VTS#VerifyApps success
SDK -> SDK: VTS#enableOfflinePayments()
SDK -> MPA: onPaymentAllowed
deactivate SDK
else VTS#VerifyApps failure
...All Visa card payments will finish with ABORTED due to security verification failed ...
end
else Android < 11 & user is online
SDK -> VTS: VTS#DPELogin online
activate SDK
alt VTS#DPELogin success
VTS -> SDK: response(dpeLoginSession)
SDK -> MPA: onPaymentAllowed
deactivate SDK
else VTS#DPELogin failure
... all Visa card payments will finish with failure (PAYMENT\_NOT\_ALLOWED) ...
end
end
end
opt User selects particular card for payment
MPA -> User: showCards
activate User
activate MPA
User -> MPA: selectCard
deactivate User
deactivate MPA
end
User -> MPA: pay
activate User
User -> TER : contactless 1st tap
deactivate User
activate TER
loop
TER -> HAS: processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: UCP::Pay#processHceApduCommand(context, apdu, extras)
activate SDK
SDK -> MPA: onContactlessPaymentStarted()
activate MPA
SDK -> SDK: Recognize Visa Card and verify\\nif Payment Allowed for Android Version below 11
alt Payment using Visa Card and VTS not allow to payment
SDK -> VTS: Async::Perform DPE Login
SDK --> MPA: onContactlessPaymentAborted(PAYMENT\_NOT\_ALLOWED)\\nMPA must wait for onPaymentAllowed callback
MPA --> User: Verify internet connection\\nand wait for instructions
destroy User
alt DPE login success (requires internet connection)
VTS --> SDK: Async::DPE login session
SDK --> MPA: onPaymentAllowed()
MPA --> User: Request retry payment
destroy User
end
end
activate SDK
group Select PPSE
MPA -> MPA: checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
end
end
group Generate AC command
SDK -> MPA: getFinalDecisionForTransaction(isUserAuthenticated, recommendedAdvice, trxInfo, trxData)
MPA -> MPA: checkTrxAndAuthentication
MPA --> SDK: result(advice)
deactivate MPA
end
SDK --> HAS: responseApdu
HAS --> TER: responseApdu
deactivate HAS
end
alt advice=AUTHENTICATION\_REQUIRED
SDK -> MPA: onAuthRequiredForContactless(paymentInstrument, trxInfo, trxData)
activate MPA
activate User
MPA -> User: show authentication view with trx info
User -> MPA: authenticate
User -> TER: contactless 2nd tap
deactivate User
loop
TER -> HAS: processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: UCP::Pay#processHceApduCommand(context, apdu, extras)
SDK -> MPA: onContactlessPaymentStarted()
group Select PPSE
activate MPA
deactivate MPA
MPA -> MPA: checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
end
end
group Generate AC command
SDK -> MPA: getFinalDecisionForTransaction(isUserAuthenticated=true, recommendedAdvice, trxInfo, trxData)
MPA -> MPA: checkTrxAndAuthentication
MPA --> SDK: result(PROCEED)
end
SDK --> HAS: responseApdu
HAS --> TER: responseApdu
deactivate HAS
deactivate TER
end
end
SDK -> MPA: onContactlessPaymentCompleted(paymentInstrument, trxInfo, trxResult, trxData)
deactivate SDK
MPA -> User: show trx info view
deactivate MPA
...Transaction Processing ...
note over HAS #1C1E3F: See Transaction Processing diagram
...Transaction Credentials Automatic Replenishment ...
note over HAS #1C1E3F: See Transaction Credentials Automatic Replenishment diagram
@enduml
##### E-commerce transaction
**TSP MDES**
E-commerce transaction can be processed using DSRP. Every DSRP transaction has to be authenticated. Depending on implementation e-commerce payment can be preceded with one time password authentication or just device level authentication.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
box "Consumer mobile android device" #white
participant "Merchant App" as MerchantApp
participant MPA
participant "Wallet SDK" as SDK
end box
participant Merchant
participant "Wallet Server" as WS
participant MDES
participant Issuer
participant "Payment Gateway" as PG
User -> MerchantApp: 1. pay
activate MerchantApp
MerchantApp -> Merchant: 2. startTransaction
activate Merchant
Merchant --> MerchantApp: 3. response(transactionId,\\r unpredictableNumber)
deactivate Merchant
MerchantApp -> MPA: 4. getDsrpData(transactionId, trxInfo)
deactivate MerchantApp
activate MPA
alt One Time Password
MPA -> User: 5. select payment instrument
User -> MPA: 6. payment instrument
MPA -> SDK: 7. UCP::requestAuthCodeForPayment(transactionId \\ras authenticationRequestId)
activate SDK
SDK -> WS: 8. requestAuthenticationCodeForPayment(authenticationRequestId)
activate WS
WS -> MDES: 9. requestAuthenticationCodeForPayment(authenticationRequestId)
activate MDES
MDES -> Issuer: 10. sendAuthenticationCode
activate Issuer
Issuer --> MDES: 11. response
MDES --> WS: 12. response
deactivate MDES
WS --> SDK: 13. response
deactivate WS
SDK --> MPA: 14. result
Issuer -> User: 15. sendAuthenticationCode(authenticationCode)
deactivate Issuer
User -> MPA: 16. provide authentication code
MPA -> SDK: 17. UCP::validateAuthenticationCodeForPayment(authenticationCode,\\r transactionId)
SDK -> WS: 18. validateAuthenticationCodeForPayment(authenticationCode,\\r authenticationRequestId)
WS -> MDES: 19. authenticate(authenticationCode,\\r authenticationRequestId)
MDES --> WS: 20. response
deactivate MDES
WS -> WS: 21. createDigitalSignature(authenticationRequestId)
WS --> SDK: 22. response(digitlSignature)
SDK --> MPA: 23. result(digitalSignature)
else Device Level Auth
MPA -> User: 24. show authentication view
User -> MPA: 25. authenticate
end
MPA -> SDK: 26. UCP::setUserAuthenticatedForPayment(id, pin?)
MPA -> SDK: 27. UCP::processDsrpTransaction(id, trxInfo)
SDK --> MPA: 28. result(dsrpData)
MPA --> MerchantApp: 29. result(dsrpData)
activate MerchantApp
MerchantApp -> MerchantApp: 30. encryptPaymentDataForTransit(dsrpData)
MerchantApp -> Merchant: 31. finishTransaction(encryptedPaymentData, \\rdigitalSignature?, transactionId)
activate Merchant
opt
Merchant -> Merchant: 32. validateSignature
note right: this check is needed to proof that given transactionId\\n\\r was preceded with OTP
end
Merchant -> PG: 33. processPayment(pan, exp, cryptogram)
activate PG
PG --> Merchant: 34. response
Merchant --> MerchantApp: 35. response
MerchantApp -> User: 36. show result
deactivate PG
deactivate Merchant
deactivate MerchantApp
@enduml
**TSP VTS**
Not available in Verestro SDK.
##### Transaction Processing
Transaction Processing starts after contactless communication between terminal and MPA in case of contactless payment or after payment gateway transaction authorization initiation in case of e-commerce payment. After authorization TSP notifies Wallet Server about the result of the authorization and sends transaction information. Transaction information is sent to MPA.
**TSP MDES**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Terminal/PG" as TER
participant "Payment Network" as PN
participant MDES
participant Issuer
TER -> PN: 1. authorizeTransaction(tokenPAN, cryptogram)
activate PN
activate TER
PN -> MDES: 2. detokenize
activate MDES
MDES -> MDES: 3. lookup token mapping
MDES --> PN: 4. response(PAN)
deactivate MDES
PN -> Issuer: 5. authorize(PAN)
activate Issuer
Issuer --> PN: 6. response
deactivate Issuer
PN --> TER: 7. response
deactivate TER
PN -> MDES: 8. storeTransactionDetails
deactivate PN
activate MDES
MDES -> WS: 9. pushTransactionDetails
deactivate MDES
activate WS
alt store transaction enabled
WS -> WS: 10. storeTransaction
end
opt
WS ->>Issuer: 11. send transaction event
end
WS -> SDK: 12. deliverMessage(trxInfo)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> MPA: 13. onNewTransaction(trxDetails)
deactivate SDK
activate MPA
MPA -> User: 14. showSystemNotification(trxDetails)
deactivate MPA
@enduml
**TSP VTS** //todo works like MDES
#### Setting Defaults for Payment
SDK manages default Payment Instrument for contactless payments. After digitization, if there is no default Payment Instrument, SDK sets digitized Payment Instrument after activation as default. In case where there are more than one active Payment Instruments and current default Payment Instrument is deleted or suspended, the SDK will set first active Payment Instrument as default. Default Payment Instrument can be changed at any time. Only active Payment Instrument can be set as default.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
MPA->User: 1. payment instrument list
activate MPA
User->MPA: 2. choose default for contactless payment)
MPA->SDK: 3. UCP::setDefaultForContactless(paymentInstrumentId)
activate SDK
SDK-> SDK: 4. storeDefault
SDK-->MPA: 5. result
deactivate MPA
deactivate SDK
@enduml
#### Login On Wallet Server
User data are protected by User session token which is issued by Wallet Server after providing authentication factor. Authentication factor is provided first in pairing device and then session is created. Since session has limited period of validity, it needs to be refreshed using login on Wallet Server methods.
Login on Wallet Server using Trusted Identity
. During login process Wallet Server checks if given device still exists, if not then responds with CANT\_FIND\_DEVICE status which is interpreted on SDK side as given device is deleted and all local data stored on SDK side are cleared.
Since MDC 2.14.5 for devices which are already paired, Wallet SDK will try to asynchronously register device in new delivery message service. To make it possible *CloudMessagingRegistrationProvider* needs to be implemented and provided within setup.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as Issuer
MPA -> SDK: 1. invoke API
activate MPA
activate SDK
SDK -> WS: 2. invoke API
activate WS
WS --> SDK: 3. response(USER\_UNATHORIZED)
deactivate WS
SDK --> MPA: 4. result(USER\_UNATHORIZED)
MPA->User: 5. show authenticate view
User->MPA: 6. put authentication data
MPA->Issuer: 7. authenticate
activate Issuer
Issuer -> Issuer: 8. generateTrustedIdentity - signed user id
Issuer --> MPA: 9. response(trustedIdentity)
deactivate Issuer
MPA-> SDK: 10. MDC::loginByTrustedIdentity(trustedIdentity)
SDK-> WS: 11. loginByTrustedIdentity(trustedIdentity)
alt Device not registered in new delivery message service
SDK -> MPA: 12. CloudMessagingRegistrationProvider::getRegistrationToken
SDK ->> WS: 13. registerDeviceForNewMessageDelivery(cloudMessageToken)
WS --> SDK: 14. response
end
activate WS
WS -> WS: 15. check if device exists
alt device exists
WS-> WS: 16. verify trusted identity
WS --> SDK: 17. response(userSessionToken)
SDK -> SDK: 18. store(userSessionToken)
SDK-->MPA: 19. result
MPA -> SDK: 20. invoke API
else device not exists
WS --> SDK: 21. response(CANT\_FIND\_DEVICE)
deactivate WS
SDK -> SDK: 22. clearAllLocalData
SDK --> MPA: 23. result(CANT\_FIND\_DEVICE)
deactivate MPA
deactivate SDK
... Pair device ...
note over MPA, WS #1C1E3F: See Pairing Device diagram
MPA -> SDK: 24. invoke API
end
@enduml
#### Getting Cards
When cards are already placed on Wallet Server, then they can be displayed to User in the application. Cards have identifiers which can be used e.g. for digitization.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
MPA->SDK: 1. MDC::getAllCards
activate MPA
activate SDK
SDK -> WS: 2. getAllCards(userSessionToken)
WS --> SDK: 3. response(userCards)
deactivate WS
SDK --> MPA: 4. result(cardList)
deactivate SDK
deactivate MPA
@enduml
#### Getting Payment Intruments
After digitization process, payment instrument is stored in VCP SDK module of Wallet SDK. Payment instrument in context of VCP SDK is digitized card and contains i:
- id (specified id which helps MPA to identify payment instrument which was digitized from MPA),
- status,
- transaction credentials count,
- paymentTokenId etc. .
MPA can get information about all Payment Instruments from the Wallet SDK at any time. Payment instruments will be retrieved only from local storage that is part of SDK. Payment Tokens for Payment Instruments can be refreshed/pulled from Wallet Server on demand. This scenario should be considered only when User e.g. makes swipe to refresh.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as IS
MPA->SDK: 1. UCP::getAllPaymentInstruments(refresh)
activate MPA
alt refresh = true
activate SDK
SDK -> WS: 2. getAllPaymentTokens(userSessionToken)
activate WS
WS -> SDK: 3. response(devicePaymentTokens)
deactivate WS
SDK -> SDK: 4. updateLocalStorage
end
SDK --> MPA: 5. result(paymentInstrumentList)
deactivate SDK
deactivate MPA
@enduml
#### Getting Transaction History
. Transactions are returned in corresponding parts for better user experience. If next part is available then response from previous part contain information needed for requesting next part. MPA should check if next part is not empty and then make another request.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
loop next != null
MPA->SDK: 1. MDC::getTransactionsHistory(filters, next?)
activate MPA
activate SDK
SDK -> WS: 2. getTransactionHistory(filters, next?, userSessionToken, ...)
activate WS
WS -> SDK: 3. response(transactionHistoryList, next?)
deactivate WS
SDK --> MPA: 4. result(transactionHistoryList, next?)
deactivate SDK
deactivate MPA
end
@enduml
#### Payment Token Lifecycle Management via SDK
Payment Token lifecycle management can be done via SDK.
##### Delete Payment Token via SDK
Payment Token can be deleted using SDK.
**TSP MDES**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant Issuer
User -> MPA: 1. Delete payment token
activate MPA
MPA -> SDK: 2. UCP::delete(paymentInstrumentId, reason)
deactivate MPA
activate SDK
SDK -> WS: 3. deletePaymentToken(userSessionToken, paymentTokenId, reason)
activate WS
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
deactivate MDES
WS --> SDK: 7. response
opt
WS ->> Issuer: 8. send Payment Token event
end
deactivate WS
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
MPA --> User: 17. show update view
deactivate MPA
@enduml
**TSP VTS**
//todo works like MDES
#### Errors Reporting
#### Device Unpairing
Unpairing device clears all modules data and report that fact only if possible to server. If server receives this signal then removes all device data including provisioned Payment Tokens. If not then data are cleared locally only - similar like during app uninstallation. This can be used for scenario when MPA does not want to use SDK at all or for scenario when MPA supports switching between users accounts on the same installation. If MPA detects that new User is trying to log into application in case when previous had digitized cards, immediately should clear all data from previous, since SDK stores data in context of one User only.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
MPA -> SDK: 1. MDC::unpairDevice
activate MPA
activate SDK
opt
SDK -> WS: 2. unpairDevice
activate WS
WS --> SDK: 3. response
deactivate WS
end
SDK -> SDK: 4. clearAllData
SDK --> MPA: 5. result
deactivate SDK
deactivate MPA
@enduml
#### MDES Initiated
This section describes use cases which are initiated from MDES.
##### Re-digitization
Re-digitization process can be triggered by MDES for several use cases:
**Token Expiry**
One month before token expiry MDES will request for redigitization.
**Attribute Change**
Issuer may perform an attribute change at the BIN account-range level impacting theri MDES enabled ranges. Some device tokens may need to have their data refreshed to match the new attributes.
**BIN Account-Range Split**
Issuer may perform a BIN account-range split. Some existing tokens may need to be updated to ensure that they are linked to the correct funding BIN account ranges internally.
**PAN Update in Different Account Range**
Issuer may update existing PAN with new Pan in a different BIN account range.
For above cases:
- token unique reference remains the same
- token expiration date is extended by three years from the date of redigitization
After successful redigitization process transaction credentials replenishment is called in case where Payment Token is active.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
MDES -> WS: 1. notifyTokenUpdated(redigitize=true)
activate MDES
activate WS
WS -> MDES: 2. redigitize
MDES --> WS: 3. response
WS --> MDES: 4. response
deactivate MDES
deactivate WS
MDES->WS: 5. sendRemoteNotificationMessage(mdesRemoteMessage)
activate MDES
deactivate MDES
activate WS
WS-> SDK: 6. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK-> MDES: 7. provision(redigitize=true)
activate MDES
MDES --> SDK: 8. response(cardProfile)
SDK-> MDES: 9. notify provisioning result(redigitize=true)
MDES --> SDK: 10. response
SDK -> WS: 11. confirmReProvisioningStatus(SUCCESS/FAILURE)
alt FAILURE
WS -> WS: 12. markRedigitizationAsFailed
note left: redigitization process will be retried after some period of time
SDK -> MPA: 13. onReProvisioningFailure(paymentInstrument)
else SUCCESS
SDK -> SDK: 14. clearTransactionCredentials
SDK -> MPA: 15. onReProvisioningSuccess(paymentInstrument)
deactivate SDK
MDES -> WS: 16. notifyTokenUpdated(redigitized=false)
deactivate MDES
activate WS
opt
WS ->> Issuer: 17. send Payment Token event
end
WS -> SDK: 18. deliverMessage(PAYMENT\_TOKEN\_INFO\_CHANGE(redigitized=true))
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: 19. replenish
... Automatic Replenishment ...
note over SDK, MDES #1C1E3F: Just after reprovisioning transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
end
@enduml
#### Wallet Server Initiated
Since important processes are asynchronous in MDES and there are many point of failures, wallet server provides additional functionalities to resolve some failure scenarios by running some operations on own side.
##### Removing Not Provisioned Tokens
Wallet Server checks periodically DEVICE Payment Tokens and verify if provisioning is completed. These Payment Tokens which have provisioning status in progress for long period of time are deleted automatically and from User perspective process needs to be started again. By default this period is set to 1 hour but can be modified.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
WS -> WS: 1. find not provisioned payment tokens for a\\r long period of time
activate WS
loop Not provisioned payment tokens for a long period of time
WS -> MDES: 2. Delete token
activate MDES
MDES -> MDES: 3. Delete token mapping
MDES --> WS: 4. response
deactivate MDES
opt
WS ->> Issuer: 5. send Payment Token event
end
WS -> SDK: 6. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
alt Request session if required
SDK -> MDES: 7. request session
activate MDES
MDES --> SDK: 8. response
MDES -> WS: 9. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 10. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 11. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 12. response
deactivate MDES
SDK -> SDK: 13. Delete transaction credentials, card profile
SDK -> MPA: 14. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
#### Wallet Server Admin API Initiated
This section describes use cases which are initiated from Wallet Server Admin Panel.
##### Admin Card Deletion
During this process all data related to given card are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
participant Issuer
AP -> WS: 1. deleteCard(cardId)
activate WS
activate AP
WS -> WS: 2. deleteCard
WS --> AP: 3. response
deactivate AP
loop All Payment Tokens for card
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
deactivate MDES
opt
WS ->>Issuer: 7. send Payment Token event
end
WS -> SDK: 8. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
##### Admin Device Deletion
During this process all data related to given device are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deleteDevice(deviceInstallationId)
activate AP
activate WS
WS --> AP: 2. response
deactivate AP
loop All Payment Tokens for given device
WS -> MDES: 3. delete token
activate MDES
MDES --> WS: 4. response
deactivate WS
deactivate MDES
end
@enduml
##### Admin Token Deletion
Payment Token can be deleted via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deletePaymentToken(paymentTokenId)
activate AP
activate WS
WS -> MDES: 2. Delete token
activate MDES
MDES -> MDES: 3. Delete token mapping
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->> Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenDeleted)
deactivate WS
activate SDK
NOTE LEFT: See: Handle Message From Server
deactivate MDES
alt Request session if required
SDK -> MDES: 8. request session
activate MDES
MDES --> SDK: 9. response
MDES -> WS: 10. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 11. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 12. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 13. response
deactivate MDES
SDK -> SDK: 14. Delete transaction credentials, card profile
SDK -> MPA: 15. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
MPA --> User: 16. show update view
deactivate MPA
@enduml
##### Admin Token Suspension
Payment Token can be suspended via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
participant Issuer
AP -> WS: 1. suspendToken(paymentTokenId)
activate WS
activate AP
WS -> MDES: 2. suspend token
activate MDES
MDES -> MDES: 3. Suspend token
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->> Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenSuspend)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: 8. suspend
SDK -> MPA: 9. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
deactivate MPA
@enduml
##### Admin Token Unsuspension
Payment Token can be unsuspended via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. unsuspendToken(paymentTokenId)
activate WS
activate AP
WS -> MDES: 2. unsuspend token
activate MDES
MDES -> MDES: 3. Unsuspend token
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->>Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenUnsuspend)
deactivate WS
activate SDK
SDK -> SDK: 8. activate
SDK -> MPA: 9. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
deactivate MPA
... Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials replenishment is performed by SDK\\r. See Transaction Credentials Automatic Replenishment diagram
@enduml
##### Admin User Deletion
During this process all data related to given User are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deleteUser(userId)
activate AP
activate WS
WS -> WS: 2. delete cards, devices
WS --> AP: 3. response
deactivate AP
loop All Payment Tokens for given User
WS -> MDES: 4. delete token
activate MDES
MDES --> WS: 5. response
deactivate WS
deactivate MDES
end
@enduml
#### Summary of Changes
This section describes changes introduced in next version based on time
##### Version 2.0
- Base version of the document describing VCP Solution for cards
##### Version 2.1
- Introduced *onContactlessPaymentStarted* in Contactless Transaction use case
- Added new use case: Handle Message From Server
- Introduced provider for *cloudMessageRegistrationToken* in Login On Wallet Server use case
- Updated all use cases with new way of message delivery from server
- Added sending Payment Token event when token is created or updated
# Technical documentation
You can find technical documentation on this site.
# Technical Documentation VCP SDK
## VCP SDK Introduction
### Basic abbreviations and definitions
| **Field** | **Description** |
|---|
| CDCVM | Consumer Device Cardholder Verification Method |
| CVM | Cardholder Verification Method |
| Contactless | Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA,
and then to VCP SDK. HCE support is required for contactless transactions
|
| DSRP | Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with
the remote merchant system. HCE support is not required for DSRP transactions
|
| FCM | Firebase Cloud Messaging
|
| HCE | Host Card Emulation |
| IBAN | Bank Account Number |
| MCBP | Mastercard Cloud Based Payments |
| MDC | Mobile Data Core. Verestro core library.
|
| MPA | Mobile Payment Application - an application that uses VCP SDK for payments
|
| NFC | Near Field Communication |
| One tap | Flow in a contactless transaction, in which the consumer after authentication(using the PIN, fingerprint, etc.)
taps the device to POS to start exchanging data
|
| PAN | Primary account number. Know as a card number. |
| Payment Instrument | Model keeping all data considering entity used for payments
|
| POS | Point Of Sale |
| QRC | QR Code transactions - allows consumer generate QR code to present to a merchant,
who then scans it to take payment
|
| SUK | Single Use Key - unique credential used for single transaction for Mastercard
|
| LUK | Limited Use Key - payment credential for usage with Visa
|
| Two tap | Flow in a contactless transaction, in which consumer firstly taps device to POS,
authenticates(using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data
|
| TVC | Token Verification Code |
| EWS | External Wallet Server |
| VCP
| Verestro Cloud Payment |
### What is VCP SDK?
The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.payment
### How VCP SDK works?
Provides methods to manage digitization using main domains:
- IBANs
- Payment
- Cloud Messaging
- Cards
- External Wallet Server
Depending on the selected payment instrument source (Card, Iban, External Wallet Server) VCP SDK allows to digitize it and provide methods for the payment process.
Usage of the following domains depends on client requirements.
### Versioning and backward compatibility
SDK version contains three digits. For example: 1.0.0.
- .
- Second version digit tracks new, not compatibility-breaking changes in public API of SDK. It is optional to update the application code when this digit is incremented.
- Third version digit tracks internal changes in SDK. No updates in application code are necessary to update to the version, which has this number incremented.
Changes not breaking compatibility:
- Adding a new optional interface to SDK setup
- Adding a new method to any domain
- Adding a new ENUM value to input or output
-
##
###
The minSdkVersion must be at least 23 (Android 6.0). The application must use AndroidX.
SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system.
**The username and password are provided by Verestro.**
| ```
repositories{
maven {
credentials {
username ""
password ""
}
url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
//if the sync time takes too long, add filters to match the repository with specific modules as below
content {
includeGroupByRegex "pl.upaid.*"
includeGroup "com.mastercard"
includeGroup "com.visa" //Only when Visa is used
}
}
}
```
|
VCP SDK is available in two versions: debug and release.
Debug version is ended with appendix "-debug" in version name. Samples below:
**For release version:**
| ```
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}'
//def strictVtsVersionBeta = "6.4.1-sandbox"
//def strictVtsVersionProduction = "6.4.1-production"
//implementation 'com.visa:cbp' + strictVtsVersionBeta
//implementation 'com.visa:cbp' + strictVtsVersionProduction
}
```
|
**For debug version:**
| ```
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}-debug'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}-debug'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
|
**Min SDK Version**
The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.
SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it.
###
VCP SDK Application Signing requirements
**Mastercard:**
There is no requirement related to Application signing.
**Visa:**
Both sandbox (test) and production environment require APK signed with valid key.
To add Application as Trusted in Visa services please provide Signing Key Certificate from chain in PEM format using below script:
```
keytool -exportcert -keystore your_apk_keystore.jks -alias your_keystore_key_alias -rfc -file certificate.pem
```
Output will be provided in *certificate.pem* file.
Please provide an result to Verestro representative with related *applicationId* (package).
**Note:** When using only Google Play signing key tests local tests related to Visa tokenization and payments will be not possible.
### VCP SDK Size
The size of SDK is dependent on its distribution system.
The table below shows the size of the module for the ask and bundle file.
****
- size from the table above is referred to release version;
-
###
####
####
Every of the described facades is divided into domains with different responsibilities. Available domains:
- IBANs
- Payment
- Cloud Messaging
- Cards
- External Wallet Server
Every domain contains domain-related methods.
#### Error handling
Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods.
SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message.
**Note**: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.
| **Exception type** | **Exception class** | **Description** |
|---|
| SDK validation | ValidationException | Additional reason codes for ValidationException used in Mobile DC SDK |
| Backend exception | BackendException | Additional reason codes for BackendException used in Mobile DC SDK.
**Note:** Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain)
|
| SDK exception | UcpSdkException | Something went wrong on the SDK side, check the table below with possible reasons |
| Process related | - | As every process is different some methods could throw a specified exception
Types of possible exceptions are described in the method description
|
Additional BackendException reason codes:
| **Reason** | **Description**
|
|---|
| INTERNAL\_ERROR | Error occurred on server
|
| VALIDATION\_ERROR
| Client sent invalid data
|
| CRYPTOGRAPHY\_ERROR
| Error occurred during cryptography operation
|
| PAYMENT\_CARD\_PREDIGITIZE\_ERROR
| Predigitize of payment card failed
|
| PAYMENT\_IBAN\_PREDIGITIZE\_ERROR
| Predigitize of payment IBAN failed
|
| PAYMENT\_CARD\_DIGITIZE\_ERROR
| Digitize of payment card failed
|
| PAYMENT\_IBAN\_DIGITIZE\_ERROR
| Digitize of payment IBAN failed
|
| PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED
| Predigitize for payment card must be executed
|
| PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED
| Predigitize for payment IBAN must be executed
|
| CLIENT\_UNAUTHORIZED
| Client of the API is unauthorized
|
| USER\_UNAUTHORIZED
| User is unauthorized
|
| CANT\_FIND\_USER
| Cannot find user
|
| CANT\_FIND\_DEVICE
| Cannot find device
|
| CANT\_FIND\_IBAN
| Cannot find payment IBAN
|
| CANT\_FIND\_CARD
| Cannot find payment card
|
| CANT\_FIND\_PAYMENT\_TOKEN
| Cannot find payment token
|
| OPERATION\_NOT\_SUPPORTED
| Requested operation is not supported
|
| OPERATION\_NOT\_ALLOWED
| Requested operation is not allowed
|
| DEVICE\_TEMPORARILY\_LOCKED
| Device is temporarily locked
|
| DEVICE\_PERMANENTLY\_LOCKED
| Device is permanently locked
|
| INVALID\_PAN
| The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly
|
| MISSING\_EXPIRY\_DATE
| The expiry date is required for this product but was missing
|
| PAN\_INELIGIBLE
| The PAN is not in an approved account range for TSP
|
| DEVICE\_INELIGIBLE
| The device is not supported for use
|
| PAN\_INELIGIBLE\_FOR\_DEVICE
| The PAN is not allowed to be provisioned to the device because of Issuer rules
|
| PAN\_ALREADY\_PROVISIONED
| The PAN is already provisioned for this device
|
| IBAN\_INELIGIBLE
| The financial account does not have an associated account range in TSP
|
| PARALLEL\_REQUESTS\_ATTEMPTS
| Action is already processing. Please try again after the time included in headers
|
| INVALID\_JWS\_TOKEN | Specified JWS token is invalid |
Additional ValidationException reason codes:
| **Reason** | **Description** |
|---|
| INVALID\_SECURITY\_CODE
| Security code is empty
|
| INVALID\_LANGUAGE\_CODE
| Language code is empty
|
| INVALID\_PAYMENT\_INSTRUMENT\_ID
| Payment instrument id is empty |
UcpSdkException reason codes:
| **Reason** | **Description** |
|---|
| PUSH\_INVALID\_SOURCE
| Relates to push processing process. Push message should be consumed in another module
|
| PUSH\_INVALID\_PUSH\_CONTENT
| Cannot process push message. The message is invalid or some process failed
|
| PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND
| Cannot find default PaymentInstrument |
| PAYMENT\_INSTRUMENT\_NOT\_FOUND
| Selected PaymentInstrument cannot be found, is not digitized or active
|
| APPLICATION\_PROCESS\_NOT\_KILLED | Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process
|
####
#### Facade
The facade is an entry point to communication with VCP SDK.
Contains SDK initialization method and domains which allows for payment instrument management.
####
#### Method structure
Please read Mobile DC Documentation for details.
####
#### Multiple facade types
VCP SDK provides three public APIs with the same functionalities, the APIs are:
- UcpJavaApi for projects which use Java programming language.
- UcpKotlinApi for projects which use Kotlin programming language.
The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same.
This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark).
####
#### HceApduService registration
To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service.
Properly configured meta-data in service will also register an application as tap&pay ready.
Exemplary service below:
Below listing of the default source file hce\_apud\_service.xml:
Check if the application is set as default for payment.
| ```
fun isSystemDefault(): Boolean {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
return cardEmulation.isDefaultServiceForCategory(
WalletHceService::class.java,
CardEmulation.CATEGORY_PAYMENT
)
}
```
|
Request for set your application as default for payment - will show a dialog for the user to approve the changes.
| ```
fun requestForSystemDefault() {
val intent = Intent().apply {
action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
putExtra("component", WalletHceService::class.java)
putExtra("category", CardEmulation.CATEGORY_PAYMENT)
}
context.startActivity(intent)
}
```
|
If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.
| ```
fun registerAsOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.setPreferredService(
activity, ComponentName(activity, WalletHceService::class.java)
)
}
fun unregisterFromOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.unsetPreferredService(activity)
}
```
|
####
#### Models
##### PaymentInstrument
| **Parameter** | **Type** | **Description** |
|---|
| String | Id of payment instrument. For card it is cardId, for IBAN sha256Hex.
In the context of the External Wallet Server use tokenUniqueReference from MDES
|
| paymentTokenId | String | Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id |
| displayablePanDigits | String | Token last 4 digits which can be used to display
|
| paymentInstrumentStatus | PaymentInstrumentStatus | Enum with status of payment instrument.
|
| contactlessSupported | Boolean | Information if payment instrument supports contactless transactions.
|
| dsrpSupported | Boolean | Information if the payment instrument supports DSRP transactions.
|
| qrcSupported | Boolean | Information if the payment instrument supports QR transactions.
|
| onDeviceCvmSupported | Boolean | Information about supporting CVM on device.
|
| credentialsCount | Int | Amount of credentials that can be used for payments.
Always 0 for Visa Cards.
|
| isDefaultForContactlessPayment
| Boolean | Information if payment instrument is default for contactless payments.
|
| isDefaultForRemotePayment | Boolean | Information if payment instrument is default for remote payments.
|
| additionalAuthenticationRequired | Boolean
| Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods
|
| tokenLastFourDigits | String?
| Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| paymentInstrumentExpirationDate | String?
| Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| paymentInstrumentLastFourDigits
| String?
| Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| productConfig
| ProductConfig?
| Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| provisioningStatus
| String
| Current state of provisioning process. One of:
IN\_PROGRESS - in case of waiting for *onProvisioningSuccess*(),
SUCCESS - when token is provisioned.
|
| paymentTokenExpirationDate | String? | Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled.
|
###
##### PaymentInstrumentStatus
| **Field** | **Description** |
|---|
| INACTIVE | Payment instrument is not , it can not be used for transactions.
The activation process depends on integration. Read the product overview for more information.
|
| ACTIVE | Payment instrument is active and it can be used for transactions.
|
| SUSPENDED | Payment instrument is suspended. |
| DELETED | Payment instrument is DELETED.
|
| UNKNOWN | Payment instrument status is unknown. |
#####
##### AdditionalAuthenticationMethod
| **Parameter** | **Type** | **Description** |
|---|
| id | String | Identifier of additional authentication method |
| name | String | Method name. One of:
OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER
|
| value | String | Value depends on method name. Described below. |
| issuerParameters | AuthMethodsIssuerParameters? | Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION |
####
##### Additional authentication method values:
| **Method** | **Value** | **Description** |
|---|
| `OTP_TO_CARDHOLDER_NUMBER` | Masked phone number
| Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number. |
| `OTP_TO_CARDHOLDER_EMAIL` | Masked email
| Email to Account holder’s email address. The value will be the Account holder’s masked email address. |
| `CARDHOLDER_TO_CALL_CUSTOMER_SERVICE` | Phone number
| Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service.
|
| `CARDHOLDER_TO_VISIT_WEBSITE` | Website URL
| Account holder to visit a website. The value will be the website URL.
|
| `CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION` | Application name
| (Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS.
|
| `ISSUER_TO_CALL_CARDHOLDER_NUMBER` | Masked phone number
| Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number.
|
| **Parameter** | **Type** | **Description** |
|---|
| mdes | AuthMethodsIssuerParametersMdes? | Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token |
| vts | AuthMethodsIssuerParametersVts? | Required for VTS Payment token |
####
##### AuthMethodsIssuerParametersMdes contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| android | AuthMethodsIssuerParametersMdesAndroid | Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device |
| ios | AuthMethodsIssuerParametersMdesIos | Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device |
####
##### AuthMethodsIssuerParametersMdesAndroid contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| action | String? | Name of the action to be performed |
| packageName | String? | The package name of the issuer's mobile app |
| extraTextValue | String? | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app |
##### AuthMethodsIssuerParametersMdesIos contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| deepLinkingUrl | String? | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. |
| extraTextValue | String? | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. |
##### AuthMethodsIssuerParametersVts contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| android | AuthMethodsIssuerParametersVtsAndroid? | Plain AuthMethodsIssuerParametersVtsAndroid object.
Required for Android devices |
| ios | AuthMethodsIssuerParametersVtsIos? | Plain AuthMethodsIssuerParametersVtsIos object.
Required for IOS devices |
##### AuthMethodsIssuerParametersVtsAndroid contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### AuthMethodsIssuerParametersVtsIos contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
#####
##### ContactlessTransactionInformation
| **Parameter** | **Type** | **Description** |
|---|
| currencyCode | ByteArray | Code of currency, that was used in transaction. Formatted in ISO 4271.
|
| amount | ByteArray | Transaction amount in bytes. Can be formatted as Int in pennies. |
| transactionRange | ContactlessTransactionRange | Type of transaction range.
|
| ContactlessRichTransactionType | Rich transaction type.
|
| ByteArray | Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset. |
**ContactlessTransactionRange**
| **Value** | **Description**
|
|---|
| LVT | Low value transaction |
| HVT | High value transaction
|
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| **Value** |
|---|
| PURCHASE |
| REFUND |
| CASH |
| TRANSIT |
| PURCHASE\_WITH\_CASHBACK |
| UNKNOWN |
##### DsrpTransactionInfo
| **Parameter** | **Type** | **Descruption** |
|---|
| amount | Long | Transaction amount |
| currencyCode | Int | |
| countryCode | Int | Code of country.
|
| issuerCryptogramType | String | Cryptogram type. |
##### TransactionAbortReason
| **Value** | **Description** |
|---|
| WALLET\_CANCEL\_REQUEST | Indicates that the wallet has requested a transaction cancellation during payment. |
| This indicates that a problem has been detected in the MChipEngine processing.
In some implementations, this can indicate badly formatted card profile data.
|
| This indicates incorrect terminal behavior.
|
| |
| . Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). |
| TERMINAL\_INACTIVITY\_TIMEOUT | There is a problem with communication between the terminal and payment device.
For example, the terminal could abort communication with the mobile device for
a long period of time and then trigger a timeout.
Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal.
The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment.
**Note:** When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again.
**Note:** Deprecated in 2.6.7, no longer used due to time difference between connection lost and providing result to application. Replaced by CONNECTION\_LOST which works immediatelly.
|
| CONNECTION\_LOST
| Connection between terminal and device is lost and payment is terminated.
|
| PAYMENT\_NOT\_ALLOWED | Payment is not allowed at this moment.
Mastercard: Application should show error and user should retry payment.
Visa: Visa requires online security services connection before performing payment on Android versions below 11.
When connected internet connection is no more required until application close.
During a Payment application should wait for UcpVtsPaymentAllowedListener::onPaymentAllowed()
|
##### NewTransaction
| **Field** | **Type** | **Description** |
|---|
| clientTransactionId
| String?
| Identifier of transaction in TSP
|
| type
| String
| The transaction type. One of: \[UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER\]
|
| amountMinor
| Long
| The monetary amount in terms of the minor units of the currency. For example,
`EUR 2.35' will return 235, and `BHD -1.345' will return -1345
|
| currency
| String
| 3-digit ISO 4217 currency code
|
| timestamp
| String
| The date/time when the transaction occurred. In ISO 8601 extended format
|
| merchantName
| String?
| The merchant (``doing business as'') name
|
| merchantPostalCode
| String?
| The postal code of the merchant
|
| transactionCountryCode
| String?
| The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1
|
| comboCardAccountType
| String?
| An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: \[UNKNOWN, CREDIT, DEBIT\]
|
| issuerResponseInformation
| String?
| Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: \[UNKNOWN, INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION\]
|
| status
| String
| The authorization status of the transaction. One of: \[AUTHORIZED, DECLINED, CLEARED, REVERSED\]
|
| paymentTokenId
| String
| Identifier of payment token in VCP
|
##### ContactlessTransactionData
| **Parameter** | **Type** | **Description** |
|---|
| currencyNumber | Int | Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. |
| currencyCode | String? | Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN
Could be null as the terminal provides only the currencyNumber and a valid code could be not found.
|
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, |
| transactionRange | ContactlessTransactionRange | Type of transaction range.
|
| ContactlessRichTransactionType | Rich transaction type.
|
| String | Merchant and location data from terminal.
**Deprecated** - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data.
|
**ContactlessTransactionRange**
| Value | Description
|
|---|
| LVT | Low value transaction |
| HVT | High value transaction
|
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| Value | Description |
|---|
| PURCHASE |
|
| REFUND |
|
| CASH |
|
| TRANSIT |
|
| PURCHASE\_WITH\_CASHBACK |
|
| UNKNOWN |
|
| WITHDRAWAL |
|
| ATM\_CONTACTLESS |
|
##### Report
| **Parameter** | **Type** | **Description** |
|---|
| name | String | Action name |
| description | String | Action details message. |
| isSuccess | Boolean | Result of action. True when action is finished successfully, false otherwise. |
| timestamp | Long | Time when the action occurred. |
| errorMessage | String? | Detailed error message when isSuccess is false. |
##### ContactlessAdvice
| **Parameter** | **Description** |
|---|
| DECLINE | Declines a processing transaction.
When provided by SDK in *getFinalDecisionForTransaction* wallet should not overrule a DECLINE.
If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response.
|
| AUTHENTICATION\_REQUIRED | An user authentication is required for transaction processing, which could be overruled on the MPA side.
When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the *onAuthRequiredForContactless* method.
|
| PROCEED | Transaction can be processed. |
##### ContactlessTransactionResult
**Important:** MPA should always refer to transaction results on the terminal.
| **Value** | **Description** | **Is success on MPA side**
|
|---|
| AUTHORIZE\_ONLINE | This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization.
The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal.
Should be treated as transaction success on the MPA side.
| Yes |
| 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 |
| 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 |
| 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 |
| If the *getFinalDecisionForTransaction* returns an AUTHENTICATION\_REQUIRED status then this result will be returned.
The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap.
If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place.
| No |
####
#### External libraries
The SDK uses several external Apache 2.0 libraries:
- com.nimbusds:nimbus-jose-jwt
- commons-codec:commons-codec
- com.fasterxml.jackson.core:jackson-core
- com.fasterxml.jackson.core:jackson-annotations
- com.fasterxml.jackson.core:jackson-databind
- com.fasterxml.jackson.module:jackson-module-kotlin
- io.insert-koin:koin-android
- io.reactivex.rxjava2:rxjava
- io.reactivex.rxjava2:rxandroid
- com.squareup.retrofit2:adapter-rxjava2
- com.squareup.retrofit2:retrofit
- com.squareup.retrofit2:converter
- com.squareup.okhttp3:logging
- com.squareup.okhttp3:okhttpSynchronous. Offline.
Contains all the necessary data to configure SDK.
Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method.
Requires MobileDC setup() already finished
Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished.
When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand.
**Important:** Before calling VCP SDK setup you must call setup from Mobile DC SDK.
Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment and loading first aplication screen.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| ucpConfiguration | UcpConfiguration | VCP configuration provided in builder described below.
| Not empty. |
**UcpConfigurationBuilder** contains the following methods:
| **Metod** | **Parameter** | **Description** | **Validation conditions**
|
|---|
| withApplication | Application | Application context. | Not empty |
| withCvmModel | WalletCvmModel (enum) | Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE
| Not empty |
| withUserAuthMode | WalletAuthMode (enum) | User authentication mode: WALLET\_PIN, CUSTOM, NONE
Contact Verestro to select proper configuration
| Not empty |
|
| UcpPaymentInstrument
EventListener
| Global listener for actions on PaymentInstrument.
| Not empty |
| UcpTransactionEventListener
| Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing
| Not empty |
| withTransactionAcceptance
EventListener | UcpTransactionAcceptance
EventListener | Global listener which allow application take final decision about transaction acceptance during transaction | Not empty |
| withReplenishThreshold | Int | Number of credentials below which replenish process will automatically begin
| Not empty |
| 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 | | Optional |
| withOptional
ExternalWalletServer |
| Prepares SDK for using external wallet server. | Optional |
| withOptional
UcpMcbpHttpExecutor | UcpMcbpHttpExecutor/
DefaultUcpMcbpHttpExecutor | Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. | Optional |
| withOptional
UcpReProvisionEventListener | UcpReProvisionEventListener | Global listener for actions during reprovisioning. | Optional |
| withOptional
UcpTransactionConfiguration
| UcpTransactionConfiguration
| Transaction configuration. Allow to enable deprecated authentication timer called when authentication is peformed.
Timer is disabled by default, usage is not recomended.
| Optional
|
| withOptionalWallet
McbpHttpExecutor |
| Prepares SDK for processing CMS-D HTTP requests with Wallet Server proxy.
| Optional |
| withOptionalEnableVisaSDK |
| Enables Visa SDK usage, requires gradle dependencies configuration
| Optional |
| withOptionalVtsPayment
ReadyCallback | UcpVtsPaymentAllowedListener | Provides information if payment with Visa Token is allowed with callback onPaymentAllowed().
Application should wait for callback when Visa Card is used. Receiving callback requires enabled internet connection. Can be switched anytime and SDK will detect connection change.
When connected internet connection is no more required until application close.
| Optional |
**UcpPaymentInstrumentEventListener**
Contains callbacks for PaymentInstrument.
| **Method name** | **Parameters** | **Description**
|
|---|
| onProvisioning
Success | paymentInstrument: PaymentInstrument
| Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below
|
| onProvisioning
Failure | errorMessage: String?,
exception: Exception?
| Method called after provisioning failure. Try processing digitization again
|
| onReplenish
Success | paymentInstrument: PaymentInstrument
numberOfTransactionCredentials: Int
| Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials.
Depending on flow is called after activation process and when requested by SDK based on *replenishThreshold* configuration.
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row
|
| onReplenish
Failure | paymentInstrument: PaymentInstrument,
errorMessage: String?,
exception: Exception?
| Method called after replenish failure with PaymentInstrument
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row
|
| onPayment
Instrument
StatusChanged | newStatus: PaymentInstrument
Status
paymentInstrumentId: String
| Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id
|
| onNewTransaction | newTransaction:
| Provides online result with details of transaction processed in VCP
Works only when application is online
|
**UcpTransactionEventListener**
Callbacks related to transaction process.
**Important:** It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| Method name | Parameters | Description
|
|---|
| onAuthRequired
ForContactless
| paymentInstrument: PaymentInstrument, transactionInformation:
ContactlessTransactionInformation
transactionData: ContactlessTransactionData
| Called when user authentication is required during contactless transaction
ContactlessTransactionInformation is deprecated in version 2.2.4.
|
| onAuthRequired
ForDsrp
| paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo
| Called when user authentication is required during Dsrp transaction
|
| onAuthTimer
Updated | secondsRemaining: Int | Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration.
Note: Deprecated and disabled by default in version 2.6.7.
To enable use configuration avaialble in SDK *setup::withOptionalUcpTransactionConfiguration.*
|
| onContactless
PaymentStarted
| \-
| Called on very beginnging of every transaction start (SELECT\_PPSE APDU command). E.g. first tap to terminal or second tap if *onAuthRequiredForContactless* method was called.
Locks communication until method is finished.
Method duration directly impacts on transaction time.
|
| onContactless
Payment
Completed
| paymentInstrument: PaymentInstrument
transactionInformation: ContactlessTransactionInformation
transactionResult: ContactlessTransactionResult
transactionData : ContactlessTransactionData,
transactionId:String
| Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
transactionId - transaction identifier for Mastercard transactions, allow to match transaction with processed transaction notification from Mobile DC SDK: *EventNewTransaction::clientTransactionId.*
|
| onContactless
Payment
Incident
| paymentInstrument: PaymentInstrument,
exception: Exception
| Called when something went wrong during transaction and Mastercard marked transaction as incident
|
| onContactless
Payment
Aborted
| paymentInstrument: PaymentInstrument?,
abortReason: TransactionAbortReason,
exception: Exception
| Called when transaction is aborted during payment from some reason described in method parameter
PaymentInstrument could be null if abortReason = TransactionAbortReason.NO\_CARDS is returned.
Note: SDK clears passed selected card with method *selectForPayment()* and authentication with *setUserAuthenticatedForPayment()*
|
| onTransaction
Stopped
|
| Method called on transaction stopped by SDK.
Deprecated in version 2.6.7, no longer used.
|
**UcpTransactionAcceptanceEventListener**
Callbacks related to transaction process.
**Important:** It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| **Method name** | **Parameters** | **Description**
|
|---|
| getFinal
Decision
ForTransaction
|
|
|
**UcpEventReportsListener**
| **Method name** | **Parameters** | **Description**
|
|---|
| onNewReport
| report: Report
| Return logs related to token management.
|
**UcpReProvisionEventListener**
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
| **Method Name** | **Parameters** | **Description** |
|---|
| onReProvisionSuccess | paymentInstrument: PaymentInstrument | Method called after reProvisioning process.
Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback.
|
| onReProvisionFailure | paymentInstrument : PaymentInstrument
errorMessage : String?
exception : Exception?
| Method called after reProvisioning failure. Try again.
|
**UcpMcbpHttpExecutor**
| Method name
| Parameters
| Description
|
|---|
| execute
| ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod:
UcpMcbpHttpMethod,
url: String,
requestData:Any,
requestProperties:
Map<String, String>
| Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
|
**DefaultUcpMcbpHttpExecutor**
| Method name
| Parameters
| Description
|
|---|
| execute
| ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType
ucpMcbpHttpMethod: UcpMcbpHttpMethod
url: String
requestData: Any
requestProperties: Map<String, String>
| Called on every time if SDK want to connect to MasterCard and should return super.execute method.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
|
**UcpTransactionConfiguration**
| Parameter
| Type
| Description
|
|---|
| enableTransaction
AuthenticationTimer
| Boolean
| Allows to enable deprecated authentication timer.
Timer is started along *setUserAuthenticatedForPayment(),* result is available in *onAuthTimerUpdated().*
|
****
**UcpTransactionEventListener**
| ```
// UcpTransactionEventListener comments
class BankingAppUcpTransactionEventListener : UcpTransactionEventListener {
override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and ContactlessTransactionData available in event object
showPaymentScreen(event.paymentInstrument, event.transactionData)
}
override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and DSRP transaction information available in event object
showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo)
}
override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) {
//check if user is on payment screen and update timer
//when timer is 0, application should close payment with failure
//deprcated, disabled by default, read method description how to enable
}
override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) {
//looks like payment is aborted, can provide result to payment screen
//and show user what is abort reason
}
override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) {
//payment completed, provide result to payment information
//REMEMBER Transaction is processed on terminal and this is where
//you will see final transaction result
}
override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) {
//something went wrong during transaction, provide result to user
}
override fun onTransactionStopped() {
//deprecated, not used anymore,
}
override fun onContactlessPaymentStarted() {
//Payment started or resumed after callback onAuthReqiredForContactless
//Best place for checking if user is authenticated for payment and call
//setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected
}
}
```
|
**UcpPaymentInstrumentEventListener**
| ```
class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener {
override fun onNewTransaction(event: EventNewTransaction) {
//information about new transaction processed by issuer
}
override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
//status of payment instrument was changed, refresh list, inform user about new status
}
override fun onProvisioningFailure(event: EventProvisioningFailure) {
//provisioning failed, try again
}
override fun onProvisioningSuccess(event: EventProvisioningSuccess) {
//provisioning success, wait for status and replenish changes until user can pay
//or provide activation method when required
}
override fun onReplenishFailure(event: EventReplenishFailure) {
//transaction credentials replenish failed
}
override fun onReplenishSuccess(event: EventReplenishSuccess) {
//transaction credentials replenish success
}
}
```
|
**UcpTransactionAcceptanceEventListener**
| ```
class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener {
//Sample implementation of transaction acceptance listener
//For the scanario when authentication is required on issuer side for every transaction
//field even.isUserAuthenticated must be always true, otherwise
//ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned
override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice {
val isScreenUnlocked = isScreenUnlocked()
val isScreenProtectedByKeyguard = isScreenUnlocked()
val isLvtTransaction =
event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT
//discard all Transit transaction
if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) {
return ContactlessAdvice.DECLINE
}
//allow for transaction when user is authenticated for payment and screen unlocked
if (event.isUserAuthenticated && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
//allow for LVT transaction on unlocked screen when protected and don't require authentication
if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
// ...
// much more cases
//require authentication anyway
return ContactlessAdvice.AUTHENTICATION_REQUIRED
}
}
```
|
**UcpEventReportsListener**
| ```
class BankReportEventListener : UcpEventReportsListener {
override fun onNewReport(report: Report) {
//may be used for debugging SDK or gathering reports on client's app or backend
}
}
```
|
**UcpMcbpHttpExecutor**
| ```
//Use UcpMcbpHTtpExecutor as supertype if you want to replace connection
class BankUcpMcbpHttpExecutor : UcpMcbpHttpExecutor {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
//invoke connect by custom connector
return when (ucpMcbpRequestType) {
UcpMcbpHttpExecutorRequestType.REQUEST_SESSION -> {
executeRequestSession(ucpMcbpHttpMethod, url, requestData as UcpMcbpRequestSessionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.PROVISION -> {
executeProvision(ucpMcbpHttpMethod, url, requestData as UcpMcbpProvisionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.REPLENISH -> {
executeReplenish(ucpMcbpHttpMethod, url, requestData as UcpMcbpReplenishRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.NOTIFY_PROVISIONING_RESULT -> {
executeNotifyProvisioningResult(ucpMcbpHttpMethod, url,
requestData as UcpMcbpNotifyProvisioningResultRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.CHANGE_MOBILE_PIN -> {
executeChangeMobilePin(ucpMcbpHttpMethod, url,
requestData as UcpMcbpChangeMobilePinRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.DELETE -> {
executeDelete(ucpMcbpHttpMethod, url, requestData as UcpMcbpDeleteRequestData,
requestProperties)
}
}
}
}
```
|
**DefaultUcpMcbpHttpExecutor**
| ```
//Use DefaultUcpMcbpHTtpExecutor as supertype if you want to only add some action before connection
class BankDefaultUcpMcbpHttpExecutor : DefaultUcpMcbpHttpExecutor() {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
return super.execute(
ucpMcbpRequestType,
ucpMcbpHttpMethod,
url,
requestData,
requestProperties
)
}
}
```
|
**UcpReProvisionEventListener**
| ```
class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() {
override fun onReProvisionSuccess(event: EventReProvisionSuccess) {
//reProvisioning success, wait for status and replenish changes until user can pay
}
override fun onReProvisionFailure(event: EventReProvisionFailure) {
//reProvisioning failed, try again.
}
}
```
|
**UcpTransactionConfiguration**
```
class BankingAppUcpTransactionConfiguration : UcpTransactionConfiguration {
override val enableTransactionAuthenticationTimer: Boolean = false
}
```
**UcpVtsPaymentAllowedListener**
```
class BankingAppUcpVtsPaymentAllowedListener : UcpVtsPaymentAllowedListener {
override fun onPaymentAllowed() {
//when during a payment an status of PAYMENT_NOT_ALLOWED is received
//Application UI should show transaction error and wait for onPaymentAllowed() callback
//When received callback shouuld inform UI to process transaction again
}}
```
**Sample VCP SDK setup implementation**
Mobile DC setup() and VCP setup() method could be called on MainThread in Application:onCreate as blocking or another thread.
When applicaiton has multiple dependencies there is possible to call both setup() methods on another thread (MobileDC setup() method must be already finished until VCP setup() is called).
Important: In case of loading SDK on another thread and using contactless payments HostApduService must be used asynchronous way to prevet using SDK until loading is finished - check sample for method *PaymentService:processHceApduCommand*.
| ```
fun setup(
application: Application,
walletCvmModel: WalletCvmModel,
walletAuthUserMode: WalletAuthUserMode,
mcbpPinningCertificates: List,
replenishThreshold: Int
) {
val ucpConfiguration = UcpConfiguration.create(
UcpConfigurationBuilder()
.withApplication(application)
.withCvmModel(walletCvmModel)
.withUserAuthMode(walletAuthUserMode)
//marked as deprecated - see description above
.withUcpTransactionEventListener(BankingAppUcpTransactionEventListener())
.withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener())
.withMcbpPinningCertificates(mcbpPinningCertificates)
.withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener())
.withReplenishThreshold(replenishThreshold)
.withOptionalEventsReports(BankReportEventListener())
.withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor())
//if you want to only add additional action before connection use below implementation
//.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor())
.withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener())
//if you want to change standard transaction configuration use configuration below
.withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration())
//.withOptionalEnableVisaSDK() //optional when Visa is used
//.withOptionalVtsPaymentReadyCallback(BankingAppUcpVtsPaymentAllowedListener()) //optional when Visa is used
)
UcpApiKotlin().setup(ucpConfiguration)
}
```
|
### reset (DEPRECATED - use restart instead)
Synchronous. Offline.
Method for resetting SDK to uninitialized state.
**NOTE:** According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. ****
|
**Input**
No input.
**Output**
No output.
**Sample**
**Sample VCP SDK reset implementation:**
| ```
fun reset() {
UcpApiKotlin().reset()
//Terminating JVM according to MC SDK Sample Application
Runtime.getRuntime().exit(0);
}
```
|
### restart
| Synchronous. Offline.
Method for resetting SDK to uninitialized state.
Replaces reset() method which requires killing application process.
When restart finishes with error, application should repeat action.
**NOTE:** SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again.
|
**Input**
No input.
**Output**
Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods.
Failure callback when something went wrong during restart. Application should repeat action.
|
**Sample**
**Sample VCP SDK reset implementation:**
| ```
UcpApiKotlin().restart({
//restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods
}, {
//some error occured, please repeat action
})
```
|
##
Cards domain
### delete
Asynchronous. Online.|
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with *onPaymentInstrumentStatusChanged*.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of PaymentInstrument to delete
| Not empty. |
| reason | CharArray? | Optional reason of deletion
|
|
**Output**
Success / failure callback
|
**Sample**
| ```
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.cardsService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
|
### checkEligibility
Asynchronous. Online.
Check eligibility required to process digitize.
|
**Input**
| **Parameter** | **Type** | **Description** |
|---|
| checkEligibility | CheckEligibility | CheckEligibility object
|
CheckEligibility
| **Parameter**
| **Type**
| **Description**
|
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\]
|
| userLanguage | String | User language |
| userCountry | String | User country |
**Output**
Success callback with CheckEligibilityResult.
|
CheckEligibilityResult
| **Parameter**
| **Type**
| **Description**
|
|---|
| termsAndConditionsAssetId | String | Identifier of Terms and Conditions asset
|
**Sample**
| ```
private fun checkEligibility(
paymentInstrumentId: String,
paymentInstrumentType: PaymentInstrumentType,
userLanguage: String,
userCountry: String
) {
ucpApi.cardsService
.checkEligibility(
CheckEligibility(
paymentInstrumentId,
paymentInstrumentType,
userLanguage,
userCountry
),
{ checkEligibilityResult ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### digitize
Asynchronous. Online.
Use only when *checkEligibility* method is used.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.
|
####
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| digitizationRequest | DigitizationRequest | Plain object of DigitizationRequest
| Not empty |
DigitizationRequest object contains following fields:
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\]
| Not empty |
| CharArray? | Optional. The CVC2 for the card to be digitized |
|
| String? | Optional. Unique external identifier of Payment Token |
|
####
**Output**
Success callback with DigitizationResult object
|
| **Parameter** | **Type** | **Description** |
|---|
| digitizationResult | DigitizationResult |
|
DigitizationResult contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Plain object of PaymentInstrument
|
| additionalAuthenticationMethods | List<AdditionalAuthenticationMethod>? | All available additional authentication method |
| productConfig | ProductConfig | Plain object of ProductConfig, contains Payment Token configuration |
| externalPaymentTokenId | String? | Optional. External payment token id configured by the consumer. In case of identifier duplicate an random id is generated |
ProductConfig contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| isCoBranded | Boolean | Whether the product is co-branded |
| coBrandName | String? | Name of the co-branded partner |
| foregroundColor | String | Foreground color, used to overlay text on top of the card image |
| backgroundColor | String | Background color, used to overlay text on top of the card image |
| labelColor | String? | Label color of the mobile wallet entry for the card |
| issuerName | String | Name of the issuing bank |
| shortDescription | String | A short description for this product |
| longDescription | String? | A long description for this product |
| custoremServiceUrl | String? | Customer service website of the issuing bank |
| customerServiceEmail | String? | Customer service email address of issuing bank |
| customerServicePhoneNumber | String? | Customer service phone number of the issuing bank |
| productConfigIssuer | ProductConfigIssuer? | Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app |
| onlineBankingLoginUrl | String? | Login URL for the issuing bank's online banking website |
| termsAndConditionsUrl | String? | URL linking to the issuing bank's terms and conditions for this product |
| privacyPolicyUrl | String? | URL linking to the issuing bank's privacy policy for this product |
| issuerProductConfigCode | String? | Freeform identifier for this product configuration as assigned by the issuer |
| contactName | String? | Name of the issuing bank |
| bankAppName | String? | Name of banking application for display |
| bankAppAddress | String? | The package name for the destination mobile application |
| unsupportedPresentationTypes | String? | The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request |
| unsupportedCardVerificationTypes | String? | The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) |
| issuerFlags | List<ProductConfigIssuerFlags>? | List of plain ProductConfigIssuerFlags object. Contains issuer flags |
| brandLogoAssetId | String | The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID |
| issuerLogoAssetId | String | The logo of the issuing bank. Provided as a Asset ID |
| coBrandLogoAssetId | String? | The co-brand logo (if any) for this product. Provided as an Asset ID |
| cardBackgroundCombinedAssetId | String? | The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID |
| cardBackgroundAssetId | String? | The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID |
| iconAssetId | String | The icon representing the primary brand(s) associated with this product. Provided as an Asset ID |
ProductConfigIssuer contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| openIssuerAndroidIntent | ProductConfigOpenIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| activateWithIssuerAndroidIntent | ProductConfigActivateWithIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| openIssuerIOSDeepLinkingUrl | ProductConfigOpenIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| activateWithIssuerIOSDeepLinkingUrl | ProductConfigActivateWithIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
ProductConfigOpenIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| deepLinkinUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| deepLinkingUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigIssuerFlags contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| deviceBinding | Boolean | Device binding |
| cardholderVerification | Boolean | Whether the issuer participating in step-up flow |
| trustedBeneficiaryEnrollment | Boolean | Whether this is a trusted beneficiary enrollment |
| delegateAuthenticationSupported | String | Whether issuer supports delegated authentication |
Sample
| ```
fun digitizeCard(digitizationRequest: DigitizationRequest) {
ucpApi.cardsService
.digitize( digitizationRequest,
{ digitizationResult ->
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
###
### digitize (deprecated)
Asynchronous. Online.
Deprecated - use digitize(DigitizationGreenPath) instead.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty. |
| userLanguage | String | Language preference selected by the consumer. Formatted as an
ISO-639-1 two letter language code
| Not empty. |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized
|
|
####
**Output**
Success / failure callback
|
#####
**Sample**
| ```
fun digitizeCard(
paymentInstrumentId: String,
languageCode: String,
securityCode: CharArray) {
ucpApi.cardsService
.digitize(paymentInstrumentId, languageCode, securityCode,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### digitize
Asynchronous. Online.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| digitizationGreenPath | DigitizationGreenPath | Plain object of DigitizationGreenPath
| Not empty |
DigitizationGreenPath contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized |
| userLanguage | String | User language |
| userCountry | String | User country |
| externalPaymentTokenId | String? | Optional. Unique external identifier of Payment Token |
**Output**
Success / failure callback
|
#####
**Sample**
```
fun digitizeCard(digitizationGreenPath: DigitizationGreenPath) {
ucpApi.cardsService
.digitize(digitizationGreenPath,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### getAdditionalAuthenticationMethods
Asynchronous. Online.
Retrieves additional user authentication methods.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| getAdditionalAuthenticationMethods | GetAdditionalAuthenticationMethods | Plain object of GetAdditionalAuthenticationMethods
| Not empty |
Fields of GetAdditionalAuthenticationMethods object:
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument |
####
**Output**
Success callback with AdditionalAuthenticationMethods object.
|
| **Parameter** | **Type** | **Description** |
|---|
| additionalAuthenticationMethods | AdditionalAuthenticationMethods | Object carrying list of AdditionalAuthenticationMethod |
AdditionalAuthenticationMethods contains following value:
| **Parameter** | **Type** | **Description** |
|---|
| additionalAuthenticationMethods | List<AdditionalAuthenticationMethod> | List of AdditionalAuthenticationMethod objects |
**Sample**
| ```
private fun getAdditionalAuthenticationMethods() {
val getAdditionalAuthenticationMethod =
GetAdditionalAuthenticationMethods("paymentInstrumentId")
ucpApi
.cardsService
.getAdditionalAuthenticationMethods(
getAdditionalAuthenticationMethod,
{ additionalAuthenticationMethods ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### submitTokenAuthenticationValue
Asynchronous. Online.
Submit authentication code when additional user authentication is required.
|
**Input**
| Parameter | Type | Description |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| authenticationCode | String | Authentication code |
####
**Output**
Success callback/failure callback.
|
#####
**Sample**
| ```
private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) {
ucpApi.cardsService
.submitAuthenticationValue(
SubmitAuthenticationValue(
paymentInstrumentId,
authenticationCode
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### submitTokenAuthenticationMethod
Asynchronous. Online.
Submit authentication method when additional user authentication is required.
|
**Input**
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| authenticationMethodId | String | Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. |
####
**Output**
Success callback/failure callback.
|
#####
**Sample**
| ```
private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) {
ucpApi.cardsService
.submitAuthenticationMethod(
SubmitAuthenticationMethod(
paymentInstrumentId,
authenticationMethodId
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getAllPaymentInstruments
Asynchronous. Online/Offline.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network and user session required) |
|
**Output**
Success callback with list of PaymentInstrument objects.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments from local or remote storage |
**Sample**
| ```
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.cardsService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
###
### getPaymentInstrument (deprecated)
Asynchronous. Online/Offline.
Deprecated - use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| paymentInstrumentId | String | Id of instrument to retrieve | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
Success callback with PaymentInstument object.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
**Sample**
| ```
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.cardsService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
##
## IBANs domain
###
### digitize
Asynchronous. Online.
Registers user and device if already not registered in VCP backend. Creates payment token in VCP backend.
Expect push after successfull finish and then proceed using process method in Cloud Messaging domain.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| signedAccountInfo | String | Signed AccountInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation
| Not empty. |
| fcmRegistrationToken | CharArray | FCM Cloud messaging registration token
| Not empty. |
| languageCode | String | Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code
| Not empty. |
**AccountInfo:**
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| userId | String | External user id
| Not empty. |
| iban | String | Bank Account Number | Not empty. |
| countryCode | String | The country of the financial account
Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1
| Not empty. |
**Output**
Success callback. Called when device token digitization finished with success .Result contains *IbanDigitizationResult* object.
Note: Cloud token digitization fail doesn't affect on success/failure callback.
|
IbanDigitizationResult contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| (DEPRECATED) cloudDigitizationSuccess | Boolean | Cloud Token Digitization Details |
| result | CloudDigitizationResult | Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN |
Failure callback. Called when **device token** digitization finished with failure.
|
**Sample**
Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
| ```
class SignedAccountInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("userId", "externalUserId")
.claim("iban", "IN15HIND23467433866365")
.claim("countryCode", "IND")
.build()
val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey)
// ...
}
```
|
| ```
fun digitizeIban(
signedAccountInfo: String,
fcmRegistrationToken: CharArray,
languageCode: String) {
ucpApi.ibansService
.digitize(signedAccountInfo, fcmRegistrationToken, languageCode,
{ ibanDigitizationResult ->
//Device token digitization finished with success
//wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success
val cloudDigitizationResult = ibanDigitizationResult.result
//check status of Cloud Token
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
###
### createTVC
Asynchronous. Online.
Provides Transaction Verification Code required to process cloud payments.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation
| Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)*
| Not empty. |
**Output**
Success callback with Tvc object or encrypted Tvc object as String.
|
| **Parameter** | **Type** | **Description** |
|---|
| plainTvc | PlainTvc? | Plain PlainTvc object
|
| encryptedTvc | CharArray? | Encrypted PlainTvc object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation
|
PlainTvc object contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| accountNumber | CharArray | Primary Account Number for the transaction – this is the Token PAN
|
| dynamicExpiryDate | CharArray | Dynamic expiration date for the token. Expressed in YYMM format
|
| dynamicCVC | CharArray | Dynamic CVC |
Failure callback when TVC cannot be created.
|
**Sample**
Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
| ```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
|
| ```
fun createTvc(signedIbanInfo: String) {
ucpApi.ibansService
.createTVC(signedIbanInfo, { tvc ->
//result object could contains encrypted TVC
val encryptedTvc: String? = tvc.encryptedTvc
//or decrypted(plain) TVC object with parameters described in documentation
val plainTvc = tvc.plainTvc
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### createPaymentData
Asynchronous. Online.
This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation
| Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)*
| Not empty. |
| userId | String | External user id given by the client | Not empty. |
**Output**
Success callback with object or encrypted payment data object as String.
|
| **Parameter** | **Type** | **Description** |
|---|
| plainPaymentData | PlainPaymentData? | Plain PlainPaymentData object
|
| encryptedPaymentData | String? | Encrypted PlainPaymentData object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation
|
PlainPaymentData object contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| accountNumber | String | Primary Account Number for the transaction – this is the Token PAN
|
| applicationExpiryDate | String? | Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format |
| panSequenceNumber | String? | Rrquired only for UCAF. Application PAN sequence number for the Token |
| track2Equivalent | String? | Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed |
| ucafCryptogram | String? | Required only for UCAF. UCAF cryptogram |
| dynamicExpiryDate | String? | Dynamic expiration date for the token. Expressed in YYMM format
|
| dynamicCVC | String? | Dynamic CVC |
Failure callback when PaymentData cannot be created.
|
**Sample**
**
| ```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.claim("userId", "123")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
|
| ```
fun createPaymentData(signedIbanInfo: String) {
ucpApi.ibansService
.createPaymentData(signedIbanInfo, { paymentData ->
//result object could contains encrypted PaymentData
val encryptedPaymentData: String? = paymentData.encryptedPaymentData
//or decrypted(plain) PaymentData object with parameters described in documentation
val plainPaymentData = paymentData.plainPaymentData
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### getAllPaymentInstruments
Asynchronous. Online/Offline.
Local storage is always instant available and should be used to incerese UX.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network required) |
|
**Output**
Success callback with list of PaymentInstrument objects
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments |
**Sample**
| ```
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.ibansService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getPaymentInstrument(deprecated)
Asynchronous. Online/Offline.
Use *getAllPaymentInstruments* instead.
Local storage is always instant available and should be used to incerese UX.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of instrument to retrieve. | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
Success callback with PaymentInstument object
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
**Sample**
| ```
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.ibansService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### delete
Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with *onPaymentInstrumentStatusChanged*.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| paymentInstrumentId | String | Id of PaymentInstrument to delete
| Not empty. |
| reason | CharArray? | Optional reason of deletion
|
|
**Output**
Success / failure callback
|
**Sample**
| ```
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.ibansService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
|
## Payment domain
### setDefaultForContactless
Asynchronous. Offline.
Sets payment instrument as default for contactless payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically after linking with PoS terminal.
Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
**Output**
Success / failure callback
|
**Sample**
| ```
fun setDefaultForContactless(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) {
//make sure selected PaymentInstrument can be seta as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForContactless(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
###
### getDefaultForContactless
Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.
|
**Input**
**Output**
Success callback with id new default PaymentInstrument
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Default Payment instrument |
**Sample**
| ```
fun getDefaultForContactless() {
ucpApi.paymentService
.getDefaultForContactless({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
|
### setDefaultForRemote (deprecated)
Asynchronous. Offline.
Sets payment instrument as default for DSRP payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically to remote payments.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
**Output**
Success / failure callback
|
**Sample**
| ```
fun setDefaultForRemote(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
&& !paymentInstrument.dsrpSupported) {
//make sure selected PaymentInstrument can be set as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForRemote(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### getDefaultForRemote (deprecated)
Asynchronous. Offline.
Provides default PaymentInstrument for remote payments.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.
|
**Input**
**Output**
Success callback with id new default PaymentInstrument
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Default Payment instrument |
**Sample**
| ```
fun getDefaultForRemote() {
ucpApi.paymentService
.getDefaultForRemote({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
|
### selectForPayment
Asynchronous. Offline.
Sets payment instrument as primary for next incoming payment.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentd | String | Payment instrument identity
| Not empty |
**Output**
Success / failure callback
|
**Sample**
**Note:** This is only sample payment scenation
|
| ```
//sample scenario of starting payment with authentication before payment
fun startPayment(paymentInstrument: PaymentInstrument) {
//checking conditions before payment
val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
val isContactlessSupported = paymentInstrument.contactlessSupported
val hasTransactionCredentials = paymentInstrument.credentialsCount > 0
if (!isActive || !isContactlessSupported || !hasTransactionCredentials) {
//PaymentInstrument doesn't meet requirements for payment
return
}
//selecting PaymentInstrument to payment
ucpApi.paymentService
.selectForPayment(paymentInstrument.id, {
//selection success
//request user authentication when
//... authentication presented
//use setUserAuthenticatedForPayment method
}, { throwable ->
//something went wrong, check exception with documentation
})
}
```
|
### setUserAuthenticatedForPayment
Asynchronous. Offline.
Sets user as authenticated to payment with provided payment instrument.
Authentication clearing depends on authentication timer configuration in *UcpTransactionConfiguration:enableTransactionAuthenticationTimer*.
By default timer is disabled and authentication is cancelled when user perform transaction and SDK send callback *onContactlessPaymentCompleted/Aborted/Incident* from *UcpTransactionEventListener*.
When timer is enabled authentication is cleared when auth timer finishes - it could casue problems when user start to pay just before timer finish. Authentication could be cleared by SDK during payement.
If application call *setUserAuthenticatedForPayment* without contactless payment context and authentication timer is disabled, authentication is never cleared by SDK. To clear authentication use *abortUserAuthenticationForPayment.*
*UcpTransactionEventListener:onContactlessPaymentStarted* is recommended place for payment authentication.
**Note:** User can be authenticated based on conditions like screen unlock. Method must be called before payment in method UcpTransactionEventListener:onContactlessPaymentStarted()
Make sure that authentication on this step is done securely. Transaction information is not available on this step.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
| pin | CharArray? | PIN or null for CUSTOM WalletAuthUserMode
|
|
**Output**
Success / failure callback
|
**Sample**
Basic user authentication usage below, call when user is authenticated.
| ```
private fun setUserAuthenticatedForPayment(
paymentInstrument: PaymentInstrument,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser,
{
//user authentication provided
//start one tap payment or continue two tap with 2nd tap to terminal after authentication
//listen for auth timer changes
//user abortUserAuthentication method when transaction cancelled by user
}, { throwable ->
//some error, check exception
})
}
```
|
Optional authentication before making transaction based on custom conditions.
| ```
override fun onContactlessPaymentStarted() {
//check internal conditions
//like user performed authentication, is logged in application, is device unlocked etc
val isUserAuthenticated = true
//check if use selected any token for payment and select it in UCP SDK
//otherwise default token will be used
if (getSelectedPaymentInstrumentId() != null) {
ucpApi
.paymentService
.selectForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
success = {
//token will be used for actual payment
//call setUserAuthenticatedForPayment here - sample below in "else" block
},
failure = { throwable ->
//something went wrong, check throwable with documentation
}
)
} else {
if (isUserAuthenticated) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
pin = null, //or pin if MobilePin is used
success =
//user authenticated in SDK
}, failure = {
//authentication failure, check exception
}
)
}
}
}
```
|
### abortUserAuthenticationForPayment
Asynchronous. Offline.
Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped.
|
**Input**
**Output**
Success / failure callback
|
**Sample**
| ```
fun abortUserAuthenticationForPayment() {
ucpApi
.paymentService
.abortUserAuthenticationForPayment(
{
//user authentication aborted
//listen for auth timer changes
},
{ throwable ->
//some error, check exception
})
}
```
|
### processHceApduCommand
Synchronous. Offline.
Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS.
Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| context | Context | Application context, can be provided from HostApduService
| Not empty |
| apdu | ByteArray | APDU command from HostApduService::processCommandApdu method parameter
| Not empty |
| extras | Bundle? | Extras object from HostApduService::processCom mandApdu method parameter
|
|
**Output**
Apdu result - method called synchronous without callback
|
| **Parameter.** | **Type** | **Description** |
|---|
| apdu | ByteArray | APDU command to return in implementation of overridden processCommandApdu method
|
**Sample (synchronized HostApduService)**
Use this version if MobileDC:setup and UCP:setup() method is called in Application:onCreate on Main Thread.
| ```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(this, commandApdu, extras)
}
//..
}
```
|
**Sample (aynchronous HostApduService)**
Use this version if SDK is called on another thread and HostApduService can receive APDU until VCP SDK is still in loading state.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
//UcpSdkStateApplicationSingleton is sample class which keep SDK state and allow to observe when SDK load is finished
if (UcpSdkStateApplicationSingleton.isLoaded()) {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
} else {
sendResponseApdu(null)
UcpSdkStateApplicationSingleton.listenForSdkReady(
onSdkLoadListener = {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
}
)
}
return null
}
override fun onDeactivated(reason: Int) {
if (UcpSdkStateApplicationSingleton.isLoaded()) {
return ucpApi
.paymentService
.handleHceApduDeactivationEvent(reason)
}
}
private fun processCommandApduInUcpSdk(
context: Context,
commandApdu: ByteArray,
extras: Bundle?
): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(context, commandApdu, extras)
}
}
//sample objec which helps to listen SDK state
object UcpSdkStateApplicationSingleton : UcpSdkState {
//flag could be synchronized
private var isLoaded = false
private var onSdkLoadListener: (() -> Unit)? = null
override fun listenForSdkReady(onSdkLoadListener: () -> Unit) {
this.onSdkLoadListener = onSdkLoadListener
if (isLoaded) this.onSdkLoadListener?.invoke()
}
//call when SDK loading thread is finished
//setupMdc() -> setupUcp() -> UcpSdkStateApplicationSingleton.onUcpSdkLoaded()
override fun onUcpSdkLoaded() {
isLoaded = true
onSdkLoadListener?.invoke()
}
override fun isLoaded(): Boolean {
return isLoaded
}
}
```
### replenishCredentials
Asynchronous. Online. User login session not required.
Method for manually replenishing payment credentials.
Application will receive push notification and notified about replenish process with global callback described in *setup* chapter.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of paymentInstrument that needs it credentials replenished
| Not empty |
**Output**
Success / failure callback
|
**Sample**
| ```
fun replenishCredentials(paymentInstrumentId: String) {
ucpApi.paymentService
.replenishCredentials(paymentInstrumentId,
{
//request for credentials replenish finished with success
//wait for push notification and pass to valid module
//when push processed application will be informed about replenish success/failure
//read chapter with setup for more information
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### restartContactlessAuthTimer
Asynchronous. Offline.
Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile.
Default auth time is provided by card profile.
|
**Input**
**Output**
Success / failure callback
|
### requestAuthenticationCodeForPayment
Asynchronous. Online.
Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| requestAuthenticationCodeForPayment | RequestAuthenticationCodeForPayment | Plain RequestAuthenticationCodeForPayment object
| Not empty |
RequestAuthenticationCodeForPayment object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| authenticationRequestId | String | Authentication request id up to 64 alphanumeric characters long.
A new id should be used for each instance than an account holder needs to be authenticated | Not empty |
**Output**
Success callback/failure callback.
|
**Sample**
| ```
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) {
ucpApi.paymentService
.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//Requesting Authentication Code went successfully.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### validateAuthenticationCodeForPayment
Asynchronous. Online.
Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| validateAuthenticationCodeForPayment | ValidateAuthenticationCodeForPayment | Plain ValidateAuthenticationCodeForPayment object
| Not empty |
ValidateAuthenticationCodeForPayment object contains following fields
| Parameter | Type | Description | Validation conditions |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| authenticationRequestId | String | Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. | Not empty |
| authenticationCode | String | Authentication Code to authenticate the account holder | Not empty |
**Output**
Success callback with ValidateAuthenticationCodeForPaymentResult object.
|
ValidateAuthenticationCodeForPaymentResult object contains following field
| **Parameter** | **Type** | **Description** |
|---|
| signedAuthenticationProcessData | String | Signed AuthenticationProcessData per RFC 7519
|
AuthenticationProcessData model
| **Parameter** | **Type** | **Description** |
|---|
| authenticationRequestId | String | Authentication request id
|
**Sample**
| ```
fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) {
ucpApi.paymentService
.validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment,
{ validateAuthenticationCodeForPaymentResult ->
//ValidateAuthenticationCodeForPaymentResult plain object,
//contains data to validate on backend
val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult
.signedAuthenticationProcessData
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)
| ```
class SignedAuthenticationProcessData {
fun verifyAndGetAuthenticationRequestID() {
val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600);
val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId")
// ...
}
}
```
|
### processDsrpTransaction(deprecated)
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | |
|
**Output**
Success callback with cryptogram for payment
|
### processDsrpTransaction
Asynchronous. Offline.
Method dedicated for starting DSRP transaction.
Every DSRP transaction has to be authenticated before processing.
Depending on implementation payment can be process with OTP authentication or device level authentication.
|
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| processDsrpTransaction | ProcessDsrpTransaction | Plain ProcessDsrpTransaction object
| Not empty |
ProcessDsrpTranasction object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | Plain DsrpTransactionInfo object | Not empty |
DsrpTransactionInfo object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| amountMinor | Long | A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 | Not empty |
| currencyCode | String | A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. | Not empty |
| countryCode | String? | A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. |
|
| issuer
Cryptogram
Type | DsrpIssuer
Cryptogram
Type | Enum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. | Not empty |
| unpredictable
Number | Long
| A long representing the random number generated by the merchant or by the Payment Gateway. The maximum value is 4,294,967,295. | Not empty |
| transactionType
| Dsrp
Transaction
Type
| A type of financial transaction, one of: PURCHASE, CASH, PURCHASE\_WITH\_CASHBACK, REFUND
| Not empty |
| transactionDate
| Date?
| A Date object indicating date of transaction. |
|
**Output**
Success callback with ProcessDsrpTransactionResult object.
|
ProcessDsrpTransactionResult object contains following field
| **Parameter** | **Type** | **Description** |
|---|
| transaction
Cryptogram
Data | ByteArray | A byte array containing a formatted response, either UCAF or a set of TLV data for the merchant to populate DE55 data.
|
| pan
| String
| String containing the PAN of the card used.
|
| panSequence
Number | Int
| An integer value specifying the PAN Sequence Number (PSN) of the card used.
|
| cryptogramType | DsrpIssuer
Cryptogram
Type | Enum value as UCAF or DE55 depending on cryptogram data format is used.
|
| track2Data
| String
| String containing the data elements of track 2 according to ISO/IEC 7813.
|
| par
| String
| String representation of byte array of permanent account reference. A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens.
|
| expirationDate
| String
| Date in ISO-8601 (YYYY-MM-DD) format indicating expiry date of the card.
|
| transactionId
| String
| Hexed byte array containing a Transaction Identifier.
|
| **DsrpPaymentException.reason** | **Description** |
|---|
| DSRP\_INVALID\_INPUT | Invalid input data.
|
| DSRP\_UNEXPECTED\_DATA
| Provided data is valid in context of validation, but doesn't mee
|
| DSRP\_AUTHENTICATION\_REQUIRED | Authentication is not provided for DSRP payment. Authenticate and process DSRP transaction again.
|
| DSRP\_TOKEN\_INACTIVE
| Token used for DSRP is inactive.
|
| DSRP\_NO\_TRANSACTION\_CREDENTIALS | There is no transaction credentials to procees DSRP payment
|
| DSRP\_NOT\_SUPPORTED\_BY\_CARD | DSRP is not suported by Card.
|
| DSRP\_TRANSACTION\_DECLINED
| Transaction is declined by Card.
|
| DSRP\_INCOMPATIBLE\_PROFILE
| Card profile is incomaptible with DSRP.
|
| DSRP\_WRONG\_STATE
| DSRP transaction is in wrong state.
|
| DSRP\_INTERNAL\_ERROR
| Unknowne error during DSRP processing.
|
| ```
// After Merchant App delivers DSRP data application should authenticate user with device level authentication
// and next execute setUserAuthenticationForPayment().
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTranasctionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
**Sample DSRP transaction with OTP authentication**
| ```
// After Merchant App delivers DSRP data user should request authentication
// code for payment with selected paymentInstrument.
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment =
RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId)
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) {
ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//When requesting went successfully User will get authentication code.
//In next step authentication code should be passed to MPA and application
//should validate this code with validateAuthenticationCode() method
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
val validateAuthenticationCode: ValidateAuthenticationCode =
ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser)
fun validateAuthenticationCode(validateAuthenticationCode) {
ucpApi.paymentService
.validateAuthenticationCode( validateAuthenticationCode,
{ validateAuthenticationCodeResulty ->
//ValidateAuthenticationCodeResult plain object
val signedAuthenticationProcessData = validateAuthenticationCodeResulty
.signedAuthenticationProcessData
//If validation went successfully MPA should show authentication view,
//and after valid authentication MPA should execute setUserAuthenticatedForPayment()
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTransactionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
**Sample input and output DSRP data:**
```Java
Input:
amountMinor: 4321,
countryCode: 840,
currencyCode: 840,
issuerCryptogramType: UCAF,
transactionDate: Apr 25, 2023 09:41:05, //Date() toString() format
transactionType: PURCHASE,
unpredictableNumber: 29496729
Output:
pan: 5204830959972699
track2Data: 5204830959972699D26052010000000000000
expirationDate: 2026-05-31 //YYYY-MM-DD
par: 500170A4PEV2GLWPFD00N6H5AX2YB
panSequenceNumber: 0
transactionId: df25a522a075680acbaa407fdc8a0348a321f77afa2f0231cd38f28e7ae691e2
cryptogramType: UCAF
transactionCryptogramData: 414d506a6d4a474650306149414155427768575a47674144464b553d //in Hex
```
## Cloud messaging domain
### process (deprecated in 2.6.7)
Asynchronous. Online. User login session not required.
Processes data sent by VCP backend (push notification data).
Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method.
Method can throw InvalidPushException in case of invalid push content passed to it.
Refer Mobile DC documentation how to handle push.
Deprecated in 2.6.7, use MobileDC:CloudMessaging:process() instead.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| pushData | Map<String, String> | Data received from notification service in object RemoteMessage object
| Not empty |
**Output**
Success / failure callback. When request fails try again
|
**Sample**
| ```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map) {
ucpApi
.cloudMessagingService
.process(pushData, {
//push processed in Mobile DC
}, {
//some error
})
}
```
|
### processMcbpNotificationData
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| encryptedPayload | String | Data received from notification service in object RemoteMessage object
| Not empty |
**Output**
Success / failure callback
|
| ```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String? = remoteMessage.from
val pushData = remoteMessage.data
//check push source based on senderId
if (isVerestroSenderId(senderId)) {
val verestroPayload: String = readVerestrpPushContent(pushData)
ucpApi
.cloudMessagingService
.processMcbpNotificationData(verestroPayload, {
//push processed in VCP
}, {
//some error
})
} else {
//proceed push from another source
}
}
```
|
## External Wallet Server domain
Chapter contains method for SDK when External Wallet Server is used.
Usage of method requires additional configuration with external API.
Basic MDES cloud messaging configuration:
| **Environment** | **FCM Sender Id** |
|---|
| MTF | 502118574555 |
| PRODUCTION | 993764297204 |
### prepareRegistrationData
Asynchronous. Offline.
Method for preparing data used for activation.
Should be used before calling register method.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentAppInstanceId | String | Identifier for the specific Mobile Payment App instance | Not empty |
| paymentAppProviderId | String | Globally unique identifier for the Wallet Provider, as assigned by MDES | Not empty |
| String | CMS-D public key certificate in pem format | Not empty |
| mobilePin | CharArray? | Mobile PIN used to payment confirmation
|
|
**Output**
Success callback with PrepareRegistrationResponse object.
|
| **Parameter** | **Type** | **Description** |
|---|
| String | CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) |
| encryptedRgk | String | Encrypted randomly-generated 128-bit AES key. |
| EwsDeviceInfo | Device info. |
| deviceFingerprint | String | Unique device fingerprint. |
| encryptedPin | String? | Encrypted pin (if passed in input). |
model:
| **Parameter** | **Type** | **Description** |
|---|
| deviceName | String | Device model name. |
| formFactor | String | The form factor of the target provisioned device. |
| storageTechnology | String | The architecture or technology used for token storage. |
| osName | String | The name of the operating system of the target provisioned device. |
| osVersion | String | The version of the operating system of the target provisioned device. |
| nfcCapable | Boolean | Whether the target provisioned device has NFC capability.
|
**Sample**
| ```
fun prepareRegistrationData(
paymentAppInstanceId: String,
paymentAppProviderId: String,
publicKeyCertificate: String,
mobilePin: CharArray?) {
ucpApi
.ewsService
.prepareRegistrationData(paymentAppInstanceId,
paymentAppProviderId,
publicKeyCertificate,
mobilePin,
{ prepareRegistrationResponse ->
//Prepared data for registration including encryptedMobilePin if mobilePin is used
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### register
Asynchronous. Online.
Method used for registration new Mobile Payment App instance with MDES for use.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| mobileKeysetId | String | Identifies the Mobile Keys used for this remote management session
| Not empty |
| ewsMobileKeys | EwsMobileKeys | Contains the mobile keys used to secure the communication during subsequent remote management sessions
| Not empty |
| remoteManagementUrl | String | The URL endpoint for subsequent remote management sessions
The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions
| Not empty |
| **Parameter** | **Type** | **Description** |
|---|
| transportKey | String | The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES
|
| macKey | String | The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES
|
| dataEncryptionKey | String | The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES
|
**Output**
Success / failure callback
|
****
| ```
fun register(
mobileKeysetId: String,
ewsMobileKeys: EwsMobileKeys,
remoteManagementUrl: String) {
ucpApi
.ewsService
.register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl,
{
//Device registration success
//application should listen to push messages and UcpPaymentInstrumentEventListener callbacks
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### activate
Asynchronous. Online.
Method to PaymentInstrument.
Should be used only on PaymentInstrumens which PaymentInstrumentStatus is .
Changes PaymentInstrumentStatus to , calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available.
Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| String | Id of paymentInstrument to activate. | Not empty. |
**Output**
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
}
)
}
```
|
### suspend
Asynchronous. Offline.
Method for suspending paymentInstrument.
Changes PaymentInstrumentStatus to .
Use activate method to allow payments again.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of paymentInstrument to suspend. | Not empty. |
**Output**
Success / failure callback
|
****
| ```
fun suspend(paymentInstrumentId: String) {
ucpApi
.ewsService
.suspend(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to SUSPENDED.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getPaymentInstrument
Asynchronous. Offline.
Method for getting single PaymentInstrument from local storage object based on id.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of paymentInstrument to get.
| Not empty. |
**Output**
Success callback with PaymentInstrument object.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Retrieved paymentInstrument |
**Sample**
| ```
fun getPaymentInstrument(paymentInstrumentId: String) {
ucpApi.ewsService
.getPaymentInstrument(paymentInstrumentId,
{ paymentInstrument ->
//PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getAllPaymentInstruments
Asynchronous. Offline.
Method for getting all payment instruments from local storage.
|
**Input**
**Output**
Success callback with list of PaymentInstrument objects.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments from local storage |
**Sample**
| ```
fun getAllPaymentInstrument() {
ucpApi.ewsService
.getAllPaymentInstruments(
{ paymentInstruments ->
//List of PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getEncryptedPin
Asynchronous. Offline.|
Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| pin | CharArray | PIN to encrypt. | Not empty. |
**Output**
Success callback with encrypted mobile PIN.
|
| **Parameter** | **Type** | **Description** |
|---|
| encryptedMobilePin | String | Hex encoded encrypted mobile PIN. |
**Sample**
| ```
fun getEncryptedPin(pin: CharArray) {
ucpApi
.ewsService
.getEncryptedPin(pin, { encryptedPin ->
//call to Wallet Server with new created encrypted mobile PIN
//when updated call onMobilePinChanged method
}, {
//Something went wrong, check exception with documentation
})
}
```
|
### onMobilePinChanged
Asynchronous. Online.
.
Should be used when mobilePin changed.
|
**Input**
**Output**
Success / failure callback
|
**Sample**
| ```
fun reactOnMobilePinChanged() {
ucpApi
.ewsService
.onMobilePinChanged(
{
// Informing SDK about changing mobile pin processed succesfully.
// SDK should delete and next replenish transaction credentials.
// Listen for UcpPaymentInstrumentEventListener events
}, { throwable ->
// Something went wrong, check exception with documentation.
})
}
```
|
### delete
When success PaymentInstrument will be no longer available in *getPaymentInstrument* and *getPaymentInstruments* methods.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| String | Id of paymentInstrument to delete. | Not empty. |
**Output**
Success / failure callback
|
****
| ```
fun delete(paymentInstrumentId: String) {
ucpApi
.ewsService
.delete(paymentInstrumentId,
{
//Selected Payment instrument is removed
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
## Assets Domain
### getAsset
Asynchronous. Online.
Method for getting all assets for selected assetId.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| assetId | String | Id of assets to retrive | Not empty |
**Output**
Success callback with list of Assets objects.
|
| **Parameter** | **Type** | **Description** |
|---|
| ucpAsset | UcpAsset | Plain UcpAsset object |
UcpAsset object contains following field
| **Parameter** | **Type** | **Description** |
|---|
| content | List<UcpAssetContent> | Plain list of UcpAssetContent objects |
UcpAssetContent contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| data | String | The data for this asset. Base64-encoded data, given in the format as specified in type. |
| type | String | The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. |
| width | Long? | For image assets, the width of this image. Specified in pixels. |
| height | Long? | For image assets, the width of this image. Specified in pixels. |
**Sample**
| ```
fun getAsset(assetId: String) {
ucpApi.assetsService
.getAssets( assetId,
{ ucpAsset ->
//List of assets of selected assetId
val ucpAssetContentList = ucpAsset.content
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
## DOCUMENT CHANGELOG
Vesion 2.10.12
- **IMPORTANT: Mobile DC dependency can no longer be declared as saperate dependency in the same application when UCP is declared. MDC will be available as default.**
- UCP is now built as a [fused library](https://developer.android.com/build/publish-library/fused-library)
- Updated Mobile DC to 2.17.5
- Updated AGP to 9.0.1
- Updated Gradle to 9.3.1
Vesion 2.10.10
- Added new field for digitization: *formFactor*
- Mobile DC updated to 2.17.3
Vesion 2.10.0
- Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes)
- Security tools updated to newest version
- Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22)
- AGP updated to 8.11.1
- Mobile DC updated to 2.17.0
Version 2.9.10
- Added new parameter *transactionId* to method *onContactlessPaymentCompleted* for Mastercard transactions.
New transaction identifier allow to match transaction with processed transaction notification *MobileDC::EventNewTransaction::clientTransactionId.*
- Mobile DC updated to 2.16.12
Version 2.9.8
- **IMPORTANT: Security tools updated to newest version. Recommneded update when using version 2.9.x due to changes fixes in security tools.**
- Visa SDK updated to 6.4.0
- Mobile DC updated to 2.16.10
Version 2.9.5
- Added MC *mtf* host name
- Update Mobile DC to 2.16.5
Version 2.9.4
- **Important:** Apply security and functional certification changes related to intruduction new security tools. Changes in security thread management and working in background
- Update Mobile DC to 2.16.4
Version 2.8.7
- Update Mobile DC to 2.15.8
Version 2.8.6
- Small fixes to 2.8.5
Version 2.8.5
- Update Proguard rules related to R8 changes
Version 2.8.2
- Added new field "externalPaymentTokenId" in DigitizationGreenPath, DigitizationRequest and DigitizationResult models.
- Added new optional configuration withOptionalWalletMcbpHttpExecutor
- Marked configuration withUcpTransactionEventListener from UcpConfigurationBuilder as deprecated. Use MobileDcTransactionEventListener.optionalMobileDcTransactionEventListener from MDC SDK instead.
Version 2.7.4
- Added new field "paymentTokenExpirationDate" in PaymentInstrument model.
Version 2.7.3
- update MobileDC dependency to 2.15.3
Version 2.7.1
- update MobileDC dependency to 2.15.1
Version 2.7.0
- update MobileDC dependency to 2.15.0
Version 2.6.9.2
- update MobileDC dependency to 2.14.7.2
Version 2.6.9.1 - Hotfix possible OutOfMemoryException in MDC 2.14.7
- update MobileDC dependency to 2.14.7.1
Version 2.6.9 - don't use, could cause OOM Exception
- Updated Mobile DC dependency to 2.14.7.
- Updated *processDsrpTransaction* method.
Version 2.6.7
- Updated Mobile DC dependency to 2.14.6
- Added support for Mastercard India datacenter.
- **important** Added new method to UcpTransactionEventListener - *onContactlessPaymentStarted()***.** Callback allows application to get event about new transaction and it's a best place for token selection and user authentication. Read more in Product Overview.
- Due to adding new place for contactless payment authentiocation also updated code samples for *HostApduSevice* implementation and method *setUserAuthenthenticatedForPayment()*
- **Important** CloudMessagingService:process became deprecated due to introducing delivery message from server service. Read more in Product Overview and Mobile DC specification.
- **Important** Added new status *AbortReason:CONNECTION\_LOST* for *UcpTransactionEventListener:onContactlessPaymentAborted.* Status TERMINAL\_INACTIVITY\_TIMEOUT became deprecated. Change significally improves contactless payment UX. Method works immediatelly when connection between device and terminal is lost.
- **Important** Aded new optional configuration for *UcpTransactionConfiguration* with field *enableTransactionAuthenticationTimer.* Timer is now disabled by default, previously was always enabled and could cause problems when authentication time leading to zero and user performs transaction. It could cause clearing user authentication during processing payment on terminal. Change is related to other payments optimizations and introducing *onContactlessPaymentStarted()* and new *AbortReason CONNECTION\_LOST.* Please align your code to new changes, enabling timer is not recommended.
- Updated Mobile DC dependency to 2.13.7
- Resolved Google Play Console Security warning
- Updated Mobile DC dependency to 2.13.6
Version 2.5.5
- Wrap in try-catch block callbacks from SDK *setup()* method to prevent breaking process in SDK. Read more in *setup*() method description.
Version 2.5.3
- Update internal libraries. **IMPORTANT** Read more in Mobile DC changelog for version 2.13.3
Version 2.5.2
- Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality
Version 2.5.1
- Methods marked as deprecated:
- reset (use restart instead)
- getPaymentInstrument (use getAllPaymentInstruments instead)
- setDefaultForRemote (usage is redundant)
- getDefaultForRemote (usage is redundant)
- processDsrpTransaction(use new processDsrpTransaction method with *ProcessDsrpTransaction* added model)
- Added new methods related to OTP authentication code:
- requestAuthenticationCodeForPayment
- validateAuthenticationCodeForPayment
- Added new methods for supporting yellow-path token activation:
- checkEligibility
- digitize (new version with support for checkEligibility usage)
- submitTokenAuthenticationMethod
- submitTokenAuthenticationValue
- getAdditionalAuthenticationMethods
- Fixed getPaymentInstrument method (case invalid error when session expired error occurred).
- Updated Kotlin version to 1.5.31 and Koin to 2.1.6.
- Removed unused permissions *ACCESS\_FINE\_LOCATION* and *com.google.android.c2dm.permission.RECEIVE .*
- Added logs for all facade methods (available in SDK debug version).
Version 2.4.4
- Updated MDC SDK to 2.12.1 - fixed aggressive security process check
- Updated documentation for TransactionAbortReason:TERMINAL\_INACTIVITY\_TIMEOUT model
Version 2.4.3
- IMPORTANT Update security tools after EMV Security Evaluation - refer to Mobile DC technical documentation version changelog (version 2.12.0)
- Update Gradle and R8 tools
- Handled authentication flow for ContactlessRichTransactionType REFUND. SDK requires authentication if not provided.
- Improved description for ContactlesssTransactionResult model in documentation.
- Added new ContactlessRichTransactionType: WITHDRAWAL and ATM\_CONTACTLESS
Version 2.3.24
- Added new state for TransactionAbortReason::TERMINAL\_INACTIVITY\_TIMEOUT. Previously status was part of TransactionAbortReason::TERMINAL\_ERROR and produces contactless payment aborted handling problems. Status is used in onContactlessPaymentAborted callback. Application can ignore this state and do not perform any action.
- Added method on UcpApi for SDK restart(). Unlike reset() new method is asynchronous and allows to usage VCP SDK without application kill. Method clears all VCP SDK data and restarts to initial state.
- Introduced new approach to handling security issue. When application will call any SDK method after security issue reporting, UcpSkdExpcetion with SECURITY\_EVENT\_OCCURRED will be returned. Previously APPLICATION\_PROCESS\_NOT\_KILLED was returned. Change doesn't impact onSecurityIssue callback.
- Added Assets Domain and getAsset() method.
- Added verification of input parameters in token profile and transaction credentials replenish.
- Added more details in callbacks onProvisioningFailure and onReplenishFailure about errors in token related operations.
Version 2.3.22.2 - hotfix
- Added more validation for input parameters for External Wallet Server service
- Added data verification before accessing data in CMS-D processes
- Improved catching exceptions for MCBP processes
- Improved flow for reset() method - added protection agains processing messaging after SDK reset()
- Changed algorithm for calculating publicKeyCertificateFingerprint in PrepareRegistrationDataResponse. From hex(sha1(certificate.publicKey.encoded)) to hex(sha1(certificate.encoded))
- Added support for multiple calling setUserAuthenticatedForPayment() method
Version 2.3.22
- Improved internal SDK logs reporting
- Using androidX in end project is necessary now
- Improved automatic replenish credentials process
- Added handling ReDigititzation process in SDK. Use withOptionalReProvisionEventListener method in SDK setup method to observe PaymentInstrument changes
Version 2.3.21
- Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration
- Replenish process optimization
Version 2.3.18
- Updated security libraries
Version 2.3.17
- Fixed parsing merchantAndLocation field from ContactlessTransactionData.
- Added EWS configuration parameter in setup.
Version 2.3.13
- Added new parameter *result* to IbanDigitizationResult model
- Parameter *cloudDigitizationSuccess* in IbanDigitizationResult is now deprecated
Version 2.3.12
- Core module with update.
- Added new reports to Wallet Server.
Version 2.3.11
- Added new method in Payment Service: processDsrpTransaction
- Added new method in User Service: resendOtp
- Added new paremeter in createPaymentData IbanInfo model: userId
- Improved default PaymentInstrument management
- Fixed clearing SDK state when unpairing device (MobileDC unPair method)
Version 2.3.8
- Improved facade exception throwing, now contains more details about error.
- Removing whitespaces from merchantAndLocation in ContectlessTransactionData model
- Updated security harmful process check mechanism
- Added MCBP cloud messaging queue handling to prevent processing errors
Version 2.3.2
- Fixed SDK provisionning process on Google Pixel devices
- Improved default Payment Instrument management
- Updated security harmful process check mechanism
Version 2.3.1
- Added *delete* method in External Wallet Server domain
- Added more detailed descriptions for methods from External Wallet Server domain
- Added more information about models related to payment processing
Version 2.2.7
- Added reset functionality.
- Addded method in Ibans service createPaymentDat.
- Method createTVC iban service is now deprecated.
- Added global listener for most important internal SDK actions related to token managem
Version 2.2.6
- Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure
- Fixed problem with flow cutting on digitalization process
Version 2.2.4
- Added new enum state TransactionAbortReason.NO\_CARDS. Callback onContactlessPaymentAborted is now called when no card is available for payment.
- Added new model ContactlessTransactionData with better formatting terminal data. New object is added for events EventGetFinalDecision, EventAuthRequiredForContactless, EventContactlessPaymentCompleted.
- ContactlessTransactionInformation is now deprecated.
- Fixed setting default PaymentInstrument after activation
- Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status
Version 2.2.2
- Fixed dependencies conflicts
- Consumer Proguard rules update
-
Version 2.2.0
- Added new method in EWS Service - getEncryptedPin
- SDK startup optimization
- Fixed dependencies for release version
- Added information about SDK size
- Added information about SDK integration on lower Android API level
Version 2.1.0
-
Version 2.0.0
- Changed approach to SDK setup
- Added UcpSdkException
- Added new reason codes to existing exceptions
- New methods in cards domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in ibans domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in cloud messaging domain: processMcbpNotificationData
- New methods in payment domain: abortUserAuthenticationForPayment, replenishCredentials, restartContactlessTimer
- New methods in external wallet server domain: prepareRegistrationData, register
Version 1.0.1
- Created
# New Page
# Token Requestor / Issuer wallet
NFC Issuer Wallet with Mobile SDK. Mastercard MCBP 2.1 SDK and Visa VTS SDK.
Due to the rename UCP and VCP are used interchangeably.
# Article
You can find more knowledge about products on this site.
# Issuer Wallet and Apple Pay / Google Pay - Differences
As we have implemented more than 50 contactless and tokenization projects for banks, fintechs and other payment institutions, let me share a quick view on key differences between various types of contactless payment technologies.
##### X-Pays
If you are a card issuer in today's world, you usually need to implement **Apple Pay** and **Google Pay** to let your users benefit from various payment activities on mobile phones. We think it is obligatory in today's world for standard card use cases. The power of Apple and Google is so strong that avoiding these platforms really impacts your customers.
In general, implementation of these technologies is not difficult. If you use our [**Token Management Platform**](https://developer.verestro.com/books/token-management-platform), implementation time can be reduced to weeks. Additionally, you have to sign contracts with Apple and Google. In the case of Apple, they charge additional fees for registering a card at Apple Pay. In the case of Google, they collect all transactions of your users to earn money on advertisement and data management. These are key disadvantages. In both cases you have to follow their requirements and changes, but if you cooperate with certified providers, you do not have problems with this, as a processor can solve these problems on your behalf.
Both Google and Apple solutions enable contactless, inApp and eCommerce payments on their browsers. The non-contactless payment transactions are an important part of these projects. You should focus not only on contactless payments.
It is worth mentioning that implementation of tokenization usually gives you access to other **X-Pays** like Fitbit Pay, Garmin Pay or others. They are much smaller companies and we treat them as nice-to-have in card issuing projects today.
##### Issuer Wallet SDK
Before Apple Pay and Google Pay appeared, both **Mastercard** and **VISA** invented other ways of contactless payments on mobile phones. They were called differently, but today they are mainly called Issuer Wallets. In such cases you do not sign contracts with Apple or Google, but you implement technology (both mobile SDKs and backend) that allows you to go live with contactless payments on mobile without signing contracts with Apple or Google. Actually it was possible for Android only, but recently (2023/2024) Apple allowed non-Apple Pay contactless payments on iPhones in the European Union.
In such cases you need to get and certify SDKs and backend components to go live with **contactless payments**. Such developments usually take 12-24 months and the software must be kept updated all the time, so it is actually better that you try to use a certified partner for this activity to avoid on-going development costs just for your project. From a contactless use case perspective, transactions work in a very similar way to X-Pays, but you have more flexibility. On Android, for example, you can implement a contactless payment just after unlocking the phone screen. You can - but do not have to - ask for additional authentication. You are also sure that data of your users and their transactions will not be shared with external entities (Apple and Google) for their benefit.
A big advantage of the Issuer Wallet SDK is that it can work not only on Android phones - for example, we have live implementations on Huawei devices. This detail has an important business impact on your users.
In today's world, working with Apple or Google is obligatory in our opinion, but we strongly recommend implementing Issuer Wallets at the same time, as it will give you more flexibility and business security in the long run. The costs and processes do not differ a lot, but the additional benefits of an issuer wallet such as flexibility, more devices, lower transaction costs make it worth implementing.
Read more: [**Push Provisioning to Google Pay and Apple Pay**](https://developer.verestro.com/books/knowledge-center/page/push-provisioning-step-by-step)
Thanks for reading.
# NFC on iPhone/iOS
#### What happened?
As part of an agreement between the European Union and Apple, Apple has decided to open access to its NFC module to 3rd party developers. It allows the creation of solutions for contactless payments (HCE), an alternative to Apple Pay.
This article aims to explain the challenges and opportunities related to this technology.
#### How it works?
- **NFC payments.** Users of participating third-party banking or wallet apps can initiate NFC transactions from within the app with compatible NFC terminals.
- **Default app settings.** Users can choose any eligible app as their default contactless payments app which will enable the app to support Field detect and Double-click features.
- **Field detect.** The default contactless payments app automatically launches when the user places the device in the presence of a compatible NFC terminal and after user authentication (if the iPhone is locked).
- **Double-click.** The default contactless payments app automatically launches when the user double-clicks the side button (for Face ID devices) or the Home button (for Touch ID) and after user authentication (if the iPhone is locked).
- **Payment support for non-default apps.** Eligible apps running in the foreground can prevent the system default contactless app from launching and interfering with the payment.
#### What are the differences compared to Android?
Since 2013 Android allows implementing alternatives to Google's own Google Pay, and there are already a few mature solutions on the market. [Apple's NFC API](https://developer.apple.com/documentation/corenfc) offers very similar capabilities from both a technical and user experience perspective. However, there are a few differences:
- **Not possible to directly ask a user to set your application as the default NFC payment app** - on Android, when users open your app, they can be presented with a dialog window that asks them if they want to use your app, as the default NFC payment app. Apple's documentation doesn't seem to hint at such a functionality.
- **Apple needs to give you special entitlement to access the NFC module** - without Apple's approval, it's not possible to include NFC payments into your app. This entitlement can be requested here: [https://developer.apple.com/contact/request/hce-payments-entitlement/](https://developer.apple.com/contact/request/hce-payments-entitlement/)
- **Security certification** - every app enabling NFC payments needs the EMVCo certification. As NFC on the Apple platform is a new thing, it's still not clear how exactly security certification will look like, however due to fundamental differences between Android and iOS we can expect slight differences.
#### What are the differences compared to Apple Pay?
Apple's API allows 3dr party developers to implement most of the functionality offered by Apple Pay. Two slight differences are:
- Power Reserve Mode - Apple Pay allows payments with the default card for some time after the iPhone battery is depleted.
- Express Transit Mode - allows to pay for public transport tickets in a few areas with compatible cards, without unlocking the iPhone. Full list of locations is [available here](https://support.apple.com/en-us/118625).
#### Will it work outside the EU?
Companies registered in the European Economic Area can offer this functionality to customers based in EEA. The table below shows various combinations of companies wanting to offer HCE payments in their App and customers, and the expected outcome according to Apple's requirements.
|
| **Company developing App established & licensed for payments in EEA**
| **Company developing App not present in EEA or not licensed for payments in EEA**
|
| **EEA citizen, transacting in EEA country**
| ✅HCE available
| ❌HCE not Available
|
| **EEA citizen, transacting outside EEA (traveling)**
| ✅HCE available | ❌HCE not Available |
| **non-EEA citizen, transacting in EEA country (traveling)**
| ❌HCE not Available | ❌HCE not Available |
| **non-EEA citizen, transacting outside EEA country** | ❌HCE not Available | ❌HCE not Available |
# On-device tokenization in India
Payment law in India required a few years ago that server based card-on-file systems are not allowed. Instead, there is a necessity to store user data on-device to perform transactions.
This is an interesting topic that impacted a lot of local players like big merchants, Cred, Phonepe or Amazon so let me describe it in some details because maybe it will be implemented in a few years in other countries as well.
Requirement for storing tokens in a secure way on customer devices forces us to implement and certify secure SDK in which payment token data will be saved. It is a similar concept to standard HCE (Host Card Emulation) implementation for mobile NFC payments. While registering to a merchant or wallet system, the user adds a payment card, performs tokenization with approval (One-Time-Passwords) of the issuing bank and the token connected with his card is stored in this wallet / SDK.
Once we have a secure place of storing the user's token on his mobile phone we can use this token for multiple purposes:
1. NFC / contactless payments - the user uses his phone to perform transactions on a contactless acceptance network. Token and payment keys are transferred through the contactless interface to the payment terminal and acquirer for authorization.
2. inApp - the user chooses products and adds them to the basket in the merchant app, clicks that he wants to pay with a particular wallet or payment brand and confirms the transaction in a wallet app. The token is taken from an SDK, transferred to the cooperating acquirer in the form of a DSRP message (Dynamic Secured Remote Payment) and processed in standard way
3. web purchase - the user chooses products and adds them to the basket on the merchant website, clicks that he/she wants to pay with a particular wallet or payment brand and receives a push notification in his/her mobile app to finalize the transaction. As above, the token is taken from an SDK, transferred to the cooperating acquirer in the form of a DSRP message (Dynamic Secured Remote Payment) and processed in standard way. There could be a possibility to store the token inside the browser of the user on his laptop / PC but this requires more discussion with Mastercard and VISA.
To enable these use cases, several implementation points needs to be considered:
- types of devices - an inApp and web purchase can work on all devices (iOS and Android) but NFC is enabled on Android only. Apple is blocking the NFC access outside of the European Union today.
- VISA vs Mastercard - do you need a solution working for both schemes? Are there any local certification requirements?
- Issuers - are banks ready to connect to your new X-Pay wallet? Which banks are enabled on local markets?
- local on-soil requirements - is there a need to store data in the country? What are the legal impacts?
This is an interesting development and area of work. We are live with a few partners and are happy to work with new ones. Please contact us if you are interested.
Thanks for reading.
# Introduction
**Token Requestor Service** is an end-to-end solution designed to enable **Issuer Wallets** for secure and flexible **NFC payments** on both Android and iOS platforms. Tailored for banks, fintechs, and other financial institutions, this solution empowers you to build a seamless and scalable digital payment ecosystem directly within your **Mobile Banking** or **Payment App**.
### A Complete Ecosystem for Tokenized Payments
The Token Requestor Service is a set of components that together deliver a comprehensive and highly customizable payment experience:
- **Android SDK**
A certified and highly configurable library for managing token lifecycle and NFC transactions. Fully compliant with [**EMVCo** standards](https://www.emvco.com/approved-registered/approved-products/?action=search_products&approved_product_expiration_date=2020-08-31&px_search=&emvco_product_sbmp%5B0%5D=mobile-app-sdk&sort=approved_product_expiration_date&sort_order=ASC), the SDK supports integration into existing applications and ensures secure and smooth payment flows.
- **iOS SDK**
Enabling in-app token-based payments based on Apple's **HCE Transactions for Apps**. The solution allows you to create a **standalone wallet on iOS**, fully independent from Apple Pay.
- **Huawei Wearables SDK**
A dedicated SDK enabling tokenized **NFC payments on Huawei smartwatches**, compatible with both Android and iOS smartphone.
- **Server Component**
A backend system integrated with **Mastercard’s MDES**, **Visa’s VTS**, and a range of proprietary **Verestro services**, managing card digitization, provisioning, and lifecycle events.
### Key Capabilities
- **Full control over card, user, and token lifecycles**
Manage how cards are issued, provisioned, and revoked within your own ecosystem.
- **Support for Huawei smartwatches**
Tokenized payments can be enabled on [Huawei wearable devices ](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/watch-integration)for both Android and iOS. Notably, **payments via Huawei smartwatches are also available when paired with iPhones, even outside the EEA**.
- **Certified and secure**
Built in compliance with global standards, including **EMVCo certification**, ensuring maximum security and interoperability.
- **Customizable user experience**
As an Issuer Wallet solution, you retain full flexibility over the UX, allowing seamless integration of additional products and services into your app.
### Easy Integration and Deployment
Whether you're looking to add tokenized payments to an existing mobile application or launch a brand-new digital wallet, integration is simple. We provide:
- A complete SDK package (Android and iOS)
- Backend server components
- Technical integration support
- Optionally, fully developed white-label applications
---
## Ready to Get Started?
Launching tokenized NFC payments has never been easier. Simply:
1. **Open a project with MDES or VTS**
2. **Integrate our SDKs**
3. **Expand the services you offer to your customers**
We provide full documentation, fast onboarding, and professional support throughout the process.
Explore more at:
👉 [developer.verestro.com/books/token-requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet)
# Intro slides
### Card Tokenization
MDES and VTS integration as token requestor. Issuer wallet or SDK integrated into mobile banking application. Available on all Android phones (including Huawei) and all countries. Enables mobile contactless transactions using NFC interface.
| **API**
| **MDES** (Mastercard Digital Enablement Service) and **VTS** (Visa Token Service) |
| **Readiness**
| Live
|
| **SDK available**
| Yes |
| **White label solution available**
| Yes |
| **Certification**
| Yes, full security and functional certification |
| **Implementation time**
| 3 months from contracting |
[](https://developer.verestro.com/uploads/images/gallery/2022-07/image-1657286927149.png)
## Implementation Steps
[](https://developer.verestro.com/uploads/images/gallery/2022-07/pba.png)
## Architecture
[](https://developer.verestro.com/uploads/images/gallery/2026-03/issuer-wallet-2.jpg)
# Overview
Verestro Cloud Payments is a solution developed to facilitate adopting cloud-based payments for the Customers. VCP provides functionalities for User identification and verification, Payment Instruments digitization, including cards and IBAN-based instruments, User data management, address management and transaction history management (to review). Cloud payments enables a card to be digitized into a wallet application on a mobile device and used for payment without the need for a Secure Element (SE) or a Trusted Execution Environment (TEE) to protect the card's sensitive assets, such as the keys needed for calculating the Application Cryptogram.
Master Keys for the digitized card are kept securely on remote servers (for plastic in the chip), hence the term 'cloud-based payment,' and a limited number of keys (where each key can only be used to perform a single transaction) are downloaded to the application.
Solution consists of:
- **server** components:
- Wallet Server - backend component,
- Wallet Admin Panel - frontend component,
- **mobile** components:
- Wallet SDK - MDC SDK for user, device, card and address management and VCP SDK for payment tokenization, payments and IBAN-based payment instruments (to review),
- Wearable SDK - libraries for payments with Huawei Smartwatches.
## Benefits of Payment Token
The MCBP service is an easy and secure way to replace a plastic payment card with a payment token. Recognition to the tokenization and digitization process without leaving the house, we can add our payment card to the mobile application and use only a mobile device during purchases.
The benefits of tokenization are felt by every participant in the process:
- **Issuer** - by implementing the tokenization service, it will provide its customers with much higher and safer access to innovative payment solutions.
- **Card Holder** - can freely use innovative payment solutions. The tokenization service will allow free and secure payments using any devices connected to the internet.
- **Device manufacturer** - TBD
## MCBP Introduction
Mastercard Cloud-Based Payments (MCBP) is technology which enables a card to be digitized into an application on a mobile device. On plastic card, Master Keys needed for calculating cryptogram are stored in the Secure Element. Using MCBP there is no need for Secure Element since keys needed for calculating the cryptogram are kept securely on remote servers, hence the term 'cloud-based payment,' and a limited number of keys (where each key can only be used to perform a single transaction) are downloaded to the application. VCP is solution which provides functionalities for digitization, user data management and payments needed for final Customer to adopt MCBP.
### MCBP High Level Architecture
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654374212441.png)
### MCBP Key Components
| Component | Description |
|---|
| MPA | Mobile Payment Application (for Android and iOS Smartphones) provides frontend interface to the user and uses part of Verestro Wallet SDK which is responsible for payments using HCE. In case of wearable payments, MPA acts as companion app. |
| 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. |
## Description
### Wallet Types
VCP supports following wallet types which can be used in the implementation:
- **OPEN** - user registers itself in the application and provides data like PAN etc.,
- **CLOSED** - user data are passed automatically from Customer servers without User interaction to Wallet Server.
### Implementation Models
Verestro provides two different implementation models for products: integrated and standalone version.
**Integrated**
In this model Customer is owner of MPA. Verestro provides Wallet SDK and Wallet Server. Customer is responsible for direct User authentication and passes the result of the authentication to Wallet SDK. Online operations which need to be performed by User using Wallet Server require valid session on Wallet Server. To obtain user online session with Wallet Server, Customer needs to pass Trusted Identity.
**Standalone**
In this model Verestro provides MPA, Wallet SDK and Wallet Server. Furthermore, Verestro manages direct user authentication.
### Architecture
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654374565801.png)
### Server Components
Server components are applications which need to be deployed on remote server to make possible to connect them by network.
#### Deployment Models
Verestro offers two deployment models of server components: On-premise and SaaS.
**SaaS** - Server components are designed to be deployed in SaaS model. In this case everything is deployed and configured on Verestro side. Verestro is responsible for maintaining infrastructure, deploying applications and monitoring.
**On-premise** - Server components also can be deployed on Customer infrastructure. Applications are designed to be deployed using [Kubernetes](https://kubernetes.io/) as system for automating deployment, scaling, and management of containerized applications. For more details please contact Verestro representative.
#### Wallet Server
Wallet Server is a backend component which consists of few internal services which are responsible for managing users, devices, cards, Payment Tokens, transaction history. It acts as Token Requestor on behalf of Issuer and is compliant with PCI Data Security Standard.
It exposes:
- **mobile API** - available via Wallet SDK to perform operations directly from mobile device,
- **LC API** - server API dedicated for Issuer to manage users and cards data on Wallet Server,
- **MDES Outbound API** - server API dedicated for MDES,
- **Verestro Cloud Payments External API** - dedicated for external clients (e.g. Issuer) to manage Payment Tokens,
- **Transaction History API** - API to receive and collect information on performed financial transactions.
Wallet Server operates with domain objects like:
- **User** - root of entity tree. User is identified in Wallet Server via some unique identifier which can be external id given by Customer. User can have access to his data and operations based on session. Session is created after pairing device and when is expired then User authentication needs to be performed. Session is valid for a configurable period of time.
- **Device** - belongs to User. When User starts using application after installation then device pairing is performed. After pairing device with some unique id (constant across installations and users), unique device installation id is generated and this installation is assigned to particular User. It is possible to have one active installation on specific device for specific User. If other User starts using application on same device then another device pairing is performed and all data from previous installation will be wiped.
- **Card** - belongs to User. User can have many cards. Card is identified via internal id given after storing card on Wallet Server. Whole PAN is stored on Wallet Server (always or short period of time).
- **Payment Token** - after PAN digitization, device Payment Token is created also on Wallet Server side without any sensitive data. One PAN can have one device Payment Token on specific device installation at the same time which is INACTIVE, ACTIVE or SUSPENDED.
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654374710316.png)
#### Wallet Admin Panel
Web frontend application which is dedicated for back office to manage all User data.
### Mobile Components
#### Wallet SDK
Verestro provides Software Development Kit (SDK) called Wallet SDK which can be used in Mobile Payment Application. As a company, Verestro provides many products which can be used in single application. For that reason Wallet SDK is divided into separated modules which covers different functionalities. There are two main modules dedicated for Verestro Cloud Payments: MDC SDK and VCP SDK. MDC SDK is core Verestro module responsible for user data management: authentication, payment cards management - since these are main functionalities used in every product. VCP SDK is dedicated for performing digitization and payments using Payment Token. In payment context VCP SDK wraps Mastercard Cloud Based Payment SDK.
#### Wearables SDK
Product supports contactless payments using Huawei smartwatches. There are multiple SDKs to be implemented both - on smartphone and wearable device. Smartphone app serves as companion app in this process. Wearable payments are fully compliant with smartphone-only solution, and act alongside it. Wearables SDK is extension, but uses wallet SDK even if smartphone payments are not necessary in project.
#### Requirements
Wallet SDK has some mandatory requirements to make it work:
- device cannot be rooted,
- Android OS image (ROM) should be genuine in version 6.0 (Marshmallow) or above,
- devices cannot have enabled debugging.
There are also some not mandatory requirements, but Customer needs to be aware of them to maintain functionalities:
- NFC module necessary for HCE payments,
- lock screen necessary for locally-verified user authentication.
#### Security
Wallet SDK was developed according to security requirements included in Security Guide MCBP SDK for Android. However Wallet SDK cannot guarantee full MPA protection and MPA must provide additional layer of security to protect user interface (mainly when PAN is manually entered in the application) and data processing within application. More detailed information can be found in *Wallet SDK API.* Moreover all sensitive data are passed as chars or bytes arrays. Wallet SDK copies the arrays and clears that copies just after processing. MPA should clear provided sensitive data immediately after passing them to Wallet SDK.
**Security Checks and Data Clearing**
On Wallet SDK side are performed security checks which includes static code analysis protection and dynamic analysis protection. Security checks consists of:
- root access detection,
- hooking protection,
- debugging protection,
- custom ROM protection,
- data tampering protection,
- man in the middle protection.
Security checks are performed periodically, if Wallet SDK detects any of above things all data hold by Wallet SDK will be cleared and security report will be sent to Wallet Server. MPA will be informed about such detection.
**Communication with Wallet Server**
Communication from genuine applications which are installed on genuine devices is accepted by the Wallet Server. Wallet SDK at the very beginning performs authentication of application and device to Wallet Server. This authentication may take advantage of Google Play Integrity which is a 3rd-party trusted side in whole authentication. Google Play Integrity verifies device and sign information about device and application. Signed data from Play Integrity are sent to the Wallet Server. Wallet Server verifies data and allow or does not allow for further communication. Application is verified according preconfigured application certificate digest used for signing application.
> **Important:** There is a limit of requests to Google Play Integrity API: 10 000 per day. If Customer predicts that there will be more installations per day then this limit needs to be increased during Google Project Setup.
Wallet SDK communicates with Wallet Server using TLS 1.2. Wallet SDK performs public key certificate pinning when it tries to establish connection with Wallet Server (similar with connection to MDES). Certificates for the pinning needs to be provided to SDK. Sensitive information are additionally encrypted and/or signed.
**Versioning**
Wallet SDK uses semantic versioning. It means that every release has own version which is MAJOR.MINOR.PATCH, where:
- MAJOR version increases when SDK has incompatible API changes,
- MINOR version increases when new functionality is added in a backwards compatible manner,
- PATCH version increases when new backwards compatible bug fixes are introduced.
MAJOR versions are supported 6 months and Customer needs to migrate to new version if they want to maintain support.
#### Remote Notification Service
Wallet SDK is responsible for remote notification processing. However MPA is responsible for obtaining FCM registration token, handling FCM token update and receiving remote notifications. Before passing remote notification to SDK, MPA needs to verify if given message is dedicated for SDK by checking sender Id. Sender Id is configured during onboarding. Verestro will create new FCM project and provide data needed to obtain FCM token for given project. Due to observing some issues with FCM token refresh notification from FCM service, additional check of new token availability is recommended (e.g. on application start). See more in *Wallet SDK API.*
#### Access
Wallet SDK is stored as artifacts in maven repository. Access there is provided during onboarding by Verestro representative.
### Configuration
Whole product has configuration which needs to be fulfilled. This configuration also consists of data which are set in MDES. More details are described in *Wallet Configuration*.
### User Experience for Contactless Transactions
MDES offers a few options for customers for defining user experience for contactless transactions. Final option is the choice of CDCVM type (Mobile PIN, Locally-verified CDCVM) and CVM model (Always, Flexible, Card-like).
#### CDCVM Types
There are two types of Consumer Device Cardholder Verification Method (CDCVM) which are supported by MDES.
#### Mobile PIN CDCVM
A PIN value (4–8 digits) that the cardholder enters on the mobile device and that is validated online by MDES during the transaction authorization process. Since Locally-verified is mostly preferable option, Mobile PIN is out of scope.
#### Locally-verified CDCVM
A CDCVM entered on and validated by the consumer's mobile device, for example system device PIN, pattern, password or biometric methods (such as fingerprint, iris or facial recognition). Swipe (slide to unlock) is not a valid cardholder verification method and must not be supported. These methods are commonly associated with a device unlock process and are validated on the cardholder's mobile device. The payment component embedded in the Mobile Payment Application will use the outcome of this authentication process. A Locally-verified CDCVM applies to all the payment tokens of a given Mobile Payment Application instance ("Wallet-level"). In some parts of system this type is also named as Custom.
### CVM Models
For two CDCVM types customer can apply different user experience CVM Models.
#### Always CVM
In this model the card profiles supplied to the SDK are configured to indicate that the mobile device supports on-device cardholder authentication. When transactions are performed on a POS supporting CDCVM, the POS will delegate cardholder authentication to the mobile device the terminal will not request an Online PIN on the terminal. In POS which does not support CDCVM cardholder authentication is required using Online PIN. This model requires the cardholder's mobile device to authenticate the cardholder for all transactions (LVT, HVT, Transit). CDCVM can be performed using either a Mobile PIN or a Locally-verified CDCVM. MPA is expected to decline any transaction for which cardholder authentication is not performed or is unsuccessful.
Below are presented sample diagrams which show how the transactions can look like:
*Always LVT, HVT - single tap*
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654375111845.png)
*Always LVT, HVT - double tap*
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654375121955.png)
#### Flexible CVM
In this model the card profile also indicates that the mobile device supports on device cardholder authentication Mobile PIN or Locally-verified CDCVM. However rather than applying authentication for every transaction the MPA defines flexible criteria such as allowing multiple transactions between each authentication. This criteria are often named as Lost & Stolen options or velocity checks. For transit transactions cardholder authentication is not expected.
Below are presented sample diagrams which show how the transactions can look like:
*Flexible LVT*
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654375214373.png)
*Flexible HVT - single tap*
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654375231686.png)
*Flexible HVT, LVT with Velocity counters - double tap*
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654375238935.png)
#### Card-like CVM
In this model the card profiles supplied to the SDK are configured to indicate that the mobile wallet is not capable of supporting on device cardholder verification. This means that when transactions are performed with a Point of Sale (POS) terminal, the POS will treat the transaction in the same way as a card transaction. Typically this means that low value transactions (LVTs) will be processed without additional user authentication and if supported, high value transactions will require an online PIN to be provided on POS. This model is put here just for general information, however it is not preferred for issuer wallets.
Below are presented sample diagrams which show how the transactions can look like:
*Card like LVT*
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654375297218.png)
*Card like HVT*
[](https://developer.verestro.com/uploads/images/gallery/2022-06/image-1654375302023.png)
#### Lost & Stolen Options
The Lost & Stolen options are dedicated to control performing transactions allowed before requiring cardholder authentication. This limits fraud risk if the cardholder's mobile device is lost or stolen. Lost & Stolen options can be applied only for Flexible CDCVM. These options also are known as velocity check counters. Wallet SDK provides interface which is invoked during transaction. Transaction information like range, rich transaction type, amount are provided within this interface. MPA can implement various checks to support velocity check counters using transaction information. MPA for example can count LVT transactions and allow only some predefined number of LVT transactions without cardholder authentication.
#### Transit Transactions
Transit transactions are transactions with given Merchant Category Code performed e.g. on traffic gates like: underground. It is up to Customer if wants to enable such transactions or not (option selected during MDES onboarding). Transit transactions are enabled in every CVM model, however for Always CDCVM needs to be performed for every transaction, for Card-Like and Flexible CDCVM can be skipped.
### Tokenization/Digitization
Tokenization is a process which enable to replace sensitive data, e.g. card number, with another string of characters - a secure payment token - as a result of which card data remains inaccessible. Payment tokens are assigned to a given device of the card owner, which means that an unauthorized person, even if he obtains the token data, will not be able to use them via another device. It is also secured inside the SDK. As a result of the tokenization process, the customer comes into possession of Transaction Credentials in a mobile application on his device.
#### Digitization decisions
- **Green (APPROVED)** - Approve the digitization request without further cardholder interaction,
- **Yellow (REQUIRE\_ADDITIONAL\_AUTHENTICATION)** - Approve the digitization request but seek additional cardholder authentication,
- **Red (DECLINED)** - Decline the digitization.
## Main processes
### User and cards registration into wallet server
User with unique identifier known on issuer side is registered along with cards in the Wallet Server. After that process, device can be paired.
### Pairing device for particular user by trusted identity
Authentication of the device in context of given user. Process needed to allow access to wallet server from that particular device.
In the integrated model signed user identifier passed from issuer into wallet server via SDK is used to authenticate given user.
### Digitization of the card
When device is paired user can have access to his own data: cards. After that he can digitize chosen card which was previously added into wallet server.
Two digitization approaches are supported:
**One-Step Digitization** - simplified process for implementations requiring no additional authentication. Expects APPROVED or DECLINED outcome only.
**Multi-Step Digitization** - includes eligibility checking, terms & conditions display, and digitization. May result in APPROVED, DECLINED, or REQUIRE\_ADDITIONAL\_AUTHENTICATION outcome.
### Digitized card profile provisioning on the device
After successful digitization, digitized card profile is delivered to device. Since only limited number of keys for transaction is delivered to the device, SDK triggers replenishment to cover up the number of transaction credentials.
### Transaction credentials replenishment
Transaction Credentials are unique per-transaction keys used to calculate cryptograms. Each set of credentials can only be used for one transaction.
Three replenishment strategies are supported:
**Automatic** - after every transaction, Wallet SDK checks if the number of transaction credentials has fallen below a preconfigured threshold. If so, replenishment is triggered automatically.
**Initial** - occurs directly after successful token activation without requiring any MPA action.
**Manual** - allows explicit user-initiated credential refresh when automatic processes fail, particularly when internet connectivity is limited.
### Payment
Solution delivers multiple options to process and complete payments. Contactless smartphone payments, wearable contactless payments, DSRP, one-tap, two-tap.
### Payment history (Optional) (to review)
It is possible to store transactions on wallet server. Retrieving data is possible using one of SDK functionalities or dedicated API methods. In addition to basic history listing, available transaction history features may include transaction filtering and pagination, transaction details, notes and custom data updates, categories, receipt or photo attachments, download links for attachments and monthly spending summaries (to review).
## Main steps and implementation
Issuer integration with MDES.
- Completing BPMS/ICG file - configuration for issuers in MDES:
- PAN ranges allowed for digitization,
- channel for the authorization cards for the digitization: predigitization API/ISO 8583 messages,
- digitization path,
- Completing PCG file - configuration for token requestors (wallet configuration):
- parameters for connection,
- transactions user experience,
- Exchanging certificates:
- connection,
- external wrapping key,
- payload encryption to mdes,
- tav,
- Adopt LC API to pass users and cards into wallet server and manage them later,
- Integrate SDK into issuer application,
- Implement signing user identity to authenticate user on wallet server via SDK.
# Use Cases
###
This section describes use cases which can be initiated using Wallet Server LC API. Customers to manage Users and cards data on Wallet Server.
#### User with Card Registration
User with Card Registration is process when user and cards are transferred to Wallet Server to make possible use them in different processes (e.g. digitization) later in the application. Registration needs to be done as the first step
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant Issuer
Issuer -> WS: 1. addUserWithCard(userData, cardData)
activate Issuer
activate WS
WS --> Issuer: 2. response(cardId)
deactivate WS
Issuer -> Issuer: 3. storeCardId
deactivate Issuer
@enduml
#### Card Reissuing
Since plastic cards have expiration date, Issuers may want to reissue them. In most cases PAN remains the same and only expiration date is extended. It is worth to mention that MDES does not check PAN expiry date for transactions performed with Payment Token. MDES offers API for Issuers where is possibility to update expiration date or even whole PAN for already provisioned Payment Tokens. In context of integration there are a few options:
- Issuer has own processor which is integrated with Customer Service MDES API and there is a possibility to update PAN or expiration date. Then reissuing is done only on processor side. Wallet Server will be notified by MDES about the change.
- Issuer uses Verestro Token Management Platform and reissuing is possible using LC API.
- Issuer uses only Wallet Server which acts as Token Requestor and there is no possibility to update PAN or expiration date for given Payment Token. Issuer needs to delete previous card and add new one. Users need to make digitization again.
All options needs to be considered individually and discussed with Verestro representative.
#### User Deletion
During this process all data related to given User are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant Issuer
Issuer -> WS: 1. deleteUser(userId)
activate Issuer
activate WS
WS -> WS: 2. delete cards, devices
WS --> Issuer: 3. response
deactivate Issuer
loop All Payment Tokens for given User
WS -> MDES: 4. delete token
activate MDES
MDES --> WS: 5. response
opt
WS ->> Issuer: 6. send Payment Token event
end
deactivate WS
deactivate MDES
end
@enduml
#### Card Deletion
During card deletion process all data related to given card are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
Issuer -> WS: 1. deleteCard(cardId)
activate WS
activate Issuer
WS -> WS: 2. deleteCard
WS --> Issuer: 3. response
deactivate Issuer
loop All Payment Tokens for card
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
opt
WS ->> Issuer: 7. send Payment Token event
end
deactivate MDES
WS -> SDK: 8. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
deactivate MPA
activate SDK
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
deactivate MPA
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
### Wallet SDK Initiated
#### Wallet SDK Setup
Setup of Wallet SDK (both modules VCP SDK and MDC SDK) is main step which needs to be made at very beginning. During setup main configuration should be provided. Moreover there is some configuration which is related with HCE payments: MPA should be registered as default application for payment (Tap & Pay) and also should implement HostApduService to emulate an NFC card inside an Android service component. Please find more details in *Wallet SDK API* document.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
participant MPA
participant "Wallet SDK" as SDK
MPA -> SDK: 1. MDC:setup(configuration)
activate MPA
activate SDK
SDK --> MPA: 2. result
MPA -> SDK: 3. UCP:setup(configuration)
SDK --> MPA: 4. result
deactivate MPA
deactivate SDK
@enduml
#### Pair Device on Wallet Server
This section describes pairing device process. Device pairing is process which authenticates device in context of given user. During this process device data and keys used in communication are exchanged with Wallet Server. To make possible device pairing, user needs to be already registered on the Wallet Server. Every device is identified by unique identifier. After every pairing device request, Wallet Server gives unique installation identifier. It means that particular installation of the application installed on particular device belongs to given User. Different Users can use same device for separate installations. If any active installation on given device already exists during pairing device, Wallet Server will delete and create new installation in context of new user. Only one active installation is possible on particular device. Device pairing is the first process which should be done after user registration. Pairing device should be done only once for individual installation.
##### Pair Device By Trusted Identity
In the integrated model, [Trusted Identity](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/trusted-identity) is used to proof User authenticity. User is firstly authenticated on the Customer side. Trusted Identity should be generated on Issuer backend side and pass via Wallet SDK, since mobile environment is treated as unsecure. Algorithm of generating Trusted Identity is placed in Wallet SDK API specification.
Access to User data stored on Wallet Server is possible only when session is established. After paring device session is automatically generated for particular User.
If previously on given device was installation which had Payment Tokens, during pairing these Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as Issuer
participant "MDES" as MDES
MPA->Issuer: 1. authenticate
activate MPA
activate Issuer
Issuer->Issuer: 2. generateTrustedIdentity - signed user id
Issuer--> MPA: 3. response(trustedIdentity)
deactivate Issuer
MPA -> MPA: 4. obtainRNSToken(walletFirebase)
MPA-> SDK: 5. MDC:pairDeviceByTrustedIdentity\\r(trustedIdentity, rnsRegistrationToken)
activate SDK
SDK -> SDK: 6. isDevicePaired
alt isDevicePaired=true
SDK --> MPA: 7. result
else isDevicePaired=false
SDK-> WS: 8. pairDeviceByTrustedIdentity\\r(trustedIdentity, rnsRegistrationToken, deviceInfo)
activate WS
WS-> WS: 9. verify trusted identity
alt isActiveInstallationOnGivenDevice
WS -> WS: 10. deleteActiveInstallation
WS -> MDES: 11. deleteDeviceTokens
activate MDES
deactivate MDES
note left: asynchronous
end
WS -> WS: 12. createNewDeviceInstallationRecordForUser
WS --> SDK: 13. response\\r (userSessionToken, installationId)
deactivate WS
SDK -> SDK: 14. store userSessionToken
SDK-->MPA: 15. result
deactivate MPA
deactivate SDK
end
@enduml
#### Card Digitization
Card digitization is process which allows to transform plastic card into . To perform digitization, card data should be placed already on Wallet Server and device should be already paired. Card digitization process uses Wallet Server identifier of the card. There are two ways of performing card digitization. Usage of the API's depends on needs in given implementation.
##### Card Digitization Ways
Depending on implementation card can be digitized in different way using different approach. There are following ways of card digitization:
- one step - which is the simplest way of card digitization and should be used in project implementation where card can be just digitized without any additional staff like additional User authentication or showing T&C or showing card art from MDES,
- multi step - which should be used when digitization will require additional User authentication, showing T&C or showing card art from MDES.
##### Card Digitization Ways - One Step
One step digitization is dedicated for implementations where there is no additional User authentication and . Mostly it should be used in Issuer applications where NFC payments is added as a new functionality without additional staff which is used in dedicated wallets. Only transaction outcomes APPROVED(see APPROVED) or DECLINE(see DECLINE) are expected in this type of digitization.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant "MPA" as MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
MPA -> SDK: 1. UCP:Cards#digitize\\r(paymentInstrumentId=verestroCardId, userLanguageCode, securityCode?)
activate MPA
activate SDK
SDK -> SDK: 2. isDeviceRegisteredForPayment
alt isDeviceRegisteredForPayment=false
SDK -> WS: 3. getPkCertificate
activate WS
WS -> MDES: 4. getPkCertificate
activate MDES
MDES --> WS: 5. response(pkCertificate)
WS --> SDK: 6. response(pkCertificate)
SDK -> SDK: 7. prepareDataForRegistration(pkCertificate)
SDK -> WS: 8. registerDeviceForPayment\\r (paymentDeviceInfo, userSessionToken)
WS -> MDES: 9. registerMobilePaymentApplication\\r (paymentDeviceInfo)
MDES --> WS: 10. response(mobileKeys,\\r remoteManagementUrl)
WS --> SDK: 11. response(mobileKeys,\\r remoteManagementUrl)
end
SDK -> SDK: 12. isPaymentInstrumentDigitized
alt isPaymentInstrumentDigitized=true
SDK --> MPA: 13. result
else isPaymentInstrumentDigitized=false
SDK -> WS: 14. digitizeCard\\r (cardId, userSessionToken)
WS -> MDES: 15. checkEligibility(cardData, paymentAppId,\\r paymentAppInstanceId)
MDES --> WS: 16. response (eligibilityReceipt)
WS -> MDES: 17. digitize(eligibilityReceipt)
MDES --> WS: 18. response
deactivate MDES
WS --> SDK: 19. response(paymentTokenInfo)
deactivate WS
SDK --> MPA: 20. result
deactivate SDK
deactivate MPA
end
deactivate SDK
deactivate MPA
note over SDK, WS #1C1E3F: See Card digitization outcome Approved or Decline diagram
@enduml
##### Card Digitization Ways - Multi step
Multi step digitization should be used in implementations where terms and are displayed before every digitization, additional user authentication is needed or card art need to be used from MDES. Multi step digitization consists of following steps:
- checking card eligibility
- showing T&C
- digitizing card
Digitization may finished with different outcomes(see Card Digitization Outcomes).
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant Issuer
MPA -> SDK: 1. UCP:Cards#checkEligibility(paymentInstrumentId=verestroCardId, locale)
activate MPA
activate SDK
SDK -> SDK: 2. isDeviceRegisteredForPayment
alt isDeviceRegisteredForPayment=false
SDK -> WS: 3. getPkCertificate
activate WS
WS -> MDES: 4. getPkCertificate
activate MDES
MDES --> WS: 5. response(pkCertificate)
WS --> SDK: 6. response(pkCertificate)
SDK -> SDK: 7. prepareDataForRegistration(pkCertificate)
SDK -> WS: 8. registerDeviceForPayment (paymentDeviceInfo, userSessionToken)
WS -> MDES: 9. registerMobilePaymentApplication (paymentDeviceInfo)
MDES --> WS: 10. response(mobileKeys, remoteManagementUrl)
WS --> SDK: 11. response(mobileKeys, remoteManagementUrl)
end
SDK -> WS: 12. checkEligibility(paymentInstrumentId,userSessionToken)
WS -> MDES: 13. checkEligibility(card)
MDES -->WS: 14. response(termsAndConditionsAssetId, eligibilityReceipt)
WS --> SDK: 15. response(termsAndConditionsAssetId, digitizationRef)
SDK --> MPA: 16. result(termsAndConditionsAssetId)
MPA -> SDK: 17. UCP:getAsset(termsAndConditionsAssetId)
SDK -> WS: 18. getAsset(termsAndConditionsAssetId)
WS -> MDES: 19. getAsset(termsAndConditionsAssetId)
MDES --> WS: 20. response(content)
deactivate MDES
WS --> SDK: 21. response(content)
deactivate WS
SDK --> MPA: 22. result
deactivate SDK
MPA -> User: 23. show T&C
deactivate MPA
User -> MPA: 24. accept
activate MPA
MPA -> SDK: 25. UCP:Cards#digitize(paymentInstrumentId, cvc?)
activate SDK
SDK -> WS: 26. digitize(digitizationRef, cvc?, userSessionToken)
activate WS
WS ->MDES: 27. digitize(eligibilityReceipt, cvc?)
activate MDES
MDES --> WS: 28. response(additionalAuthenticationRequired, authenticationMethods?, tokenInfo, productConfig)
deactivate MDES
WS --> SDK: 29. response(additionalAuthenticationRequired, authenticationMethods?, tokenInfo, productConfig)
deactivate WS
SDK --> MPA: 30. result
deactivate SDK
MPA -> User: 31. please wait
deactivate MPA
note over SDK, WS #1C1E3F: See Card digitization outcome Approved or Decline or Require Additional Authentication diagram
@enduml
##### Card Digitazation Outcomes
There are following digitization outcomes which should be handled differently:
- APPROVED
- DECLINED
- REQUIRE\_ADDITIONAL\_AUTHENTICATION
##### APPROVED
This digitization outcome always refers to green path digitization decision. When digitization is APPROVED then profile provisioning(See Profile Provisioning) starts automatically. According to MDES architecture just after digitization Payment Token is in INACTIVE state even though does not require additional User authentication. Due that fact new flag was introduced which informs which Payment Token exactly needs to be additionally authenticated. After successful provisioning token is activated and then SDK will perform Transaction Credentials - Initial Replenishment.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
group APPROVED
MDES --> WS : 1. responseFromDigitization(APPROVED, cardDigitizationData)
activate MDES
activate WS
opt
WS ->>Issuer: 2. send Payment Token Event
end
WS --> SDK : 3. response(digitizatonData, paymentToken)
deactivate WS
activate SDK
SDK --> MPA : 4. result
activate MPA
MPA --> User : 5. result
deactivate MPA
... Profile Provisioning ...
note over MPA, MDES #1C1E3F: See Profile Provisioning diagram
... MDES Token Activation ...
SDK -> MDES: 6. notifyProvisioningResult
MDES -> MDES: 7. createTokenMapping
MDES -> WS: 8. notifyTokenUpdated(Active)
deactivate MDES
activate WS
opt
WS ->>Issuer: 9. send Payment Token Event
end
WS -> SDK: 10. deliverMessage(paymentTokenActive)
NOTE LEFT: See: Handle Message From Server
deactivate WS
SDK -> SDK: 11. updateTokenStatus
SDK -> MPA: 12. onPaymentInstrumentStatusChanged(id, status)
deactivate MPA
deactivate SDK
... Initial Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
end
@enduml
##### DECLINE
This digitization outcome refers to red digitization decision.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
group APPROVED
MDES --> WS : 1. responseFromDigitization(DECLINED)
activate MDES
deactivate MDES
activate WS
WS --> SDK : 2. response(error)
deactivate WS
activate SDK
SDK --> MPA : 3. result
deactivate SDK
activate MPA
MPA --> User : 4 result
deactivate MPA
@enduml
##### REQUIRE\_ADDITIONAL\_AUTHENTICATION
This digitization outcome always refers to yellow path digitization decision. When digitization is REQUIRE\_ADDITIONAL\_AUTHENTICATION then profile provisioning(See Profile Provisioning) starts automatically but remain INACTIVE until the User is authenticated(see Card Digitization Activation). Flag *additionalAuthenticationRequired* informs if additional user authentication is needed or not.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
participant Issuer
group REQUIRE\_ADDITIONAL\_AUTHENTICATION
MDES --> WS : 1. responseFromDigitization(response(additionalAuthenticationRequired=true, authenticationMethods?, tokenInfo, productConfig))
activate MDES
deactivate MDES
activate WS
opt
WS ->> Issuer: 2. send Payment Token event
end
WS --> SDK : 3. response(response(additionalAuthenticationRequired=true, authenticationMethods?, tokenInfo, productConfig))
deactivate WS
activate SDK
SDK --> MPA : 4. result
deactivate SDK
activate MPA
MPA --> User : 5. result
deactivate MPA
... Profile Provisioning ...
note over MPA, MDES #1C1E3F: See Profile Provisioning diagram
... Card Digitization Activation ...
note over MPA, MDES #1C1E3F: See Card Digitization Activation diagram
end
@enduml
##### Card Digitization Activation
This process is applicable only if digitization has infomation that additional authentication is required. During this process User can choose one of the additional authentication methods. If user-entered authentication code is chosen then MDES will send authentication code which later should be provided by User for submission. Once user enters correct authentication code, Payment Token is activated by MDES asynchronously. After activation Wallet Server is notified that Payment Token is activated and this information is passed to Wallet SDK. After Payment Token activation, Wallet SDK start Transaction Credentials - Initial Replenishment.
NOTE: Submit authentication value is allowed only if provisioning is finished.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
alt Just after digitization
MDES --> WS : 1. responseFromDigitization(additionalAuthenticationRequired=true, \\rauthenticationMethods?, tokenInfo,productConfig)
activate MDES
activate WS
WS --> SDK : 2. response(additionalAuthenticationRequired=true, \\rauthenticationMethods?, tokenInfo, productConfig)
activate SDK
SDK --> MPA: 3. result(authenticationMethods)
activate MPA
else Activation not finished after digitization
User -> MPA: 4. activate token
MPA -> SDK: 5. UCP::getAdditionalAuthenticationMethods(paymentInstrumentId)
SDK -> WS: 6. getAuthenticationMethods(cardId, userSessionToken)
WS --> SDK: 7. response(authenticationMethods)
SDK --> MPA: 8. result(authenticationMethods)
end
MPA --> User: 9. show authentication methods
User -> MPA: 10. select authentication method
MPA -> SDK: 11. UCP::submitTokenAuthenticationMethod(authenticationMethod)
deactivate MPA
SDK -> WS: 12. submitTokenAuthenticationMethod(authenticationMethod, userSessionToken)
deactivate SDK
WS -> MDES: 13. submitAuthenticationMethod(authenticationMethod)
deactivate WS
MDES -> Issuer: 14. deliverAuthCode(authCode)
deactivate MDES
activate Issuer
Issuer -> User: 15. deliver authCode
deactivate Issuer
alt Provisioning finished - onProvisioningSuccess(paymentInstrumentId) was called
User -> MPA: 16. enter authCode
NOTE LEFT: User should have possibility to enter code\\n only when provisioning finished
activate MPA
MPA -> SDK: 17. UCP::submitTokenAuthenticationValue(authCode)
activate SDK
SDK -> WS: 18. submitTokenAuthenticationValue(authCode, userSessionToken)
activate WS
WS -> WS: 19. checkProvisioningStatus
WS -> MDES: 20. submitAuthenticationValue(authCode)
activate MDES
MDES -> MDES: 21. verify authCode
MDES --> WS: 22. response
WS --> SDK: 23. response
deactivate WS
SDK --> MPA: 24. response
deactivate SDK
deactivate MPA
MDES -> MDES: 25. createTokenMapping
MDES -> WS: 26. notifyTokenUpdated(Active)
deactivate MDES
activate WS
opt
WS ->>Issuer: 27. send Payment Token event
end
WS -> SDK: 28. deliverMessage(paymentTokenActive)
NOTE LEFT: See: Handle Message From Server
deactivate WS
SDK -> SDK: 29. updateTokenStatus
SDK -> MPA: 30. onPaymentInstrumentStatusChanged(id, status)
deactivate MPA
deactivate SDK
end
... Initial Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
@enduml
#### Handle Message From Server
In whole system there are processes where server needs to send messages to the device. Wallet Server has separate component which is responsible for sending messages to the device. This component uses different channels for message delivery. There are two channels: SSE(Server Sent Events) and RNS(Remote Notification Service). When message is ready for delivery, Wallet Server uses both channels to deliver such message. In first versions of Wallet Server only RNS was used, however sometimes messages were not delivered and to improve delivery new SSE channel was introduced. This channel helps in processes which start from the device and device expects message from the server. Moreover device checks messages which are still not delivered on actions where such messages are expected. Below diagram describes how delivery message process works and how needs to be handled on MPA side.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant "MPA" as MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "RNS" as RNS
opt
SDK -> WS: 1. callActionAfterWhichMessageIsExpected
WS --> SDK: 2. response
SDK -> WS: 3. openSSEConnection
end
WS -> WS: messageReadyForDelivery
opt If device has opened connection
WS -> SDK: 4. deliverUsingSSE
end
WS -> RNS: 5. deliverMessage
RNS --> WS: 6. response
RNS -> MPA: 7. deliverMessage
MPA -> MPA: 8. checkWalletSenderId
MPA-> SDK: 9. MDC:CloudMessage#process(pushData)
SDK -> SDK: 10. deduplicateMessage
SDK -> WS: 11. acknowledgeMessage
WS --> SDK: 12. response
SDK -> SDK: 13. processMessage
...Obtain pending messages...
MPA -> SDK: 14. someActionWhereMessageMayBeStillPending
SDK -> SDK: 15. doAction
SDK ->> WS: 16. getPendingMessages
WS --> SDK: 17. response
SDK -> SDK: do actions from 10 to 13
@enduml
#### Update RNS Token
Wallet Server is responsible for sending push notifications to the Wallet SDK. For that reason RNS token is passed to Wallet Server during pairing device or in some cases is obtained by SDK from MPA whenere is needed. However this token can be . MPA will be notified when token is being updated and then needs to obtain new RNS token and update via Wallet SDK on Wallet Server. Retrieving push notifications and RNS tokens is responsibility of the MPA.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Remote Notification Service" as RNS
activate RNS
RNS -> MPA: 1. onTokenRefresh
deactivate RNS
activate MPA
MPA -> MPA: 2. obtainNewToken(walletFirebase)
MPA -> SDK: 3. MDC::updateRegistrationToken(newRNSToken)
activate SDK
SDK -> WS: 4. updateRNSToken(deviceInstallationId, newRNSToken)
activate WS
WS -> WS: 5. updateRNSToken
WS --> SDK: 6. response
deactivate WS
SDK --> MPA: 7. result
deactivate SDK
deactivate MPA
deactivate RNS
@enduml
#### Profile Provisioning
During this process digitized card profile is delivered to the device. This process is triggered automatically after successful digitization where outcome is APPROVED or REQUIRE\_ADDITIONAL\_AUTHENTICATION. It is not possible to retry provisioning itself. To retry provisioning, previous token needs to be deleted and new digitization called hence when SDK reports that provisioning has failed then given token is automatically deleted and User can perform digitization once again. During process there is few point of failures and provisioning can be not finished at all. In this scenario Payment Tokens which are not provisioned for long period of time are delete by Wallet Server (see Removing Not Provisioned Tokens). From User perspective it can be good approach to treat digitization and provisioning as one process and inform User about steps(if User has to wait long time without any information then can treat this as some failure). From MPA perspective can be also good approach to wait for provisioning status as long as User stays on view dedicated to it. If User wants to cancel the process because provisioning status is not available for long period of time it is recommended to delete Payment Token(see Delete Payment Token via SDK) once User click cancel or back. Thanks to deletion, new digitization can be called and User does not have to wait until Payment Token is deleted by Wallet Server due to lack of provisioning.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
MDES->WS: 1. sendRemoteNotificationMessage(mdesRemoteMessage)
activate MDES
deactivate MDES
activate WS
WS-> SDK: 2. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK-> MDES: 3. provision
activate MDES
MDES --> SDK: 4. response(cardProfile)
SDK-> MDES: 5. notify provisioning result
MDES --> SDK: 6. response
deactivate MDES
SDK -> SDK: 7. store card profile
SDK -> WS: 8. confirmProvisioningStatus(SUCCESS/FAILURE)
activate WS
alt FAILURE
WS -> MDES: 9. deleteToken
activate MDES
MDES --> WS: 10. response
deactivate MDES
WS --> SDK: 11. response
SDK -> SDK: 12. deleteToken
SDK -> MPA: 13. onProvisioningFailure
activate MPA
MPA -> User: 14. please try again
deactivate MPA
else SUCCESS
WS --> SDK: 15. response
deactivate WS
SDK -> MPA: 16. onProvisioningSuccess(paymentInstrument)
deactivate SDK
activate MPA
MPA -> User: 17. card digitized successfully
deactivate MPA
end
@enduml
#### Getting Asset
Every field which's name consists of *assetId* is an identifier to some static asset. This asset can be:
- Card art
- Mastercard brand logos
- Issuers's logos
- Terms and Conditions
There are different types of assets and multiple formats may be supported. For example a single image may be supported in various file formats or variant sizes and most appropriate format to use for a particular device.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "MDES" as MDES
MPA -> SDK: 1. UCP::getAsset(assetId)
activate SDK
SDK -> WS: 2. getAsset(assetId)
activate WS
WS -> MDES: 3. getAsset(assetId)
activate MDES
MDES --> WS: 4. response(content)
deactivate MDES
WS --> SDK: 5. response(content)
deactivate WS
SDK --> MPA: 6. result(content)
deactivate SDK
@enduml
#### Transaction Credentials Replenishment
Transaction Credentials are unique per transactions keys that are used to calculate cryptograms in transactions. Each set of credentials is linked with a unique Application Transaction Counter (ATC). Each set of credentials can only be used for one transaction. There is a limit (set on MDES onboarding) of transaction credentials stored on device.
##### Transaction Credentials - Automatic Replenishment
After every transaction Wallet SDK checks if number of transaction credentials is below, . If yes then SDK will call replenish. During replenish process transaction credentials are being delivered to mobile
##### Transaction Credentials - Initial Replenishment
Initial replenishment is process which starts directly after successful token activation. Wallet SDK is notified by Wallet Server using push notification or refreshing payment instruments. A.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
WS -> SDK: 1. notifyTokenUpdated(Active)
activate WS
deactivate WS
activate SDK
alt Request session if required
SDK-> MDES: 2. requestSession
activate MDES
MDES--> SDK: 3. response
MDES-> WS: 4. sendRemoteNotificationMessage(mdesRemoteMessage)
deactivate MDES
activate WS
WS-> SDK: 5. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK-> MDES: 6. replenish
activate MDES
MDES-> MDES: 7. checkIfPaymentTokenIsActive
MDES-->SDK: 8. response(transactionCredentials)
deactivate MDES
SDK -> MPA: 9. onReplenishSuccess(paymentInstrument)
deactivate SDK
@enduml
##### Transaction Credentials - Manual Replenishment
There are scenarios when automatic replenish is not possible and after some number of transactions, transaction credentials number will decrease to 0. In such case MPA should handle NO\_TRANSACTION\_CREDENTIALS error from transaction listener, show user proper alert and call replenish method manually. MPA can also check number of transaction credentials at any other time.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES as MDES
MPA -> SDK: 1. UCP::replenishCredentials(paymentInstrumentId)
activate MPA
deactivate MPA
activate SDK
alt Request session if required
SDK-> MDES: 2. requestSession
activate MDES
MDES--> SDK: 3. response
MDES-> WS: 4. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS-> SDK: 5. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK-> MDES: 6. replenish
activate MDES
MDES-> MDES: 7. checkIfPaymentTokenIsActive
MDES-->SDK: 8. response(transactionCredentials)
deactivate MDES
SDK -> MPA: 9. onReplenishSuccess(paymentInstrument)
deactivate SDK
@enduml
#### Transacting
Wallet SDK provides functionalities to make contactless payments (using HCE) and e-commerce payments.
##### Contactless Transaction
CDCVM and on how transaction is started, user experience is different and MPA should interact with Wallet SDK in different way. The final decision about transaction processing belongs to MPA. Wallet SDK provides transaction information and based on that and User authentication, MPA can advise to proceed, decline or require authentication(if User should be authenticated but was not). For contactless transaction Wallet SDK provides result of transaction. This result is only from the communication between and Terminal. Transaction Processing with is done separately (see Transaction Processing). Also after every contactless transaction, Transaction Credentials Replenishment is performed automatically by SDK if needed(see Transaction Credentials - Automatic Replenishment).
NOTE: The way of authentication depends on MPA. For transaction User may also choose specific card. If no card is chosen, SDK will use the one which is set as default for contactless payments. Whenever user is authenticated or chose card for payment MPA should pass this information when *onContactlessPaymentStarted* is called.
As was described above, the final decision(PROCEED, DECLINE, AUTHENTICATION\_REQUIRED) for given transaction is taken on MPA side based on transaction information and User authentication. Because of that reason there could be different scenarios which may occur and transaction experience will be single or double tap.
Sample scenarios:
- User can be already authenticated and if MPA will not decline transaction then will be processed as single tap,
- velocity check counters can be applied and even if User was not authenticated MPA can decide to proceed transaction without authentication, taking decision based on transaction information,
- User was not authenticated but MPA recognised transaction as authentication needed. MPA returns AUTHENTICATION\_REQUIRED decision and and SDK informs MPA that authentication is needed.
**Contactless Transaction with MasterCard Token**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "HostApduService" as HAS
participant "Wallet SDK" as SDK
participant Terminal as TER
opt User selects particular card for payment
MPA -> User: 1. showCards
activate MPA
User -> MPA: 2. selectCard
deactivate MPA
end
User -> MPA: 3. pay
User -> TER : 4. contactless 1st tap
activate TER
loop
TER -> HAS: 5. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 6. UCP::Pay#processHceApduCommand(apdu, extras)
activate SDK
group Select PPSE
SDK -> MPA: 7. onContactlessPaymentStarted()
activate MPA
MPA -> MPA: 8. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 9. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 10. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 11. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
deactivate MPA
end
end
group Generate AC command
SDK -> MPA: 12. getFinalDecisionForTransaction(isUserAuthenticated,recommendedAdvice, trxInfo)
activate MPA
MPA -> MPA: 13. checkTrxAndAuthentication
MPA --> SDK: 14. result(advice)
deactivate MPA
end
SDK --> HAS: 15. responseApdu
HAS --> TER: 16. responseApdu
deactivate HAS
end
alt advice=AUTHENTICATION\_REQUIRED
SDK -> MPA: 17. onAuthRequiredForContactless(paymentInstrument, trxInfo)
activate MPA
MPA -> User: 18. show authentication view with trx info
User -> MPA: 19. authenticate
User -> TER: 20. contactless 2nd tap
loop
TER -> HAS: 21. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 22. UCP::Pay#processHceApduCommand(apdu, extras)
group Select PPSE
SDK -> MPA: 23. onContactlessPaymentStarted()
MPA -> MPA: 24. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 25. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 26. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 27. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
end
end
group Generate AC command
SDK -> MPA: 28. getFinalDecisionForTransaction(isUserAuthenticated=true,recommendedAdvice, trxInfo)
MPA -> MPA: 29. checkTrxAndAuthentication
MPA --> SDK: 30. result(PROCEED)
end
SDK --> HAS: 31. responseApdu
HAS --> TER: 32. responseApdu
deactivate HAS
deactivate TER
end
end
SDK -> MPA: 33. onContactlessPaymentCompleted(paymentInstrument, trxInfo, trxResult)
deactivate SDK
MPA -> User: 34. show trx info view
deactivate MPA
...Transaction Processing ...
note over HAS #1C1E3F: See Transaction Processing diagram
...Transaction Credentials Automatic Replenishment ...
note over HAS #1C1E3F: See Transaction Credentials Automatic Replenishment diagram
@enduml
**Contactless Transaction with Visa Token**
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam maxMessageSize 120
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "HostApduService" as HAS
participant "Wallet SDK" as SDK
participant Terminal as TER
participant "VTS Backend" as VTS
User -> MPA: tap&pay on Terminal or launch MPA
MPA -> SDK: initialize MDC SDK & UCP SDK
... VTS SDK initialization ...
SDK -> SDK: VTS#initialize
alt Android >= 11
SDK -> SDK: VTS#VerifyApps offline
alt VTS#VerifyApps success
SDK -> SDK: VTS#enableOfflinePayments()
SDK -> MPA: onPaymentAllowed
else VTS#VerifyApps failure
...All Visa card payments will finish with failure ...
end
else Android < 11
SDK -> VTS: VTS#DPELogin online
alt VTS#DPELogin success
VTS -> SDK: response(dpeLoginSession)
SDK -> MPA: onPaymentAllowed
else VTS#DPELogin failure
... all Visa card payments will finish with failure ...
end
end
opt User selects particular card for payment
MPA -> User: 1. showCards
activate MPA
User -> MPA: 2. selectCard
deactivate MPA
end
User -> MPA: 3. pay
User -> TER : 4. contactless 1st tap
activate TER
loop
TER -> HAS: 5. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 6. UCP::Pay#processHceApduCommand(apdu, extras)
SDK -> SDK: Recognize Visa Card and verify if Payment Allowed\\nBreaks
alt Payment using Visa Card and VTS not allow to payment
SDK --> MPA: onContactlessPaymentAborted(PAYMENT\_NOT\_ALLOWED)\\nMPA must wait for onPaymentAllowed callback
destroy MPA
end
activate SDK
group Select PPSE
SDK -> MPA: 7. onContactlessPaymentStarted()
activate MPA
MPA -> MPA: 8. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 9. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 10. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 11. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
deactivate MPA
end
end
group Generate AC command
SDK -> MPA: 12. getFinalDecisionForTransaction(isUserAuthenticated,recommendedAdvice, trxInfo)
activate MPA
MPA -> MPA: 13. checkTrxAndAuthentication
MPA --> SDK: 14. result(advice)
deactivate MPA
end
SDK --> HAS: 15. responseApdu
HAS --> TER: 16. responseApdu
deactivate HAS
end
alt advice=AUTHENTICATION\_REQUIRED
SDK -> MPA: 17. onAuthRequiredForContactless(paymentInstrument, trxInfo)
activate MPA
MPA -> User: 18. show authentication view with trx info
User -> MPA: 19. authenticate
User -> TER: 20. contactless 2nd tap
loop
TER -> HAS: 21. processCommandApdu(commandApdu, extras)
activate HAS
HAS -> SDK: 22. UCP::Pay#processHceApduCommand(apdu, extras)
group Select PPSE
SDK -> MPA: 23. onContactlessPaymentStarted()
MPA -> MPA: 24. checkIsUserAuthenticated
alt isAuthenticated=true
MPA -> SDK: 25. UCP::Pay#setUserAuthenticatedForPayment(paymentInstrumentId, pin?)
end
alt selectedCard == null
SDK -> SDK: 26. useDefaultPaymentInstrumentForContactless
else selectedCard != null
MPA -> SDK: 27. UCP::Pay#selectForPayment(selectedPaymentInstrumentId)
end
end
group Generate AC command
SDK -> MPA: 28. getFinalDecisionForTransaction(isUserAuthenticated=true,recommendedAdvice, trxInfo)
MPA -> MPA: 29. checkTrxAndAuthentication
MPA --> SDK: 30. result(PROCEED)
end
SDK --> HAS: 31. responseApdu
HAS --> TER: 32. responseApdu
deactivate HAS
deactivate TER
end
end
SDK -> MPA: 33. onContactlessPaymentCompleted(paymentInstrument, trxInfo, trxResult)
deactivate SDK
MPA -> User: 34. show trx info view
deactivate MPA
...Transaction Processing ...
note over HAS #1C1E3F: See Transaction Processing diagram
...Transaction Credentials Automatic Replenishment ...
note over HAS #1C1E3F: See Transaction Credentials Automatic Replenishment diagram
@enduml
##### E-commerce transaction
E-commerce transaction can be processed using DSRP. Every DSRP transaction has to be authenticated. Depending on implementation e-commerce payment can be preceded with one time password authentication or just device level authentication.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
box "Consumer mobile android device" #white
participant "Merchant App" as MerchantApp
participant MPA
participant "Wallet SDK" as SDK
end box
participant Merchant
participant "Wallet Server" as WS
participant MDES
participant Issuer
participant "Payment Gateway" as PG
User -> MerchantApp: 1. pay
activate MerchantApp
MerchantApp -> Merchant: 2. startTransaction
activate Merchant
Merchant --> MerchantApp: 3. response(transactionId,\\r unpredictableNumber)
deactivate Merchant
MerchantApp -> MPA: 4. getDsrpData(transactionId, trxInfo)
deactivate MerchantApp
activate MPA
alt One Time Password
MPA -> User: 5. select payment instrument
User -> MPA: 6. payment instrument
MPA -> SDK: 7. UCP::requestAuthCodeForPayment(transactionId \\ras authenticationRequestId)
activate SDK
SDK -> WS: 8. requestAuthenticationCodeForPayment(authenticationRequestId)
activate WS
WS -> MDES: 9. requestAuthenticationCodeForPayment(authenticationRequestId)
activate MDES
MDES -> Issuer: 10. sendAuthenticationCode
activate Issuer
Issuer --> MDES: 11. response
MDES --> WS: 12. response
deactivate MDES
WS --> SDK: 13. response
deactivate WS
SDK --> MPA: 14. result
Issuer -> User: 15. sendAuthenticationCode(authenticationCode)
deactivate Issuer
User -> MPA: 16. provide authentication code
MPA -> SDK: 17. UCP::validateAuthenticationCodeForPayment(authenticationCode,\\r transactionId)
SDK -> WS: 18. validateAuthenticationCodeForPayment(authenticationCode,\\r authenticationRequestId)
WS -> MDES: 19. authenticate(authenticationCode,\\r authenticationRequestId)
MDES --> WS: 20. response
deactivate MDES
WS -> WS: 21. createDigitalSignature(authenticationRequestId)
WS --> SDK: 22. response(digitlSignature)
SDK --> MPA: 23. result(digitalSignature)
else Device Level Auth
MPA -> User: 24. show authentication view
User -> MPA: 25. authenticate
end
MPA -> SDK: 26. UCP::setUserAuthenticatedForPayment(id, pin?)
MPA -> SDK: 27. UCP::processDsrpTransaction(id, trxInfo)
SDK --> MPA: 28. result(dsrpData)
MPA --> MerchantApp: 29. result(dsrpData)
activate MerchantApp
MerchantApp -> MerchantApp: 30. encryptPaymentDataForTransit(dsrpData)
MerchantApp -> Merchant: 31. finishTransaction(encryptedPaymentData, \\rdigitalSignature?, transactionId)
activate Merchant
opt
Merchant -> Merchant: 32. validateSignature
note right: this check is needed to proof that given transactionId\\n\\r was preceded with OTP
end
Merchant -> PG: 33. processPayment(pan, exp, cryptogram)
activate PG
PG --> Merchant: 34. response
Merchant --> MerchantApp: 35. response
MerchantApp -> User: 36. show result
deactivate PG
deactivate Merchant
deactivate MerchantApp
@enduml
##### Transaction Processing
Transaction Processing starts after contactless communication between terminal and MPA in case of contactless payment or after payment gateway transaction authorization initiation in case of e-commerce payment. After authorization MDES notifies Wallet Server about the result of the authorization and sends transaction information. Transaction information is sent to MPA.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Terminal/PG" as TER
participant "Payment Network" as PN
participant MDES
participant Issuer
TER -> PN: 1. authorizeTransaction(tokenPAN, cryptogram)
activate PN
activate TER
PN -> MDES: 2. detokenize
activate MDES
MDES -> MDES: 3. lookup token mapping
MDES --> PN: 4. response(PAN)
deactivate MDES
PN -> Issuer: 5. authorize(PAN)
activate Issuer
Issuer --> PN: 6. response
deactivate Issuer
PN --> TER: 7. response
deactivate TER
PN -> MDES: 8. storeTransactionDetails
deactivate PN
activate MDES
MDES -> WS: 9. pushTransactionDetails
deactivate MDES
activate WS
alt store transaction enabled
WS -> WS: 10. storeTransaction
end
opt
WS ->>Issuer: 11. send transaction event
end
WS -> SDK: 12. deliverMessage(trxInfo)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> MPA: 13. onNewTransaction(trxDetails)
deactivate SDK
activate MPA
MPA -> User: 14. showSystemNotification(trxDetails)
deactivate MPA
@enduml
#### Setting Defaults for Payment
SDK manages default Payment Instrument for contactless payments. After digitization, if there is no default Payment Instrument, SDK sets digitized Payment Instrument after activation as default. In case where there are more than one active Payment Instruments and current default Payment Instrument is deleted or suspended, the SDK will set first active Payment Instrument as default. Default Payment Instrument can be changed at any time. Only active Payment Instrument can be set as default.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
MPA->User: 1. payment instrument list
activate MPA
User->MPA: 2. choose default for contactless payment)
MPA->SDK: 3. UCP::setDefaultForContactless(paymentInstrumentId)
activate SDK
SDK-> SDK: 4. storeDefault
SDK-->MPA: 5. result
deactivate MPA
deactivate SDK
@enduml
#### Login On Wallet Server
User data are protected by User session token which is issued by Wallet Server after providing authentication factor. Authentication factor is provided first in pairing device and then session is created. Since session has limited period of validity, it needs to be refreshed using login on Wallet Server methods.
Login on Wallet Server using Trusted Identity
. During login process Wallet Server checks if given device still exists, if not then responds with CANT\_FIND\_DEVICE status which is interpreted on SDK side as given device is deleted and all local data stored on SDK side are cleared.
Since MDC 2.14.5 for devices which are already paired, Wallet SDK will try to asynchronously register device in new delivery message service. To make it possible *CloudMessagingRegistrationProvider* needs to be implemented and provided within setup.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as Issuer
MPA -> SDK: 1. invoke API
activate MPA
activate SDK
SDK -> WS: 2. invoke API
activate WS
WS --> SDK: 3. response(USER\_UNATHORIZED)
deactivate WS
SDK --> MPA: 4. result(USER\_UNATHORIZED)
MPA->User: 5. show authenticate view
User->MPA: 6. put authentication data
MPA->Issuer: 7. authenticate
activate Issuer
Issuer -> Issuer: 8. generateTrustedIdentity - signed user id
Issuer --> MPA: 9. response(trustedIdentity)
deactivate Issuer
MPA-> SDK: 10. MDC::loginByTrustedIdentity(trustedIdentity)
SDK-> WS: 11. loginByTrustedIdentity(trustedIdentity)
alt Device not registered in new delivery message service
SDK -> MPA: 12. CloudMessagingRegistrationProvider::getRegistrationToken
SDK ->> WS: 13. registerDeviceForNewMessageDelivery(cloudMessageToken)
WS --> SDK: 14. response
end
activate WS
WS -> WS: 15. check if device exists
alt device exists
WS-> WS: 16. verify trusted identity
WS --> SDK: 17. response(userSessionToken)
SDK -> SDK: 18. store(userSessionToken)
SDK-->MPA: 19. result
MPA -> SDK: 20. invoke API
else device not exists
WS --> SDK: 21. response(CANT\_FIND\_DEVICE)
deactivate WS
SDK -> SDK: 22. clearAllLocalData
SDK --> MPA: 23. result(CANT\_FIND\_DEVICE)
deactivate MPA
deactivate SDK
... Pair device ...
note over MPA, WS #1C1E3F: See Pairing Device diagram
MPA -> SDK: 24. invoke API
end
@enduml
#### Getting Cards
When cards are already placed on Wallet Server, then they can be displayed to User in the application. Cards have identifiers which can be used e.g. for digitization.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
MPA->SDK: 1. MDC::getAllCards
activate MPA
activate SDK
SDK -> WS: 2. getAllCards(userSessionToken)
WS --> SDK: 3. response(userCards)
deactivate WS
SDK --> MPA: 4. result(cardList)
deactivate SDK
deactivate MPA
@enduml
#### Getting Payment Intruments
After digitization process, payment instrument is stored in VCP SDK module of Wallet SDK. Payment instrument in context of VCP SDK is digitized card and contains i:
- id (specified id which helps MPA to identify payment instrument which was digitized from MPA),
- status,
- transaction credentials count,
- paymentTokenId etc. .
MPA can get information about all Payment Instruments from the Wallet SDK at any time. Payment instruments will be retrieved only from local storage that is part of SDK. Payment Tokens for Payment Instruments can be refreshed/pulled from Wallet Server on demand. This scenario should be considered only when User e.g. makes swipe to refresh.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant "Issuer" as IS
MPA->SDK: 1. UCP::getAllPaymentInstruments(refresh)
activate MPA
alt refresh = true
activate SDK
SDK -> WS: 2. getAllPaymentTokens(userSessionToken)
activate WS
WS -> SDK: 3. response(devicePaymentTokens)
deactivate WS
SDK -> SDK: 4. updateLocalStorage
end
SDK --> MPA: 5. result(paymentInstrumentList)
deactivate SDK
deactivate MPA
@enduml
#### Getting Transaction History
. Transactions are returned in corresponding parts for better user experience. If next part is available then response from previous part contain information needed for requesting next part. MPA should check if next part is not empty and then make another request.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
loop next != null
MPA->SDK: 1. MDC::getTransactionsHistory(filters, next?)
activate MPA
activate SDK
SDK -> WS: 2. getTransactionHistory(filters, next?, userSessionToken, ...)
activate WS
WS -> SDK: 3. response(transactionHistoryList, next?)
deactivate WS
SDK --> MPA: 4. result(transactionHistoryList, next?)
deactivate SDK
deactivate MPA
end
@enduml
#### Payment Token Lifecycle Management via SDK
Payment Token lifecycle management can be done via SDK.
##### Delete Payment Token via SDK
Payment Token can be deleted using SDK.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant Issuer
User -> MPA: 1. Delete payment token
activate MPA
MPA -> SDK: 2. UCP::delete(paymentInstrumentId, reason)
deactivate MPA
activate SDK
SDK -> WS: 3. deletePaymentToken(userSessionToken, paymentTokenId, reason)
activate WS
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
deactivate MDES
WS --> SDK: 7. response
opt
WS ->> Issuer: 8. send Payment Token event
end
deactivate WS
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
MPA --> User: 17. show update view
deactivate MPA
@enduml
#### Errors Reporting
#### Device Unpairing
Unpairing device clears all modules data and report that fact only if possible to server. If server receives this signal then removes all device data including provisioned Payment Tokens. If not then data are cleared locally only - similar like during app uninstallation. This can be used for scenario when MPA does not want to use SDK at all or for scenario when MPA supports switching between users accounts on the same installation. If MPA detects that new User is trying to log into application in case when previous had digitized cards, immediately should clear all data from previous, since SDK stores data in context of one User only.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
MPA -> SDK: 1. MDC::unpairDevice
activate MPA
activate SDK
opt
SDK -> WS: 2. unpairDevice
activate WS
WS --> SDK: 3. response
deactivate WS
end
SDK -> SDK: 4. clearAllData
SDK --> MPA: 5. result
deactivate SDK
deactivate MPA
@enduml
#### MDES Initiated
This section describes use cases which are initiated from MDES.
##### Re-digitization
Re-digitization process can be triggered by MDES for several use cases:
**Token Expiry**
One month before token expiry MDES will request for redigitization.
**Attribute Change**
Issuer may perform an attribute change at the BIN account-range level impacting theri MDES enabled ranges. Some device tokens may need to have their data refreshed to match the new attributes.
**BIN Account-Range Split**
Issuer may perform a BIN account-range split. Some existing tokens may need to be updated to ensure that they are linked to the correct funding BIN account ranges internally.
**PAN Update in Different Account Range**
Issuer may update existing PAN with new Pan in a different BIN account range.
For above cases:
- token unique reference remains the same
- token expiration date is extended by three years from the date of redigitization
After successful redigitization process transaction credentials replenishment is called in case where Payment Token is active.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
MDES -> WS: 1. notifyTokenUpdated(redigitize=true)
activate MDES
activate WS
WS -> MDES: 2. redigitize
MDES --> WS: 3. response
WS --> MDES: 4. response
deactivate MDES
deactivate WS
MDES->WS: 5. sendRemoteNotificationMessage(mdesRemoteMessage)
activate MDES
deactivate MDES
activate WS
WS-> SDK: 6. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK-> MDES: 7. provision(redigitize=true)
activate MDES
MDES --> SDK: 8. response(cardProfile)
SDK-> MDES: 9. notify provisioning result(redigitize=true)
MDES --> SDK: 10. response
SDK -> WS: 11. confirmReProvisioningStatus(SUCCESS/FAILURE)
alt FAILURE
WS -> WS: 12. markRedigitizationAsFailed
note left: redigitization process will be retried after some period of time
SDK -> MPA: 13. onReProvisioningFailure(paymentInstrument)
else SUCCESS
SDK -> SDK: 14. clearTransactionCredentials
SDK -> MPA: 15. onReProvisioningSuccess(paymentInstrument)
deactivate SDK
MDES -> WS: 16. notifyTokenUpdated(redigitized=false)
deactivate MDES
activate WS
opt
WS ->> Issuer: 17. send Payment Token event
end
WS -> SDK: 18. deliverMessage(PAYMENT\_TOKEN\_INFO\_CHANGE(redigitized=true))
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: 19. replenish
... Automatic Replenishment ...
note over SDK, MDES #1C1E3F: Just after reprovisioning transaction credentials initial replenishment is performed by SDK\\r. See Transaction Credentials Initial Replenishment diagram
end
@enduml
#### Wallet Server Initiated
Since important processes are asynchronous in MDES and there are many point of failures, wallet server provides additional functionalities to resolve some failure scenarios by running some operations on own side.
##### Removing Not Provisioned Tokens
Wallet Server checks periodically DEVICE Payment Tokens and verify if provisioning is completed. These Payment Tokens which have provisioning status in progress for long period of time are deleted automatically and from User perspective process needs to be started again. By default this period is set to 1 hour but can be modified.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
WS -> WS: 1. find not provisioned payment tokens for a\\r long period of time
activate WS
loop Not provisioned payment tokens for a long period of time
WS -> MDES: 2. Delete token
activate MDES
MDES -> MDES: 3. Delete token mapping
MDES --> WS: 4. response
deactivate MDES
opt
WS ->> Issuer: 5. send Payment Token event
end
WS -> SDK: 6. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
alt Request session if required
SDK -> MDES: 7. request session
activate MDES
MDES --> SDK: 8. response
MDES -> WS: 9. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 10. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 11. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 12. response
deactivate MDES
SDK -> SDK: 13. Delete transaction credentials, card profile
SDK -> MPA: 14. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
#### Wallet Server Admin API Initiated
This section describes use cases which are initiated from Wallet Server Admin Panel.
##### Admin Card Deletion
During this process all data related to given card are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
participant Issuer
AP -> WS: 1. deleteCard(cardId)
activate WS
activate AP
WS -> WS: 2. deleteCard
WS --> AP: 3. response
deactivate AP
loop All Payment Tokens for card
WS -> MDES: 4. Delete token
activate MDES
MDES -> MDES: 5. Delete token mapping
MDES --> WS: 6. response
deactivate MDES
opt
WS ->>Issuer: 7. send Payment Token event
end
WS -> SDK: 8. deliverMessage(paymentTokenDelete)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
alt Request session if required
SDK -> MDES: 9. request session
activate MDES
MDES --> SDK: 10. response
MDES -> WS: 11. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 12. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 13. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 14. response
deactivate MDES
SDK -> SDK: 15. Delete transaction credentials, card profile
SDK -> MPA: 16. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
end
deactivate MPA
@enduml
##### Admin Device Deletion
During this process all data related to given device are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deleteDevice(deviceInstallationId)
activate AP
activate WS
WS --> AP: 2. response
deactivate AP
loop All Payment Tokens for given device
WS -> MDES: 3. delete token
activate MDES
MDES --> WS: 4. response
deactivate WS
deactivate MDES
end
@enduml
##### Admin Token Deletion
Payment Token can be deleted via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deletePaymentToken(paymentTokenId)
activate AP
activate WS
WS -> MDES: 2. Delete token
activate MDES
MDES -> MDES: 3. Delete token mapping
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->> Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenDeleted)
deactivate WS
activate SDK
NOTE LEFT: See: Handle Message From Server
deactivate MDES
alt Request session if required
SDK -> MDES: 8. request session
activate MDES
MDES --> SDK: 9. response
MDES -> WS: 10. sendRemoteNotificationMessage
deactivate MDES
activate WS
WS -> SDK: 11. deliverMessage(mdesRemoteMessage)
NOTE LEFT: See: Handle Message From Server
deactivate WS
end
SDK -> MDES: 12. delete(tokenUniqueReference)
activate MDES
MDES --> SDK: 13. response
deactivate MDES
SDK -> SDK: 14. Delete transaction credentials, card profile
SDK -> MPA: 15. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
MPA --> User: 16. show update view
deactivate MPA
@enduml
##### Admin Token Suspension
Payment Token can be suspended via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
participant Issuer
AP -> WS: 1. suspendToken(paymentTokenId)
activate WS
activate AP
WS -> MDES: 2. suspend token
activate MDES
MDES -> MDES: 3. Suspend token
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->> Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenSuspend)
NOTE LEFT: See: Handle Message From Server
deactivate WS
activate SDK
SDK -> SDK: 8. suspend
SDK -> MPA: 9. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
deactivate MPA
@enduml
##### Admin Token Unsuspension
Payment Token can be unsuspended via admin panel.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. unsuspendToken(paymentTokenId)
activate WS
activate AP
WS -> MDES: 2. unsuspend token
activate MDES
MDES -> MDES: 3. Unsuspend token
MDES --> WS: 4. response
deactivate MDES
WS --> AP: 5. response
deactivate AP
opt
WS ->>Issuer: 6. send Payment Token event
end
WS -> SDK: 7. deliverMessage(paymentTokenUnsuspend)
deactivate WS
activate SDK
SDK -> SDK: 8. activate
SDK -> MPA: 9. onPaymentInstrumentStatusChanged(id, status)
deactivate SDK
deactivate MPA
... Replenishment ...
note over SDK, MDES #1C1E3F: Just after token activation transaction credentials replenishment is performed by SDK\\r. See Transaction Credentials Automatic Replenishment diagram
@enduml
##### Admin User Deletion
During this process all data related to given User are deleted. Payment Tokens are deleted asynchronously.
@startuml
skinparam ParticipantPadding 30
skinparam BoxPadding 30
skinparam noteFontColor #FFFFFF
skinparam noteBackgroundColor #1C1E3F
skinparam noteBorderColor #1C1E3F
skinparam noteBorderThickness 1
skinparam sequence {
ArrowColor #1C1E3F
ArrowFontColor #1C1E3F
ActorBorderColor #1C1E3F
ActorBackgroundColor #FFFFFF
ActorFontStyle bold
ParticipantBorderColor #1C1E3F
ParticipantBackgroundColor #1C1E3F
ParticipantFontColor #FFFFFF
ParticipantFontStyle bold
LifeLineBackgroundColor #1C1E3F
LifeLineBorderColor #1C1E3F
}
actor User
participant MPA
participant "Wallet SDK" as SDK
participant "Wallet Server" as WS
participant MDES
participant "Admin Panel" as AP
AP -> WS: 1. deleteUser(userId)
activate AP
activate WS
WS -> WS: 2. delete cards, devices
WS --> AP: 3. response
deactivate AP
loop All Payment Tokens for given User
WS -> MDES: 4. delete token
activate MDES
MDES --> WS: 5. response
deactivate WS
deactivate MDES
end
@enduml
#### Summary of Changes
This section describes changes introduced in next version based on time
##### Version 2.0
- Base version of the document describing VCP Solution for cards
##### Version 2.1
- Introduced *onContactlessPaymentStarted* in Contactless Transaction use case
- Added new use case: Handle Message From Server
- Introduced provider for *cloudMessageRegistrationToken* in Login On Wallet Server use case
- Updated all use cases with new way of message delivery from server
- Added sending Payment Token event when token is created or updated
# Technical documentation
You can find technical documentation on this site.
# Technical Documentation VCP SDK
## VCP SDK Introduction
### Basic abbreviations and definitions
| **Field** | **Description** |
|---|
| CDCVM | Consumer Device Cardholder Verification Method |
| CVM | Cardholder Verification Method |
| Contactless | Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA,
and then to VCP SDK. HCE support is required for contactless transactions
|
| DSRP | Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with
the remote merchant system. HCE support is not required for DSRP transactions
|
| FCM | Firebase Cloud Messaging
|
| HCE | Host Card Emulation |
| IBAN | Bank Account Number |
| MCBP | Mastercard Cloud Based Payments |
| MDC | Mobile Data Core. Verestro core library.
|
| MPA | Mobile Payment Application - an application that uses VCP SDK for payments
|
| NFC | Near Field Communication |
| One tap | Flow in a contactless transaction, in which the consumer after authentication(using the PIN, fingerprint, etc.)
taps the device to POS to start exchanging data
|
| PAN | Primary account number. Know as a card number. |
| Payment Instrument | Model keeping all data considering entity used for payments
|
| POS | Point Of Sale |
| QRC | QR Code transactions - allows consumer generate QR code to present to a merchant,
who then scans it to take payment
|
| SUK | Single Use Key - unique credential used for single transaction for Mastercard
|
| LUK | Limited Use Key - payment credential for usage with Visa
|
| Two tap | Flow in a contactless transaction, in which consumer firstly taps device to POS,
authenticates(using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data
|
| TVC | Token Verification Code |
| EWS | External Wallet Server |
| VCP
| Verestro Cloud Payment |
### What is VCP SDK?
The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.payment
### How VCP SDK works?
Provides methods to manage digitization using main domains:
- IBANs
- Payment
- Cloud Messaging
- Cards
- External Wallet Server
Depending on the selected payment instrument source (Card, Iban, External Wallet Server) VCP SDK allows to digitize it and provide methods for the payment process.
Usage of the following domains depends on client requirements.
### Versioning and backward compatibility
SDK version contains three digits. For example: 1.0.0.
- .
- Second version digit tracks new, not compatibility-breaking changes in public API of SDK. It is optional to update the application code when this digit is incremented.
- Third version digit tracks internal changes in SDK. No updates in application code are necessary to update to the version, which has this number incremented.
Changes not breaking compatibility:
- Adding a new optional interface to SDK setup
- Adding a new method to any domain
- Adding a new ENUM value to input or output
-
##
###
The minSdkVersion must be at least 23 (Android 6.0). The application must use AndroidX.
SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system.
**The username and password are provided by Verestro.**
| ```
repositories{
maven {
credentials {
username ""
password ""
}
url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
//if the sync time takes too long, add filters to match the repository with specific modules as below
content {
includeGroupByRegex "pl.upaid.*"
includeGroup "com.mastercard"
includeGroup "com.visa" //Only when Visa is used
}
}
}
```
|
VCP SDK is available in two versions: debug and release.
Debug version is ended with appendix "-debug" in version name. Samples below:
**For release version:**
| ```
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
|
**For debug version:**
| ```
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}-debug'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}-debug'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
|
**Min SDK Version**
The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.
SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it.
###
VCP SDK Application Signing requirements
**Mastercard:**
There is no requirement related to Application signing.
**Visa:**
Both sandbox (test) and production environment require APK signed with valid key.
To add Application as Trusted in Visa services please provide Signing Key Certificate from chain in PEM format using below script:
```
keytool -exportcert -keystore your_apk_keystore.jks -alias your_keystore_key_alias -rfc -file certificate.pem
```
Output will be provided in *certificate.pem* file.
Please provide an result to Verestro representative with related *applicationId* (package).
**Note:** When using only Google Play signing key tests local tests related to Visa tokenization and payments will be not possible.
### VCP SDK Size
The size of SDK is dependent on its distribution system.
The table below shows the size of the module for the ask and bundle file.
****
- size from the table above is referred to release version;
-
###
####
####
Every of the described facades is divided into domains with different responsibilities. Available domains:
- IBANs
- Payment
- Cloud Messaging
- Cards
- External Wallet Server
- Assets (to review)
Every domain contains domain-related methods.
#### Error handling
Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods.
SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message.
**Note**: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.
| **Exception type** | **Exception class** | **Description** |
|---|
| SDK validation | ValidationException | Additional reason codes for ValidationException used in Mobile DC SDK |
| Backend exception | BackendException | Additional reason codes for BackendException used in Mobile DC SDK.
**Note:** Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain)
|
| SDK exception | UcpSdkException | Something went wrong on the SDK side, check the table below with possible reasons |
| Process related | - | As every process is different some methods could throw a specified exception
Types of possible exceptions are described in the method description
|
Additional BackendException reason codes:
| **Reason** | **Description**
|
|---|
| INTERNAL\_ERROR | Error occurred on server
|
| VALIDATION\_ERROR
| Client sent invalid data
|
| CRYPTOGRAPHY\_ERROR
| Error occurred during cryptography operation
|
| PAYMENT\_CARD\_PREDIGITIZE\_ERROR
| Predigitize of payment card failed
|
| PAYMENT\_IBAN\_PREDIGITIZE\_ERROR
| Predigitize of payment IBAN failed
|
| PAYMENT\_CARD\_DIGITIZE\_ERROR
| Digitize of payment card failed
|
| PAYMENT\_IBAN\_DIGITIZE\_ERROR
| Digitize of payment IBAN failed
|
| PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED
| Predigitize for payment card must be executed
|
| PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED
| Predigitize for payment IBAN must be executed
|
| CLIENT\_UNAUTHORIZED
| Client of the API is unauthorized
|
| USER\_UNAUTHORIZED
| User is unauthorized
|
| CANT\_FIND\_USER
| Cannot find user
|
| CANT\_FIND\_DEVICE
| Cannot find device
|
| CANT\_FIND\_IBAN
| Cannot find payment IBAN
|
| CANT\_FIND\_CARD
| Cannot find payment card
|
| CANT\_FIND\_PAYMENT\_TOKEN
| Cannot find payment token
|
| OPERATION\_NOT\_SUPPORTED
| Requested operation is not supported
|
| OPERATION\_NOT\_ALLOWED
| Requested operation is not allowed
|
| DEVICE\_TEMPORARILY\_LOCKED
| Device is temporarily locked
|
| DEVICE\_PERMANENTLY\_LOCKED
| Device is permanently locked
|
| INVALID\_PAN
| The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly
|
| MISSING\_EXPIRY\_DATE
| The expiry date is required for this product but was missing
|
| PAN\_INELIGIBLE
| The PAN is not in an approved account range for TSP
|
| DEVICE\_INELIGIBLE
| The device is not supported for use
|
| PAN\_INELIGIBLE\_FOR\_DEVICE
| The PAN is not allowed to be provisioned to the device because of Issuer rules
|
| PAN\_ALREADY\_PROVISIONED
| The PAN is already provisioned for this device
|
| IBAN\_INELIGIBLE
| The financial account does not have an associated account range in TSP
|
| PARALLEL\_REQUESTS\_ATTEMPTS
| Action is already processing. Please try again after the time included in headers
|
| INVALID\_JWS\_TOKEN | Specified JWS token is invalid |
Additional ValidationException reason codes:
| **Reason** | **Description** |
|---|
| INVALID\_SECURITY\_CODE
| Security code is empty
|
| INVALID\_LANGUAGE\_CODE
| Language code is empty
|
| INVALID\_PAYMENT\_INSTRUMENT\_ID
| Payment instrument id is empty |
UcpSdkException reason codes:
| **Reason** | **Description** |
|---|
| PUSH\_INVALID\_SOURCE
| Relates to push processing process. Push message should be consumed in another module
|
| PUSH\_INVALID\_PUSH\_CONTENT
| Cannot process push message. The message is invalid or some process failed
|
| PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND
| Cannot find default PaymentInstrument |
| PAYMENT\_INSTRUMENT\_NOT\_FOUND
| Selected PaymentInstrument cannot be found, is not digitized or active
|
| APPLICATION\_PROCESS\_NOT\_KILLED | Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process
|
####
#### Facade
The facade is an entry point to communication with VCP SDK.
Contains SDK initialization method and domains which allows for payment instrument management.
####
#### Method structure
Please read Mobile DC Documentation for details.
####
#### Multiple facade types
VCP SDK provides three public APIs with the same functionalities, the APIs are:
- UcpJavaApi for projects which use Java programming language.
- UcpKotlinApi for projects which use Kotlin programming language.
The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same.
This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark).
####
#### HceApduService registration
To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service.
Properly configured meta-data in service will also register an application as tap&pay ready.
Exemplary service below:
Below listing of the default source file hce\_apud\_service.xml:
Check if the application is set as default for payment.
| ```
fun isSystemDefault(): Boolean {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
return cardEmulation.isDefaultServiceForCategory(
WalletHceService::class.java,
CardEmulation.CATEGORY_PAYMENT
)
}
```
|
Request for set your application as default for payment - will show a dialog for the user to approve the changes.
| ```
fun requestForSystemDefault() {
val intent = Intent().apply {
action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
putExtra("component", WalletHceService::class.java)
putExtra("category", CardEmulation.CATEGORY_PAYMENT)
}
context.startActivity(intent)
}
```
|
If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.
| ```
fun registerAsOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.setPreferredService(
activity, ComponentName(activity, WalletHceService::class.java)
)
}
fun unregisterFromOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.unsetPreferredService(activity)
}
```
|
####
#### Models
##### PaymentInstrument
| **Parameter** | **Type** | **Description** |
|---|
| String | Id of payment instrument. For card it is cardId, for IBAN sha256Hex.
In the context of the External Wallet Server use tokenUniqueReference from MDES
|
| paymentTokenId | String | Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id |
| displayablePanDigits | String | Token last 4 digits which can be used to display
|
| paymentInstrumentStatus | PaymentInstrumentStatus | Enum with status of payment instrument.
|
| contactlessSupported | Boolean | Information if payment instrument supports contactless transactions.
|
| dsrpSupported | Boolean | Information if the payment instrument supports DSRP transactions.
|
| qrcSupported | Boolean | Information if the payment instrument supports QR transactions.
|
| onDeviceCvmSupported | Boolean | Information about supporting CVM on device.
|
| credentialsCount | Int | Amount of credentials that can be used for payments.
Always 0 for Visa Cards.
|
| isDefaultForContactlessPayment
| Boolean | Information if payment instrument is default for contactless payments.
|
| isDefaultForRemotePayment | Boolean | Information if payment instrument is default for remote payments.
|
| additionalAuthenticationRequired | Boolean
| Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods
|
| tokenLastFourDigits | String?
| Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| paymentInstrumentExpirationDate | String?
| Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| paymentInstrumentLastFourDigits
| String?
| Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| productConfig
| ProductConfig?
| Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately).
|
| provisioningStatus
| String
| Current state of provisioning process. One of:
IN\_PROGRESS - in case of waiting for *onProvisioningSuccess*(),
SUCCESS - when token is provisioned.
|
| paymentTokenExpirationDate | String? | Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled.
|
###
##### PaymentInstrumentStatus
| **Field** | **Description** |
|---|
| INACTIVE | Payment instrument is not , it can not be used for transactions.
The activation process depends on integration. Read the product overview for more information.
|
| ACTIVE | Payment instrument is active and it can be used for transactions.
|
| SUSPENDED | Payment instrument is suspended. |
| DELETED | Payment instrument is DELETED.
|
| UNKNOWN | Payment instrument status is unknown. |
#####
##### AdditionalAuthenticationMethod
| **Parameter** | **Type** | **Description** |
|---|
| id | String | Identifier of additional authentication method |
| name | String | Method name. One of:
OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER
|
| value | String | Value depends on method name. Described below. |
| issuerParameters | AuthMethodsIssuerParameters? | Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION |
####
##### Additional authentication method values:
| **Method** | **Value** | **Description** |
|---|
| `OTP_TO_CARDHOLDER_NUMBER` | Masked phone number
| Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number. |
| `OTP_TO_CARDHOLDER_EMAIL` | Masked email
| Email to Account holder’s email address. The value will be the Account holder’s masked email address. |
| `CARDHOLDER_TO_CALL_CUSTOMER_SERVICE` | Phone number
| Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service.
|
| `CARDHOLDER_TO_VISIT_WEBSITE` | Website URL
| Account holder to visit a website. The value will be the website URL.
|
| `CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION` | Application name
| (Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS.
|
| `ISSUER_TO_CALL_CARDHOLDER_NUMBER` | Masked phone number
| Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number.
|
| **Parameter** | **Type** | **Description** |
|---|
| mdes | AuthMethodsIssuerParametersMdes? | Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token |
| vts | AuthMethodsIssuerParametersVts? | Required for VTS Payment token |
####
##### AuthMethodsIssuerParametersMdes contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| android | AuthMethodsIssuerParametersMdesAndroid | Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device |
| ios | AuthMethodsIssuerParametersMdesIos | Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device |
####
##### AuthMethodsIssuerParametersMdesAndroid contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| action | String? | Name of the action to be performed |
| packageName | String? | The package name of the issuer's mobile app |
| extraTextValue | String? | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app |
##### AuthMethodsIssuerParametersMdesIos contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| deepLinkingUrl | String? | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. |
| extraTextValue | String? | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. |
##### AuthMethodsIssuerParametersVts contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| android | AuthMethodsIssuerParametersVtsAndroid? | Plain AuthMethodsIssuerParametersVtsAndroid object.
Required for Android devices |
| ios | AuthMethodsIssuerParametersVtsIos? | Plain AuthMethodsIssuerParametersVtsIos object.
Required for IOS devices |
##### AuthMethodsIssuerParametersVtsAndroid contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### AuthMethodsIssuerParametersVtsIos contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
#####
##### ContactlessTransactionInformation
| **Parameter** | **Type** | **Description** |
|---|
| currencyCode | ByteArray | Code of currency, that was used in transaction. Formatted in ISO 4271.
|
| amount | ByteArray | Transaction amount in bytes. Can be formatted as Int in pennies. |
| transactionRange | ContactlessTransactionRange | Type of transaction range.
|
| ContactlessRichTransactionType | Rich transaction type.
|
| ByteArray | Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset. |
**ContactlessTransactionRange**
| **Value** | **Description**
|
|---|
| LVT | Low value transaction |
| HVT | High value transaction
|
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| **Value** |
|---|
| PURCHASE |
| REFUND |
| CASH |
| TRANSIT |
| PURCHASE\_WITH\_CASHBACK |
| UNKNOWN |
##### DsrpTransactionInfo
| **Parameter** | **Type** | **Descruption** |
|---|
| amount | Long | Transaction amount |
| currencyCode | Int | |
| countryCode | Int | Code of country.
|
| issuerCryptogramType | String | Cryptogram type. |
##### TransactionAbortReason
| **Value** | **Description** |
|---|
| WALLET\_CANCEL\_REQUEST | Indicates that the wallet has requested a transaction cancellation during payment. |
| This indicates that a problem has been detected in the MChipEngine processing.
In some implementations, this can indicate badly formatted card profile data.
|
| This indicates incorrect terminal behavior.
|
| |
| . Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). |
| TERMINAL\_INACTIVITY\_TIMEOUT | There is a problem with communication between the terminal and payment device.
For example, the terminal could abort communication with the mobile device for
a long period of time and then trigger a timeout.
Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal.
The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment.
**Note:** When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again.
**Note:** Deprecated in 2.6.7, no longer used due to time difference between connection lost and providing result to application. Replaced by CONNECTION\_LOST which works immediatelly.
|
| CONNECTION\_LOST
| Connection between terminal and device is lost and payment is terminated.
|
| PAYMENT\_NOT\_ALLOWED | Payment is not allowed at this moment.
For Mastercard Card application should show error and user should retry payment.
For Visa Card application should wait for UcpVtsPaymentAllowedListener::onPaymentAllowed()
|
##### NewTransaction
| **Field** | **Type** | **Description** |
|---|
| clientTransactionId
| String?
| Identifier of transaction in TSP
|
| type
| String
| The transaction type. One of: \[UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER\]
|
| amountMinor
| Long
| The monetary amount in terms of the minor units of the currency. For example,
`EUR 2.35' will return 235, and `BHD -1.345' will return -1345
|
| currency
| String
| 3-digit ISO 4217 currency code
|
| timestamp
| String
| The date/time when the transaction occurred. In ISO 8601 extended format
|
| merchantName
| String?
| The merchant (``doing business as'') name
|
| merchantPostalCode
| String?
| The postal code of the merchant
|
| transactionCountryCode
| String?
| The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1
|
| comboCardAccountType
| String?
| An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: \[UNKNOWN, CREDIT, DEBIT\]
|
| issuerResponseInformation
| String?
| Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: \[UNKNOWN, INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION\]
|
| status
| String
| The authorization status of the transaction. One of: \[AUTHORIZED, DECLINED, CLEARED, REVERSED\]
|
| paymentTokenId
| String
| Identifier of payment token in VCP
|
##### ContactlessTransactionData
| **Parameter** | **Type** | **Description** |
|---|
| currencyNumber | Int | Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. |
| currencyCode | String? | Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN
Could be null as the terminal provides only the currencyNumber and a valid code could be not found.
|
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, |
| transactionRange | ContactlessTransactionRange | Type of transaction range.
|
| ContactlessRichTransactionType | Rich transaction type.
|
| String | Merchant and location data from terminal.
**Deprecated** - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data.
|
**ContactlessTransactionRange**
| Value | Description
|
|---|
| LVT | Low value transaction |
| HVT | High value transaction
|
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| Value | Description |
|---|
| PURCHASE |
|
| REFUND |
|
| CASH |
|
| TRANSIT |
|
| PURCHASE\_WITH\_CASHBACK |
|
| UNKNOWN |
|
| WITHDRAWAL |
|
| ATM\_CONTACTLESS |
|
##### Report
| **Parameter** | **Type** | **Description** |
|---|
| name | String | Action name |
| description | String | Action details message. |
| isSuccess | Boolean | Result of action. True when action is finished successfully, false otherwise. |
| timestamp | Long | Time when the action occurred. |
| errorMessage | String? | Detailed error message when isSuccess is false. |
##### ContactlessAdvice
| **Parameter** | **Description** |
|---|
| DECLINE | Declines a processing transaction.
When provided by SDK in *getFinalDecisionForTransaction* wallet should not overrule a DECLINE.
If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response.
|
| AUTHENTICATION\_REQUIRED | An user authentication is required for transaction processing, which could be overruled on the MPA side.
When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the *onAuthRequiredForContactless* method.
|
| PROCEED | Transaction can be processed. |
##### ContactlessTransactionResult
**Important:** MPA should always refer to transaction results on the terminal.
| **Value** | **Description** | **Is success on MPA side**
|
|---|
| AUTHORIZE\_ONLINE | This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization.
The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal.
Should be treated as transaction success on the MPA side.
| Yes |
| 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 |
| 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 |
| 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 |
| If the *getFinalDecisionForTransaction* returns an AUTHENTICATION\_REQUIRED status then this result will be returned.
The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap.
If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place.
| No |
####
#### External libraries
The SDK uses several external Apache 2.0 libraries:
- com.nimbusds:nimbus-jose-jwt
- commons-codec:commons-codec
- com.fasterxml.jackson.core:jackson-core
- com.fasterxml.jackson.core:jackson-annotations
- com.fasterxml.jackson.core:jackson-databind
- com.fasterxml.jackson.module:jackson-module-kotlin
- io.insert-koin:koin-android
- io.reactivex.rxjava2:rxjava
- io.reactivex.rxjava2:rxandroid
- com.squareup.retrofit2:adapter-rxjava2
- com.squareup.retrofit2:retrofit
- com.squareup.retrofit2:converter
- com.squareup.okhttp3:logging
- com.squareup.okhttp3:okhttpSynchronous. Offline.
Contains all the necessary data to configure SDK.
Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method.
Requires MobileDC setup() already finished
Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished.
When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand.
**Important:** Before calling VCP SDK setup you must call setup from Mobile DC SDK.
Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment and loading first aplication screen.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| ucpConfiguration | UcpConfiguration | VCP configuration provided in builder described below.
| Not empty. |
**UcpConfigurationBuilder** contains the following methods:
| **Metod** | **Parameter** | **Description** | **Validation conditions**
|
|---|
| withApplication | Application | Application context. | Not empty |
| withCvmModel | WalletCvmModel (enum) | Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE
| Not empty |
| withUserAuthMode | WalletAuthMode (enum) | User authentication mode: WALLET\_PIN, CUSTOM, NONE
Contact Verestro to select proper configuration
| Not empty |
|
| UcpPaymentInstrument
EventListener
| Global listener for actions on PaymentInstrument.
| Not empty |
| UcpTransactionEventListener
| Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing
| Not empty |
| withTransactionAcceptance
EventListener | UcpTransactionAcceptance
EventListener | Global listener which allow application take final decision about transaction acceptance during transaction | Not empty |
| withReplenishThreshold | Int | Number of credentials below which replenish process will automatically begin
| Not empty |
| 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 | | Optional |
| withOptional
ExternalWalletServer |
| Prepares SDK for using external wallet server. | Optional |
| withOptional
UcpMcbpHttpExecutor | UcpMcbpHttpExecutor/
DefaultUcpMcbpHttpExecutor | Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. | Optional |
| withOptional
UcpReProvisionEventListener | UcpReProvisionEventListener | Global listener for actions during reprovisioning. | Optional |
| withOptional
UcpTransactionConfiguration
| UcpTransactionConfiguration
| Transaction configuration. Allow to enable deprecated authentication timer called when authentication is peformed.
Timer is disabled by default, usage is not recomended.
| Optional
|
| withOptionalWallet
McbpHttpExecutor |
| Prepares SDK for processing CMS-D HTTP requests with Wallet Server proxy.
| Optional |
| withOptionalEnableVisaSDK |
| Enables Visa SDK usage, requires gradle dependencies configuration
| Optional |
| withOptionalVtsPayment
ReadyCallback | UcpVtsPaymentAllowedListener | Provides information if payment with Visa Token is allowed with callback onPaymentAllowed().
Application should wait for callback when Visa Card is used.
| Optional |
**UcpPaymentInstrumentEventListener**
Contains callbacks for PaymentInstrument.
| **Method name** | **Parameters** | **Description**
|
|---|
| onProvisioning
Success | paymentInstrument: PaymentInstrument
| Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below
|
| onProvisioning
Failure | errorMessage: String?,
exception: Exception?
| Method called after provisioning failure. Try processing digitization again
|
| onReplenish
Success | paymentInstrument: PaymentInstrument
numberOfTransactionCredentials: Int
| Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials.
Depending on flow is called after activation process and when requested by SDK based on *replenishThreshold* configuration.
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row
|
| onReplenish
Failure | paymentInstrument: PaymentInstrument,
errorMessage: String?,
exception: Exception?
| Method called after replenish failure with PaymentInstrument
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row
|
| onPayment
Instrument
StatusChanged | newStatus: PaymentInstrument
Status
paymentInstrumentId: String
| Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id
|
| onNewTransaction | newTransaction:
| Provides online result with details of transaction processed in VCP
Works only when application is online
|
**UcpTransactionEventListener**
Callbacks related to transaction process.
**Important:** It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| Method name | Parameters | Description
|
|---|
| onAuthRequired
ForContactless
| paymentInstrument: PaymentInstrument, transactionInformation:
ContactlessTransactionInformation
transactionData: ContactlessTransactionData
| Called when user authentication is required during contactless transaction
ContactlessTransactionInformation is deprecated in version 2.2.4.
|
| onAuthRequired
ForDsrp
| paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo
| Called when user authentication is required during Dsrp transaction
|
| onAuthTimer
Updated | secondsRemaining: Int | Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration.
Note: Deprecated and disabled by default in version 2.6.7.
To enable use configuration avaialble in SDK *setup::withOptionalUcpTransactionConfiguration.*
|
| onContactless
PaymentStarted
| \-
| Called on very beginnging of every transaction start (SELECT\_PPSE APDU command). E.g. first tap to terminal or second tap if *onAuthRequiredForContactless* method was called.
Locks communication until method is finished.
Method duration directly impacts on transaction time.
|
| onContactless
Payment
Completed
| paymentInstrument: PaymentInstrument
transactionInformation: ContactlessTransactionInformation
transactionResult: ContactlessTransactionResult
transactionData : ContactlessTransactionData,
transactionId:String
| Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
transactionId - transaction identifier for Mastercard transactions, allow to match transaction with processed transaction notification from Mobile DC SDK: *EventNewTransaction::clientTransactionId.*
|
| onContactless
Payment
Incident
| paymentInstrument: PaymentInstrument,
exception: Exception
| Called when something went wrong during transaction and Mastercard marked transaction as incident
|
| onContactless
Payment
Aborted
| paymentInstrument: PaymentInstrument?,
abortReason: TransactionAbortReason,
exception: Exception
| Called when transaction is aborted during payment from some reason described in method parameter
PaymentInstrument could be null if abortReason = TransactionAbortReason.NO\_CARDS is returned.
Note: SDK clears passed selected card with method *selectForPayment()* and authentication with *setUserAuthenticatedForPayment()*
|
| onTransaction
Stopped
|
| Method called on transaction stopped by SDK.
Deprecated in version 2.6.7, no longer used.
|
**UcpTransactionAcceptanceEventListener**
Callbacks related to transaction process.
**Important:** It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| **Method name** | **Parameters** | **Description**
|
|---|
| getFinal
Decision
ForTransaction
|
|
|
**UcpEventReportsListener**
| **Method name** | **Parameters** | **Description**
|
|---|
| onNewReport
| report: Report
| Return logs related to token management.
|
**UcpReProvisionEventListener**
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
| **Method Name** | **Parameters** | **Description** |
|---|
| onReProvisionSuccess | paymentInstrument: PaymentInstrument | Method called after reProvisioning process.
Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback.
|
| onReProvisionFailure | paymentInstrument : PaymentInstrument
errorMessage : String?
exception : Exception?
| Method called after reProvisioning failure. Try again.
|
**UcpMcbpHttpExecutor**
| Method name
| Parameters
| Description
|
|---|
| execute
| ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod:
UcpMcbpHttpMethod,
url: String,
requestData:Any,
requestProperties:
Map<String, String>
| Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
|
**DefaultUcpMcbpHttpExecutor**
| Method name
| Parameters
| Description
|
|---|
| execute
| ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType
ucpMcbpHttpMethod: UcpMcbpHttpMethod
url: String
requestData: Any
requestProperties: Map<String, String>
| Called on every time if SDK want to connect to MasterCard and should return super.execute method.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
|
**UcpTransactionConfiguration**
| Parameter
| Type
| Description
|
|---|
| enableTransaction
AuthenticationTimer
| Boolean
| Allows to enable deprecated authentication timer.
Timer is started along *setUserAuthenticatedForPayment(),* result is available in *onAuthTimerUpdated().*
|
****
**UcpTransactionEventListener**
| ```
// UcpTransactionEventListener comments
class BankingAppUcpTransactionEventListener : UcpTransactionEventListener {
override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and ContactlessTransactionData available in event object
showPaymentScreen(event.paymentInstrument, event.transactionData)
}
override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and DSRP transaction information available in event object
showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo)
}
override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) {
//check if user is on payment screen and update timer
//when timer is 0, application should close payment with failure
//deprcated, disabled by default, read method description how to enable
}
override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) {
//looks like payment is aborted, can provide result to payment screen
//and show user what is abort reason
}
override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) {
//payment completed, provide result to payment information
//REMEMBER Transaction is processed on terminal and this is where
//you will see final transaction result
}
override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) {
//something went wrong during transaction, provide result to user
}
override fun onTransactionStopped() {
//deprecated, not used anymore,
}
override fun onContactlessPaymentStarted() {
//Payment started or resumed after callback onAuthReqiredForContactless
//Best place for checking if user is authenticated for payment and call
//setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected
}
}
```
|
**UcpPaymentInstrumentEventListener**
| ```
class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener {
override fun onNewTransaction(event: EventNewTransaction) {
//information about new transaction processed by issuer
}
override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
//status of payment instrument was changed, refresh list, inform user about new status
}
override fun onProvisioningFailure(event: EventProvisioningFailure) {
//provisioning failed, try again
}
override fun onProvisioningSuccess(event: EventProvisioningSuccess) {
//provisioning success, wait for status and replenish changes until user can pay
//or provide activation method when required
}
override fun onReplenishFailure(event: EventReplenishFailure) {
//transaction credentials replenish failed
}
override fun onReplenishSuccess(event: EventReplenishSuccess) {
//transaction credentials replenish success
}
}
```
|
**UcpTransactionAcceptanceEventListener**
| ```
class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener {
//Sample implementation of transaction acceptance listener
//For the scanario when authentication is required on issuer side for every transaction
//field even.isUserAuthenticated must be always true, otherwise
//ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned
override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice {
val isScreenUnlocked = isScreenUnlocked()
val isScreenProtectedByKeyguard = isScreenUnlocked()
val isLvtTransaction =
event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT
//discard all Transit transaction
if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) {
return ContactlessAdvice.DECLINE
}
//allow for transaction when user is authenticated for payment and screen unlocked
if (event.isUserAuthenticated && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
//allow for LVT transaction on unlocked screen when protected and don't require authentication
if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
// ...
// much more cases
//require authentication anyway
return ContactlessAdvice.AUTHENTICATION_REQUIRED
}
}
```
|
**UcpEventReportsListener**
| ```
class BankReportEventListener : UcpEventReportsListener {
override fun onNewReport(report: Report) {
//may be used for debugging SDK or gathering reports on client's app or backend
}
}
```
|
**UcpMcbpHttpExecutor**
| ```
//Use UcpMcbpHTtpExecutor as supertype if you want to replace connection
class BankUcpMcbpHttpExecutor : UcpMcbpHttpExecutor {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
//invoke connect by custom connector
return when (ucpMcbpRequestType) {
UcpMcbpHttpExecutorRequestType.REQUEST_SESSION -> {
executeRequestSession(ucpMcbpHttpMethod, url, requestData as UcpMcbpRequestSessionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.PROVISION -> {
executeProvision(ucpMcbpHttpMethod, url, requestData as UcpMcbpProvisionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.REPLENISH -> {
executeReplenish(ucpMcbpHttpMethod, url, requestData as UcpMcbpReplenishRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.NOTIFY_PROVISIONING_RESULT -> {
executeNotifyProvisioningResult(ucpMcbpHttpMethod, url,
requestData as UcpMcbpNotifyProvisioningResultRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.CHANGE_MOBILE_PIN -> {
executeChangeMobilePin(ucpMcbpHttpMethod, url,
requestData as UcpMcbpChangeMobilePinRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.DELETE -> {
executeDelete(ucpMcbpHttpMethod, url, requestData as UcpMcbpDeleteRequestData,
requestProperties)
}
}
}
}
```
|
**DefaultUcpMcbpHttpExecutor**
| ```
//Use DefaultUcpMcbpHTtpExecutor as supertype if you want to only add some action before connection
class BankDefaultUcpMcbpHttpExecutor : DefaultUcpMcbpHttpExecutor() {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
return super.execute(
ucpMcbpRequestType,
ucpMcbpHttpMethod,
url,
requestData,
requestProperties
)
}
}
```
|
**UcpReProvisionEventListener**
| ```
class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() {
override fun onReProvisionSuccess(event: EventReProvisionSuccess) {
//reProvisioning success, wait for status and replenish changes until user can pay
}
override fun onReProvisionFailure(event: EventReProvisionFailure) {
//reProvisioning failed, try again.
}
}
```
|
**UcpTransactionConfiguration**
```
class BankingAppUcpTransactionConfiguration : UcpTransactionConfiguration {
override val enableTransactionAuthenticationTimer: Boolean = false
}
```
**UcpVtsPaymentAllowedListener**
```
class BankingAppUcpVtsPaymentAllowedListener : UcpVtsPaymentAllowedListener {
override fun onPaymentAllowed() {
//when during a payment an status of PAYMENT_NOT_ALLOWED is received
//Application UI should show transaction error and wait for onPaymentAllowed() callback
//When received callback shouuld inform UI to process transaction again
}}
```
**Sample VCP SDK setup implementation**
Mobile DC setup() and VCP setup() method could be called on MainThread in Application:onCreate as blocking or another thread.
When applicaiton has multiple dependencies there is possible to call both setup() methods on another thread (MobileDC setup() method must be already finished until VCP setup() is called).
Important: In case of loading SDK on another thread and using contactless payments HostApduService must be used asynchronous way to prevet using SDK until loading is finished - check sample for method *PaymentService:processHceApduCommand*.
| ```
fun setup(
application: Application,
walletCvmModel: WalletCvmModel,
walletAuthUserMode: WalletAuthUserMode,
mcbpPinningCertificates: List,
replenishThreshold: Int
) {
val ucpConfiguration = UcpConfiguration.create(
UcpConfigurationBuilder()
.withApplication(application)
.withCvmModel(walletCvmModel)
.withUserAuthMode(walletAuthUserMode)
//marked as deprecated - see description above
.withUcpTransactionEventListener(BankingAppUcpTransactionEventListener())
.withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener())
.withMcbpPinningCertificates(mcbpPinningCertificates)
.withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener())
.withReplenishThreshold(replenishThreshold)
.withOptionalEventsReports(BankReportEventListener())
.withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor())
//if you want to only add additional action before connection use below implementation
//.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor())
.withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener())
//if you want to change standard transaction configuration use configuration below
.withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration())
//.withOptionalEnableVisaSDK() //optional when Visa is used
//.withOptionalVtsPaymentReadyCallback(BankingAppUcpVtsPaymentAllowedListener()) //optional when Visa is used
)
UcpApiKotlin().setup(ucpConfiguration)
}
```
|
### reset (DEPRECATED - use restart instead)
Synchronous. Offline.
Method for resetting SDK to uninitialized state.
**NOTE:** According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. ****
|
**Input**
No input.
**Output**
No output.
**Sample**
**Sample VCP SDK reset implementation:**
| ```
fun reset() {
UcpApiKotlin().reset()
//Terminating JVM according to MC SDK Sample Application
Runtime.getRuntime().exit(0);
}
```
|
### restart
| Synchronous. Offline.
Method for resetting SDK to uninitialized state.
Replaces reset() method which requires killing application process.
When restart finishes with error, application should repeat action.
**NOTE:** SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again.
|
**Input**
No input.
**Output**
Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods.
Failure callback when something went wrong during restart. Application should repeat action.
|
**Sample**
**Sample VCP SDK reset implementation:**
| ```
UcpApiKotlin().restart({
//restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods
}, {
//some error occured, please repeat action
})
```
|
##
Cards domain
### delete
Asynchronous. Online.|
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with *onPaymentInstrumentStatusChanged*.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of PaymentInstrument to delete
| Not empty. |
| reason | CharArray? | Optional reason of deletion
|
|
**Output**
Success / failure callback
|
**Sample**
| ```
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.cardsService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
|
### checkEligibility
Asynchronous. Online.
Check eligibility required to process digitize.
|
**Input**
| **Parameter** | **Type** | **Description** |
|---|
| checkEligibility | CheckEligibility | CheckEligibility object
|
CheckEligibility
| **Parameter**
| **Type**
| **Description**
|
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\]
|
| userLanguage | String | User language |
| userCountry | String | User country |
**Output**
Success callback with CheckEligibilityResult.
|
CheckEligibilityResult
| **Parameter**
| **Type**
| **Description**
|
|---|
| termsAndConditionsAssetId | String | Identifier of Terms and Conditions asset
|
**Sample**
| ```
private fun checkEligibility(
paymentInstrumentId: String,
paymentInstrumentType: PaymentInstrumentType,
userLanguage: String,
userCountry: String
) {
ucpApi.cardsService
.checkEligibility(
CheckEligibility(
paymentInstrumentId,
paymentInstrumentType,
userLanguage,
userCountry
),
{ checkEligibilityResult ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### digitize
Asynchronous. Online.
Use only when *checkEligibility* method is used.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.
|
####
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| digitizationRequest | DigitizationRequest | Plain object of DigitizationRequest
| Not empty |
DigitizationRequest object contains following fields:
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\]
| Not empty |
| CharArray? | Optional. The CVC2 for the card to be digitized |
|
| String? | Optional. Unique external identifier of Payment Token |
|
####
**Output**
Success callback with DigitizationResult object
|
| **Parameter** | **Type** | **Description** |
|---|
| digitizationResult | DigitizationResult |
|
DigitizationResult contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Plain object of PaymentInstrument
|
| additionalAuthenticationMethods | List<AdditionalAuthenticationMethod>? | All available additional authentication method |
| productConfig | ProductConfig | Plain object of ProductConfig, contains Payment Token configuration |
| externalPaymentTokenId | String? | Optional. External payment token id configured by the consumer. In case of identifier duplicate an random id is generated |
ProductConfig contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| isCoBranded | Boolean | Whether the product is co-branded |
| coBrandName | String? | Name of the co-branded partner |
| foregroundColor | String | Foreground color, used to overlay text on top of the card image |
| backgroundColor | String | Background color, used to overlay text on top of the card image |
| labelColor | String? | Label color of the mobile wallet entry for the card |
| issuerName | String | Name of the issuing bank |
| shortDescription | String | A short description for this product |
| longDescription | String? | A long description for this product |
| custoremServiceUrl | String? | Customer service website of the issuing bank |
| customerServiceEmail | String? | Customer service email address of issuing bank |
| customerServicePhoneNumber | String? | Customer service phone number of the issuing bank |
| productConfigIssuer | ProductConfigIssuer? | Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app |
| onlineBankingLoginUrl | String? | Login URL for the issuing bank's online banking website |
| termsAndConditionsUrl | String? | URL linking to the issuing bank's terms and conditions for this product |
| privacyPolicyUrl | String? | URL linking to the issuing bank's privacy policy for this product |
| issuerProductConfigCode | String? | Freeform identifier for this product configuration as assigned by the issuer |
| contactName | String? | Name of the issuing bank |
| bankAppName | String? | Name of banking application for display |
| bankAppAddress | String? | The package name for the destination mobile application |
| unsupportedPresentationTypes | String? | The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request |
| unsupportedCardVerificationTypes | String? | The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) |
| issuerFlags | List<ProductConfigIssuerFlags>? | List of plain ProductConfigIssuerFlags object. Contains issuer flags |
| brandLogoAssetId | String | The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID |
| issuerLogoAssetId | String | The logo of the issuing bank. Provided as a Asset ID |
| coBrandLogoAssetId | String? | The co-brand logo (if any) for this product. Provided as an Asset ID |
| cardBackgroundCombinedAssetId | String? | The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID |
| cardBackgroundAssetId | String? | The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID |
| iconAssetId | String | The icon representing the primary brand(s) associated with this product. Provided as an Asset ID |
ProductConfigIssuer contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| openIssuerAndroidIntent | ProductConfigOpenIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| activateWithIssuerAndroidIntent | ProductConfigActivateWithIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| openIssuerIOSDeepLinkingUrl | ProductConfigOpenIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| activateWithIssuerIOSDeepLinkingUrl | ProductConfigActivateWithIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
ProductConfigOpenIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| deepLinkinUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| deepLinkingUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigIssuerFlags contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| deviceBinding | Boolean | Device binding |
| cardholderVerification | Boolean | Whether the issuer participating in step-up flow |
| trustedBeneficiaryEnrollment | Boolean | Whether this is a trusted beneficiary enrollment |
| delegateAuthenticationSupported | String | Whether issuer supports delegated authentication |
Sample
| ```
fun digitizeCard(digitizationRequest: DigitizationRequest) {
ucpApi.cardsService
.digitize( digitizationRequest,
{ digitizationResult ->
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
###
### digitize (deprecated)
Asynchronous. Online.
Deprecated - use digitize(DigitizationGreenPath) instead.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty. |
| userLanguage | String | Language preference selected by the consumer. Formatted as an
ISO-639-1 two letter language code
| Not empty. |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized
|
|
####
**Output**
Success / failure callback
|
#####
**Sample**
| ```
fun digitizeCard(
paymentInstrumentId: String,
languageCode: String,
securityCode: CharArray) {
ucpApi.cardsService
.digitize(paymentInstrumentId, languageCode, securityCode,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### digitize
Asynchronous. Online.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| digitizationGreenPath | DigitizationGreenPath | Plain object of DigitizationGreenPath
| Not empty |
DigitizationGreenPath contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized |
| userLanguage | String | User language |
| userCountry | String | User country |
| externalPaymentTokenId | String? | Optional. Unique external identifier of Payment Token |
**Output**
Success / failure callback
|
#####
**Sample**
```
fun digitizeCard(digitizationGreenPath: DigitizationGreenPath) {
ucpApi.cardsService
.digitize(digitizationGreenPath,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### getAdditionalAuthenticationMethods
Asynchronous. Online.
Retrieves additional user authentication methods.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| getAdditionalAuthenticationMethods | GetAdditionalAuthenticationMethods | Plain object of GetAdditionalAuthenticationMethods
| Not empty |
Fields of GetAdditionalAuthenticationMethods object:
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument |
####
**Output**
Success callback with AdditionalAuthenticationMethods object.
|
| **Parameter** | **Type** | **Description** |
|---|
| additionalAuthenticationMethods | AdditionalAuthenticationMethods | Object carrying list of AdditionalAuthenticationMethod |
AdditionalAuthenticationMethods contains following value:
| **Parameter** | **Type** | **Description** |
|---|
| additionalAuthenticationMethods | List<AdditionalAuthenticationMethod> | List of AdditionalAuthenticationMethod objects |
**Sample**
| ```
private fun getAdditionalAuthenticationMethods() {
val getAdditionalAuthenticationMethod =
GetAdditionalAuthenticationMethods("paymentInstrumentId")
ucpApi
.cardsService
.getAdditionalAuthenticationMethods(
getAdditionalAuthenticationMethod,
{ additionalAuthenticationMethods ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### submitTokenAuthenticationValue
Asynchronous. Online.
Submit authentication code when additional user authentication is required.
|
**Input**
| Parameter | Type | Description |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| authenticationCode | String | Authentication code |
####
**Output**
Success callback/failure callback.
|
#####
**Sample**
| ```
private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) {
ucpApi.cardsService
.submitAuthenticationValue(
SubmitAuthenticationValue(
paymentInstrumentId,
authenticationCode
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### submitTokenAuthenticationMethod
Asynchronous. Online.
Submit authentication method when additional user authentication is required.
|
**Input**
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
|
| authenticationMethodId | String | Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. |
####
**Output**
Success callback/failure callback.
|
#####
**Sample**
| ```
private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) {
ucpApi.cardsService
.submitAuthenticationMethod(
SubmitAuthenticationMethod(
paymentInstrumentId,
authenticationMethodId
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getAllPaymentInstruments
Asynchronous. Online/Offline.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network and user session required) |
|
**Output**
Success callback with list of PaymentInstrument objects.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments from local or remote storage |
**Sample**
| ```
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.cardsService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
###
### getPaymentInstrument (deprecated)
Asynchronous. Online/Offline.
Deprecated - use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| paymentInstrumentId | String | Id of instrument to retrieve | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
Success callback with PaymentInstument object.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
**Sample**
| ```
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.cardsService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
##
## IBANs domain
###
### digitize
Asynchronous. Online.
Registers user and device if already not registered in VCP backend. Creates payment token in VCP backend.
Expect push after successfull finish and then proceed using process method in Cloud Messaging domain.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| signedAccountInfo | String | Signed AccountInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation
| Not empty. |
| fcmRegistrationToken | CharArray | FCM Cloud messaging registration token
| Not empty. |
| languageCode | String | Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code
| Not empty. |
**AccountInfo:**
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| userId | String | External user id
| Not empty. |
| iban | String | Bank Account Number | Not empty. |
| countryCode | String | The country of the financial account
Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1
| Not empty. |
**Output**
Success callback. Called when device token digitization finished with success .Result contains *IbanDigitizationResult* object.
Note: Cloud token digitization fail doesn't affect on success/failure callback.
|
IbanDigitizationResult contains following fields:
| **Parameter** | **Type** | **Description** |
|---|
| (DEPRECATED) cloudDigitizationSuccess | Boolean | Cloud Token Digitization Details |
| result | CloudDigitizationResult | Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN |
Failure callback. Called when **device token** digitization finished with failure.
|
**Sample**
Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
| ```
class SignedAccountInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("userId", "externalUserId")
.claim("iban", "IN15HIND23467433866365")
.claim("countryCode", "IND")
.build()
val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey)
// ...
}
```
|
| ```
fun digitizeIban(
signedAccountInfo: String,
fcmRegistrationToken: CharArray,
languageCode: String) {
ucpApi.ibansService
.digitize(signedAccountInfo, fcmRegistrationToken, languageCode,
{ ibanDigitizationResult ->
//Device token digitization finished with success
//wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success
val cloudDigitizationResult = ibanDigitizationResult.result
//check status of Cloud Token
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
###
### createTVC
Asynchronous. Online.
Provides Transaction Verification Code required to process cloud payments.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation
| Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)*
| Not empty. |
**Output**
Success callback with Tvc object or encrypted Tvc object as String.
|
| **Parameter** | **Type** | **Description** |
|---|
| plainTvc | PlainTvc? | Plain PlainTvc object
|
| encryptedTvc | CharArray? | Encrypted PlainTvc object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation
|
PlainTvc object contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| accountNumber | CharArray | Primary Account Number for the transaction – this is the Token PAN
|
| dynamicExpiryDate | CharArray | Dynamic expiration date for the token. Expressed in YYMM format
|
| dynamicCVC | CharArray | Dynamic CVC |
Failure callback when TVC cannot be created.
|
**Sample**
Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
| ```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
|
| ```
fun createTvc(signedIbanInfo: String) {
ucpApi.ibansService
.createTVC(signedIbanInfo, { tvc ->
//result object could contains encrypted TVC
val encryptedTvc: String? = tvc.encryptedTvc
//or decrypted(plain) TVC object with parameters described in documentation
val plainTvc = tvc.plainTvc
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### createPaymentData
Asynchronous. Online.
This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation
| Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions**
|
|---|
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)*
| Not empty. |
| userId | String | External user id given by the client | Not empty. |
**Output**
Success callback with object or encrypted payment data object as String.
|
| **Parameter** | **Type** | **Description** |
|---|
| plainPaymentData | PlainPaymentData? | Plain PlainPaymentData object
|
| encryptedPaymentData | String? | Encrypted PlainPaymentData object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation
|
PlainPaymentData object contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| accountNumber | String | Primary Account Number for the transaction – this is the Token PAN
|
| applicationExpiryDate | String? | Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format |
| panSequenceNumber | String? | Rrquired only for UCAF. Application PAN sequence number for the Token |
| track2Equivalent | String? | Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed |
| ucafCryptogram | String? | Required only for UCAF. UCAF cryptogram |
| dynamicExpiryDate | String? | Dynamic expiration date for the token. Expressed in YYMM format
|
| dynamicCVC | String? | Dynamic CVC |
Failure callback when PaymentData cannot be created.
|
**Sample**
**
| ```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.claim("userId", "123")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
|
| ```
fun createPaymentData(signedIbanInfo: String) {
ucpApi.ibansService
.createPaymentData(signedIbanInfo, { paymentData ->
//result object could contains encrypted PaymentData
val encryptedPaymentData: String? = paymentData.encryptedPaymentData
//or decrypted(plain) PaymentData object with parameters described in documentation
val plainPaymentData = paymentData.plainPaymentData
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### getAllPaymentInstruments
Asynchronous. Online/Offline.
Local storage is always instant available and should be used to incerese UX.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network required) |
|
**Output**
Success callback with list of PaymentInstrument objects
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments |
**Sample**
| ```
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.ibansService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getPaymentInstrument(deprecated)
Asynchronous. Online/Offline.
Use *getAllPaymentInstruments* instead.
Local storage is always instant available and should be used to incerese UX.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of instrument to retrieve. | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
Success callback with PaymentInstument object
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
**Sample**
| ```
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.ibansService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### delete
Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with *onPaymentInstrumentStatusChanged*.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| paymentInstrumentId | String | Id of PaymentInstrument to delete
| Not empty. |
| reason | CharArray? | Optional reason of deletion
|
|
**Output**
Success / failure callback
|
**Sample**
| ```
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.ibansService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
|
## Payment domain
### setDefaultForContactless
Asynchronous. Offline.
Sets payment instrument as default for contactless payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically after linking with PoS terminal.
Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
**Output**
Success / failure callback
|
**Sample**
| ```
fun setDefaultForContactless(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) {
//make sure selected PaymentInstrument can be seta as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForContactless(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
###
### getDefaultForContactless
Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.
|
**Input**
**Output**
Success callback with id new default PaymentInstrument
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Default Payment instrument |
**Sample**
| ```
fun getDefaultForContactless() {
ucpApi.paymentService
.getDefaultForContactless({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
|
### setDefaultForRemote (deprecated)
Asynchronous. Offline.
Sets payment instrument as default for DSRP payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically to remote payments.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
**Output**
Success / failure callback
|
**Sample**
| ```
fun setDefaultForRemote(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
&& !paymentInstrument.dsrpSupported) {
//make sure selected PaymentInstrument can be set as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForRemote(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### getDefaultForRemote (deprecated)
Asynchronous. Offline.
Provides default PaymentInstrument for remote payments.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default.
|
**Input**
**Output**
Success callback with id new default PaymentInstrument
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Default Payment instrument |
**Sample**
| ```
fun getDefaultForRemote() {
ucpApi.paymentService
.getDefaultForRemote({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
|
### selectForPayment
Asynchronous. Offline.
Sets payment instrument as primary for next incoming payment.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentd | String | Payment instrument identity
| Not empty |
**Output**
Success / failure callback
|
**Sample**
**Note:** This is only sample payment scenation
|
| ```
//sample scenario of starting payment with authentication before payment
fun startPayment(paymentInstrument: PaymentInstrument) {
//checking conditions before payment
val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
val isContactlessSupported = paymentInstrument.contactlessSupported
val hasTransactionCredentials = paymentInstrument.credentialsCount > 0
if (!isActive || !isContactlessSupported || !hasTransactionCredentials) {
//PaymentInstrument doesn't meet requirements for payment
return
}
//selecting PaymentInstrument to payment
ucpApi.paymentService
.selectForPayment(paymentInstrument.id, {
//selection success
//request user authentication when
//... authentication presented
//use setUserAuthenticatedForPayment method
}, { throwable ->
//something went wrong, check exception with documentation
})
}
```
|
### setUserAuthenticatedForPayment
Asynchronous. Offline.
Sets user as authenticated to payment with provided payment instrument.
Authentication clearing depends on authentication timer configuration in *UcpTransactionConfiguration:enableTransactionAuthenticationTimer*.
By default timer is disabled and authentication is cancelled when user perform transaction and SDK send callback *onContactlessPaymentCompleted/Aborted/Incident* from *UcpTransactionEventListener*.
When timer is enabled authentication is cleared when auth timer finishes - it could casue problems when user start to pay just before timer finish. Authentication could be cleared by SDK during payement.
If application call *setUserAuthenticatedForPayment* without contactless payment context and authentication timer is disabled, authentication is never cleared by SDK. To clear authentication use *abortUserAuthenticationForPayment.*
*UcpTransactionEventListener:onContactlessPaymentStarted* is recommended place for payment authentication.
**Note:** User can be authenticated based on conditions like screen unlock. Method must be called before payment in method UcpTransactionEventListener:onContactlessPaymentStarted()
Make sure that authentication on this step is done securely. Transaction information is not available on this step.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
| pin | CharArray? | PIN or null for CUSTOM WalletAuthUserMode
|
|
**Output**
Success / failure callback
|
**Sample**
Basic user authentication usage below, call when user is authenticated.
| ```
private fun setUserAuthenticatedForPayment(
paymentInstrument: PaymentInstrument,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser,
{
//user authentication provided
//start one tap payment or continue two tap with 2nd tap to terminal after authentication
//listen for auth timer changes
//user abortUserAuthentication method when transaction cancelled by user
}, { throwable ->
//some error, check exception
})
}
```
|
Optional authentication before making transaction based on custom conditions.
| ```
override fun onContactlessPaymentStarted() {
//check internal conditions
//like user performed authentication, is logged in application, is device unlocked etc
val isUserAuthenticated = true
//check if use selected any token for payment and select it in UCP SDK
//otherwise default token will be used
if (getSelectedPaymentInstrumentId() != null) {
ucpApi
.paymentService
.selectForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
success = {
//token will be used for actual payment
//call setUserAuthenticatedForPayment here - sample below in "else" block
},
failure = { throwable ->
//something went wrong, check throwable with documentation
}
)
} else {
if (isUserAuthenticated) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
pin = null, //or pin if MobilePin is used
success =
//user authenticated in SDK
}, failure = {
//authentication failure, check exception
}
)
}
}
}
```
|
### abortUserAuthenticationForPayment
Asynchronous. Offline.
Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped.
|
**Input**
**Output**
Success / failure callback
|
**Sample**
| ```
fun abortUserAuthenticationForPayment() {
ucpApi
.paymentService
.abortUserAuthenticationForPayment(
{
//user authentication aborted
//listen for auth timer changes
},
{ throwable ->
//some error, check exception
})
}
```
|
### processHceApduCommand
Synchronous. Offline.
Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS.
Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| context | Context | Application context, can be provided from HostApduService
| Not empty |
| apdu | ByteArray | APDU command from HostApduService::processCommandApdu method parameter
| Not empty |
| extras | Bundle? | Extras object from HostApduService::processCom mandApdu method parameter
|
|
**Output**
Apdu result - method called synchronous without callback
|
| **Parameter.** | **Type** | **Description** |
|---|
| apdu | ByteArray | APDU command to return in implementation of overridden processCommandApdu method
|
**Sample (synchronized HostApduService)**
Use this version if MobileDC:setup and UCP:setup() method is called in Application:onCreate on Main Thread.
| ```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(this, commandApdu, extras)
}
//..
}
```
|
**Sample (aynchronous HostApduService)**
Use this version if SDK is called on another thread and HostApduService can receive APDU until VCP SDK is still in loading state.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
//UcpSdkStateApplicationSingleton is sample class which keep SDK state and allow to observe when SDK load is finished
if (UcpSdkStateApplicationSingleton.isLoaded()) {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
} else {
sendResponseApdu(null)
UcpSdkStateApplicationSingleton.listenForSdkReady(
onSdkLoadListener = {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
}
)
}
return null
}
override fun onDeactivated(reason: Int) {
if (UcpSdkStateApplicationSingleton.isLoaded()) {
return ucpApi
.paymentService
.handleHceApduDeactivationEvent(reason)
}
}
private fun processCommandApduInUcpSdk(
context: Context,
commandApdu: ByteArray,
extras: Bundle?
): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(context, commandApdu, extras)
}
}
//sample objec which helps to listen SDK state
object UcpSdkStateApplicationSingleton : UcpSdkState {
//flag could be synchronized
private var isLoaded = false
private var onSdkLoadListener: (() -> Unit)? = null
override fun listenForSdkReady(onSdkLoadListener: () -> Unit) {
this.onSdkLoadListener = onSdkLoadListener
if (isLoaded) this.onSdkLoadListener?.invoke()
}
//call when SDK loading thread is finished
//setupMdc() -> setupUcp() -> UcpSdkStateApplicationSingleton.onUcpSdkLoaded()
override fun onUcpSdkLoaded() {
isLoaded = true
onSdkLoadListener?.invoke()
}
override fun isLoaded(): Boolean {
return isLoaded
}
}
```
### replenishCredentials
Asynchronous. Online. User login session not required.
Method for manually replenishing payment credentials.
Application will receive push notification and notified about replenish process with global callback described in *setup* chapter.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of paymentInstrument that needs it credentials replenished
| Not empty |
**Output**
Success / failure callback
|
**Sample**
| ```
fun replenishCredentials(paymentInstrumentId: String) {
ucpApi.paymentService
.replenishCredentials(paymentInstrumentId,
{
//request for credentials replenish finished with success
//wait for push notification and pass to valid module
//when push processed application will be informed about replenish success/failure
//read chapter with setup for more information
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
|
### restartContactlessAuthTimer
Asynchronous. Offline.
Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile.
Default auth time is provided by card profile.
|
**Input**
**Output**
Success / failure callback
|
### requestAuthenticationCodeForPayment
Asynchronous. Online.
Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| requestAuthenticationCodeForPayment | RequestAuthenticationCodeForPayment | Plain RequestAuthenticationCodeForPayment object
| Not empty |
RequestAuthenticationCodeForPayment object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| authenticationRequestId | String | Authentication request id up to 64 alphanumeric characters long.
A new id should be used for each instance than an account holder needs to be authenticated | Not empty |
**Output**
Success callback/failure callback.
|
**Sample**
| ```
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) {
ucpApi.paymentService
.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//Requesting Authentication Code went successfully.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### validateAuthenticationCodeForPayment
Asynchronous. Online.
Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid.
|
**Input**
| Parameter | Type | Description | Validation conditions |
|---|
| validateAuthenticationCodeForPayment | ValidateAuthenticationCodeForPayment | Plain ValidateAuthenticationCodeForPayment object
| Not empty |
ValidateAuthenticationCodeForPayment object contains following fields
| Parameter | Type | Description | Validation conditions |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| authenticationRequestId | String | Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. | Not empty |
| authenticationCode | String | Authentication Code to authenticate the account holder | Not empty |
**Output**
Success callback with ValidateAuthenticationCodeForPaymentResult object.
|
ValidateAuthenticationCodeForPaymentResult object contains following field
| **Parameter** | **Type** | **Description** |
|---|
| signedAuthenticationProcessData | String | Signed AuthenticationProcessData per RFC 7519
|
AuthenticationProcessData model
| **Parameter** | **Type** | **Description** |
|---|
| authenticationRequestId | String | Authentication request id
|
**Sample**
| ```
fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) {
ucpApi.paymentService
.validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment,
{ validateAuthenticationCodeForPaymentResult ->
//ValidateAuthenticationCodeForPaymentResult plain object,
//contains data to validate on backend
val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult
.signedAuthenticationProcessData
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)
| ```
class SignedAuthenticationProcessData {
fun verifyAndGetAuthenticationRequestID() {
val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600);
val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId")
// ...
}
}
```
|
### processDsrpTransaction(deprecated)
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Payment instrument identity
| Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | |
|
**Output**
Success callback with cryptogram for payment
|
### processDsrpTransaction
Asynchronous. Offline.
Method dedicated for starting DSRP transaction.
Every DSRP transaction has to be authenticated before processing.
Depending on implementation payment can be process with OTP authentication or device level authentication.
|
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| processDsrpTransaction | ProcessDsrpTransaction | Plain ProcessDsrpTransaction object
| Not empty |
ProcessDsrpTranasction object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Identifier of payment instrument
| Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | Plain DsrpTransactionInfo object | Not empty |
DsrpTransactionInfo object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| amountMinor | Long | A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 | Not empty |
| currencyCode | String | A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. | Not empty |
| countryCode | String? | A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. |
|
| issuer
Cryptogram
Type | DsrpIssuer
Cryptogram
Type | Enum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. | Not empty |
| unpredictable
Number | Long
| A long representing the random number generated by the merchant or by the Payment Gateway. The maximum value is 4,294,967,295. | Not empty |
| transactionType
| Dsrp
Transaction
Type
| A type of financial transaction, one of: PURCHASE, CASH, PURCHASE\_WITH\_CASHBACK, REFUND
| Not empty |
| transactionDate
| Date?
| A Date object indicating date of transaction. |
|
**Output**
Success callback with ProcessDsrpTransactionResult object.
|
ProcessDsrpTransactionResult object contains following field
| **Parameter** | **Type** | **Description** |
|---|
| transaction
Cryptogram
Data | ByteArray | A byte array containing a formatted response, either UCAF or a set of TLV data for the merchant to populate DE55 data.
|
| pan
| String
| String containing the PAN of the card used.
|
| panSequence
Number | Int
| An integer value specifying the PAN Sequence Number (PSN) of the card used.
|
| cryptogramType | DsrpIssuer
Cryptogram
Type | Enum value as UCAF or DE55 depending on cryptogram data format is used.
|
| track2Data
| String
| String containing the data elements of track 2 according to ISO/IEC 7813.
|
| par
| String
| String representation of byte array of permanent account reference. A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens.
|
| expirationDate
| String
| Date in ISO-8601 (YYYY-MM-DD) format indicating expiry date of the card.
|
| transactionId
| String
| Hexed byte array containing a Transaction Identifier.
|
| **DsrpPaymentException.reason** | **Description** |
|---|
| DSRP\_INVALID\_INPUT | Invalid input data.
|
| DSRP\_UNEXPECTED\_DATA
| Provided data is valid in context of validation, but doesn't mee
|
| DSRP\_AUTHENTICATION\_REQUIRED | Authentication is not provided for DSRP payment. Authenticate and process DSRP transaction again.
|
| DSRP\_TOKEN\_INACTIVE
| Token used for DSRP is inactive.
|
| DSRP\_NO\_TRANSACTION\_CREDENTIALS | There is no transaction credentials to procees DSRP payment
|
| DSRP\_NOT\_SUPPORTED\_BY\_CARD | DSRP is not suported by Card.
|
| DSRP\_TRANSACTION\_DECLINED
| Transaction is declined by Card.
|
| DSRP\_INCOMPATIBLE\_PROFILE
| Card profile is incomaptible with DSRP.
|
| DSRP\_WRONG\_STATE
| DSRP transaction is in wrong state.
|
| DSRP\_INTERNAL\_ERROR
| Unknowne error during DSRP processing.
|
| ```
// After Merchant App delivers DSRP data application should authenticate user with device level authentication
// and next execute setUserAuthenticationForPayment().
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTranasctionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
**Sample DSRP transaction with OTP authentication**
| ```
// After Merchant App delivers DSRP data user should request authentication
// code for payment with selected paymentInstrument.
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment =
RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId)
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) {
ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//When requesting went successfully User will get authentication code.
//In next step authentication code should be passed to MPA and application
//should validate this code with validateAuthenticationCode() method
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
val validateAuthenticationCode: ValidateAuthenticationCode =
ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser)
fun validateAuthenticationCode(validateAuthenticationCode) {
ucpApi.paymentService
.validateAuthenticationCode( validateAuthenticationCode,
{ validateAuthenticationCodeResulty ->
//ValidateAuthenticationCodeResult plain object
val signedAuthenticationProcessData = validateAuthenticationCodeResulty
.signedAuthenticationProcessData
//If validation went successfully MPA should show authentication view,
//and after valid authentication MPA should execute setUserAuthenticatedForPayment()
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTransactionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
**Sample input and output DSRP data:**
```Java
Input:
amountMinor: 4321,
countryCode: 840,
currencyCode: 840,
issuerCryptogramType: UCAF,
transactionDate: Apr 25, 2023 09:41:05, //Date() toString() format
transactionType: PURCHASE,
unpredictableNumber: 29496729
Output:
pan: 5204830959972699
track2Data: 5204830959972699D26052010000000000000
expirationDate: 2026-05-31 //YYYY-MM-DD
par: 500170A4PEV2GLWPFD00N6H5AX2YB
panSequenceNumber: 0
transactionId: df25a522a075680acbaa407fdc8a0348a321f77afa2f0231cd38f28e7ae691e2
cryptogramType: UCAF
transactionCryptogramData: 414d506a6d4a474650306149414155427768575a47674144464b553d //in Hex
```
## Cloud messaging domain
### process (deprecated in 2.6.7)
Asynchronous. Online. User login session not required.
Processes data sent by VCP backend (push notification data).
Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method.
Method can throw InvalidPushException in case of invalid push content passed to it.
Refer Mobile DC documentation how to handle push.
Deprecated in 2.6.7, use MobileDC:CloudMessaging:process() instead.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| pushData | Map<String, String> | Data received from notification service in object RemoteMessage object
| Not empty |
**Output**
Success / failure callback. When request fails try again
|
**Sample**
| ```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map) {
ucpApi
.cloudMessagingService
.process(pushData, {
//push processed in Mobile DC
}, {
//some error
})
}
```
|
### processMcbpNotificationData
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| encryptedPayload | String | Data received from notification service in object RemoteMessage object
| Not empty |
**Output**
Success / failure callback
|
| ```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String? = remoteMessage.from
val pushData = remoteMessage.data
//check push source based on senderId
if (isVerestroSenderId(senderId)) {
val verestroPayload: String = readVerestrpPushContent(pushData)
ucpApi
.cloudMessagingService
.processMcbpNotificationData(verestroPayload, {
//push processed in VCP
}, {
//some error
})
} else {
//proceed push from another source
}
}
```
|
## External Wallet Server domain
Chapter contains method for SDK when External Wallet Server is used.
Usage of method requires additional configuration with external API.
Basic MDES cloud messaging configuration:
| **Environment** | **FCM Sender Id** |
|---|
| MTF | 502118574555 |
| PRODUCTION | 993764297204 |
### prepareRegistrationData
Asynchronous. Offline.
Method for preparing data used for activation.
Should be used before calling register method.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentAppInstanceId | String | Identifier for the specific Mobile Payment App instance | Not empty |
| paymentAppProviderId | String | Globally unique identifier for the Wallet Provider, as assigned by MDES | Not empty |
| String | CMS-D public key certificate in pem format | Not empty |
| mobilePin | CharArray? | Mobile PIN used to payment confirmation
|
|
**Output**
Success callback with PrepareRegistrationResponse object.
|
| **Parameter** | **Type** | **Description** |
|---|
| String | CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) |
| encryptedRgk | String | Encrypted randomly-generated 128-bit AES key. |
| EwsDeviceInfo | Device info. |
| deviceFingerprint | String | Unique device fingerprint. |
| encryptedPin | String? | Encrypted pin (if passed in input). |
model:
| **Parameter** | **Type** | **Description** |
|---|
| deviceName | String | Device model name. |
| formFactor | String | The form factor of the target provisioned device. |
| storageTechnology | String | The architecture or technology used for token storage. |
| osName | String | The name of the operating system of the target provisioned device. |
| osVersion | String | The version of the operating system of the target provisioned device. |
| nfcCapable | Boolean | Whether the target provisioned device has NFC capability.
|
**Sample**
| ```
fun prepareRegistrationData(
paymentAppInstanceId: String,
paymentAppProviderId: String,
publicKeyCertificate: String,
mobilePin: CharArray?) {
ucpApi
.ewsService
.prepareRegistrationData(paymentAppInstanceId,
paymentAppProviderId,
publicKeyCertificate,
mobilePin,
{ prepareRegistrationResponse ->
//Prepared data for registration including encryptedMobilePin if mobilePin is used
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### register
Asynchronous. Online.
Method used for registration new Mobile Payment App instance with MDES for use.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| mobileKeysetId | String | Identifies the Mobile Keys used for this remote management session
| Not empty |
| ewsMobileKeys | EwsMobileKeys | Contains the mobile keys used to secure the communication during subsequent remote management sessions
| Not empty |
| remoteManagementUrl | String | The URL endpoint for subsequent remote management sessions
The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions
| Not empty |
| **Parameter** | **Type** | **Description** |
|---|
| transportKey | String | The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES
|
| macKey | String | The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES
|
| dataEncryptionKey | String | The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES
|
**Output**
Success / failure callback
|
****
| ```
fun register(
mobileKeysetId: String,
ewsMobileKeys: EwsMobileKeys,
remoteManagementUrl: String) {
ucpApi
.ewsService
.register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl,
{
//Device registration success
//application should listen to push messages and UcpPaymentInstrumentEventListener callbacks
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### activate
Asynchronous. Online.
Method to PaymentInstrument.
Should be used only on PaymentInstrumens which PaymentInstrumentStatus is .
Changes PaymentInstrumentStatus to , calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available.
Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| String | Id of paymentInstrument to activate. | Not empty. |
**Output**
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
}
)
}
```
|
### suspend
Asynchronous. Offline.
Method for suspending paymentInstrument.
Changes PaymentInstrumentStatus to .
Use activate method to allow payments again.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of paymentInstrument to suspend. | Not empty. |
**Output**
Success / failure callback
|
****
| ```
fun suspend(paymentInstrumentId: String) {
ucpApi
.ewsService
.suspend(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to SUSPENDED.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getPaymentInstrument
Asynchronous. Offline.
Method for getting single PaymentInstrument from local storage object based on id.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| paymentInstrumentId | String | Id of paymentInstrument to get.
| Not empty. |
**Output**
Success callback with PaymentInstrument object.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstrument | PaymentInstrument | Retrieved paymentInstrument |
**Sample**
| ```
fun getPaymentInstrument(paymentInstrumentId: String) {
ucpApi.ewsService
.getPaymentInstrument(paymentInstrumentId,
{ paymentInstrument ->
//PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getAllPaymentInstruments
Asynchronous. Offline.
Method for getting all payment instruments from local storage.
|
**Input**
**Output**
Success callback with list of PaymentInstrument objects.
|
| **Parameter** | **Type** | **Description** |
|---|
| paymentInstruments | List<PaymentInstrument> | List of retrieved payment instruments from local storage |
**Sample**
| ```
fun getAllPaymentInstrument() {
ucpApi.ewsService
.getAllPaymentInstruments(
{ paymentInstruments ->
//List of PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
### getEncryptedPin
Asynchronous. Offline.|
Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| pin | CharArray | PIN to encrypt. | Not empty. |
**Output**
Success callback with encrypted mobile PIN.
|
| **Parameter** | **Type** | **Description** |
|---|
| encryptedMobilePin | String | Hex encoded encrypted mobile PIN. |
**Sample**
| ```
fun getEncryptedPin(pin: CharArray) {
ucpApi
.ewsService
.getEncryptedPin(pin, { encryptedPin ->
//call to Wallet Server with new created encrypted mobile PIN
//when updated call onMobilePinChanged method
}, {
//Something went wrong, check exception with documentation
})
}
```
|
### onMobilePinChanged
Asynchronous. Online.
.
Should be used when mobilePin changed.
|
**Input**
**Output**
Success / failure callback
|
**Sample**
| ```
fun reactOnMobilePinChanged() {
ucpApi
.ewsService
.onMobilePinChanged(
{
// Informing SDK about changing mobile pin processed succesfully.
// SDK should delete and next replenish transaction credentials.
// Listen for UcpPaymentInstrumentEventListener events
}, { throwable ->
// Something went wrong, check exception with documentation.
})
}
```
|
### delete
When success PaymentInstrument will be no longer available in *getPaymentInstrument* and *getPaymentInstruments* methods.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| String | Id of paymentInstrument to delete. | Not empty. |
**Output**
Success / failure callback
|
****
| ```
fun delete(paymentInstrumentId: String) {
ucpApi
.ewsService
.delete(paymentInstrumentId,
{
//Selected Payment instrument is removed
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
## Assets Domain
### getAsset
Asynchronous. Online.
Method for getting all assets for selected assetId.
|
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
|---|
| assetId | String | Id of assets to retrive | Not empty |
**Output**
Success callback with list of Assets objects.
|
| **Parameter** | **Type** | **Description** |
|---|
| ucpAsset | UcpAsset | Plain UcpAsset object |
UcpAsset object contains following field
| **Parameter** | **Type** | **Description** |
|---|
| content | List<UcpAssetContent> | Plain list of UcpAssetContent objects |
UcpAssetContent contains following fields.
| **Parameter** | **Type** | **Description** |
|---|
| data | String | The data for this asset. Base64-encoded data, given in the format as specified in type. |
| type | String | The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. |
| width | Long? | For image assets, the width of this image. Specified in pixels. |
| height | Long? | For image assets, the width of this image. Specified in pixels. |
**Sample**
| ```
fun getAsset(assetId: String) {
ucpApi.assetsService
.getAssets( assetId,
{ ucpAsset ->
//List of assets of selected assetId
val ucpAssetContentList = ucpAsset.content
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
|
## DOCUMENT CHANGELOG
Vesion 2.10.12
- **IMPORTANT: Mobile DC dependency can no longer be declared as saperate dependency in the same application when UCP is declared. MDC will be available as default.**
- UCP is now built as a [fused library](https://developer.android.com/build/publish-library/fused-library)
- Updated Mobile DC to 2.17.5
- Updated AGP to 9.0.1
- Updated Gradle to 9.3.1
Vesion 2.10.10
- Added new field for digitization: *formFactor*
- Mobile DC updated to 2.17.3
Vesion 2.10.0
- Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes)
- Security tools updated to newest version
- Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22)
- AGP updated to 8.11.1
- Mobile DC updated to 2.17.0
Version 2.9.10
- Added new parameter *transactionId* to method *onContactlessPaymentCompleted* for Mastercard transactions.
New transaction identifier allow to match transaction with processed transaction notification *MobileDC::EventNewTransaction::clientTransactionId.*
- Mobile DC updated to 2.16.12
Version 2.9.8
- **IMPORTANT: Security tools updated to newest version. Recommneded update when using version 2.9.x due to changes fixes in security tools.**
- Visa SDK updated to 6.4.0
- Mobile DC updated to 2.16.10
Version 2.9.5
- Added MC *mtf* host name
- Update Mobile DC to 2.16.5
Version 2.9.4
- **Important:** Apply security and functional certification changes related to intruduction new security tools. Changes in security thread management and working in background
- Update Mobile DC to 2.16.4
Version 2.8.7
- Update Mobile DC to 2.15.8
Version 2.8.6
- Small fixes to 2.8.5
Version 2.8.5
- Update Proguard rules related to R8 changes
Version 2.8.2
- Added new field "externalPaymentTokenId" in DigitizationGreenPath, DigitizationRequest and DigitizationResult models.
- Added new optional configuration withOptionalWalletMcbpHttpExecutor
- Marked configuration withUcpTransactionEventListener from UcpConfigurationBuilder as deprecated. Use MobileDcTransactionEventListener.optionalMobileDcTransactionEventListener from MDC SDK instead.
Version 2.7.4
- Added new field "paymentTokenExpirationDate" in PaymentInstrument model.
Version 2.7.3
- update MobileDC dependency to 2.15.3
Version 2.7.1
- update MobileDC dependency to 2.15.1
Version 2.7.0
- update MobileDC dependency to 2.15.0
Version 2.6.9.2
- update MobileDC dependency to 2.14.7.2
Version 2.6.9.1 - Hotfix possible OutOfMemoryException in MDC 2.14.7
- update MobileDC dependency to 2.14.7.1
Version 2.6.9 - don't use, could cause OOM Exception
- Updated Mobile DC dependency to 2.14.7.
- Updated *processDsrpTransaction* method.
Version 2.6.7
- Updated Mobile DC dependency to 2.14.6
- Added support for Mastercard India datacenter.
- **important** Added new method to UcpTransactionEventListener - *onContactlessPaymentStarted()***.** Callback allows application to get event about new transaction and it's a best place for token selection and user authentication. Read more in Product Overview.
- Due to adding new place for contactless payment authentiocation also updated code samples for *HostApduSevice* implementation and method *setUserAuthenthenticatedForPayment()*
- **Important** CloudMessagingService:process became deprecated due to introducing delivery message from server service. Read more in Product Overview and Mobile DC specification.
- **Important** Added new status *AbortReason:CONNECTION\_LOST* for *UcpTransactionEventListener:onContactlessPaymentAborted.* Status TERMINAL\_INACTIVITY\_TIMEOUT became deprecated. Change significally improves contactless payment UX. Method works immediatelly when connection between device and terminal is lost.
- **Important** Aded new optional configuration for *UcpTransactionConfiguration* with field *enableTransactionAuthenticationTimer.* Timer is now disabled by default, previously was always enabled and could cause problems when authentication time leading to zero and user performs transaction. It could cause clearing user authentication during processing payment on terminal. Change is related to other payments optimizations and introducing *onContactlessPaymentStarted()* and new *AbortReason CONNECTION\_LOST.* Please align your code to new changes, enabling timer is not recommended.
- Updated Mobile DC dependency to 2.13.7
- Resolved Google Play Console Security warning
- Updated Mobile DC dependency to 2.13.6
Version 2.5.5
- Wrap in try-catch block callbacks from SDK *setup()* method to prevent breaking process in SDK. Read more in *setup*() method description.
Version 2.5.3
- Update internal libraries. **IMPORTANT** Read more in Mobile DC changelog for version 2.13.3
Version 2.5.2
- Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality
Version 2.5.1
- Methods marked as deprecated:
- reset (use restart instead)
- getPaymentInstrument (use getAllPaymentInstruments instead)
- setDefaultForRemote (usage is redundant)
- getDefaultForRemote (usage is redundant)
- processDsrpTransaction(use new processDsrpTransaction method with *ProcessDsrpTransaction* added model)
- Added new methods related to OTP authentication code:
- requestAuthenticationCodeForPayment
- validateAuthenticationCodeForPayment
- Added new methods for supporting yellow-path token activation:
- checkEligibility
- digitize (new version with support for checkEligibility usage)
- submitTokenAuthenticationMethod
- submitTokenAuthenticationValue
- getAdditionalAuthenticationMethods
- Fixed getPaymentInstrument method (case invalid error when session expired error occurred).
- Updated Kotlin version to 1.5.31 and Koin to 2.1.6.
- Removed unused permissions *ACCESS\_FINE\_LOCATION* and *com.google.android.c2dm.permission.RECEIVE .*
- Added logs for all facade methods (available in SDK debug version).
Version 2.4.4
- Updated MDC SDK to 2.12.1 - fixed aggressive security process check
- Updated documentation for TransactionAbortReason:TERMINAL\_INACTIVITY\_TIMEOUT model
Version 2.4.3
- IMPORTANT Update security tools after EMV Security Evaluation - refer to Mobile DC technical documentation version changelog (version 2.12.0)
- Update Gradle and R8 tools
- Handled authentication flow for ContactlessRichTransactionType REFUND. SDK requires authentication if not provided.
- Improved description for ContactlesssTransactionResult model in documentation.
- Added new ContactlessRichTransactionType: WITHDRAWAL and ATM\_CONTACTLESS
Version 2.3.24
- Added new state for TransactionAbortReason::TERMINAL\_INACTIVITY\_TIMEOUT. Previously status was part of TransactionAbortReason::TERMINAL\_ERROR and produces contactless payment aborted handling problems. Status is used in onContactlessPaymentAborted callback. Application can ignore this state and do not perform any action.
- Added method on UcpApi for SDK restart(). Unlike reset() new method is asynchronous and allows to usage VCP SDK without application kill. Method clears all VCP SDK data and restarts to initial state.
- Introduced new approach to handling security issue. When application will call any SDK method after security issue reporting, UcpSkdExpcetion with SECURITY\_EVENT\_OCCURRED will be returned. Previously APPLICATION\_PROCESS\_NOT\_KILLED was returned. Change doesn't impact onSecurityIssue callback.
- Added Assets Domain and getAsset() method.
- Added verification of input parameters in token profile and transaction credentials replenish.
- Added more details in callbacks onProvisioningFailure and onReplenishFailure about errors in token related operations.
Version 2.3.22.2 - hotfix
- Added more validation for input parameters for External Wallet Server service
- Added data verification before accessing data in CMS-D processes
- Improved catching exceptions for MCBP processes
- Improved flow for reset() method - added protection agains processing messaging after SDK reset()
- Changed algorithm for calculating publicKeyCertificateFingerprint in PrepareRegistrationDataResponse. From hex(sha1(certificate.publicKey.encoded)) to hex(sha1(certificate.encoded))
- Added support for multiple calling setUserAuthenticatedForPayment() method
Version 2.3.22
- Improved internal SDK logs reporting
- Using androidX in end project is necessary now
- Improved automatic replenish credentials process
- Added handling ReDigititzation process in SDK. Use withOptionalReProvisionEventListener method in SDK setup method to observe PaymentInstrument changes
Version 2.3.21
- Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration
- Replenish process optimization
Version 2.3.18
- Updated security libraries
Version 2.3.17
- Fixed parsing merchantAndLocation field from ContactlessTransactionData.
- Added EWS configuration parameter in setup.
Version 2.3.13
- Added new parameter *result* to IbanDigitizationResult model
- Parameter *cloudDigitizationSuccess* in IbanDigitizationResult is now deprecated
Version 2.3.12
- Core module with update.
- Added new reports to Wallet Server.
Version 2.3.11
- Added new method in Payment Service: processDsrpTransaction
- Added new method in User Service: resendOtp
- Added new paremeter in createPaymentData IbanInfo model: userId
- Improved default PaymentInstrument management
- Fixed clearing SDK state when unpairing device (MobileDC unPair method)
Version 2.3.8
- Improved facade exception throwing, now contains more details about error.
- Removing whitespaces from merchantAndLocation in ContectlessTransactionData model
- Updated security harmful process check mechanism
- Added MCBP cloud messaging queue handling to prevent processing errors
Version 2.3.2
- Fixed SDK provisionning process on Google Pixel devices
- Improved default Payment Instrument management
- Updated security harmful process check mechanism
Version 2.3.1
- Added *delete* method in External Wallet Server domain
- Added more detailed descriptions for methods from External Wallet Server domain
- Added more information about models related to payment processing
Version 2.2.7
- Added reset functionality.
- Addded method in Ibans service createPaymentDat.
- Method createTVC iban service is now deprecated.
- Added global listener for most important internal SDK actions related to token managem
Version 2.2.6
- Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure
- Fixed problem with flow cutting on digitalization process
Version 2.2.4
- Added new enum state TransactionAbortReason.NO\_CARDS. Callback onContactlessPaymentAborted is now called when no card is available for payment.
- Added new model ContactlessTransactionData with better formatting terminal data. New object is added for events EventGetFinalDecision, EventAuthRequiredForContactless, EventContactlessPaymentCompleted.
- ContactlessTransactionInformation is now deprecated.
- Fixed setting default PaymentInstrument after activation
- Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status
Version 2.2.2
- Fixed dependencies conflicts
- Consumer Proguard rules update
-
Version 2.2.0
- Added new method in EWS Service - getEncryptedPin
- SDK startup optimization
- Fixed dependencies for release version
- Added information about SDK size
- Added information about SDK integration on lower Android API level
Version 2.1.0
-
Version 2.0.0
- Changed approach to SDK setup
- Added UcpSdkException
- Added new reason codes to existing exceptions
- New methods in cards domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in ibans domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in cloud messaging domain: processMcbpNotificationData
- New methods in payment domain: abortUserAuthenticationForPayment, replenishCredentials, restartContactlessTimer
- New methods in external wallet server domain: prepareRegistrationData, register
Version 1.0.1
- Created
# Technical Documentation VCP SDK - iOS (to review)
Important (to review): The iOS SDK is a separate product and documentation track. The Android VCP SDK documented on this page is not the same repository or deliverable as the iOS SDK. The links below are provided as separate references only.
SDK for smartphones: [https://developer-ios.verestro.com/vcpsdk/latest/documentation/](https://developer-ios.verestro.com/vcpsdk/latest/documentation/)
SDK for communciation to the Watch: [https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/](https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/)
# Technical Documentation MDC SDK
| ### MDC - Basic application flow
|
| **Android** [Link to Mobile DC SDK technical documentation](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/technical-documentation-mdc-sdk "User Lifecycle & Card Management API & SDK") |
| **iOS** [https://developer-ios.verestro.com/mobiledcsdk/latest/documentation/](https://developer-ios.verestro.com/mobiledcsdk/latest/documentation/) |
MDC SDK Services (to review)
MDC SDK is responsible for user, device and card management on Wallet Server side. It also exposes cloud messaging, address management and transaction history capabilities used by the Mobile Payment Application.
### Addresses (to review)
| Service responsibility |
| Address management for the current wallet user. Allows storing and maintaining postal addresses inside Wallet Server. |
| Available methods |
| getAll(), addAddress(), updateAddress(), deleteAddress() |
### Device (to review)
| Service responsibility |
| Device pairing, device state management and security incident reporting for a specific application installation. |
| Supported pairing methods |
| pairByPassword(), pairByTrustedIdentity(), pairByExternalCredentials() |
| Two-factor pairing |
| For projects requiring additional verification, pairing can be finalized with OTP-based second-factor authentication. In this flow MPA dispatches OTP using dispatchOtpForPairDeviceWithTwoFactor(), then completes pairing using finalizePairDeviceWithTwoFactorAuthentication(). |
| Additional methods |
| unPairDevice(), isDevicePaired(), reportSecurityIssueEvent() |
### Cloud Messaging (to review)
| Service responsibility |
| MDC SDK processes wallet-related push messages and updates the registration token stored on Wallet Server. |
| Integrator responsibility |
| MPA is responsible for obtaining FCM registration token, observing token refresh and calling updateRegistrationToken() whenever a new token is generated. |
### Transaction History (to review)
| Service responsibility |
| Transaction history retrieval and management for the current user. |
| Available capabilities |
| getTransactionsHistory() with filters and pagination, getTransactionDetails(), updateSingleTransactionData(), updateTransactionCategory(), getTransactionUserCategories(), storeAttachment(), deleteAttachment(), generateAttachmentLink(), getMonthlySpendingAmount() |
| User-facing functionality |
| History listing, transaction details, notes and custom data updates, custom categories, receipt or photo attachments, download links for attachments and monthly spending summaries. |
### IBAN (to review)
| Current status |
| IBAN service is currently reserved on MDC SDK level. Business IBAN payment flows are exposed by VCP SDK IBANs domain. |
# Technical documentation VCP External API
Technical Documentation VCP External API
@swagger="https://services.upaidtest.pl/ucp/doc.yaml/external"
# DRAFT W MD Technical Documentation VCP SDK
VCP SDK Introduction
### **Basic abbreviations and definitions**
| **Field** | **Description** |
| :---- | :--- |
| CDCVM | Consumer Device Cardholder Verification Method |
| CVM | Cardholder Verification Method |
| Contactless | Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to VCP SDK. HCE support is required for contactless transactions |
| DSRP | Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions |
| FCM | Firebase Cloud Messaging |
| HCE | Host Card Emulation |
| IBAN | Bank Account Number |
| MCBP | Mastercard Cloud Based Payments |
| MDC | Mobile Data Core. Verestro core library. |
| MPA | Mobile Payment Application - an application that uses VCP SDK for payments |
| NFC | Near Field Communication |
| One tap | Flow in a contactless transaction, in which the consumer after authentication (using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data |
| PAN | Primary account number. Know as a card number. |
| Payment Instrument | Model keeping all data considering entity used for payments |
| POS | Point Of Sale |
| SUK | Single Use Key - unique credential used for single transaction for Mastercard |
| LUK | Limited Use Key - payment credential for usage with Visa |
| Two tap | Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates (using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data |
| TVC | Token Verification Code |
| EWS | External Wallet Server |
| VCP | Verestro Cloud Payment |
### **What is VCP SDK?**
The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.
### **How VCP SDK works?**
Provides methods to manage digitization using main domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
*Depending on the selected payment instrument source (Card, Iban, External Wallet Server) VCP SDK allows to digitize it and provide methods for the payment process. Usage of the following domains depends on client requirements.*
### **Versioning and backward compatibility**
SDK version contains three digits. For example: `1.0.0`.
| **Version digit** | **Description** | **Update requirement** |
| :--- | :--- | :--- |
| **First** | Tracks compatibility-breaking changes in SDK public APIs. | 🔴 **Mandatory** to update the application code to use SDK when this is incremented. |
| **Second** | Tracks new, not compatibility-breaking changes in public API of SDK. | 🟡 **Optional** to update the application code when this digit is incremented. |
| **Third** | Tracks internal changes in SDK. | 🟢 **No updates** in application code are necessary to update to the version, which has this number incremented. |
Changes not breaking compatibility:
* Adding a new optional interface to SDK setup
* Adding a new method to any domain
* Adding a new ENUM value to input or output
* Adding a new field in the input or output model
Technical overview
### **SDK Basic configuration**
The `minSdkVersion` must be at least 23 (Android 6.0). The application must use AndroidX.
SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system. **The username and password are provided by Verestro.**
```gradle
repositories{
maven {
credentials {
username ""
password ""
}
url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
//if the sync time takes too long, add filters to match the repository with specific modules as below
content {
includeGroupByRegex "pl.upaid.*"
includeGroup "com.mastercard"
includeGroup "com.visa" //Only when Visa is used
}
}
}
```
VCP SDK is available in two versions: **debug** and **release**.
Debug version is ended with appendix "-debug" in version name. Samples below:
**For release version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**For debug version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}-debug'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}-debug'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**Min SDK version:**
The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.
```gradle
```
SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it.
### **VCP SDK Application Signing requirements**
Mastercard:
There is no requirement related to Application signing.
Visa:
Both sandbox (test) and production environment require APK signed with valid key. To add Application as Trusted in Visa services please provide Signing Key Certificate from chain in PEM format using below script:
```bash
keytool -exportcert -keystore your_apk_keystore.jks -alias your_keystore_key_alias -rfc -file certificate.pem
```
Output will be provided in certificate.pem file.
Please provide an result to Verestro representative with related applicationId (package).
Note: When using only Google Play signing key tests local tests related to Visa tokenization and payments will be not possible.
### **VCP SDK Size**
The size of SDK is dependent on its distribution system.
The table below shows the size of the module for the ask and bundle file.
| **Format** | **Size increment** | **Notes** |
| :--- | :--- | :--- |
| APK all architectures | ~13,6 MB | Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
| APK Arm64 | ~2.8 MB | Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
**VCP size already includes Mobile DC SDK size.**
Additional information:
- size from the table above is referred to release version;
- size depends on configured proguard;
### **VCP SDK Usage**
This chapter describes the structure and basic usage of VCP SDK.
#### ▹ **Domains**
#### **— Domains**
#### **· Domains**
#### **› Domains**
#### **▸ Domains**
#### ▸ Domains
#### **Domains**
Every of the described facades is divided into domains with different responsibilities. Available domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
* [x] **Assets (to review)**
* [x] **Every domain contains domain-related methods**
#### **Error handling**
Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods.
SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message.
Note: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.
| **Exception type** | **Exception class** | **Description** |
| :--- | :--- | :--- |
| SDK validation | ValidationException | Additional reason codes for ValidationException used in Mobile DC SDK |
| Backend exception | BackendException | Additional reason codes for BackendException used in Mobile DC SDK.
**Note:** Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain) |
| SDK exception | UcpSdkException | Something went wrong on the SDK side, check the table below with possible reasons |
| Process related | - | As every process is different some methods could throw a specified exception
Types of possible exceptions are described in the method description |
Additional BackendException reason codes:
| **Reason** | **Description** |
| :--- | :--- |
| INTERNAL\_ERROR | Error occurred on server |
| VALIDATION\_ERROR | Client sent invalid data |
| CRYPTOGRAPHY\_ERROR | Error occurred during cryptography operation |
| PAYMENT\_CARD\_PREDIGITIZE\_ERROR | Predigitize of payment card failed |
| PAYMENT\_IBAN\_PREDIGITIZE\_ERROR | Predigitize of payment IBAN failed |
| PAYMENT\_CARD\_DIGITIZE\_ERROR | Digitize of payment card failed |
| PAYMENT\_IBAN\_DIGITIZE\_ERROR | Digitize of payment IBAN failed |
| PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED | Predigitize for payment card must be executed |
| PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED | Predigitize for payment IBAN must be executed |
| CLIENT\_UNAUTHORIZED | Client of the API is unauthorized |
| USER\_UNAUTHORIZED | User is unauthorized |
| CANT\_FIND\_USER | Cannot find user |
| CANT\_FIND\_DEVICE | Cannot find device |
| CANT\_FIND\_IBAN | Cannot find payment IBAN |
| CANT\_FIND\_CARD | Cannot find payment card |
| CANT\_FIND\_PAYMENT\_TOKEN | Cannot find payment token |
| OPERATION\_NOT\_SUPPORTED | Requested operation is not supported |
| OPERATION\_NOT\_ALLOWED | Requested operation is not allowed |
| DEVICE\_TEMPORARILY\_LOCKED | Device is temporarily locked |
| DEVICE\_PERMANENTLY\_LOCKED | Device is permanently locked |
| INVALID\_PAN | The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly |
| MISSING\_EXPIRY\_DATE | The expiry date is required for this product but was missing |
| PAN\_INELIGIBLE | The PAN is not in an approved account range for TSP |
| DEVICE\_INELIGIBLE | The device is not supported for use |
| PAN\_INELIGIBLE\_FOR\_DEVICE | The PAN is not allowed to be provisioned to the device because of Issuer rules |
| IBAN\_INELIGIBLE | The financial account does not have an associated account range in TSP |
| PARALLEL\_REQUESTS\_ATTEMPTS | Action is already processing. Please try again after the time included in headers |
| INVALID\_JWS\_TOKEN | Specified JWS token is invalid |
Additional ValidationException reason codes:
| **Reason** | **Description** |
| :--- | :--- |
| INVALID\_SECURITY\_CODE | Security code is empty |
| INVALID\_LANGUAGE\_CODE | Language code is empty |
| INVALID\_PAYMENT\_INSTRUMENT\_ID | Payment instrument id is empty |
UcpSdkException reason codes:
| **Reason** | **Description** |
| :--- | :--- |
| PUSH\_INVALID\_SOURCE | Relates to push processing process. Push message should be consumed in another module |
| PUSH\_INVALID\_PUSH\_CONTENT | Cannot process push message. The message is invalid or some process failed |
| PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND | Cannot find default PaymentInstrument |
| PAYMENT\_INSTRUMENT\_NOT\_FOUND | Selected PaymentInstrument cannot be found, is not digitized or active |
| APPLICATION\_PROCESS\_NOT\_KILLED | Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process |
#### **Facade**
The facade is an entry point to communication with VCP SDK.
Contains SDK initialization method and domains which allows for payment instrument management.
#### **Method structure**
Please read Mobile DC Documentation for details.
#### **Multiple facade types**
VCP SDK provides three public APIs with the same functionalities, the APIs are:
- UcpJavaApi for projects which use Java programming language.
- UcpKotlinApi for projects which use Kotlin programming language.
The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same.
This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark).
#### **HceApduService registration**
To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service.
Properly configured meta-data in service will also register an application as tap&pay ready.
Exemplary service below:
```xml
```
Below listing of the default source file hce\_apud\_service.xml:
```xml
```
Check if the application is set as default for payment.
```kotlin
fun isSystemDefault(): Boolean {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
return cardEmulation.isDefaultServiceForCategory(
WalletHceService::class.java,
CardEmulation.CATEGORY_PAYMENT
)
}
```
Request for set your application as default for payment - will show a dialog for the user to approve the changes.
```kotlin
fun requestForSystemDefault() {
val intent = Intent().apply {
action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
putExtra("component", WalletHceService::class.java)
putExtra("category", CardEmulation.CATEGORY_PAYMENT)
}
context.startActivity(intent)
}
```
If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.
```kotlin
fun registerAsOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.setPreferredService(
activity, ComponentName(activity, WalletHceService::class.java)
)
}
fun unregisterFromOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.unsetPreferredService(activity)
}
```
#### **Models**
##### **PaymentInstrument**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| id | String | Id of payment instrument. For card it is cardId, for IBAN sha256Hex.
In the context of the External Wallet Server use tokenUniqueReference from MDES |
| paymentTokenId | String | Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id |
| displayablePanDigits | String | Token last 4 digits which can be used to display |
| paymentInstrumentStatus | PaymentInstrumentStatus | Enum with status of payment instrument. |
| contactlessSupported | Boolean | Information if payment instrument supports contactless transactions. |
| dsrpSupported | Boolean | Information if the payment instrument supports DSRP transactions. |
| qrcSupported | Boolean | Information if the payment instrument supports QR transactions. |
| onDeviceCvmSupported | Boolean | Information about supporting CVM on device. |
| credentialsCount | Int | Amount of credentials that can be used for payments.
Always 0 for Visa Cards. |
| isDefaultForContactlessPayment | Boolean | Information if payment instrument is default for contactless payments. |
| isDefaultForRemotePayment | Boolean | Information if payment instrument is default for remote payments. |
| additionalAuthenticationRequired | Boolean | Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods |
| tokenLastFourDigits | String? | Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentExpirationDate | String? | Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentLastFourDigits | String? | Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| productConfig | ProductConfig? | Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| provisioningStatus | String | Current state of provisioning process. One of:
IN\_PROGRESS - in case of waiting for *onProvisioningSuccess*(),
SUCCESS - when token is provisioned. |
| paymentTokenExpirationDate | String? | Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled. |
##### **PaymentInstrumentStatus**
| **Field** | **Description** |
| :--- | :--- |
| INACTIVE | Payment instrument is not active, it can not be used for transactions.
The activation process depends on integration. Read the product overview for more information. |
| ACTIVE | Payment instrument is active and it can be used for transactions. |
| SUSPENDED | Payment instrument is suspended. |
| DELETED | Payment instrument is DELETED. |
| UNKNOWN | Payment instrument status is unknown. |
##### **AdditionalAuthenticationMethod**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| id | String | Identifier of additional authentication method |
| name | String | Method name. One of:
OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER |
| value | String | Value depends on method name. Described below. |
| issuerParameters | AuthMethodsIssuerParameters? | Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION |
##### **Additional authentication method values:**
| **Method** | **Value** | **Description** |
| :--- | :--- | :--- |
| `OTP_TO_CARDHOLDER_NUMBER` | Masked phone number | Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number. |
| `OTP_TO_CARDHOLDER_EMAIL` | Masked email | Email to Account holder’s email address. The value will be the Account holder’s masked email address. |
| `CARDHOLDER_TO_CALL_CUSTOMER_SERVICE` | Phone number | Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service. |
| `CARDHOLDER_TO_VISIT_WEBSITE` | Website URL | Account holder to visit a website. The value will be the website URL. |
| `CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION` | Application name | (Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS. |
| `ISSUER_TO_CALL_CARDHOLDER_NUMBER` | Masked phone number | Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number. |
##### **AuthMethodsIssuerParameters contains the following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| mdes | AuthMethodsIssuerParametersMdes? | Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token |
| vts | AuthMethodsIssuerParametersVts? | Required for VTS Payment token |
##### **AuthMethodsIssuerParametersMdes contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| android | AuthMethodsIssuerParametersMdesAndroid | Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device |
| ios | AuthMethodsIssuerParametersMdesIos | Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device |
##### **AuthMethodsIssuerParametersMdesAndroid contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| action | String? | Name of the action to be performed |
| packageName | String? | The package name of the issuer's mobile app |
| extraTextValue | String? | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app |
##### **AuthMethodsIssuerParametersMdesIos contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deepLinkingUrl | String? | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. |
| extraTextValue | String? | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. |
##### **AuthMethodsIssuerParametersVts contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| android | AuthMethodsIssuerParametersVtsAndroid? | Plain AuthMethodsIssuerParametersVtsAndroid object.
Required for Android devices |
| ios | AuthMethodsIssuerParametersVtsIos? | Plain AuthMethodsIssuerParametersVtsIos object.
Required for IOS devices |
##### **AuthMethodsIssuerParametersVtsAndroid contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **AuthMethodsIssuerParametersVtsIos contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **ContactlessTransactionInformation**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| currencyCode | ByteArray | Code of currency, that was used in transaction. Formatted in ISO 4271. |
| amount | ByteArray | Transaction amount in bytes. Can be formatted as Int in pennies. |
| transactionRange | ContactlessTransactionRange | Type of transaction range. |
| richTransactionType | ContactlessRichTransactionType | Rich transaction type. |
| merchantAndLocation | ByteArray | Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset. |
**ContactlessTransactionRange**
| **Value** | **Description** |
| :--- | :--- |
| LVT | Low value transaction |
| HVT | High value transaction |
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| **Value** |
| :--- |
| PURCHASE |
| REFUND |
| CASH |
| TRANSIT |
| PURCHASE\_WITH\_CASHBACK |
| UNKNOWN |
##### **DsrpTransactionInfo**
| **Parameter** | **Type** | **Descruption** |
| :--- | :--- | :--- |
| amount | Long | Transaction amount |
| currencyCode | Int | Code of currency, that was used in transaction. |
| countryCode | Int | Code of country. |
| issuerCryptogramType | String | Cryptogram type. |
##### **TransactionAbortReason**
| **Value** | **Description** |
| :--- | :--- |
| WALLET\_CANCEL\_REQUEST | Indicates that the wallet has requested a transaction cancellation during payment. |
| CARD\_ERROR | This indicates that a problem has been detected in the MChipEngine processing.
In some implementations, this can indicate badly formatted card profile data. |
| TERMINAL\_ERROR | This indicates incorrect terminal behavior. |
| NO\_TRANSACTION\_CREDENTIALS | There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility. |
| NO\_CARDS | There is no active PaymentInstrument to start payment. Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). |
| TERMINAL\_INACTIVITY\_TIMEOUT | There is a problem with communication between the terminal and payment device.
For example, the terminal could abort communication with the mobile device for
a long period of time and then trigger a timeout.
Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal.
The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment.
**Note:** When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again.
**Note:** Deprecated in 2.6.7, no longer used due to time difference between connection lost and providing result to application. Replaced by CONNECTION\_LOST which works immediatelly. |
| CONNECTION\_LOST | Connection between terminal and device is lost and payment is terminated. |
| PAYMENT\_NOT\_ALLOWED | Payment is not allowed at this moment.
For Mastercard Card application should show error and user should retry payment.
For Visa Card application should wait for UcpVtsPaymentAllowedListener::onPaymentAllowed() |
##### **NewTransaction**
| **Field** | **Type** | **Description** |
| :--- | :--- | :--- |
| clientTransactionId | String? | Identifier of transaction in TSP |
| type | String | The transaction type. One of: \[UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER\] |
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example,
`EUR 2.35' will return 235, and `BHD -1.345' will return -1345 |
| currency | String | 3-digit ISO 4217 currency code |
| timestamp | String | The date/time when the transaction occurred. In ISO 8601 extended format |
| merchantName | String? | The merchant (``doing business as'') name |
| merchantPostalCode | String? | The postal code of the merchant |
| transactionCountryCode | String? | The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1 |
| comboCardAccountType | String? | An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: \[UNKNOWN, CREDIT, DEBIT\] |
| issuerResponseInformation | String? | Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: \[UNKNOWN, INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION\] |
| status | String | The authorization status of the transaction. One of: \[AUTHORIZED, DECLINED, CLEARED, REVERSED\] |
| paymentTokenId | String | Identifier of payment token in VCP |
##### **ContactlessTransactionData**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| currencyNumber | Int | Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. |
| currencyCode | String? | Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN
Could be null as the terminal provides only the currencyNumber and a valid code could be not found. |
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, |
| transactionRange | ContactlessTransactionRange | Type of transaction range. |
| richTransactionType | ContactlessRichTransactionType | Rich transaction type. |
| merchantAndLocation | String | Merchant and location data from terminal.
**Deprecated** - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data. |
**ContactlessTransactionRange**
| **Value** | **Description** |
| :--- | :--- |
| LVT | Low value transaction |
| HVT | High value transaction |
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| **Value** | **Description** |
| :--- | :--- |
| PURCHASE | |
| REFUND | |
| CASH | |
| TRANSIT | |
| PURCHASE\_WITH\_CASHBACK | |
| UNKNOWN | |
| WITHDRAWAL | |
| ATM\_CONTACTLESS | |
##### **Report**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| name | String | Action name |
| description | String | Action details message. |
| isSuccess | Boolean | Result of action. True when action is finished successfully, false otherwise. |
| timestamp | Long | Time when the action occurred. |
| errorMessage | String? | Detailed error message when isSuccess is false. |
##### **ContactlessAdvice**
| **Parameter** | **Description** |
| :--- | :--- |
| DECLINE | Declines a processing transaction.
When provided by SDK in *getFinalDecisionForTransaction* wallet should not overrule a DECLINE.
If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response. |
| AUTHENTICATION\_REQUIRED | An user authentication is required for transaction processing, which could be overruled on the MPA side.
When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the *onAuthRequiredForContactless* method. |
| PROCEED | Transaction can be processed. |
##### **ContactlessTransactionResult**
Important! MPA should always refer to transaction results on the terminal.
| **Value** | **Description** | **Is success on MPA side** |
| :--- | :--- | :--- |
| AUTHORIZE\_ONLINE | This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization.
The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal.
Should be treated as transaction success on the MPA side. | Yes |
| AUTHENTICATE\_OFFLINE | This indicates that the POS requested a decline (AAC) with a CDA signature.
SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature.
Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization.
Should be treated as transaction success on the MPA side. | Yes |
| DECLINE\_BY\_TERMINAL | The POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request.
Paying on the terminal with offline-only network connectivity can also return this callback.
Application Cryptogram was generated with genuine credentials.
Should be treated as transaction success on the MPA side. | Yes |
| DECLINE\_BY\_CARD | The digitized card has declined the transaction. A non-exhaustive list of possible reasons may be:
- Context mismatch between first and second tap
- Terminal is offline-only
- Terminal is a transit gate, and transit transactions are not allowed by the card profile
- Transaction is international, while the card profile is domestic-only | No |
| WALLET\_ACTION\_REQUIRED | If the *getFinalDecisionForTransaction* returns an AUTHENTICATION\_REQUIRED status then this result will be returned.
The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap.
If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place. | No |
#### **External libraries**
The SDK uses several external Apache 2.0 libraries:
- com.nimbusds:nimbus-jose-jwt
- commons-codec:commons-codec
- com.fasterxml.jackson.core:jackson-core
- com.fasterxml.jackson.core:jackson-annotations
- com.fasterxml.jackson.core:jackson-databind
- com.fasterxml.jackson.module:jackson-module-kotlin
- io.insert-koin:koin-android
- io.reactivex.rxjava2:rxjava
- io.reactivex.rxjava2:rxandroid
- com.squareup.retrofit2:adapter-rxjava2
- com.squareup.retrofit2:retrofit
- com.squareup.retrofit2:converter
- com.squareup.okhttp3:logging
- com.squareup.okhttp3:okhttp
VCP SDK Setup
VCP SDK has to be configured every time when is used. Before VCP SDK usage Mobile DC SDK should be already configured.
### **setup**
| Synchronous. Offline.
:--- |
Note: Contains all the necessary data to configure SDK.
Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method.
Requires MobileDC setup() already finished
Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished.
When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand.
Important! Before calling VCP SDK setup you must call setup from Mobile DC SDK.
Note: Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment and loading first aplication screen.
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| ucpConfiguration | UcpConfiguration | VCP configuration provided in builder described below. | Not empty. |
**UcpConfigurationBuilder** contains the following methods:
| **Metod** | **Parameter** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| withApplication | Application | Application context. | Not empty |
| withCvmModel | WalletCvmModel (enum) | Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE | Not empty |
| withUserAuthMode | WalletAuthMode (enum) | User authentication mode: WALLET\_PIN, CUSTOM, NONE
Contact Verestro to select proper configuration | Not empty |
| withUcpPaymentInstrument
EventListener | UcpPaymentInstrument
EventListener | Global listener for actions on PaymentInstrument. | Not empty |
| withUcpTransaction
EventListener | UcpTransactionEventListener | Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing | Not empty |
| withTransactionAcceptance
EventListener | UcpTransactionAcceptance
EventListener | Global listener which allow application take final decision about transaction acceptance during transaction | Not empty |
| withReplenishThreshold | Int | Number of credentials below which replenish process will automatically begin | Not empty |
| withMcbpPinningCertificates | List | List of public key certificates in PEM format.
Pass list with empty String if *withOptionalUcpMcbpHttpExecutor* mentioned below is used with custom HTTP communication. | Not empty List |
| withOptionalEventsReports | UcpEventReportListener | Global listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. | Optional |
| withOptional
ExternalWalletServer | | Prepares SDK for using external wallet server. | Optional |
| withOptional
UcpMcbpHttpExecutor | UcpMcbpHttpExecutor/
DefaultUcpMcbpHttpExecutor | Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. | Optional |
| withOptional
UcpReProvisionEventListener | UcpReProvisionEventListener | Global listener for actions during reprovisioning. | Optional |
| withOptional
UcpTransactionConfiguration | UcpTransactionConfiguration | Transaction configuration. Allow to enable deprecated authentication timer called when authentication is peformed.
Timer is disabled by default, usage is not recomended. | Optional |
| withOptionalWallet
McbpHttpExecutor | | Prepares SDK for processing CMS-D HTTP requests with Wallet Server proxy. | Optional |
| withOptionalEnableVisaSDK | | Enables Visa SDK usage, requires gradle dependencies configuration | Optional |
| withOptionalVtsPayment
ReadyCallback | UcpVtsPaymentAllowedListener | Provides information if payment with Visa Token is allowed with callback onPaymentAllowed().
Application should wait for callback when Visa Card is used. | Optional |
**UcpPaymentInstrumentEventListener**
Contains callbacks for PaymentInstrument.
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onProvisioning
Success | paymentInstrument: PaymentInstrument | Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below |
| onProvisioning
Failure | errorMessage: String?,
exception: Exception? | Method called after provisioning failure. Try processing digitization again |
| onReplenish
Success | paymentInstrument: PaymentInstrument
numberOfTransactionCredentials: Int | Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials.
Depending on flow is called after activation process and when requested by SDK based on *replenishThreshold* configuration.
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
| onReplenish
Failure | paymentInstrument: PaymentInstrument,
errorMessage: String?,
exception: Exception? | Method called after replenish failure with PaymentInstrument
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
| onPayment
Instrument
StatusChanged | newStatus: PaymentInstrument
Status
paymentInstrumentId: String | Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id |
| onNewTransaction | newTransaction: NewTransaction | Provides online result with details of transaction processed in VCP
Works only when application is online |
**UcpTransactionEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onAuthRequired
ForContactless | paymentInstrument: PaymentInstrument, transactionInformation:
ContactlessTransactionInformation
transactionData: ContactlessTransactionData | Called when user authentication is required during contactless transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
| onAuthRequired
ForDsrp | paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo | Called when user authentication is required during Dsrp transaction |
| onAuthTimer
Updated | secondsRemaining: Int | Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration.
Note: Deprecated and disabled by default in version 2.6.7.
To enable use configuration avaialble in SDK *setup::withOptionalUcpTransactionConfiguration.* |
| onContactless
PaymentStarted | \- | Called on very beginnging of every transaction start (SELECT\_PPSE APDU command). E.g. first tap to terminal or second tap if *onAuthRequiredForContactless* method was called.
Locks communication until method is finished.
Method duration directly impacts on transaction time. |
| onContactless
Payment
Completed | paymentInstrument: PaymentInstrument
transactionInformation:
ContactlessTransactionInformation
transactionResult: ContactlessTransactionResult
transactionData : ContactlessTransactionData,
transactionId:String | Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
transactionId - transaction identifier for Mastercard transactions, allow to match transaction with processed transaction notification from Mobile DC SDK: *EventNewTransaction::clientTransactionId.* |
| onContactless
Payment
Incident | paymentInstrument: PaymentInstrument,
exception: Exception | Called when something went wrong during transaction and Mastercard marked transaction as incident |
| onContactless
Payment
Aborted | paymentInstrument: PaymentInstrument?,
abortReason: TransactionAbortReason,
exception: Exception | Called when transaction is aborted during payment from some reason described in method parameter
PaymentInstrument could be null if abortReason = TransactionAbortReason.NO\_CARDS is returned.
Note: SDK clears passed selected card with method *selectForPayment()* and authentication with *setUserAuthenticatedForPayment()* |
| onTransaction
Stopped | | Method called on transaction stopped by SDK.
Deprecated in version 2.6.7, no longer used. |
**UcpTransactionAcceptanceEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| getFinal
Decision
ForTransaction | isUserAuthenticated : Boolean
recommendedAdvice : ContactlessAdvice
trasactionInformation :
ContactlessTransactionInformation
transactionData : ContactlessTransactionData | Called on every transaction for the final decision about transaction processing
An application can decide based on information about authentication, transaction details like amount, currency, and transaction types
The method also provide recommended by MCBP advice based on transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
**UcpEventReportsListener**
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onNewReport | report: Report | Return logs related to token management. |
**UcpReProvisionEventListener**
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
| **Method Name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onReProvisionSuccess | paymentInstrument: PaymentInstrument | Method called after reProvisioning process.
Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback. |
| onReProvisionFailure | paymentInstrument : PaymentInstrument
errorMessage : String?
exception : Exception? | Method called after reProvisioning failure. Try again. |
**UcpMcbpHttpExecutor**
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| execute | ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod:
UcpMcbpHttpMethod,
url: String,
requestData:Any,
requestProperties:
Map | Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
``` |
**DefaultUcpMcbpHttpExecutor**
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| execute | ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType
ucpMcbpHttpMethod: UcpMcbpHttpMethod
url: String
requestData: Any
requestProperties: Map | Called on every time if SDK want to connect to MasterCard and should return super.execute method.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
``` |
**UcpTransactionConfiguration**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| enableTransaction
AuthenticationTimer | Boolean | Allows to enable deprecated authentication timer.
Timer is started along *setUserAuthenticatedForPayment(),* result is available in *onAuthTimerUpdated().* |
**Callback samples:**
**UcpTransactionEventListener**
```
// UcpTransactionEventListener comments
class BankingAppUcpTransactionEventListener : UcpTransactionEventListener {
override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and ContactlessTransactionData available in event object
showPaymentScreen(event.paymentInstrument, event.transactionData)
}
override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and DSRP transaction information available in event object
showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo)
}
override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) {
//check if user is on payment screen and update timer
//when timer is 0, application should close payment with failure
//deprcated, disabled by default, read method description how to enable
}
override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) {
//looks like payment is aborted, can provide result to payment screen
//and show user what is abort reason
}
override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) {
//payment completed, provide result to payment information
//REMEMBER Transaction is processed on terminal and this is where
//you will see final transaction result
}
override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) {
//something went wrong during transaction, provide result to user
}
override fun onTransactionStopped() {
//deprecated, not used anymore,
}
override fun onContactlessPaymentStarted() {
//Payment started or resumed after callback onAuthReqiredForContactless
//Best place for checking if user is authenticated for payment and call
//setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected
}
}
```
**UcpPaymentInstrumentEventListener**
```
class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener {
override fun onNewTransaction(event: EventNewTransaction) {
//information about new transaction processed by issuer
}
override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
//status of payment instrument was changed, refresh list, inform user about new status
}
override fun onProvisioningFailure(event: EventProvisioningFailure) {
//provisioning failed, try again
}
override fun onProvisioningSuccess(event: EventProvisioningSuccess) {
//provisioning success, wait for status and replenish changes until user can pay
//or provide activation method when required
}
override fun onReplenishFailure(event: EventReplenishFailure) {
//transaction credentials replenish failed
}
override fun onReplenishSuccess(event: EventReplenishSuccess) {
//transaction credentials replenish success
}
}
```
**UcpTransactionAcceptanceEventListener**
```
class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener {
//Sample implementation of transaction acceptance listener
//For the scanario when authentication is required on issuer side for every transaction
//field even.isUserAuthenticated must be always true, otherwise
//ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned
override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice {
val isScreenUnlocked = isScreenUnlocked()
val isScreenProtectedByKeyguard = isScreenUnlocked()
val isLvtTransaction =
event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT
//discard all Transit transaction
if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) {
return ContactlessAdvice.DECLINE
}
//allow for transaction when user is authenticated for payment and screen unlocked
if (event.isUserAuthenticated && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
//allow for LVT transaction on unlocked screen when protected and don't require authentication
if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
// ...
// much more cases
//require authentication anyway
return ContactlessAdvice.AUTHENTICATION_REQUIRED
}
}
```
**UcpEventReportsListener**
```
class BankReportEventListener : UcpEventReportsListener {
override fun onNewReport(report: Report) {
//may be used for debugging SDK or gathering reports on client's app or backend
}
}
```
**UcpMcbpHttpExecutor**
```
//Use UcpMcbpHTtpExecutor as supertype if you want to replace connection
class BankUcpMcbpHttpExecutor : UcpMcbpHttpExecutor {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
//invoke connect by custom connector
return when (ucpMcbpRequestType) {
UcpMcbpHttpExecutorRequestType.REQUEST_SESSION -> {
executeRequestSession(ucpMcbpHttpMethod, url, requestData as UcpMcbpRequestSessionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.PROVISION -> {
executeProvision(ucpMcbpHttpMethod, url, requestData as UcpMcbpProvisionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.REPLENISH -> {
executeReplenish(ucpMcbpHttpMethod, url, requestData as UcpMcbpReplenishRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.NOTIFY_PROVISIONING_RESULT -> {
executeNotifyProvisioningResult(ucpMcbpHttpMethod, url,
requestData as UcpMcbpNotifyProvisioningResultRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.CHANGE_MOBILE_PIN -> {
executeChangeMobilePin(ucpMcbpHttpMethod, url,
requestData as UcpMcbpChangeMobilePinRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.DELETE -> {
executeDelete(ucpMcbpHttpMethod, url, requestData as UcpMcbpDeleteRequestData,
requestProperties)
}
}
}
}
```
**DefaultUcpMcbpHttpExecutor**
```
//Use DefaultUcpMcbpHTtpExecutor as supertype if you want to only add some action before connection
class BankDefaultUcpMcbpHttpExecutor : DefaultUcpMcbpHttpExecutor() {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
return super.execute(
ucpMcbpRequestType,
ucpMcbpHttpMethod,
url,
requestData,
requestProperties
)
}
}
```
**UcpReProvisionEventListener**
```
class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() {
override fun onReProvisionSuccess(event: EventReProvisionSuccess) {
//reProvisioning success, wait for status and replenish changes until user can pay
}
override fun onReProvisionFailure(event: EventReProvisionFailure) {
//reProvisioning failed, try again.
}
}
```
**UcpTransactionConfiguration**
```
class BankingAppUcpTransactionConfiguration : UcpTransactionConfiguration {
override val enableTransactionAuthenticationTimer: Boolean = false
}
```
**UcpVtsPaymentAllowedListener**
```
class BankingAppUcpVtsPaymentAllowedListener : UcpVtsPaymentAllowedListener {
override fun onPaymentAllowed() {
//when during a payment an status of PAYMENT_NOT_ALLOWED is received
//Application UI should show transaction error and wait for onPaymentAllowed() callback
//When received callback shouuld inform UI to process transaction again
}}
```
**Sample VCP SDK setup implementation**
Mobile DC setup() and VCP setup() method could be called on MainThread in Application:onCreate as blocking or another thread.
When applicaiton has multiple dependencies there is possible to call both setup() methods on another thread (MobileDC setup() method must be already finished until VCP setup() is called).
Important: In case of loading SDK on another thread and using contactless payments HostApduService must be used asynchronous way to prevet using SDK until loading is finished - check sample for method *PaymentService:processHceApduCommand*.
```kotlin
fun setup(
application: Application,
walletCvmModel: WalletCvmModel,
walletAuthUserMode: WalletAuthUserMode,
mcbpPinningCertificates: List,
replenishThreshold: Int
) {
val ucpConfiguration = UcpConfiguration.create(
UcpConfigurationBuilder()
.withApplication(application)
.withCvmModel(walletCvmModel)
.withUserAuthMode(walletAuthUserMode)
//marked as deprecated - see description above
.withUcpTransactionEventListener(BankingAppUcpTransactionEventListener())
.withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener())
.withMcbpPinningCertificates(mcbpPinningCertificates)
.withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener())
.withReplenishThreshold(replenishThreshold)
.withOptionalEventsReports(BankReportEventListener())
.withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor())
//if you want to only add additional action before connection use below implementation
//.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor())
.withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener())
//if you want to change standard transaction configuration use configuration below
.withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration())
//.withOptionalEnableVisaSDK() //optional when Visa is used
//.withOptionalVtsPaymentReadyCallback(BankingAppUcpVtsPaymentAllowedListener()) //optional when Visa is used
)
UcpApiKotlin().setup(ucpConfiguration)
}
```
### **reset (DEPRECATED - use restart instead)**
| Synchronous. Offline.
Method for resetting SDK to uninitialized state.
|
| :--- |
Note: According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. Please kill application process after using this method. Trying using any facade method without stopping application process will cause throwing UcpSdkException.
To avoid closing application use restart() methods.
**Input**
No input.
**Output**
No output.
**Sample**
**Sample VCP SDK reset implementation:**
```kotlin
fun reset() {
UcpApiKotlin().reset()
//Terminating JVM according to MC SDK Sample Application
Runtime.getRuntime().exit(0);
}
```
### **restart**
| Synchronous. Offline.
Method for resetting SDK to uninitialized state.
Replaces reset() method which requires killing application process.
When restart finishes with error, application should repeat action. |
| :--- |
Note: SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again.
**Input**
No input.
**Output**
Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods.
Failure callback when something went wrong during restart. Application should repeat action.
**Sample**
**Sample VCP SDK reset implementation:**
```
UcpApiKotlin().restart({
//restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods
}, {
//some error occured, please repeat action
})
```
Cards domain
### **delete**
| Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
:--- |
Result of action will be notified with onPaymentInstrumentStatusChanged.
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of PaymentInstrument to delete | Not empty. |
| reason | CharArray? | Optional reason of deletion | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.cardsService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
### **checkEligibility**
| Asynchronous. Online.
Check eligibility required to process digitize. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| checkEligibility | CheckEligibility | CheckEligibility object |
CheckEligibility
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] |
| userLanguage | String | User language |
| userCountry | String | User country |
**Output**
| Success callback with CheckEligibilityResult. |
| :--- |
CheckEligibilityResult
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| termsAndConditionsAssetId | String | Identifier of Terms and Conditions asset |
| Failure callback |
| :--- |
**Sample**
```
private fun checkEligibility(
paymentInstrumentId: String,
paymentInstrumentType: PaymentInstrumentType,
userLanguage: String,
userCountry: String
) {
ucpApi.cardsService
.checkEligibility(
CheckEligibility(
paymentInstrumentId,
paymentInstrumentType,
userLanguage,
userCountry
),
{ checkEligibilityResult ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
| Asynchronous. Online.
Use only when *checkEligibility* method is used.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| digitizationRequest | DigitizationRequest | Plain object of DigitizationRequest | Not empty |
DigitizationRequest object contains following fields:
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] | Not empty |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized | |
| externalPaymentTokenId | String? | Optional. Unique external identifier of Payment Token | |
**Output**
Success callback with DigitizationResult object
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| digitizationResult | DigitizationResult | Plain object of DigitizationResult |
DigitizationResult contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Plain object of PaymentInstrument |
| additionalAuthenticationMethods | List? | All available additional authentication method |
| productConfig | ProductConfig | Plain object of ProductConfig, contains Payment Token configuration |
| externalPaymentTokenId | String? | Optional. External payment token id configured by the consumer. In case of identifier duplicate an random id is generated |
ProductConfig contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| isCoBranded | Boolean | Whether the product is co-branded |
| coBrandName | String? | Name of the co-branded partner |
| foregroundColor | String | Foreground color, used to overlay text on top of the card image |
| backgroundColor | String | Background color, used to overlay text on top of the card image |
| labelColor | String? | Label color of the mobile wallet entry for the card |
| issuerName | String | Name of the issuing bank |
| shortDescription | String | A short description for this product |
| longDescription | String? | A long description for this product |
| custoremServiceUrl | String? | Customer service website of the issuing bank |
| customerServiceEmail | String? | Customer service email address of issuing bank |
| customerServicePhoneNumber | String? | Customer service phone number of the issuing bank |
| productConfigIssuer | ProductConfigIssuer? | Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app |
| onlineBankingLoginUrl | String? | Login URL for the issuing bank's online banking website |
| termsAndConditionsUrl | String? | URL linking to the issuing bank's terms and conditions for this product |
| privacyPolicyUrl | String? | URL linking to the issuing bank's privacy policy for this product |
| issuerProductConfigCode | String? | Freeform identifier for this product configuration as assigned by the issuer |
| contactName | String? | Name of the issuing bank |
| bankAppName | String? | Name of banking application for display |
| bankAppAddress | String? | The package name for the destination mobile application |
| unsupportedPresentationTypes | String? | The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request |
| unsupportedCardVerificationTypes | String? | The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) |
| issuerFlags | List? | List of plain ProductConfigIssuerFlags object. Contains issuer flags |
| brandLogoAssetId | String | The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID |
| issuerLogoAssetId | String | The logo of the issuing bank. Provided as a Asset ID |
| coBrandLogoAssetId | String? | The co-brand logo (if any) for this product. Provided as an Asset ID |
| cardBackgroundCombinedAssetId | String? | The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID |
| cardBackgroundAssetId | String? | The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID |
| iconAssetId | String | The icon representing the primary brand(s) associated with this product. Provided as an Asset ID |
ProductConfigIssuer contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| openIssuerAndroidIntent | ProductConfigOpenIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| activateWithIssuerAndroidIntent | ProductConfigActivateWithIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| openIssuerIOSDeepLinkingUrl | ProductConfigOpenIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| activateWithIssuerIOSDeepLinkingUrl | ProductConfigActivateWithIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
ProductConfigOpenIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deepLinkinUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deepLinkingUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigIssuerFlags contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deviceBinding | Boolean | Device binding |
| cardholderVerification | Boolean | Whether the issuer participating in step-up flow |
| trustedBeneficiaryEnrollment | Boolean | Whether this is a trusted beneficiary enrollment |
| delegateAuthenticationSupported | String | Whether issuer supports delegated authentication |
| Failure callback |
| :--- |
Sample
```kotlin
fun digitizeCard(digitizationRequest: DigitizationRequest) {
ucpApi.cardsService
.digitize( digitizationRequest,
{ digitizationResult ->
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize (deprecated)**
| Asynchronous. Online. |
| :--- |
Deprecated - use digitize(DigitizationGreenPath) instead.
| Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty. |
| userLanguage | String | Language preference selected by the consumer. Formatted as an
ISO-639-1 two letter language code | Not empty. |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun digitizeCard(
paymentInstrumentId: String,
languageCode: String,
securityCode: CharArray) {
ucpApi.cardsService
.digitize(paymentInstrumentId, languageCode, securityCode,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
| Asynchronous. Online.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| digitizationGreenPath | DigitizationGreenPath | Plain object of DigitizationGreenPath | Not empty |
DigitizationGreenPath contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized |
| userLanguage | String | User language |
| userCountry | String | User country |
| externalPaymentTokenId | String? | Optional. Unique external identifier of Payment Token |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```
fun digitizeCard(digitizationGreenPath: DigitizationGreenPath) {
ucpApi.cardsService
.digitize(digitizationGreenPath,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAdditionalAuthenticationMethods**
| Asynchronous. Online.
Retrieves additional user authentication methods. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| getAdditionalAuthenticationMethods | GetAdditionalAuthenticationMethods | Plain object of GetAdditionalAuthenticationMethods | Not empty |
Fields of GetAdditionalAuthenticationMethods object:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
**Output**
| Success callback with AdditionalAuthenticationMethods object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| additionalAuthenticationMethods | AdditionalAuthenticationMethods | Object carrying list of AdditionalAuthenticationMethod |
AdditionalAuthenticationMethods contains following value:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| additionalAuthenticationMethods | List | List of AdditionalAuthenticationMethod objects |
| Failure callback. |
| :--- |
**Sample**
```
private fun getAdditionalAuthenticationMethods() {
val getAdditionalAuthenticationMethod =
GetAdditionalAuthenticationMethods("paymentInstrumentId")
ucpApi
.cardsService
.getAdditionalAuthenticationMethods(
getAdditionalAuthenticationMethod,
{ additionalAuthenticationMethods ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **submitTokenAuthenticationValue**
| Asynchronous. Online.
Submit authentication code when additional user authentication is required. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| authenticationCode | String | Authentication code |
**Output**
| Success callback/failure callback. |
| :--- |
**Sample**
```
private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) {
ucpApi.cardsService
.submitAuthenticationValue(
SubmitAuthenticationValue(
paymentInstrumentId,
authenticationCode
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **submitTokenAuthenticationMethod**
| Asynchronous. Online.
Submit authentication method when additional user authentication is required. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| authenticationMethodId | String | Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. |
**Output**
| Success callback/failure callback. |
| :--- |
**Sample**
```
private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) {
ucpApi.cardsService
.submitAuthenticationMethod(
SubmitAuthenticationMethod(
paymentInstrumentId,
authenticationMethodId
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
| Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to increase UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network and user session required) | |
**Output**
| Success callback with list of PaymentInstrument objects. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstruments | List | List of retrieved payment instruments from local or remote storage |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.cardsService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument (deprecated)**
| Asynchronous. Online/Offline.
Deprecated - use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of instrument to retrieve | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) | |
**Output**
| Success callback with PaymentInstument object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.cardsService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
IBANs domain
### **digitize**
| Asynchronous. Online.
Registers user and device if already not registered in VCP backend. Creates payment token in VCP backend.
Expect push after successfull finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| signedAccountInfo | String | Signed AccountInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
| fcmRegistrationToken | CharArray | FCM Cloud messaging registration token | Not empty. |
| languageCode | String | Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code | Not empty. |
**AccountInfo:**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| userId | String | External user id | Not empty. |
| iban | String | Bank Account Number | Not empty. |
| countryCode | String | The country of the financial account
Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 | Not empty. |
**Output**
| Success callback. Called when device token digitization finished with success .Result contains *IbanDigitizationResult* object.
Note: Cloud token digitization fail doesn't affect on success/failure callback. |
| :--- |
IbanDigitizationResult contains following fields:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| (DEPRECATED) cloudDigitizationSuccess | Boolean | Cloud Token Digitization Details |
| result | CloudDigitizationResult | Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN |
| Failure callback. Called when **device token** digitization finished with failure. |
| :--- |
**Sample**
Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAccountInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("userId", "externalUserId")
.claim("iban", "IN15HIND23467433866365")
.claim("countryCode", "IND")
.build()
val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey)
// ...
}
```
```kotlin
fun digitizeIban(
signedAccountInfo: String,
fcmRegistrationToken: CharArray,
languageCode: String) {
ucpApi.ibansService
.digitize(signedAccountInfo, fcmRegistrationToken, languageCode,
{ ibanDigitizationResult ->
//Device token digitization finished with success
//wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success
val cloudDigitizationResult = ibanDigitizationResult.result
//check status of Cloud Token
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **createTVC**
| Asynchronous. Online.
Provides Transaction Verification Code required to process cloud payments. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* | Not empty. |
**Output**
| Success callback with Tvc object or encrypted Tvc object as String. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| plainTvc | PlainTvc? | Plain PlainTvc object |
| encryptedTvc | CharArray? | Encrypted PlainTvc object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation |
PlainTvc object contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| accountNumber | CharArray | Primary Account Number for the transaction – this is the Token PAN |
| dynamicExpiryDate | CharArray | Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC | CharArray | Dynamic CVC |
| Failure callback when TVC cannot be created. |
| :--- |
**Sample**
Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createTvc(signedIbanInfo: String) {
ucpApi.ibansService
.createTVC(signedIbanInfo, { tvc ->
//result object could contains encrypted TVC
val encryptedTvc: String? = tvc.encryptedTvc
//or decrypted(plain) TVC object with parameters described in documentation
val plainTvc = tvc.plainTvc
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **createPaymentData**
| Asynchronous. Online.
This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* | Not empty. |
| userId | String | External user id given by the client | Not empty. |
**Output**
| Success callback with PaymentData object or encrypted payment data object as String. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| plainPaymentData | PlainPaymentData? | Plain PlainPaymentData object |
| encryptedPaymentData | String? | Encrypted PlainPaymentData object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation |
PlainPaymentData object contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| accountNumber | String | Primary Account Number for the transaction – this is the Token PAN |
| applicationExpiryDate | String? | Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format |
| panSequenceNumber | String? | Rrquired only for UCAF. Application PAN sequence number for the Token |
| track2Equivalent | String? | Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed |
| ucafCryptogram | String? | Required only for UCAF. UCAF cryptogram |
| dynamicExpiryDate | String? | Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC | String? | Dynamic CVC |
| Failure callback when PaymentData cannot be created. |
| :--- |
**Sample**
Sample generation of *signedIbanInfo* (see [Data signing and encryption](https://wiki.verestro.com/display/UCP/Data+signing+and+encryption) chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.claim("userId", "123")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createPaymentData(signedIbanInfo: String) {
ucpApi.ibansService
.createPaymentData(signedIbanInfo, { paymentData ->
//result object could contains encrypted PaymentData
val encryptedPaymentData: String? = paymentData.encryptedPaymentData
//or decrypted(plain) PaymentData object with parameters described in documentation
val plainPaymentData = paymentData.plainPaymentData
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getAllPaymentInstruments**
| Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network required) | |
**Output**
| Success callback with list of PaymentInstrument objects |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstruments | List | List of retrieved payment instruments |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.ibansService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument(deprecated)**
| Asynchronous. Online/Offline.
Use *getAllPaymentInstruments* instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of instrument to retrieve. | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) | |
**Output**
| Success callback with PaymentInstument object |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.ibansService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **delete**
| Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with *onPaymentInstrumentStatusChanged*. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of PaymentInstrument to delete | Not empty. |
| reason | CharArray? | Optional reason of deletion | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.ibansService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
Payment domain
### **setDefaultForContactless**
| Asynchronous. Offline.
Sets payment instrument as default for contactless payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically after linking with PoS terminal.
Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun setDefaultForContactless(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) {
//make sure selected PaymentInstrument can be seta as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForContactless(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForContactless**
| Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success callback with id new default PaymentInstrument |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Default Payment instrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getDefaultForContactless() {
ucpApi.paymentService
.getDefaultForContactless({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **setDefaultForRemote (deprecated)**
| Asynchronous. Offline.
Sets payment instrument as default for DSRP payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically to remote payments. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun setDefaultForRemote(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
&& !paymentInstrument.dsrpSupported) {
//make sure selected PaymentInstrument can be set as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForRemote(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForRemote (deprecated)**
| Asynchronous. Offline.
Provides default PaymentInstrument for remote payments.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success callback with id new default PaymentInstrument |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Default Payment instrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getDefaultForRemote() {
ucpApi.paymentService
.getDefaultForRemote({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **selectForPayment**
| Asynchronous. Offline.
Sets payment instrument as primary for next incoming payment. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentd | String | Payment instrument identity | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
| **Note:** This is only sample payment scenation |
| :--- |
```
//sample scenario of starting payment with authentication before payment
fun startPayment(paymentInstrument: PaymentInstrument) {
//checking conditions before payment
val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
val isContactlessSupported = paymentInstrument.contactlessSupported
val hasTransactionCredentials = paymentInstrument.credentialsCount > 0
if (!isActive || !isContactlessSupported || !hasTransactionCredentials) {
//PaymentInstrument doesn't meet requirements for payment
return
}
//selecting PaymentInstrument to payment
ucpApi.paymentService
.selectForPayment(paymentInstrument.id, {
//selection success
//request user authentication when
//... authentication presented
//use setUserAuthenticatedForPayment method
}, { throwable ->
//something went wrong, check exception with documentation
})
}
```
### **setUserAuthenticatedForPayment**
| Asynchronous. Offline.
Sets user as authenticated to payment with provided payment instrument.
Authentication clearing depends on authentication timer configuration in *UcpTransactionConfiguration:enableTransactionAuthenticationTimer*.
By default timer is disabled and authentication is cancelled when user perform transaction and SDK send callback *onContactlessPaymentCompleted/Aborted/Incident* from *UcpTransactionEventListener*.
When timer is enabled authentication is cleared when auth timer finishes - it could casue problems when user start to pay just before timer finish. Authentication could be cleared by SDK during payement.
If application call *setUserAuthenticatedForPayment* without contactless payment context and authentication timer is disabled, authentication is never cleared by SDK. To clear authentication use *abortUserAuthenticationForPayment.*
*UcpTransactionEventListener:onContactlessPaymentStarted* is recommended place for payment authentication.
**Note:** User can be authenticated based on conditions like screen unlock. Method must be called before payment in method UcpTransactionEventListener:onContactlessPaymentStarted()
Make sure that authentication on this step is done securely. Transaction information is not available on this step. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
| pin | CharArray? | PIN or null for CUSTOM WalletAuthUserMode | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
Basic user authentication usage below, call when user is authenticated.
```
private fun setUserAuthenticatedForPayment(
paymentInstrument: PaymentInstrument,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser,
{
//user authentication provided
//start one tap payment or continue two tap with 2nd tap to terminal after authentication
//listen for auth timer changes
//user abortUserAuthentication method when transaction cancelled by user
}, { throwable ->
//some error, check exception
})
}
```
Optional authentication before making transaction based on custom conditions.
```
override fun onContactlessPaymentStarted() {
//check internal conditions
//like user performed authentication, is logged in application, is device unlocked etc
val isUserAuthenticated = true
//check if use selected any token for payment and select it in UCP SDK
//otherwise default token will be used
if (getSelectedPaymentInstrumentId() != null) {
ucpApi
.paymentService
.selectForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
success = {
//token will be used for actual payment
//call setUserAuthenticatedForPayment here - sample below in "else" block
},
failure = { throwable ->
//something went wrong, check throwable with documentation
}
)
} else {
if (isUserAuthenticated) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
pin = null, //or pin if MobilePin is used
success =
//user authenticated in SDK
}, failure = {
//authentication failure, check exception
}
)
}
}
}
```
### **abortUserAuthenticationForPayment**
| Asynchronous. Offline.
Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun abortUserAuthenticationForPayment() {
ucpApi
.paymentService
.abortUserAuthenticationForPayment(
{
//user authentication aborted
//listen for auth timer changes
},
{ throwable ->
//some error, check exception
})
}
```
### **processHceApduCommand**
| Synchronous. Offline.
Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS.
Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| context | Context | Application context, can be provided from HostApduService | Not empty |
| apdu | ByteArray | APDU command from HostApduService::processCommandApdu method parameter | Not empty |
| extras | Bundle? | Extras object from HostApduService::processCom mandApdu method parameter | |
**Output**
| Apdu result - method called synchronous without callback |
| :--- |
| **Parameter.** | **Type** | **Description** |
| :--- | :--- | :--- |
| apdu | ByteArray | APDU command to return in implementation of overridden processCommandApdu method |
**Sample (synchronized HostApduService)**
Use this version if MobileDC:setup and UCP:setup() method is called in Application:onCreate on Main Thread.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(this, commandApdu, extras)
}
//..
}
```
**Sample (aynchronous HostApduService)**
Use this version if SDK is called on another thread and HostApduService can receive APDU until VCP SDK is still in loading state.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
//UcpSdkStateApplicationSingleton is sample class which keep SDK state and allow to observe when SDK load is finished
if (UcpSdkStateApplicationSingleton.isLoaded()) {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
} else {
sendResponseApdu(null)
UcpSdkStateApplicationSingleton.listenForSdkReady(
onSdkLoadListener = {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
}
)
}
return null
}
override fun onDeactivated(reason: Int) {
if (UcpSdkStateApplicationSingleton.isLoaded()) {
return ucpApi
.paymentService
.handleHceApduDeactivationEvent(reason)
}
}
private fun processCommandApduInUcpSdk(
context: Context,
commandApdu: ByteArray,
extras: Bundle?
): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(context, commandApdu, extras)
}
}
//sample objec which helps to listen SDK state
object UcpSdkStateApplicationSingleton : UcpSdkState {
//flag could be synchronized
private var isLoaded = false
private var onSdkLoadListener: (() -> Unit)? = null
override fun listenForSdkReady(onSdkLoadListener: () -> Unit) {
this.onSdkLoadListener = onSdkLoadListener
if (isLoaded) this.onSdkLoadListener?.invoke()
}
//call when SDK loading thread is finished
//setupMdc() -> setupUcp() -> UcpSdkStateApplicationSingleton.onUcpSdkLoaded()
override fun onUcpSdkLoaded() {
isLoaded = true
onSdkLoadListener?.invoke()
}
override fun isLoaded(): Boolean {
return isLoaded
}
}
```
### **replenishCredentials**
| Asynchronous. Online. User login session not required.
Method for manually replenishing payment credentials.
Application will receive push notification and notified about replenish process with global callback described in *setup* chapter. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument that needs it credentials replenished | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun replenishCredentials(paymentInstrumentId: String) {
ucpApi.paymentService
.replenishCredentials(paymentInstrumentId,
{
//request for credentials replenish finished with success
//wait for push notification and pass to valid module
//when push processed application will be informed about replenish success/failure
//read chapter with setup for more information
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **restartContactlessAuthTimer**
| Asynchronous. Offline.
Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile.
Default auth time is provided by card profile. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success / failure callback |
| :--- |
### **requestAuthenticationCodeForPayment**
| Asynchronous. Online.
Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| requestAuthenticationCodeForPayment | RequestAuthenticationCodeForPayment | Plain RequestAuthenticationCodeForPayment object | Not empty |
RequestAuthenticationCodeForPayment object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| authenticationRequestId | String | Authentication request id up to 64 alphanumeric characters long.
A new id should be used for each instance than an account holder needs to be authenticated | Not empty |
**Output**
| Success callback/failure callback. |
| :--- |
**Sample**
```kotlin
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) {
ucpApi.paymentService
.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//Requesting Authentication Code went successfully.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **validateAuthenticationCodeForPayment**
| Asynchronous. Online.
Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| validateAuthenticationCodeForPayment | ValidateAuthenticationCodeForPayment | Plain ValidateAuthenticationCodeForPayment object | Not empty |
ValidateAuthenticationCodeForPayment object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| authenticationRequestId | String | Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. | Not empty |
| authenticationCode | String | Authentication Code to authenticate the account holder | Not empty |
**Output**
| Success callback with ValidateAuthenticationCodeForPaymentResult object. |
| :--- |
ValidateAuthenticationCodeForPaymentResult object contains following field
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| signedAuthenticationProcessData | String | Signed AuthenticationProcessData per RFC 7519 |
AuthenticationProcessData model
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| authenticationRequestId | String | Authentication request id |
**Sample**
```kotlin
fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) {
ucpApi.paymentService
.validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment,
{ validateAuthenticationCodeForPaymentResult ->
//ValidateAuthenticationCodeForPaymentResult plain object,
//contains data to validate on backend
val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult
.signedAuthenticationProcessData
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAuthenticationProcessData {
fun verifyAndGetAuthenticationRequestID() {
val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600);
val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId")
// ...
}
}
```
### **processDsrpTransaction(deprecated)**
| Asynchronous. Online. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | | |
**Output**
| Success callback with cryptogram for payment |
| :--- |
| Failure callback |
| :--- |
### **processDsrpTransaction**
| Asynchronous. Offline.
Method dedicated for starting DSRP transaction.
Every DSRP transaction has to be authenticated before processing.
Depending on implementation payment can be process with OTP authentication or device level authentication. |
| :--- |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| processDsrpTransaction | ProcessDsrpTransaction | Plain ProcessDsrpTransaction object | Not empty |
ProcessDsrpTranasction object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | Plain DsrpTransactionInfo object | Not empty |
DsrpTransactionInfo object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| amountMinor | Long | A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 | Not empty |
| currencyCode | String | A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. | Not empty |
| countryCode | String? | A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. | |
| issuer
Cryptogram
Type | DsrpIssuer
Cryptogram
Type | Enum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. | Not empty |
| unpredictable
Number | Long | A long representing the random number generated by the merchant or by the Payment Gateway. The maximum value is 4,294,967,295. | Not empty |
| transactionType | Dsrp
Transaction
Type | A type of financial transaction, one of: PURCHASE, CASH, PURCHASE\_WITH\_CASHBACK, REFUND | Not empty |
| transactionDate | Date? | A Date object indicating date of transaction. | |
**Output**
| Success callback with ProcessDsrpTransactionResult object. |
| :--- |
ProcessDsrpTransactionResult object contains following field
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| transaction
Cryptogram
Data | ByteArray | A byte array containing a formatted response, either UCAF or a set of TLV data for the merchant to populate DE55 data. |
| pan | String | String containing the PAN of the card used. |
| panSequence
Number | Int | An integer value specifying the PAN Sequence Number (PSN) of the card used. |
| cryptogramType | DsrpIssuer
Cryptogram
Type | Enum value as UCAF or DE55 depending on cryptogram data format is used. |
| track2Data | String | String containing the data elements of track 2 according to ISO/IEC 7813. |
| par | String | String representation of byte array of permanent account reference. A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens. |
| expirationDate | String | Date in ISO-8601 (YYYY-MM-DD) format indicating expiry date of the card. |
| transactionId | String | Hexed byte array containing a Transaction Identifier. |
**Errors**
DsrpPaymentException exception throwed on error in DSRP processing
| **DsrpPaymentException.reason** | **Description** |
| :--- | :--- |
| DSRP\_INVALID\_INPUT | Invalid input data. |
| DSRP\_UNEXPECTED\_DATA | Provided data is valid in context of validation, but doesn't mee |
| DSRP\_AUTHENTICATION\_REQUIRED | Authentication is not provided for DSRP payment. Authenticate and process DSRP transaction again. |
| DSRP\_TOKEN\_INACTIVE | Token used for DSRP is inactive. |
| DSRP\_NO\_TRANSACTION\_CREDENTIALS | There is no transaction credentials to procees DSRP payment |
| DSRP\_NOT\_SUPPORTED\_BY\_CARD | DSRP is not suported by Card. |
| DSRP\_TRANSACTION\_DECLINED | Transaction is declined by Card. |
| DSRP\_INCOMPATIBLE\_PROFILE | Card profile is incomaptible with DSRP. |
| DSRP\_WRONG\_STATE | DSRP transaction is in wrong state. |
| DSRP\_INTERNAL\_ERROR | Unknowne error during DSRP processing. |
**Sample** **DSRP transaction with device level authentication**
```
// After Merchant App delivers DSRP data application should authenticate user with device level authentication
// and next execute setUserAuthenticationForPayment().
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTranasctionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample DSRP transaction with OTP authentication**
```
// After Merchant App delivers DSRP data user should request authentication
// code for payment with selected paymentInstrument.
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment =
RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId)
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) {
ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//When requesting went successfully User will get authentication code.
//In next step authentication code should be passed to MPA and application
//should validate this code with validateAuthenticationCode() method
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
val validateAuthenticationCode: ValidateAuthenticationCode =
ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser)
fun validateAuthenticationCode(validateAuthenticationCode) {
ucpApi.paymentService
.validateAuthenticationCode( validateAuthenticationCode,
{ validateAuthenticationCodeResulty ->
//ValidateAuthenticationCodeResult plain object
val signedAuthenticationProcessData = validateAuthenticationCodeResulty
.signedAuthenticationProcessData
//If validation went successfully MPA should show authentication view,
//and after valid authentication MPA should execute setUserAuthenticatedForPayment()
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTransactionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample input and output DSRP data:**
```Java
Input:
amountMinor: 4321,
countryCode: 840,
currencyCode: 840,
issuerCryptogramType: UCAF,
transactionDate: Apr 25, 2023 09:41:05, //Date() toString() format
transactionType: PURCHASE,
unpredictableNumber: 29496729
Output:
pan: 5204830959972699
track2Data: 5204830959972699D26052010000000000000
expirationDate: 2026-05-31 //YYYY-MM-DD
par: 500170A4PEV2GLWPFD00N6H5AX2YB
panSequenceNumber: 0
transactionId: df25a522a075680acbaa407fdc8a0348a321f77afa2f0231cd38f28e7ae691e2
cryptogramType: UCAF
transactionCryptogramData: 414d506a6d4a474650306149414155427768575a47674144464b553d //in Hex
```
Cloud messaging domain
### **process (deprecated in 2.6.7)**
| Asynchronous. Online. User login session not required.
Processes data sent by VCP backend (push notification data).
Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method.
Method can throw InvalidPushException in case of invalid push content passed to it.
Refer Mobile DC documentation how to handle push.
Deprecated in 2.6.7, use MobileDC:CloudMessaging:process() instead. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| pushData | Map | Data received from notification service in object RemoteMessage object | Not empty |
**Output**
| Success / failure callback. When request fails try again |
| :--- |
**Sample**
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map) {
ucpApi
.cloudMessagingService
.process(pushData, {
//push processed in Mobile DC
}, {
//some error
})
}
```
### **processMcbpNotificationData**
| Asynchronous. Offline.
Processes data sent by MCBP.
Application should check senderId in RemoteMessage object before passing data to VCP SDK.
Basic configuration for push processing from External Wallet Server: [External Wallet Server domain](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain).
Method can throw InvalidPushException in case of invalid push content passed to it.
**Note:** External Wallet Server Registration process mus be finished before push processing. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| encryptedPayload | String | Data received from notification service in object RemoteMessage object | Not empty |
**Output**
| Success / failure callback |
| :--- |
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String? = remoteMessage.from
val pushData = remoteMessage.data
//check push source based on senderId
if (isVerestroSenderId(senderId)) {
val verestroPayload: String = readVerestrpPushContent(pushData)
ucpApi
.cloudMessagingService
.processMcbpNotificationData(verestroPayload, {
//push processed in VCP
}, {
//some error
})
} else {
//proceed push from another source
}
}
```
External Wallet Server domain
Chapter contains method for SDK when External Wallet Server is used.
Usage of method requires additional configuration with external API.
Basic MDES cloud messaging configuration:
| **Environment** | **FCM Sender Id** |
| :--- | :--- |
| MTF | 502118574555 |
| PRODUCTION | 993764297204 |
### **prepareRegistrationData**
| Asynchronous. Offline.
Method for preparing data used for activation.
Should be used before calling register method. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentAppInstanceId | String | Identifier for the specific Mobile Payment App instance | Not empty |
| paymentAppProviderId | String | Globally unique identifier for the Wallet Provider, as assigned by MDES | Not empty |
| publicKeyCertificate | String | CMS-D public key certificate in pem format | Not empty |
| mobilePin | CharArray? | Mobile PIN used to payment confirmation | |
**Output**
| Success callback with PrepareRegistrationResponse object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| publicKeyCertificateFingerprint | String | CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) |
| encryptedRgk | String | Encrypted randomly-generated 128-bit AES key. |
| deviceInfo | EwsDeviceInfo | Device info. |
| deviceFingerprint | String | Unique device fingerprint. |
| encryptedPin | String? | Encrypted pin (if passed in input). |
EwsDeviceInfo model:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deviceName | String | Device model name. |
| formFactor | String | The form factor of the target provisioned device. |
| storageTechnology | String | The architecture or technology used for token storage. |
| osName | String | The name of the operating system of the target provisioned device. |
| osVersion | String | The version of the operating system of the target provisioned device. |
| nfcCapable | Boolean | Whether the target provisioned device has NFC capability. |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun prepareRegistrationData(
paymentAppInstanceId: String,
paymentAppProviderId: String,
publicKeyCertificate: String,
mobilePin: CharArray?) {
ucpApi
.ewsService
.prepareRegistrationData(paymentAppInstanceId,
paymentAppProviderId,
publicKeyCertificate,
mobilePin,
{ prepareRegistrationResponse ->
//Prepared data for registration including encryptedMobilePin if mobilePin is used
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **register**
| Asynchronous. Online.
Method used for registration new Mobile Payment App instance with MDES for use. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| mobileKeysetId | String | Identifies the Mobile Keys used for this remote management session | Not empty |
| ewsMobileKeys | EwsMobileKeys | Contains the mobile keys used to secure the communication during subsequent remote management sessions | Not empty |
| remoteManagementUrl | String | The URL endpoint for subsequent remote management sessions
The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions | Not empty |
EwsMobileKeys
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| transportKey | String | The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES |
| macKey | String | The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES |
| dataEncryptionKey | String | The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun register(
mobileKeysetId: String,
ewsMobileKeys: EwsMobileKeys,
remoteManagementUrl: String) {
ucpApi
.ewsService
.register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl,
{
//Device registration success
//application should listen to push messages and UcpPaymentInstrumentEventListener callbacks
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **activate**
| Asynchronous. Online.
Method to activate PaymentInstrument.
Should be used only on PaymentInstrumens which PaymentInstrumentStatus is SUSPENDED or INACTIVE.
Changes PaymentInstrumentStatus to ACTIVE, calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available.
Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to activate. | Not empty. |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun activate(paymentInstrumentId: String) {
ucpApi
.ewsService
.activate(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to ACTIVE, set card as default for payment if another
//is not already setted Performing replenish,
//application should listen to push message with information about replenish success/failure
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **suspend**
| Asynchronous. Offline.
Method for suspending paymentInstrument.
Changes PaymentInstrumentStatus to SUSPENDED.
Use activate method to allow payments again. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to suspend. | Not empty. |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun suspend(paymentInstrumentId: String) {
ucpApi
.ewsService
.suspend(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to SUSPENDED.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument**
| Asynchronous. Offline.
Method for getting single PaymentInstrument from local storage object based on id. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to get. | Not empty. |
**Output**
| Success callback with PaymentInstrument object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Retrieved paymentInstrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String) {
ucpApi.ewsService
.getPaymentInstrument(paymentInstrumentId,
{ paymentInstrument ->
//PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
| Asynchronous. Offline.
Method for getting all payment instruments from local storage. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success callback with list of PaymentInstrument objects. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstruments | List | List of retrieved payment instruments from local storage |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getAllPaymentInstrument() {
ucpApi.ewsService
.getAllPaymentInstruments(
{ paymentInstruments ->
//List of PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getEncryptedPin**
| Asynchronous. Offline.\|
Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| pin | CharArray | PIN to encrypt. | Not empty. |
**Output**
| Success callback with encrypted mobile PIN. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| encryptedMobilePin | String | Hex encoded encrypted mobile PIN. |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getEncryptedPin(pin: CharArray) {
ucpApi
.ewsService
.getEncryptedPin(pin, { encryptedPin ->
//call to Wallet Server with new created encrypted mobile PIN
//when updated call onMobilePinChanged method
}, {
//Something went wrong, check exception with documentation
})
}
```
### **onMobilePinChanged**
| Asynchronous. Online.
Method for informing SDK about mobilePin change.
Should be used when mobilePin changed.
The result of action is deletion of existing transaction credentials and replenish. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun reactOnMobilePinChanged() {
ucpApi
.ewsService
.onMobilePinChanged(
{
// Informing SDK about changing mobile pin processed succesfully.
// SDK should delete and next replenish transaction credentials.
// Listen for UcpPaymentInstrumentEventListener events
}, { throwable ->
// Something went wrong, check exception with documentation.
})
}
```
### **delete**
| Asynchronous. Online.
Method to removing PaymentInstrument.
Removed transaction credentials and PaymentInstrument from local storage and in MDES.
When success PaymentInstrument will be no longer available in *getPaymentInstrument* and *getPaymentInstruments* methods. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to delete. | Not empty. |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String) {
ucpApi
.ewsService
.delete(paymentInstrumentId,
{
//Selected Payment instrument is removed
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Assets Domain
### **getAsset**
| Asynchronous. Online.
Method for getting all assets for selected assetId. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| assetId | String | Id of assets to retrive | Not empty |
**Output**
| Success callback with list of Assets objects. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| ucpAsset | UcpAsset | Plain UcpAsset object |
UcpAsset object contains following field
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| content | List | Plain list of UcpAssetContent objects |
UcpAssetContent contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| data | String | The data for this asset. Base64-encoded data, given in the format as specified in type. |
| type | String | The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. |
| width | Long? | For image assets, the width of this image. Specified in pixels. |
| height | Long? | For image assets, the width of this image. Specified in pixels. |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun getAsset(assetId: String) {
ucpApi.assetsService
.getAssets( assetId,
{ ucpAsset ->
//List of assets of selected assetId
val ucpAssetContentList = ucpAsset.content
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Document changelog
Vesion 2.10.10
- Added new field for digitization: *formFactor*
- Mobile DC updated to 2.17.3
Vesion 2.10.0
- Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes)
- Security tools updated to newest version
- Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22)
- AGP updated to 8.11.1
- Mobile DC updated to 2.17.0
Version 2.9.10
- Added new parameter *transactionId* to method *onContactlessPaymentCompleted* for Mastercard transactions.
New transaction identifier allow to match transaction with processed transaction notification *MobileDC::EventNewTransaction::clientTransactionId.*
- Mobile DC updated to 2.16.12
Version 2.9.8
- **IMPORTANT: Security tools updated to newest version. Recommneded update when using version 2.9.x due to changes fixes in security tools.**
- Visa SDK updated to 6.4.0
- Mobile DC updated to 2.16.10
Version 2.9.5
- Added MC *mtf* host name
- Update Mobile DC to 2.16.5
Version 2.9.4
- **Important:** Apply security and functional certification changes related to intruduction new security tools. Changes in security thread management and working in background
- Update Mobile DC to 2.16.4
Version 2.8.7
- Update Mobile DC to 2.15.8
Version 2.8.6
- Small fixes to 2.8.5
Version 2.8.5
- Update Proguard rules related to R8 changes
Version 2.8.2
- Added new field "externalPaymentTokenId" in DigitizationGreenPath, DigitizationRequest and DigitizationResult models.
- Added new optional configuration withOptionalWalletMcbpHttpExecutor
- Marked configuration withUcpTransactionEventListener from UcpConfigurationBuilder as deprecated. Use MobileDcTransactionEventListener.optionalMobileDcTransactionEventListener from MDC SDK instead.
Version 2.7.4
- Added new field "paymentTokenExpirationDate" in PaymentInstrument model.
Version 2.7.3
- update MobileDC dependency to 2.15.3
Version 2.7.1
- update MobileDC dependency to 2.15.1
Version 2.7.0
- update MobileDC dependency to 2.15.0
Version 2.6.9.2
- update MobileDC dependency to 2.14.7.2
Version 2.6.9.1 - Hotfix possible OutOfMemoryException in MDC 2.14.7
- update MobileDC dependency to 2.14.7.1
Version 2.6.9 - don't use, could cause OOM Exception
- Updated Mobile DC dependency to 2.14.7.
- Updated *processDsrpTransaction* method.
Version 2.6.7
- Updated Mobile DC dependency to 2.14.6
- Added support for Mastercard India datacenter.
- **important** Added new method to UcpTransactionEventListener - *onContactlessPaymentStarted()***.** Callback allows application to get event about new transaction and it's a best place for token selection and user authentication. Read more in Product Overview.
- Due to adding new place for contactless payment authentiocation also updated code samples for *HostApduSevice* implementation and method *setUserAuthenthenticatedForPayment()*
- **Important** CloudMessagingService:process became deprecated due to introducing delivery message from server service. Read more in Product Overview and Mobile DC specification.
- **Important** Added new status *AbortReason:CONNECTION\_LOST* for *UcpTransactionEventListener:onContactlessPaymentAborted.* Status TERMINAL\_INACTIVITY\_TIMEOUT became deprecated. Change significally improves contactless payment UX. Method works immediatelly when connection between device and terminal is lost.
- **Important** Aded new optional configuration for *UcpTransactionConfiguration* with field *enableTransactionAuthenticationTimer.* Timer is now disabled by default, previously was always enabled and could cause problems when authentication time leading to zero and user performs transaction. It could cause clearing user authentication during processing payment on terminal. Change is related to other payments optimizations and introducing *onContactlessPaymentStarted()* and new *AbortReason CONNECTION\_LOST.* Please align your code to new changes, enabling timer is not recommended.
- Updated Mobile DC dependency to 2.13.7
- Resolved Google Play Console Security warning
- Updated Mobile DC dependency to 2.13.6
Version 2.5.5
- Wrap in try-catch block callbacks from SDK *setup()* method to prevent breaking process in SDK. Read more in *setup*() method description.
Version 2.5.3
- Update internal libraries. **IMPORTANT** Read more in Mobile DC changelog for version 2.13.3
Version 2.5.2
- Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality
Version 2.5.1
- Methods marked as deprecated:
- reset (use restart instead)
- getPaymentInstrument (use getAllPaymentInstruments instead)
- setDefaultForRemote (usage is redundant)
- getDefaultForRemote (usage is redundant)
- processDsrpTransaction(use new processDsrpTransaction method with *ProcessDsrpTransaction* added model)
- Added new methods related to OTP authentication code:
- requestAuthenticationCodeForPayment
- validateAuthenticationCodeForPayment
- Added new methods for supporting yellow-path token activation:
- checkEligibility
- digitize (new version with support for checkEligibility usage)
- submitTokenAuthenticationMethod
- submitTokenAuthenticationValue
- getAdditionalAuthenticationMethods
- Fixed getPaymentInstrument method (case invalid error when session expired error occurred).
- Updated Kotlin version to 1.5.31 and Koin to 2.1.6.
- Removed unused permissions *ACCESS\_FINE\_LOCATION* and *com.google.android.c2dm.permission.RECEIVE .*
- Added logs for all facade methods (available in SDK debug version).
Version 2.4.4
- Updated MDC SDK to 2.12.1 - fixed aggressive security process check
- Updated documentation for TransactionAbortReason:TERMINAL\_INACTIVITY\_TIMEOUT model
Version 2.4.3
- IMPORTANT Update security tools after EMV Security Evaluation - refer to Mobile DC technical documentation version changelog (version 2.12.0)
- Update Gradle and R8 tools
- Handled authentication flow for ContactlessRichTransactionType REFUND. SDK requires authentication if not provided.
- Improved description for ContactlesssTransactionResult model in documentation.
- Added new ContactlessRichTransactionType: WITHDRAWAL and ATM\_CONTACTLESS
Version 2.3.24
- Added new state for TransactionAbortReason::TERMINAL\_INACTIVITY\_TIMEOUT. Previously status was part of TransactionAbortReason::TERMINAL\_ERROR and produces contactless payment aborted handling problems. Status is used in onContactlessPaymentAborted callback. Application can ignore this state and do not perform any action.
- Added method on UcpApi for SDK restart(). Unlike reset() new method is asynchronous and allows to usage VCP SDK without application kill. Method clears all VCP SDK data and restarts to initial state.
- Introduced new approach to handling security issue. When application will call any SDK method after security issue reporting, UcpSkdExpcetion with SECURITY\_EVENT\_OCCURRED will be returned. Previously APPLICATION\_PROCESS\_NOT\_KILLED was returned. Change doesn't impact onSecurityIssue callback.
- Added Assets Domain and getAsset() method.
- Added verification of input parameters in token profile and transaction credentials replenish.
- Added more details in callbacks onProvisioningFailure and onReplenishFailure about errors in token related operations.
Version 2.3.22.2 - hotfix
- Added more validation for input parameters for External Wallet Server service
- Added data verification before accessing data in CMS-D processes
- Improved catching exceptions for MCBP processes
- Improved flow for reset() method - added protection agains processing messaging after SDK reset()
- Changed algorithm for calculating publicKeyCertificateFingerprint in PrepareRegistrationDataResponse. From hex(sha1(certificate.publicKey.encoded)) to hex(sha1(certificate.encoded))
- Added support for multiple calling setUserAuthenticatedForPayment() method
Version 2.3.22
- Improved internal SDK logs reporting
- Using androidX in end project is necessary now
- Improved automatic replenish credentials process
- Added handling ReDigititzation process in SDK. Use withOptionalReProvisionEventListener method in SDK setup method to observe PaymentInstrument changes
Version 2.3.21
- Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration
- Replenish process optimization
Version 2.3.18
- Updated security libraries
Version 2.3.17
- Fixed parsing merchantAndLocation field from ContactlessTransactionData.
- Added EWS configuration parameter in setup.
Version 2.3.13
- Added new parameter *result* to IbanDigitizationResult model
- Parameter *cloudDigitizationSuccess* in IbanDigitizationResult is now deprecated
Version 2.3.12
- Core module with update.
- Added new reports to Wallet Server.
Version 2.3.11
- Added new method in Payment Service: processDsrpTransaction
- Added new method in User Service: resendOtp
- Added new paremeter in createPaymentData IbanInfo model: userId
- Improved default PaymentInstrument management
- Fixed clearing SDK state when unpairing device (MobileDC unPair method)
Version 2.3.8
- Improved facade exception throwing, now contains more details about error.
- Removing whitespaces from merchantAndLocation in ContectlessTransactionData model
- Updated security harmful process check mechanism
- Added MCBP cloud messaging queue handling to prevent processing errors
Version 2.3.2
- Fixed SDK provisionning process on Google Pixel devices
- Improved default Payment Instrument management
- Updated security harmful process check mechanism
Version 2.3.1
- Added *delete* method in External Wallet Server domain
- Added more detailed descriptions for methods from External Wallet Server domain
- Added more information about models related to payment processing
Version 2.2.7
- Added reset functionality.
- Addded method in Ibans service createPaymentDat.
- Method createTVC iban service is now deprecated.
- Added global listener for most important internal SDK actions related to token managem
Version 2.2.6
- Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure
- Fixed problem with flow cutting on digitalization process
Version 2.2.4
- Added new enum state TransactionAbortReason.NO\_CARDS. Callback onContactlessPaymentAborted is now called when no card is available for payment.
- Added new model ContactlessTransactionData with better formatting terminal data. New object is added for events EventGetFinalDecision, EventAuthRequiredForContactless, EventContactlessPaymentCompleted.
- ContactlessTransactionInformation is now deprecated.
Version 2.2.3
- Fixed setting default PaymentInstrument after activation
- Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status
Version 2.2.2
- Fixed dependencies conflicts
- Consumer Proguard rules update
- Certificate pinning implementation improvement
Version 2.2.0
- Added new method in EWS Service - getEncryptedPin
- SDK startup optimization
Version 2.1.1
- Fixed dependencies for release version
- Added information about SDK size
- Added information about SDK integration on lower Android API level
Version 2.1.0
- Added new methods in External Wallet Server domain (activate, suspend, getPaymentInstrument, getPaymentInstruments, onMobilePinChanged)
Version 2.0.0
- Changed approach to SDK setup
- Added UcpSdkException
- Added new reason codes to existing exceptions
- New methods in cards domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in ibans domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in cloud messaging domain: processMcbpNotificationData
- New methods in payment domain: abortUserAuthenticationForPayment, replenishCredentials, restartContactlessTimer
- New methods in external wallet server domain: prepareRegistrationData, register
Version 1.0.1
- Created
# draft v2
VCP SDK Introduction
### **Basic abbreviations and definitions**
| Field |
Description |
| CDCVM |
Consumer Device Cardholder Verification Method |
| CVM |
Cardholder Verification Method |
| Contactless |
Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to VCP SDK. HCE support is required for contactless transactions |
| DSRP |
Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions |
| FCM |
Firebase Cloud Messaging |
| HCE |
Host Card Emulation |
| IBAN |
Bank Account Number |
| MCBP |
Mastercard Cloud Based Payments |
| MDC |
Mobile Data Core. Verestro core library. |
| MPA |
Mobile Payment Application - an application that uses VCP SDK for payments |
| NFC |
Near Field Communication |
| One tap |
Flow in a contactless transaction, in which the consumer after authentication (using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data |
| PAN |
Primary account number. Know as a card number. |
| Payment Instrument |
Model keeping all data considering entity used for payments |
| POS |
Point Of Sale |
| SUK |
Single Use Key - unique credential used for single transaction for Mastercard |
| LUK |
Limited Use Key - payment credential for usage with Visa |
| Two tap |
Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates (using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data |
| TVC |
Token Verification Code |
| EWS |
External Wallet Server |
| VCP |
Verestro Cloud Payment |
### **What is VCP SDK?**
The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.
### **How VCP SDK works?**
Provides methods to manage digitization using main domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
*Depending on the selected payment instrument source (Card, Iban, External Wallet Server) VCP SDK allows to digitize it and provide methods for the payment process. Usage of the following domains depends on client requirements.*
### **Versioning and backward compatibility**
SDK version contains three digits. For example: `1.0.0`.
| Version digit |
Description |
Update requirement |
| First |
Tracks compatibility-breaking changes in SDK public APIs. |
🔴 Mandatory to update the application code to use SDK when this is incremented. |
| Second |
Tracks new, not compatibility-breaking changes in public API of SDK. |
🟡 Optional to update the application code when this digit is incremented. |
| Third |
Tracks internal changes in SDK. |
🟢 No updates in application code are necessary to update to the version, which has this number incremented. |
Changes not breaking compatibility:
* Adding a new optional interface to SDK setup
* Adding a new method to any domain
* Adding a new ENUM value to input or output
* Adding a new field in the input or output model
Technical overview
### **SDK Basic configuration**
The `minSdkVersion` must be at least 23 (Android 6.0). The application must use AndroidX.
SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system. **The username and password are provided by Verestro.**
```gradle
repositories{
maven {
credentials {
username ""
password ""
}
url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
//if the sync time takes too long, add filters to match the repository with specific modules as below
content {
includeGroupByRegex "pl.upaid.*"
includeGroup "com.mastercard"
includeGroup "com.visa" //Only when Visa is used
}
}
}
```
VCP SDK is available in two versions: **debug** and **release**.
Debug version is ended with appendix "-debug" in version name. Samples below:
**For release version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**For debug version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}-debug'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}-debug'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**Min SDK version:**
The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.
```gradle
```
SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it.
### **VCP SDK Application Signing requirements**
Mastercard:
There is no requirement related to Application signing.
Visa:
Both sandbox (test) and production environment require APK signed with valid key. To add Application as Trusted in Visa services please provide Signing Key Certificate from chain in PEM format using below script:
```bash
keytool -exportcert -keystore your_apk_keystore.jks -alias your_keystore_key_alias -rfc -file certificate.pem
```
Output will be provided in certificate.pem file.
Please provide an result to Verestro representative with related applicationId (package).
Note: When using only Google Play signing key tests local tests related to Visa tokenization and payments will be not possible.
### **VCP SDK Size**
The size of SDK is dependent on its distribution system.
The table below shows the size of the module for the ask and bundle file.
| Format |
Size increment |
Notes |
| APK all architectures |
~13,6 MB |
Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
| APK Arm64 |
~2.8 MB |
Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
**VCP size already includes Mobile DC SDK size.**
Additional information:
- size from the table above is referred to release version;
- size depends on configured proguard;
### **VCP SDK Usage**
This chapter describes the structure and basic usage of VCP SDK.
#### **· Domains**
Every of the described facades is divided into domains with different responsibilities. Available domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
* [x] **Every domain contains domain-related methods**
#### **· Error handling**
Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods.
SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message.
Note: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.
| Exception type |
Exception class |
Description |
| SDK validation |
ValidationException |
Additional reason codes for ValidationException used in Mobile DC SDK |
| Backend exception |
BackendException |
Additional reason codes for BackendException used in Mobile DC SDK.
Note: Not applicable for External Wallet Server domain |
| SDK exception |
UcpSdkException |
Something went wrong on the SDK side, check the table below with possible reasons |
| Process related |
- |
As every process is different some methods could throw a specified exception
Types of possible exceptions are described in the method description |
Additional BackendException reason codes:
| Reason |
Description |
| INTERNAL\_ERROR |
Error occurred on server |
| VALIDATION\_ERROR |
Client sent invalid data |
| CRYPTOGRAPHY\_ERROR |
Error occurred during cryptography operation |
| PAYMENT\_CARD\_PREDIGITIZE\_ERROR |
Predigitize of payment card failed |
| PAYMENT\_IBAN\_PREDIGITIZE\_ERROR |
Predigitize of payment IBAN failed |
| PAYMENT\_CARD\_DIGITIZE\_ERROR |
Digitize of payment card failed |
| PAYMENT\_IBAN\_DIGITIZE\_ERROR |
Digitize of payment IBAN failed |
| PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED |
Predigitize for payment card must be executed |
| PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED |
Predigitize for payment IBAN must be executed |
| CLIENT\_UNAUTHORIZED |
Client of the API is unauthorized |
| USER\_UNAUTHORIZED |
User is unauthorized |
| CANT\_FIND\_USER |
Cannot find user |
| CANT\_FIND\_DEVICE |
Cannot find device |
| CANT\_FIND\_IBAN |
Cannot find payment IBAN |
| CANT\_FIND\_CARD |
Cannot find payment card |
| CANT\_FIND\_PAYMENT\_TOKEN |
Cannot find payment token |
| OPERATION\_NOT\_SUPPORTED |
Requested operation is not supported |
| OPERATION\_NOT\_ALLOWED |
Requested operation is not allowed |
| DEVICE\_TEMPORARILY\_LOCKED |
Device is temporarily locked |
| DEVICE\_PERMANENTLY\_LOCKED |
Device is permanently locked |
| INVALID\_PAN |
The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly |
| MISSING\_EXPIRY\_DATE |
The expiry date is required for this product but was missing |
| PAN\_INELIGIBLE |
The PAN is not in an approved account range for TSP |
| DEVICE\_INELIGIBLE |
The device is not supported for use |
| PAN\_INELIGIBLE\_FOR\_DEVICE |
The PAN is not allowed to be provisioned to the device because of Issuer rules |
| IBAN\_INELIGIBLE |
The financial account does not have an associated account range in TSP |
| PARALLEL\_REQUESTS\_ATTEMPTS |
Action is already processing. Please try again after the time included in headers |
| INVALID\_JWS\_TOKEN |
Specified JWS token is invalid |
Additional ValidationException reason codes:
| Reason |
Description |
| INVALID\_SECURITY\_CODE |
Security code is empty |
| INVALID\_LANGUAGE\_CODE |
Language code is empty |
| INVALID\_PAYMENT\_INSTRUMENT\_ID |
Payment instrument id is empty |
UcpSdkException reason codes:
| Reason |
Description |
| PUSH\_INVALID\_SOURCE |
Relates to push processing process. Push message should be consumed in another module |
| PUSH\_INVALID\_PUSH\_CONTENT |
Cannot process push message. The message is invalid or some process failed |
| PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND |
Cannot find default PaymentInstrument |
| PAYMENT\_INSTRUMENT\_NOT\_FOUND |
Selected PaymentInstrument cannot be found, is not digitized or active |
| APPLICATION\_PROCESS\_NOT\_KILLED |
Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process |
#### **· Facade**
The facade is an entry point to communication with VCP SDK.
Contains SDK initialization method and domains which allows for payment instrument management.
#### **· Method structure**
Please read Mobile DC Documentation for details.
#### **· Multiple facade types**
VCP SDK provides three public APIs with the same functionalities, the APIs are:
- UcpJavaApi for projects which use Java programming language.
- UcpKotlinApi for projects which use Kotlin programming language.
The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same.
This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark).
#### **· HceApduService registration**
To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service.
Properly configured meta-data in service will also register an application as tap&pay ready.
Exemplary service below:
```xml
```
Below listing of the default source file hce\_apud\_service.xml:
```xml
```
Check if the application is set as default for payment.
```kotlin
fun isSystemDefault(): Boolean {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
return cardEmulation.isDefaultServiceForCategory(
WalletHceService::class.java,
CardEmulation.CATEGORY_PAYMENT
)
}
```
Request for set your application as default for payment - will show a dialog for the user to approve the changes.
```kotlin
fun requestForSystemDefault() {
val intent = Intent().apply {
action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
putExtra("component", WalletHceService::class.java)
putExtra("category", CardEmulation.CATEGORY_PAYMENT)
}
context.startActivity(intent)
}
```
If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.
```kotlin
fun registerAsOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.setPreferredService(
activity, ComponentName(activity, WalletHceService::class.java)
)
}
fun unregisterFromOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.unsetPreferredService(activity)
}
```
#### **· Models**
##### **PaymentInstrument**
| Parameter |
Type |
Description |
| id |
String |
Id of payment instrument. For card it is cardId, for IBAN sha256Hex.
In the context of the External Wallet Server use tokenUniqueReference from MDES |
| paymentTokenId |
String |
Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id |
| displayablePanDigits |
String |
Token last 4 digits which can be used to display |
| paymentInstrumentStatus |
PaymentInstrumentStatus |
Enum with status of payment instrument. |
| contactlessSupported |
Boolean |
Information if payment instrument supports contactless transactions. |
| dsrpSupported |
Boolean |
Information if the payment instrument supports DSRP transactions. |
| qrcSupported |
Boolean |
Information if the payment instrument supports QR transactions. |
| onDeviceCvmSupported |
Boolean |
Information about supporting CVM on device. |
| credentialsCount |
Int |
Amount of credentials that can be used for payments.
Always 0 for Visa Cards. |
| isDefaultForContactlessPayment |
Boolean |
Information if payment instrument is default for contactless payments. |
| isDefaultForRemotePayment |
Boolean |
Information if payment instrument is default for remote payments. |
| additionalAuthenticationRequired |
Boolean |
Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods |
| tokenLastFourDigits |
String? |
Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentExpirationDate |
String? |
Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentLastFourDigits |
String? |
Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| productConfig |
ProductConfig? |
Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| provisioningStatus |
String |
Current state of provisioning process. One of:
IN\_PROGRESS - in case of waiting for onProvisioningSuccess(),
SUCCESS - when token is provisioned. |
| paymentTokenExpirationDate |
String? |
Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled. |
##### **PaymentInstrumentStatus**
| Field |
Description |
| INACTIVE |
Payment instrument is not active, it can not be used for transactions.
The activation process depends on integration. Read the product overview for more information. |
| ACTIVE |
Payment instrument is active and it can be used for transactions. |
| SUSPENDED |
Payment instrument is suspended. |
| DELETED |
Payment instrument is DELETED. |
| UNKNOWN |
Payment instrument status is unknown. |
##### **AdditionalAuthenticationMethod**
| Parameter |
Type |
Description |
| id |
String |
Identifier of additional authentication method |
| name |
String |
Method name. One of:
OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER |
| value |
String |
Value depends on method name. Described below. |
| issuerParameters |
AuthMethodsIssuerParameters? |
Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION |
##### **Additional authentication method values:**
| Method |
Value |
Description |
OTP_TO_CARDHOLDER_NUMBER |
Masked phone number |
Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number. |
OTP_TO_CARDHOLDER_EMAIL |
Masked email |
Email to Account holder’s email address. The value will be the Account holder’s masked email address. |
CARDHOLDER_TO_CALL_CUSTOMER_SERVICE |
Phone number |
Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service. |
CARDHOLDER_TO_VISIT_WEBSITE |
Website URL |
Account holder to visit a website. The value will be the website URL. |
CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION |
Application name |
(Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS. |
ISSUER_TO_CALL_CARDHOLDER_NUMBER |
Masked phone number |
Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number. |
##### **AuthMethodsIssuerParameters contains the following fields:**
| Parameter |
Type |
Description |
| mdes |
AuthMethodsIssuerParametersMdes? |
Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token |
| vts |
AuthMethodsIssuerParametersVts? |
Required for VTS Payment token |
##### **AuthMethodsIssuerParametersMdes contains following fields:**
| Parameter |
Type |
Description |
| android |
AuthMethodsIssuerParametersMdesAndroid |
Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device |
| ios |
AuthMethodsIssuerParametersMdesIos |
Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device |
##### **AuthMethodsIssuerParametersMdesAndroid contains following fields:**
| Parameter |
Type |
Description |
| action |
String? |
Name of the action to be performed |
| packageName |
String? |
The package name of the issuer's mobile app |
| extraTextValue |
String? |
Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app |
##### **AuthMethodsIssuerParametersMdesIos contains following fields:**
| Parameter |
Type |
Description |
| deepLinkingUrl |
String? |
The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. |
| extraTextValue |
String? |
Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. |
##### **AuthMethodsIssuerParametersVts contains following fields:**
| Parameter |
Type |
Description |
| android |
AuthMethodsIssuerParametersVtsAndroid? |
Plain AuthMethodsIssuerParametersVtsAndroid object.
Required for Android devices |
| ios |
AuthMethodsIssuerParametersVtsIos? |
Plain AuthMethodsIssuerParametersVtsIos object.
Required for IOS devices |
##### **AuthMethodsIssuerParametersVtsAndroid contains following fields:**
| Parameter |
Type |
Description |
| appId |
String? |
Unique identifier for the application within the application store. |
| appUrl |
String? |
URL of the application in the application store. |
| intentUrl |
String? |
URL of banking app designed to respond to authentication code handling. |
| requestPayload |
String? |
The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **AuthMethodsIssuerParametersVtsIos contains following fields:**
| Parameter |
Type |
Description |
| appId |
String? |
Unique identifier for the application within the application store. |
| appUrl |
String? |
URL of the application in the application store. |
| intentUrl |
String? |
URL of banking app designed to respond to authentication code handling. |
| requestPayload |
String? |
The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **ContactlessTransactionInformation**
| Parameter |
Type |
Description |
| currencyCode |
ByteArray |
Code of currency, that was used in transaction. Formatted in ISO 4271. |
| amount |
ByteArray |
Transaction amount in bytes. Can be formatted as Int in pennies. |
| transactionRange |
ContactlessTransactionRange |
Type of transaction range. |
| richTransactionType |
ContactlessRichTransactionType |
Rich transaction type. |
| merchantAndLocation |
ByteArray |
Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset. |
**ContactlessTransactionRange**
| Value |
Description |
| LVT |
Low value transaction |
| HVT |
High value transaction |
| UNKNOWN |
Unknown |
**ContactlessRichTransactionType**
| Value |
| PURCHASE |
| REFUND |
| CASH |
| TRANSIT |
| PURCHASE\_WITH\_CASHBACK |
| UNKNOWN |
##### **DsrpTransactionInfo**
| Parameter |
Type |
Descruption |
| amount |
Long |
Transaction amount |
| currencyCode |
Int |
Code of currency, that was used in transaction. |
| countryCode |
Int |
Code of country. |
| issuerCryptogramType |
String |
Cryptogram type. |
##### **TransactionAbortReason**
| Value |
Description |
| WALLET\_CANCEL\_REQUEST |
Indicates that the wallet has requested a transaction cancellation during payment. |
| CARD\_ERROR |
This indicates that a problem has been detected in the MChipEngine processing.
In some implementations, this can indicate badly formatted card profile data. |
| TERMINAL\_ERROR |
This indicates incorrect terminal behavior. |
| NO\_TRANSACTION\_CREDENTIALS |
There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility. |
| NO\_CARDS |
There is no active PaymentInstrument to start payment. Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). |
| TERMINAL\_INACTIVITY\_TIMEOUT |
There is a problem with communication between the terminal and payment device.
For example, the terminal could abort communication with the mobile device for
a long period of time and then trigger a timeout.
Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal.
The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment.
Note: When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again.
Note: Deprecated in 2.6.7, no longer used due to time difference between connection lost and providing result to application. Replaced by CONNECTION\_LOST which works immediatelly. |
| CONNECTION\_LOST |
Connection between terminal and device is lost and payment is terminated. |
| PAYMENT\_NOT\_ALLOWED |
Payment is not allowed at this moment.
For Mastercard Card application should show error and user should retry payment.
For Visa Card application should wait for UcpVtsPaymentAllowedListener::onPaymentAllowed() |
##### **NewTransaction**
| Field |
Type |
Description |
| clientTransactionId |
String? |
Identifier of transaction in TSP |
| type |
String |
The transaction type. One of: \[UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER\] |
| amountMinor |
Long |
The monetary amount in terms of the minor units of the currency. For example,
EUR 2.35' will return 235, and BHD -1.345' will return -1345 |
| currency |
String |
3-digit ISO 4217 currency code |
| timestamp |
String |
The date/time when the transaction occurred. In ISO 8601 extended format |
| merchantName |
String? |
The merchant (``doing business as'') name |
| merchantPostalCode |
String? |
The postal code of the merchant |
| transactionCountryCode |
String? |
The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1 |
| comboCardAccountType |
String? |
An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: \[UNKNOWN, CREDIT, DEBIT\] |
| issuerResponseInformation |
String? |
Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: \[UNKNOWN, INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION\] |
| status |
String |
The authorization status of the transaction. One of: \[AUTHORIZED, DECLINED, CLEARED, REVERSED\] |
| paymentTokenId |
String |
Identifier of payment token in VCP |
##### **ContactlessTransactionData**
| Parameter |
Type |
Description |
| currencyNumber |
Int |
Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. |
| currencyCode |
String? |
Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN
Could be null as the terminal provides only the currencyNumber and a valid code could be not found. |
| amountMinor |
Long |
The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, |
| transactionRange |
ContactlessTransactionRange |
Type of transaction range. |
| richTransactionType |
ContactlessRichTransactionType |
Rich transaction type. |
| merchantAndLocation |
String |
Merchant and location data from terminal.
Deprecated - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data. |
**ContactlessTransactionRange**
| Value |
Description |
| LVT |
Low value transaction |
| HVT |
High value transaction |
| UNKNOWN |
Unknown |
**ContactlessRichTransactionType**
| Value |
Description |
| PURCHASE |
|
| REFUND |
|
| CASH |
|
| TRANSIT |
|
| PURCHASE\_WITH\_CASHBACK |
|
| UNKNOWN |
|
| WITHDRAWAL |
|
| ATM\_CONTACTLESS |
|
##### **Report**
| Parameter |
Type |
Description |
| name |
String |
Action name |
| description |
String |
Action details message. |
| isSuccess |
Boolean |
Result of action. True when action is finished successfully, false otherwise. |
| timestamp |
Long |
Time when the action occurred. |
| errorMessage |
String? |
Detailed error message when isSuccess is false. |
##### **ContactlessAdvice**
| Parameter |
Description |
| DECLINE |
Declines a processing transaction.
When provided by SDK in getFinalDecisionForTransaction wallet should not overrule a DECLINE.
If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response. |
| AUTHENTICATION\_REQUIRED |
An user authentication is required for transaction processing, which could be overruled on the MPA side.
When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the onAuthRequiredForContactless method. |
| PROCEED |
Transaction can be processed. |
##### **ContactlessTransactionResult**
Important! MPA should always refer to transaction results on the terminal.
| Value |
Description |
Is success on MPA side |
| AUTHORIZE\_ONLINE |
This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization.
The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal.
Should be treated as transaction success on the MPA side. |
Yes |
| AUTHENTICATE\_OFFLINE |
This indicates that the POS requested a decline (AAC) with a CDA signature.
SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature.
Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization.
Should be treated as transaction success on the MPA side. |
Yes |
| DECLINE\_BY\_TERMINAL |
The POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request.
Paying on the terminal with offline-only network connectivity can also return this callback.
Application Cryptogram was generated with genuine credentials.
Should be treated as transaction success on the MPA side. |
Yes |
| DECLINE\_BY\_CARD |
The digitized card has declined the transaction. A non-exhaustive list of possible reasons may be:
- Context mismatch between first and second tap
- Terminal is offline-only
- Terminal is a transit gate, and transit transactions are not allowed by the card profile
- Transaction is international, while the card profile is domestic-only |
No |
| WALLET\_ACTION\_REQUIRED |
If the getFinalDecisionForTransaction returns an AUTHENTICATION\_REQUIRED status then this result will be returned.
The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap.
If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place. |
No |
#### **· External libraries**
The SDK uses several external Apache 2.0 libraries:
- com.nimbusds:nimbus-jose-jwt
- commons-codec:commons-codec
- com.fasterxml.jackson.core:jackson-core
- com.fasterxml.jackson.core:jackson-annotations
- com.fasterxml.jackson.core:jackson-databind
- com.fasterxml.jackson.module:jackson-module-kotlin
- io.insert-koin:koin-android
- io.reactivex.rxjava2:rxjava
- io.reactivex.rxjava2:rxandroid
- com.squareup.retrofit2:adapter-rxjava2
- com.squareup.retrofit2:retrofit
- com.squareup.retrofit2:converter
- com.squareup.okhttp3:logging
- com.squareup.okhttp3:okhttp
VCP SDK Setup
VCP SDK has to be configured every time when is used. Before VCP SDK usage Mobile DC SDK should be already configured.
### **setup**
Note: Contains all the necessary data to configure SDK.
Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method.
Requires MobileDC setup() already finished
Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished.
When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand.
Important! Before calling VCP SDK setup you must call setup from Mobile DC SDK.
Note: Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment and loading first aplication screen.
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| ucpConfiguration |
UcpConfiguration |
VCP configuration provided in builder described below. |
Not empty. |
**UcpConfigurationBuilder** contains the following methods:
| Metod |
Parameter |
Description |
Validation conditions |
| withApplication |
Application |
Application context. |
Not empty |
| withCvmModel |
WalletCvmModel (enum) |
Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE |
Not empty |
| withUserAuthMode |
WalletAuthMode (enum) |
User authentication mode: WALLET\_PIN, CUSTOM, NONE
Contact Verestro to select proper configuration |
Not empty |
withUcpPaymentInstrument
EventListener |
UcpPaymentInstrument
EventListener |
Global listener for actions on PaymentInstrument. |
Not empty |
withUcpTransaction
EventListener |
UcpTransactionEventListener |
Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing |
Not empty |
withTransactionAcceptance
EventListener |
UcpTransactionAcceptance
EventListener |
Global listener which allow application take final decision about transaction acceptance during transaction |
Not empty |
| withReplenishThreshold |
Int |
Number of credentials below which replenish process will automatically begin |
Not empty |
| withMcbpPinningCertificates |
List |
List of public key certificates in PEM format.
Pass list with empty String if withOptionalUcpMcbpHttpExecutor mentioned below is used with custom HTTP communication. |
Not empty List |
| withOptionalEventsReports |
UcpEventReportListener |
Global listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. |
Optional |
withOptional
ExternalWalletServer |
|
Prepares SDK for using external wallet server. |
Optional |
withOptional
UcpMcbpHttpExecutor |
UcpMcbpHttpExecutor/
DefaultUcpMcbpHttpExecutor |
Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. |
Optional |
withOptional
UcpReProvisionEventListener |
UcpReProvisionEventListener |
Global listener for actions during reprovisioning. |
Optional |
withOptional
UcpTransactionConfiguration |
UcpTransactionConfiguration |
Transaction configuration. Allow to enable deprecated authentication timer called when authentication is peformed.
Timer is disabled by default, usage is not recomended. |
Optional |
withOptionalWallet
McbpHttpExecutor |
|
Prepares SDK for processing CMS-D HTTP requests with Wallet Server proxy. |
Optional |
| withOptionalEnableVisaSDK |
|
Enables Visa SDK usage, requires gradle dependencies configuration |
Optional |
withOptionalVtsPayment
ReadyCallback |
UcpVtsPaymentAllowedListener |
Provides information if payment with Visa Token is allowed with callback onPaymentAllowed().
Application should wait for callback when Visa Card is used. |
Optional |
**UcpPaymentInstrumentEventListener**
Contains callbacks for PaymentInstrument.
| Method name |
Parameters |
Description |
onProvisioning
Success |
paymentInstrument: PaymentInstrument |
Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below |
onProvisioning
Failure |
errorMessage: String?,
exception: Exception? |
Method called after provisioning failure. Try processing digitization again |
onReplenish
Success |
paymentInstrument: PaymentInstrument
numberOfTransactionCredentials: Int |
Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials.
Depending on flow is called after activation process and when requested by SDK based on replenishThreshold configuration.
Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
onReplenish
Failure |
paymentInstrument: PaymentInstrument,
errorMessage: String?,
exception: Exception? |
Method called after replenish failure with PaymentInstrument
Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
onPayment
Instrument
StatusChanged |
newStatus: PaymentInstrument
Status
paymentInstrumentId: String |
Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id |
| onNewTransaction |
newTransaction: NewTransaction |
Provides online result with details of transaction processed in VCP
Works only when application is online |
**UcpTransactionEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| Method name |
Parameters |
Description |
onAuthRequired
ForContactless |
paymentInstrument: PaymentInstrument, transactionInformation:
ContactlessTransactionInformation
transactionData: ContactlessTransactionData |
Called when user authentication is required during contactless transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
onAuthRequired
ForDsrp |
paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo |
Called when user authentication is required during Dsrp transaction |
onAuthTimer
Updated |
secondsRemaining: Int |
Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration.
Note: Deprecated and disabled by default in version 2.6.7.
To enable use configuration avaialble in SDK setup::withOptionalUcpTransactionConfiguration. |
onContactless
PaymentStarted |
\- |
Called on very beginnging of every transaction start (SELECT\_PPSE APDU command). E.g. first tap to terminal or second tap if onAuthRequiredForContactless method was called.
Locks communication until method is finished.
Method duration directly impacts on transaction time. |
onContactless
Payment
Completed |
paymentInstrument: PaymentInstrument
transactionInformation:
ContactlessTransactionInformation
transactionResult: ContactlessTransactionResult
transactionData : ContactlessTransactionData,
transactionId:String |
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
transactionId - transaction identifier for Mastercard transactions, allow to match transaction with processed transaction notification from Mobile DC SDK: EventNewTransaction::clientTransactionId. |
onContactless
Payment
Incident |
paymentInstrument: PaymentInstrument,
exception: Exception |
Called when something went wrong during transaction and Mastercard marked transaction as incident |
onContactless
Payment
Aborted |
paymentInstrument: PaymentInstrument?,
abortReason: TransactionAbortReason,
exception: Exception |
Called when transaction is aborted during payment from some reason described in method parameter
PaymentInstrument could be null if abortReason = TransactionAbortReason.NO\_CARDS is returned.
Note: SDK clears passed selected card with method selectForPayment() and authentication with setUserAuthenticatedForPayment() |
onTransaction
Stopped |
|
Method called on transaction stopped by SDK.
Deprecated in version 2.6.7, no longer used. |
**UcpTransactionAcceptanceEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| Method name |
Parameters |
Description |
getFinal
Decision
ForTransaction |
isUserAuthenticated : Boolean
recommendedAdvice : ContactlessAdvice
trasactionInformation :
ContactlessTransactionInformation
transactionData : ContactlessTransactionData |
Called on every transaction for the final decision about transaction processing
An application can decide based on information about authentication, transaction details like amount, currency, and transaction types
The method also provide recommended by MCBP advice based on transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
**UcpEventReportsListener**
| Method name |
Parameters |
Description |
| onNewReport |
report: Report |
Return logs related to token management. |
**UcpReProvisionEventListener**
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
| Method Name |
Parameters |
Description |
| onReProvisionSuccess |
paymentInstrument: PaymentInstrument |
Method called after reProvisioning process.
Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback. |
| onReProvisionFailure |
paymentInstrument : PaymentInstrument
errorMessage : String?
exception : Exception? |
Method called after reProvisioning failure. Try again. |
**UcpMcbpHttpExecutor**
| Method name |
Parameters |
Description |
| execute |
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod:
UcpMcbpHttpMethod,
url: String,
requestData:Any,
requestProperties:
Map |
Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
|
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
**DefaultUcpMcbpHttpExecutor**
| Method name |
Parameters |
Description |
| execute |
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType
ucpMcbpHttpMethod: UcpMcbpHttpMethod
url: String
requestData: Any
requestProperties: Map |
Called on every time if SDK want to connect to MasterCard and should return super.execute method.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
|
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
**UcpTransactionConfiguration**
| Parameter |
Type |
Description |
enableTransaction
AuthenticationTimer |
Boolean |
Allows to enable deprecated authentication timer.
Timer is started along setUserAuthenticatedForPayment(), result is available in onAuthTimerUpdated(). |
**Callback samples:**
**UcpTransactionEventListener**
```
// UcpTransactionEventListener comments
class BankingAppUcpTransactionEventListener : UcpTransactionEventListener {
override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and ContactlessTransactionData available in event object
showPaymentScreen(event.paymentInstrument, event.transactionData)
}
override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and DSRP transaction information available in event object
showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo)
}
override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) {
//check if user is on payment screen and update timer
//when timer is 0, application should close payment with failure
//deprcated, disabled by default, read method description how to enable
}
override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) {
//looks like payment is aborted, can provide result to payment screen
//and show user what is abort reason
}
override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) {
//payment completed, provide result to payment information
//REMEMBER Transaction is processed on terminal and this is where
//you will see final transaction result
}
override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) {
//something went wrong during transaction, provide result to user
}
override fun onTransactionStopped() {
//deprecated, not used anymore,
}
override fun onContactlessPaymentStarted() {
//Payment started or resumed after callback onAuthReqiredForContactless
//Best place for checking if user is authenticated for payment and call
//setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected
}
}
```
**UcpPaymentInstrumentEventListener**
```
class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener {
override fun onNewTransaction(event: EventNewTransaction) {
//information about new transaction processed by issuer
}
override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
//status of payment instrument was changed, refresh list, inform user about new status
}
override fun onProvisioningFailure(event: EventProvisioningFailure) {
//provisioning failed, try again
}
override fun onProvisioningSuccess(event: EventProvisioningSuccess) {
//provisioning success, wait for status and replenish changes until user can pay
//or provide activation method when required
}
override fun onReplenishFailure(event: EventReplenishFailure) {
//transaction credentials replenish failed
}
override fun onReplenishSuccess(event: EventReplenishSuccess) {
//transaction credentials replenish success
}
}
```
**UcpTransactionAcceptanceEventListener**
```
class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener {
//Sample implementation of transaction acceptance listener
//For the scanario when authentication is required on issuer side for every transaction
//field even.isUserAuthenticated must be always true, otherwise
//ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned
override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice {
val isScreenUnlocked = isScreenUnlocked()
val isScreenProtectedByKeyguard = isScreenUnlocked()
val isLvtTransaction =
event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT
//discard all Transit transaction
if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) {
return ContactlessAdvice.DECLINE
}
//allow for transaction when user is authenticated for payment and screen unlocked
if (event.isUserAuthenticated && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
//allow for LVT transaction on unlocked screen when protected and don't require authentication
if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
// ...
// much more cases
//require authentication anyway
return ContactlessAdvice.AUTHENTICATION_REQUIRED
}
}
```
**UcpEventReportsListener**
```
class BankReportEventListener : UcpEventReportsListener {
override fun onNewReport(report: Report) {
//may be used for debugging SDK or gathering reports on client's app or backend
}
}
```
**UcpMcbpHttpExecutor**
```
//Use UcpMcbpHTtpExecutor as supertype if you want to replace connection
class BankUcpMcbpHttpExecutor : UcpMcbpHttpExecutor {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
//invoke connect by custom connector
return when (ucpMcbpRequestType) {
UcpMcbpHttpExecutorRequestType.REQUEST_SESSION -> {
executeRequestSession(ucpMcbpHttpMethod, url, requestData as UcpMcbpRequestSessionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.PROVISION -> {
executeProvision(ucpMcbpHttpMethod, url, requestData as UcpMcbpProvisionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.REPLENISH -> {
executeReplenish(ucpMcbpHttpMethod, url, requestData as UcpMcbpReplenishRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.NOTIFY_PROVISIONING_RESULT -> {
executeNotifyProvisioningResult(ucpMcbpHttpMethod, url,
requestData as UcpMcbpNotifyProvisioningResultRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.CHANGE_MOBILE_PIN -> {
executeChangeMobilePin(ucpMcbpHttpMethod, url,
requestData as UcpMcbpChangeMobilePinRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.DELETE -> {
executeDelete(ucpMcbpHttpMethod, url, requestData as UcpMcbpDeleteRequestData,
requestProperties)
}
}
}
}
```
**DefaultUcpMcbpHttpExecutor**
```
//Use DefaultUcpMcbpHTtpExecutor as supertype if you want to only add some action before connection
class BankDefaultUcpMcbpHttpExecutor : DefaultUcpMcbpHttpExecutor() {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
return super.execute(
ucpMcbpRequestType,
ucpMcbpHttpMethod,
url,
requestData,
requestProperties
)
}
}
```
**UcpReProvisionEventListener**
```
class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() {
override fun onReProvisionSuccess(event: EventReProvisionSuccess) {
//reProvisioning success, wait for status and replenish changes until user can pay
}
override fun onReProvisionFailure(event: EventReProvisionFailure) {
//reProvisioning failed, try again.
}
}
```
**UcpTransactionConfiguration**
```
class BankingAppUcpTransactionConfiguration : UcpTransactionConfiguration {
override val enableTransactionAuthenticationTimer: Boolean = false
}
```
**UcpVtsPaymentAllowedListener**
```
class BankingAppUcpVtsPaymentAllowedListener : UcpVtsPaymentAllowedListener {
override fun onPaymentAllowed() {
//when during a payment an status of PAYMENT_NOT_ALLOWED is received
//Application UI should show transaction error and wait for onPaymentAllowed() callback
//When received callback shouuld inform UI to process transaction again
}}
```
**Sample VCP SDK setup implementation**
Mobile DC setup() and VCP setup() method could be called on MainThread in Application:onCreate as blocking or another thread.
When applicaiton has multiple dependencies there is possible to call both setup() methods on another thread (MobileDC setup() method must be already finished until VCP setup() is called).
Important: In case of loading SDK on another thread and using contactless payments HostApduService must be used asynchronous way to prevet using SDK until loading is finished - check sample for method *PaymentService:processHceApduCommand*.
```kotlin
fun setup(
application: Application,
walletCvmModel: WalletCvmModel,
walletAuthUserMode: WalletAuthUserMode,
mcbpPinningCertificates: List,
replenishThreshold: Int
) {
val ucpConfiguration = UcpConfiguration.create(
UcpConfigurationBuilder()
.withApplication(application)
.withCvmModel(walletCvmModel)
.withUserAuthMode(walletAuthUserMode)
//marked as deprecated - see description above
.withUcpTransactionEventListener(BankingAppUcpTransactionEventListener())
.withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener())
.withMcbpPinningCertificates(mcbpPinningCertificates)
.withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener())
.withReplenishThreshold(replenishThreshold)
.withOptionalEventsReports(BankReportEventListener())
.withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor())
//if you want to only add additional action before connection use below implementation
//.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor())
.withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener())
//if you want to change standard transaction configuration use configuration below
.withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration())
//.withOptionalEnableVisaSDK() //optional when Visa is used
//.withOptionalVtsPaymentReadyCallback(BankingAppUcpVtsPaymentAllowedListener()) //optional when Visa is used
)
UcpApiKotlin().setup(ucpConfiguration)
}
```
### **reset (DEPRECATED - use restart instead)**
Synchronous. Offline.
Method for resetting SDK to uninitialized state.
|
Note: According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. Please kill application process after using this method. Trying using any facade method without stopping application process will cause throwing UcpSdkException.
To avoid closing application use restart() methods.
**Input**
No input.
**Output**
No output.
**Sample**
**Sample VCP SDK reset implementation:**
```kotlin
fun reset() {
UcpApiKotlin().reset()
//Terminating JVM according to MC SDK Sample Application
Runtime.getRuntime().exit(0);
}
```
### **restart**
Synchronous. Offline.
Method for resetting SDK to uninitialized state.
Replaces reset() method which requires killing application process.
When restart finishes with error, application should repeat action. |
Note: SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again.
**Input**
No input.
**Output**
Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods.
Failure callback when something went wrong during restart. Application should repeat action.
**Sample**
**Sample VCP SDK reset implementation:**
```
UcpApiKotlin().restart({
//restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods
}, {
//some error occured, please repeat action
})
```
Cards domain
### **delete**
Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
|
Result of action will be notified with onPaymentInstrumentStatusChanged.
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of PaymentInstrument to delete |
Not empty. |
| reason |
CharArray? |
Optional reason of deletion |
|
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.cardsService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
### **checkEligibility**
Asynchronous. Online.
Check eligibility required to process digitize. |
**Input**
| Parameter |
Type |
Description |
| checkEligibility |
CheckEligibility |
CheckEligibility object |
CheckEligibility
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| paymentInstrumentType |
PaymentInstrumentType |
Payment instrument type. One of: \[MASTERCARD,VISA\] |
| userLanguage |
String |
User language |
| userCountry |
String |
User country |
**Output**
| Success callback with CheckEligibilityResult. |
CheckEligibilityResult
| Parameter |
Type |
Description |
| termsAndConditionsAssetId |
String |
Identifier of Terms and Conditions asset |
**Sample**
```
private fun checkEligibility(
paymentInstrumentId: String,
paymentInstrumentType: PaymentInstrumentType,
userLanguage: String,
userCountry: String
) {
ucpApi.cardsService
.checkEligibility(
CheckEligibility(
paymentInstrumentId,
paymentInstrumentType,
userLanguage,
userCountry
),
{ checkEligibilityResult ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
Asynchronous. Online.
Use only when checkEligibility method is used.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| digitizationRequest |
DigitizationRequest |
Plain object of DigitizationRequest |
Not empty |
DigitizationRequest object contains following fields:
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| paymentInstrumentType |
PaymentInstrumentType |
Payment instrument type. One of: \[MASTERCARD,VISA\] |
Not empty |
| securityCode |
CharArray? |
Optional. The CVC2 for the card to be digitized |
|
| externalPaymentTokenId |
String? |
Optional. Unique external identifier of Payment Token |
|
**Output**
Success callback with DigitizationResult object
| Parameter |
Type |
Description |
| digitizationResult |
DigitizationResult |
Plain object of DigitizationResult |
DigitizationResult contains following fields.
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Plain object of PaymentInstrument |
| additionalAuthenticationMethods |
List? |
All available additional authentication method |
| productConfig |
ProductConfig |
Plain object of ProductConfig, contains Payment Token configuration |
| externalPaymentTokenId |
String? |
Optional. External payment token id configured by the consumer. In case of identifier duplicate an random id is generated |
ProductConfig contains following fields.
| Parameter |
Type |
Description |
| isCoBranded |
Boolean |
Whether the product is co-branded |
| coBrandName |
String? |
Name of the co-branded partner |
| foregroundColor |
String |
Foreground color, used to overlay text on top of the card image |
| backgroundColor |
String |
Background color, used to overlay text on top of the card image |
| labelColor |
String? |
Label color of the mobile wallet entry for the card |
| issuerName |
String |
Name of the issuing bank |
| shortDescription |
String |
A short description for this product |
| longDescription |
String? |
A long description for this product |
| custoremServiceUrl |
String? |
Customer service website of the issuing bank |
| customerServiceEmail |
String? |
Customer service email address of issuing bank |
| customerServicePhoneNumber |
String? |
Customer service phone number of the issuing bank |
| productConfigIssuer |
ProductConfigIssuer? |
Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app |
| onlineBankingLoginUrl |
String? |
Login URL for the issuing bank's online banking website |
| termsAndConditionsUrl |
String? |
URL linking to the issuing bank's terms and conditions for this product |
| privacyPolicyUrl |
String? |
URL linking to the issuing bank's privacy policy for this product |
| issuerProductConfigCode |
String? |
Freeform identifier for this product configuration as assigned by the issuer |
| contactName |
String? |
Name of the issuing bank |
| bankAppName |
String? |
Name of banking application for display |
| bankAppAddress |
String? |
The package name for the destination mobile application |
| unsupportedPresentationTypes |
String? |
The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request |
| unsupportedCardVerificationTypes |
String? |
The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) |
| issuerFlags |
List? |
List of plain ProductConfigIssuerFlags object. Contains issuer flags |
| brandLogoAssetId |
String |
The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID |
| issuerLogoAssetId |
String |
The logo of the issuing bank. Provided as a Asset ID |
| coBrandLogoAssetId |
String? |
The co-brand logo (if any) for this product. Provided as an Asset ID |
| cardBackgroundCombinedAssetId |
String? |
The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID |
| cardBackgroundAssetId |
String? |
The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID |
| iconAssetId |
String |
The icon representing the primary brand(s) associated with this product. Provided as an Asset ID |
ProductConfigIssuer contains following fields.
| Parameter |
Type |
Description |
| openIssuerAndroidIntent |
ProductConfigOpenIssuerAndroidIntent? |
AndroidIntent object can be used to open the issuer mobile app |
| activateWithIssuerAndroidIntent |
ProductConfigActivateWithIssuerAndroidIntent? |
AndroidIntent object can be used to open the issuer mobile app |
| openIssuerIOSDeepLinkingUrl |
ProductConfigOpenIssuerIOSDeepLinkingUrl? |
IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| activateWithIssuerIOSDeepLinkingUrl |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl? |
IOSDeepLinkingUrl object can be used to open the issuer mobile app |
ProductConfigOpenIssuerAndroidIntent contains following fields.
| Parameter |
Type |
Description |
| action |
String |
The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName |
String |
The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerAndroidIntent contains following fields.
| Parameter |
Type |
Description |
| action |
String |
The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName |
String |
The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.
| Parameter |
Type |
Description |
| deepLinkinUrl |
String |
The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.
| Parameter |
Type |
Description |
| deepLinkingUrl |
String |
The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigIssuerFlags contains following fields.
| Parameter |
Type |
Description |
| deviceBinding |
Boolean |
Device binding |
| cardholderVerification |
Boolean |
Whether the issuer participating in step-up flow |
| trustedBeneficiaryEnrollment |
Boolean |
Whether this is a trusted beneficiary enrollment |
| delegateAuthenticationSupported |
String |
Whether issuer supports delegated authentication |
Sample
```kotlin
fun digitizeCard(digitizationRequest: DigitizationRequest) {
ucpApi.cardsService
.digitize( digitizationRequest,
{ digitizationResult ->
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize (deprecated)**
Deprecated - use digitize(DigitizationGreenPath) instead.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty. |
| userLanguage |
String |
Language preference selected by the consumer. Formatted as an
ISO-639-1 two letter language code |
Not empty. |
| securityCode |
CharArray? |
Optional. The CVC2 for the card to be digitized |
|
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun digitizeCard(
paymentInstrumentId: String,
languageCode: String,
securityCode: CharArray) {
ucpApi.cardsService
.digitize(paymentInstrumentId, languageCode, securityCode,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
Asynchronous. Online.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| digitizationGreenPath |
DigitizationGreenPath |
Plain object of DigitizationGreenPath |
Not empty |
DigitizationGreenPath contains following fields.
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| paymentInstrumentType |
PaymentInstrumentType |
Payment instrument type. One of: \[MASTERCARD,VISA\] |
| securityCode |
CharArray? |
Optional. The CVC2 for the card to be digitized |
| userLanguage |
String |
User language |
| userCountry |
String |
User country |
| externalPaymentTokenId |
String? |
Optional. Unique external identifier of Payment Token |
**Output**
| Success / failure callback |
**Sample**
```
fun digitizeCard(digitizationGreenPath: DigitizationGreenPath) {
ucpApi.cardsService
.digitize(digitizationGreenPath,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAdditionalAuthenticationMethods**
Asynchronous. Online.
Retrieves additional user authentication methods. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| getAdditionalAuthenticationMethods |
GetAdditionalAuthenticationMethods |
Plain object of GetAdditionalAuthenticationMethods |
Not empty |
Fields of GetAdditionalAuthenticationMethods object:
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
**Output**
| Success callback with AdditionalAuthenticationMethods object. |
| Parameter |
Type |
Description |
| additionalAuthenticationMethods |
AdditionalAuthenticationMethods |
Object carrying list of AdditionalAuthenticationMethod |
AdditionalAuthenticationMethods contains following value:
| Parameter |
Type |
Description |
| additionalAuthenticationMethods |
List |
List of AdditionalAuthenticationMethod objects |
**Sample**
```
private fun getAdditionalAuthenticationMethods() {
val getAdditionalAuthenticationMethod =
GetAdditionalAuthenticationMethods("paymentInstrumentId")
ucpApi
.cardsService
.getAdditionalAuthenticationMethods(
getAdditionalAuthenticationMethod,
{ additionalAuthenticationMethods ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **submitTokenAuthenticationValue**
Asynchronous. Online.
Submit authentication code when additional user authentication is required. |
**Input**
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| authenticationCode |
String |
Authentication code |
**Output**
| Success callback/failure callback. |
**Sample**
```
private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) {
ucpApi.cardsService
.submitAuthenticationValue(
SubmitAuthenticationValue(
paymentInstrumentId,
authenticationCode
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **submitTokenAuthenticationMethod**
Asynchronous. Online.
Submit authentication method when additional user authentication is required. |
**Input**
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| authenticationMethodId |
String |
Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. |
**Output**
| Success callback/failure callback. |
**Sample**
```
private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) {
ucpApi.cardsService
.submitAuthenticationMethod(
SubmitAuthenticationMethod(
paymentInstrumentId,
authenticationMethodId
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to increase UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| refresh |
Boolean |
Refresh all PaymentInstrument objects state with remote VCP server (network and user session required) |
|
**Output**
| Success callback with list of PaymentInstrument objects. |
| Parameter |
Type |
Description |
| paymentInstruments |
List |
List of retrieved payment instruments from local or remote storage |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.cardsService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument (deprecated)**
Asynchronous. Online/Offline.
Deprecated - use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of instrument to retrieve |
Not empty |
| refresh |
Boolean |
Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
| Success callback with PaymentInstument object. |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Retrieved payment instrument |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.cardsService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
IBANs domain
### **digitize**
Asynchronous. Online.
Registers user and device if already not registered in VCP backend. Creates payment token in VCP backend.
Expect push after successfull finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| signedAccountInfo |
String |
Signed AccountInfo per RFC 7519
Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation |
Not empty. |
| fcmRegistrationToken |
CharArray |
FCM Cloud messaging registration token |
Not empty. |
| languageCode |
String |
Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code |
Not empty. |
**AccountInfo:**
| Parameter |
Type |
Description |
Validation conditions |
| userId |
String |
External user id |
Not empty. |
| iban |
String |
Bank Account Number |
Not empty. |
| countryCode |
String |
The country of the financial account
Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 |
Not empty. |
**Output**
Success callback. Called when device token digitization finished with success .Result contains IbanDigitizationResult object.
Note: Cloud token digitization fail doesn't affect on success/failure callback. |
IbanDigitizationResult contains following fields:
| Parameter |
Type |
Description |
| (DEPRECATED) cloudDigitizationSuccess |
Boolean |
Cloud Token Digitization Details |
| result |
CloudDigitizationResult |
Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN |
| Failure callback. Called when device token digitization finished with failure. |
**Sample**
Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAccountInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("userId", "externalUserId")
.claim("iban", "IN15HIND23467433866365")
.claim("countryCode", "IND")
.build()
val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey)
// ...
}
```
```kotlin
fun digitizeIban(
signedAccountInfo: String,
fcmRegistrationToken: CharArray,
languageCode: String) {
ucpApi.ibansService
.digitize(signedAccountInfo, fcmRegistrationToken, languageCode,
{ ibanDigitizationResult ->
//Device token digitization finished with success
//wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success
val cloudDigitizationResult = ibanDigitizationResult.result
//check status of Cloud Token
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **createTVC**
Asynchronous. Online.
Provides Transaction Verification Code required to process cloud payments. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| signedIbanInfo |
String |
Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation |
Not empty. |
IbanInfo
| Parameter |
Type |
Description |
Validation conditions |
| ibanId |
String |
Iban id returned in addUserWithIban methdod or sha256Hex(iban) |
Not empty. |
**Output**
| Success callback with Tvc object or encrypted Tvc object as String. |
| Parameter |
Type |
Description |
| plainTvc |
PlainTvc? |
Plain PlainTvc object |
| encryptedTvc |
CharArray? |
Encrypted PlainTvc object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation |
PlainTvc object contains following fields.
| Parameter |
Type |
Description |
| accountNumber |
CharArray |
Primary Account Number for the transaction – this is the Token PAN |
| dynamicExpiryDate |
CharArray |
Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC |
CharArray |
Dynamic CVC |
| Failure callback when TVC cannot be created. |
**Sample**
Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createTvc(signedIbanInfo: String) {
ucpApi.ibansService
.createTVC(signedIbanInfo, { tvc ->
//result object could contains encrypted TVC
val encryptedTvc: String? = tvc.encryptedTvc
//or decrypted(plain) TVC object with parameters described in documentation
val plainTvc = tvc.plainTvc
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **createPaymentData**
Asynchronous. Online.
This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| signedIbanInfo |
String |
Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation |
Not empty. |
IbanInfo
| Parameter |
Type |
Description |
Validation conditions |
| ibanId |
String |
Iban id returned in addUserWithIban methdod or sha256Hex(iban) |
Not empty. |
| userId |
String |
External user id given by the client |
Not empty. |
**Output**
| Success callback with PaymentData object or encrypted payment data object as String. |
| Parameter |
Type |
Description |
| plainPaymentData |
PlainPaymentData? |
Plain PlainPaymentData object |
| encryptedPaymentData |
String? |
Encrypted PlainPaymentData object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation |
PlainPaymentData object contains following fields.
| Parameter |
Type |
Description |
| accountNumber |
String |
Primary Account Number for the transaction – this is the Token PAN |
| applicationExpiryDate |
String? |
Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format |
| panSequenceNumber |
String? |
Rrquired only for UCAF. Application PAN sequence number for the Token |
| track2Equivalent |
String? |
Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed |
| ucafCryptogram |
String? |
Required only for UCAF. UCAF cryptogram |
| dynamicExpiryDate |
String? |
Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC |
String? |
Dynamic CVC |
| Failure callback when PaymentData cannot be created. |
**Sample**
Sample generation of *signedIbanInfo* (see [Data signing and encryption](https://wiki.verestro.com/display/UCP/Data+signing+and+encryption) chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.claim("userId", "123")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createPaymentData(signedIbanInfo: String) {
ucpApi.ibansService
.createPaymentData(signedIbanInfo, { paymentData ->
//result object could contains encrypted PaymentData
val encryptedPaymentData: String? = paymentData.encryptedPaymentData
//or decrypted(plain) PaymentData object with parameters described in documentation
val plainPaymentData = paymentData.plainPaymentData
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getAllPaymentInstruments**
Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| refresh |
Boolean |
Refresh all PaymentInstrument objects state with remote VCP server (network required) |
|
**Output**
| Success callback with list of PaymentInstrument objects |
| Parameter |
Type |
Description |
| paymentInstruments |
List |
List of retrieved payment instruments |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.ibansService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument(deprecated)**
Asynchronous. Online/Offline.
Use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of instrument to retrieve. |
Not empty |
| refresh |
Boolean |
Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
| Success callback with PaymentInstument object |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Retrieved payment instrument |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.ibansService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **delete**
Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with onPaymentInstrumentStatusChanged. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of PaymentInstrument to delete |
Not empty. |
| reason |
CharArray? |
Optional reason of deletion |
|
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.ibansService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
Payment domain
### **setDefaultForContactless**
Asynchronous. Offline.
Sets payment instrument as default for contactless payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically after linking with PoS terminal.
Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun setDefaultForContactless(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) {
//make sure selected PaymentInstrument can be seta as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForContactless(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForContactless**
Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
**Input**
**Output**
| Success callback with id new default PaymentInstrument |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Default Payment instrument |
**Sample**
```kotlin
fun getDefaultForContactless() {
ucpApi.paymentService
.getDefaultForContactless({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **setDefaultForRemote (deprecated)**
Asynchronous. Offline.
Sets payment instrument as default for DSRP payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically to remote payments. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun setDefaultForRemote(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
&& !paymentInstrument.dsrpSupported) {
//make sure selected PaymentInstrument can be set as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForRemote(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForRemote (deprecated)**
Asynchronous. Offline.
Provides default PaymentInstrument for remote payments.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
**Input**
**Output**
| Success callback with id new default PaymentInstrument |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Default Payment instrument |
**Sample**
```kotlin
fun getDefaultForRemote() {
ucpApi.paymentService
.getDefaultForRemote({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **selectForPayment**
Asynchronous. Offline.
Sets payment instrument as primary for next incoming payment. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentd |
String |
Payment instrument identity |
Not empty |
**Output**
| Success / failure callback |
**Sample**
| Note: This is only sample payment scenation |
```
//sample scenario of starting payment with authentication before payment
fun startPayment(paymentInstrument: PaymentInstrument) {
//checking conditions before payment
val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
val isContactlessSupported = paymentInstrument.contactlessSupported
val hasTransactionCredentials = paymentInstrument.credentialsCount > 0
if (!isActive || !isContactlessSupported || !hasTransactionCredentials) {
//PaymentInstrument doesn't meet requirements for payment
return
}
//selecting PaymentInstrument to payment
ucpApi.paymentService
.selectForPayment(paymentInstrument.id, {
//selection success
//request user authentication when
//... authentication presented
//use setUserAuthenticatedForPayment method
}, { throwable ->
//something went wrong, check exception with documentation
})
}
```
### **setUserAuthenticatedForPayment**
Asynchronous. Offline.
Sets user as authenticated to payment with provided payment instrument.
Authentication clearing depends on authentication timer configuration in UcpTransactionConfiguration:enableTransactionAuthenticationTimer.
By default timer is disabled and authentication is cancelled when user perform transaction and SDK send callback onContactlessPaymentCompleted/Aborted/Incident from UcpTransactionEventListener.
When timer is enabled authentication is cleared when auth timer finishes - it could casue problems when user start to pay just before timer finish. Authentication could be cleared by SDK during payement.
If application call setUserAuthenticatedForPayment without contactless payment context and authentication timer is disabled, authentication is never cleared by SDK. To clear authentication use abortUserAuthenticationForPayment.
UcpTransactionEventListener:onContactlessPaymentStarted is recommended place for payment authentication.
Note: User can be authenticated based on conditions like screen unlock. Method must be called before payment in method UcpTransactionEventListener:onContactlessPaymentStarted()
Make sure that authentication on this step is done securely. Transaction information is not available on this step. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
| pin |
CharArray? |
PIN or null for CUSTOM WalletAuthUserMode |
|
**Output**
| Success / failure callback |
**Sample**
Basic user authentication usage below, call when user is authenticated.
```
private fun setUserAuthenticatedForPayment(
paymentInstrument: PaymentInstrument,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser,
{
//user authentication provided
//start one tap payment or continue two tap with 2nd tap to terminal after authentication
//listen for auth timer changes
//user abortUserAuthentication method when transaction cancelled by user
}, { throwable ->
//some error, check exception
})
}
```
Optional authentication before making transaction based on custom conditions.
```
override fun onContactlessPaymentStarted() {
//check internal conditions
//like user performed authentication, is logged in application, is device unlocked etc
val isUserAuthenticated = true
//check if use selected any token for payment and select it in UCP SDK
//otherwise default token will be used
if (getSelectedPaymentInstrumentId() != null) {
ucpApi
.paymentService
.selectForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
success = {
//token will be used for actual payment
//call setUserAuthenticatedForPayment here - sample below in "else" block
},
failure = { throwable ->
//something went wrong, check throwable with documentation
}
)
} else {
if (isUserAuthenticated) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
pin = null, //or pin if MobilePin is used
success =
//user authenticated in SDK
}, failure = {
//authentication failure, check exception
}
)
}
}
}
```
### **abortUserAuthenticationForPayment**
Asynchronous. Offline.
Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped. |
**Input**
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun abortUserAuthenticationForPayment() {
ucpApi
.paymentService
.abortUserAuthenticationForPayment(
{
//user authentication aborted
//listen for auth timer changes
},
{ throwable ->
//some error, check exception
})
}
```
### **processHceApduCommand**
Synchronous. Offline.
Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS.
Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| context |
Context |
Application context, can be provided from HostApduService |
Not empty |
| apdu |
ByteArray |
APDU command from HostApduService::processCommandApdu method parameter |
Not empty |
| extras |
Bundle? |
Extras object from HostApduService::processCom mandApdu method parameter |
|
**Output**
| Apdu result - method called synchronous without callback |
| Parameter. |
Type |
Description |
| apdu |
ByteArray |
APDU command to return in implementation of overridden processCommandApdu method |
**Sample (synchronized HostApduService)**
Use this version if MobileDC:setup and UCP:setup() method is called in Application:onCreate on Main Thread.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(this, commandApdu, extras)
}
//..
}
```
**Sample (aynchronous HostApduService)**
Use this version if SDK is called on another thread and HostApduService can receive APDU until VCP SDK is still in loading state.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
//UcpSdkStateApplicationSingleton is sample class which keep SDK state and allow to observe when SDK load is finished
if (UcpSdkStateApplicationSingleton.isLoaded()) {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
} else {
sendResponseApdu(null)
UcpSdkStateApplicationSingleton.listenForSdkReady(
onSdkLoadListener = {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
}
)
}
return null
}
override fun onDeactivated(reason: Int) {
if (UcpSdkStateApplicationSingleton.isLoaded()) {
return ucpApi
.paymentService
.handleHceApduDeactivationEvent(reason)
}
}
private fun processCommandApduInUcpSdk(
context: Context,
commandApdu: ByteArray,
extras: Bundle?
): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(context, commandApdu, extras)
}
}
//sample objec which helps to listen SDK state
object UcpSdkStateApplicationSingleton : UcpSdkState {
//flag could be synchronized
private var isLoaded = false
private var onSdkLoadListener: (() -> Unit)? = null
override fun listenForSdkReady(onSdkLoadListener: () -> Unit) {
this.onSdkLoadListener = onSdkLoadListener
if (isLoaded) this.onSdkLoadListener?.invoke()
}
//call when SDK loading thread is finished
//setupMdc() -> setupUcp() -> UcpSdkStateApplicationSingleton.onUcpSdkLoaded()
override fun onUcpSdkLoaded() {
isLoaded = true
onSdkLoadListener?.invoke()
}
override fun isLoaded(): Boolean {
return isLoaded
}
}
```
### **replenishCredentials**
Asynchronous. Online. User login session not required.
Method for manually replenishing payment credentials.
Application will receive push notification and notified about replenish process with global callback described in setup chapter. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument that needs it credentials replenished |
Not empty |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun replenishCredentials(paymentInstrumentId: String) {
ucpApi.paymentService
.replenishCredentials(paymentInstrumentId,
{
//request for credentials replenish finished with success
//wait for push notification and pass to valid module
//when push processed application will be informed about replenish success/failure
//read chapter with setup for more information
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **restartContactlessAuthTimer**
Asynchronous. Offline.
Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile.
Default auth time is provided by card profile. |
**Input**
**Output**
| Success / failure callback |
### **requestAuthenticationCodeForPayment**
Asynchronous. Online.
Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| requestAuthenticationCodeForPayment |
RequestAuthenticationCodeForPayment |
Plain RequestAuthenticationCodeForPayment object |
Not empty |
RequestAuthenticationCodeForPayment object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| authenticationRequestId |
String |
Authentication request id up to 64 alphanumeric characters long.
A new id should be used for each instance than an account holder needs to be authenticated |
Not empty |
**Output**
| Success callback/failure callback. |
**Sample**
```kotlin
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) {
ucpApi.paymentService
.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//Requesting Authentication Code went successfully.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **validateAuthenticationCodeForPayment**
Asynchronous. Online.
Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| validateAuthenticationCodeForPayment |
ValidateAuthenticationCodeForPayment |
Plain ValidateAuthenticationCodeForPayment object |
Not empty |
ValidateAuthenticationCodeForPayment object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| authenticationRequestId |
String |
Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. |
Not empty |
| authenticationCode |
String |
Authentication Code to authenticate the account holder |
Not empty |
**Output**
| Success callback with ValidateAuthenticationCodeForPaymentResult object. |
ValidateAuthenticationCodeForPaymentResult object contains following field
| Parameter |
Type |
Description |
| signedAuthenticationProcessData |
String |
Signed AuthenticationProcessData per RFC 7519 |
AuthenticationProcessData model
| Parameter |
Type |
Description |
| authenticationRequestId |
String |
Authentication request id |
**Sample**
```kotlin
fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) {
ucpApi.paymentService
.validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment,
{ validateAuthenticationCodeForPaymentResult ->
//ValidateAuthenticationCodeForPaymentResult plain object,
//contains data to validate on backend
val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult
.signedAuthenticationProcessData
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAuthenticationProcessData {
fun verifyAndGetAuthenticationRequestID() {
val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600);
val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId")
// ...
}
}
```
### **processDsrpTransaction(deprecated)**
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
| dsrpTransactionInfo |
DsrpTransactionInfo |
|
|
**Output**
| Success callback with cryptogram for payment |
### **processDsrpTransaction**
Asynchronous. Offline.
Method dedicated for starting DSRP transaction.
Every DSRP transaction has to be authenticated before processing.
Depending on implementation payment can be process with OTP authentication or device level authentication. |
| Parameter |
Type |
Description |
Validation conditions |
| processDsrpTransaction |
ProcessDsrpTransaction |
Plain ProcessDsrpTransaction object |
Not empty |
ProcessDsrpTranasction object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| dsrpTransactionInfo |
DsrpTransactionInfo |
Plain DsrpTransactionInfo object |
Not empty |
DsrpTransactionInfo object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| amountMinor |
Long |
A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 |
Not empty |
| currencyCode |
String |
A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. |
Not empty |
| countryCode |
String? |
A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. |
|
issuer
Cryptogram
Type |
DsrpIssuer
Cryptogram
Type |
Enum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. |
Not empty |
unpredictable
Number |
Long |
A long representing the random number generated by the merchant or by the Payment Gateway. The maximum value is 4,294,967,295. |
Not empty |
| transactionType |
Dsrp
Transaction
Type |
A type of financial transaction, one of: PURCHASE, CASH, PURCHASE\_WITH\_CASHBACK, REFUND |
Not empty |
| transactionDate |
Date? |
A Date object indicating date of transaction. |
|
**Output**
| Success callback with ProcessDsrpTransactionResult object. |
ProcessDsrpTransactionResult object contains following field
| Parameter |
Type |
Description |
transaction
Cryptogram
Data |
ByteArray |
A byte array containing a formatted response, either UCAF or a set of TLV data for the merchant to populate DE55 data. |
| pan |
String |
String containing the PAN of the card used. |
panSequence
Number |
Int |
An integer value specifying the PAN Sequence Number (PSN) of the card used. |
| cryptogramType |
DsrpIssuer
Cryptogram
Type |
Enum value as UCAF or DE55 depending on cryptogram data format is used. |
| track2Data |
String |
String containing the data elements of track 2 according to ISO/IEC 7813. |
| par |
String |
String representation of byte array of permanent account reference. A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens. |
| expirationDate |
String |
Date in ISO-8601 (YYYY-MM-DD) format indicating expiry date of the card. |
| transactionId |
String |
Hexed byte array containing a Transaction Identifier. |
**Errors**
DsrpPaymentException exception throwed on error in DSRP processing
| DsrpPaymentException.reason |
Description |
| DSRP\_INVALID\_INPUT |
Invalid input data. |
| DSRP\_UNEXPECTED\_DATA |
Provided data is valid in context of validation, but doesn't mee |
| DSRP\_AUTHENTICATION\_REQUIRED |
Authentication is not provided for DSRP payment. Authenticate and process DSRP transaction again. |
| DSRP\_TOKEN\_INACTIVE |
Token used for DSRP is inactive. |
| DSRP\_NO\_TRANSACTION\_CREDENTIALS |
There is no transaction credentials to procees DSRP payment |
| DSRP\_NOT\_SUPPORTED\_BY\_CARD |
DSRP is not suported by Card. |
| DSRP\_TRANSACTION\_DECLINED |
Transaction is declined by Card. |
| DSRP\_INCOMPATIBLE\_PROFILE |
Card profile is incomaptible with DSRP. |
| DSRP\_WRONG\_STATE |
DSRP transaction is in wrong state. |
| DSRP\_INTERNAL\_ERROR |
Unknowne error during DSRP processing. |
**Sample** **DSRP transaction with device level authentication**
```
// After Merchant App delivers DSRP data application should authenticate user with device level authentication
// and next execute setUserAuthenticationForPayment().
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTranasctionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample DSRP transaction with OTP authentication**
```
// After Merchant App delivers DSRP data user should request authentication
// code for payment with selected paymentInstrument.
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment =
RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId)
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) {
ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//When requesting went successfully User will get authentication code.
//In next step authentication code should be passed to MPA and application
//should validate this code with validateAuthenticationCode() method
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
val validateAuthenticationCode: ValidateAuthenticationCode =
ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser)
fun validateAuthenticationCode(validateAuthenticationCode) {
ucpApi.paymentService
.validateAuthenticationCode( validateAuthenticationCode,
{ validateAuthenticationCodeResulty ->
//ValidateAuthenticationCodeResult plain object
val signedAuthenticationProcessData = validateAuthenticationCodeResulty
.signedAuthenticationProcessData
//If validation went successfully MPA should show authentication view,
//and after valid authentication MPA should execute setUserAuthenticatedForPayment()
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTransactionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample input and output DSRP data:**
```Java
Input:
amountMinor: 4321,
countryCode: 840,
currencyCode: 840,
issuerCryptogramType: UCAF,
transactionDate: Apr 25, 2023 09:41:05, //Date() toString() format
transactionType: PURCHASE,
unpredictableNumber: 29496729
Output:
pan: 5204830959972699
track2Data: 5204830959972699D26052010000000000000
expirationDate: 2026-05-31 //YYYY-MM-DD
par: 500170A4PEV2GLWPFD00N6H5AX2YB
panSequenceNumber: 0
transactionId: df25a522a075680acbaa407fdc8a0348a321f77afa2f0231cd38f28e7ae691e2
cryptogramType: UCAF
transactionCryptogramData: 414d506a6d4a474650306149414155427768575a47674144464b553d //in Hex
```
Cloud messaging domain
### **process (deprecated in 2.6.7)**
Asynchronous. Online. User login session not required.
Processes data sent by VCP backend (push notification data).
Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method.
Method can throw InvalidPushException in case of invalid push content passed to it.
Refer Mobile DC documentation how to handle push.
Deprecated in 2.6.7, use MobileDC:CloudMessaging:process() instead. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| pushData |
Map |
Data received from notification service in object RemoteMessage object |
Not empty |
**Output**
| Success / failure callback. When request fails try again |
**Sample**
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map) {
ucpApi
.cloudMessagingService
.process(pushData, {
//push processed in Mobile DC
}, {
//some error
})
}
```
### **processMcbpNotificationData**
Asynchronous. Offline.
Processes data sent by MCBP.
Application should check senderId in RemoteMessage object before passing data to VCP SDK.
Basic configuration for push processing from External Wallet Server: External Wallet Server domain.
Method can throw InvalidPushException in case of invalid push content passed to it.
Note: External Wallet Server Registration process mus be finished before push processing. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| encryptedPayload |
String |
Data received from notification service in object RemoteMessage object |
Not empty |
**Output**
| Success / failure callback |
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String? = remoteMessage.from
val pushData = remoteMessage.data
//check push source based on senderId
if (isVerestroSenderId(senderId)) {
val verestroPayload: String = readVerestrpPushContent(pushData)
ucpApi
.cloudMessagingService
.processMcbpNotificationData(verestroPayload, {
//push processed in VCP
}, {
//some error
})
} else {
//proceed push from another source
}
}
```
External Wallet Server domain
Chapter contains method for SDK when External Wallet Server is used.
Usage of method requires additional configuration with external API.
Basic MDES cloud messaging configuration:
| Environment |
FCM Sender Id |
| MTF |
502118574555 |
| PRODUCTION |
993764297204 |
### **prepareRegistrationData**
Asynchronous. Offline.
Method for preparing data used for activation.
Should be used before calling register method. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentAppInstanceId |
String |
Identifier for the specific Mobile Payment App instance |
Not empty |
| paymentAppProviderId |
String |
Globally unique identifier for the Wallet Provider, as assigned by MDES |
Not empty |
| publicKeyCertificate |
String |
CMS-D public key certificate in pem format |
Not empty |
| mobilePin |
CharArray? |
Mobile PIN used to payment confirmation |
|
**Output**
| Success callback with PrepareRegistrationResponse object. |
| Parameter |
Type |
Description |
| publicKeyCertificateFingerprint |
String |
CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) |
| encryptedRgk |
String |
Encrypted randomly-generated 128-bit AES key. |
| deviceInfo |
EwsDeviceInfo |
Device info. |
| deviceFingerprint |
String |
Unique device fingerprint. |
| encryptedPin |
String? |
Encrypted pin (if passed in input). |
EwsDeviceInfo model:
| Parameter |
Type |
Description |
| deviceName |
String |
Device model name. |
| formFactor |
String |
The form factor of the target provisioned device. |
| storageTechnology |
String |
The architecture or technology used for token storage. |
| osName |
String |
The name of the operating system of the target provisioned device. |
| osVersion |
String |
The version of the operating system of the target provisioned device. |
| nfcCapable |
Boolean |
Whether the target provisioned device has NFC capability. |
**Sample**
```kotlin
fun prepareRegistrationData(
paymentAppInstanceId: String,
paymentAppProviderId: String,
publicKeyCertificate: String,
mobilePin: CharArray?) {
ucpApi
.ewsService
.prepareRegistrationData(paymentAppInstanceId,
paymentAppProviderId,
publicKeyCertificate,
mobilePin,
{ prepareRegistrationResponse ->
//Prepared data for registration including encryptedMobilePin if mobilePin is used
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **register**
Asynchronous. Online.
Method used for registration new Mobile Payment App instance with MDES for use. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| mobileKeysetId |
String |
Identifies the Mobile Keys used for this remote management session |
Not empty |
| ewsMobileKeys |
EwsMobileKeys |
Contains the mobile keys used to secure the communication during subsequent remote management sessions |
Not empty |
| remoteManagementUrl |
String |
The URL endpoint for subsequent remote management sessions
The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions |
Not empty |
EwsMobileKeys
| Parameter |
Type |
Description |
| transportKey |
String |
The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES |
| macKey |
String |
The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES |
| dataEncryptionKey |
String |
The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun register(
mobileKeysetId: String,
ewsMobileKeys: EwsMobileKeys,
remoteManagementUrl: String) {
ucpApi
.ewsService
.register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl,
{
//Device registration success
//application should listen to push messages and UcpPaymentInstrumentEventListener callbacks
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **activate**
Asynchronous. Online.
Method to activate PaymentInstrument.
Should be used only on PaymentInstrumens which PaymentInstrumentStatus is SUSPENDED or INACTIVE.
Changes PaymentInstrumentStatus to ACTIVE, calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available.
Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to activate. |
Not empty. |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun activate(paymentInstrumentId: String) {
ucpApi
.ewsService
.activate(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to ACTIVE, set card as default for payment if another
//is not already setted Performing replenish,
//application should listen to push message with information about replenish success/failure
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **suspend**
Asynchronous. Offline.
Method for suspending paymentInstrument.
Changes PaymentInstrumentStatus to SUSPENDED.
Use activate method to allow payments again. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to suspend. |
Not empty. |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun suspend(paymentInstrumentId: String) {
ucpApi
.ewsService
.suspend(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to SUSPENDED.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument**
Asynchronous. Offline.
Method for getting single PaymentInstrument from local storage object based on id. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to get. |
Not empty. |
**Output**
| Success callback with PaymentInstrument object. |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Retrieved paymentInstrument |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String) {
ucpApi.ewsService
.getPaymentInstrument(paymentInstrumentId,
{ paymentInstrument ->
//PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
Asynchronous. Offline.
Method for getting all payment instruments from local storage. |
**Input**
**Output**
| Success callback with list of PaymentInstrument objects. |
| Parameter |
Type |
Description |
| paymentInstruments |
List |
List of retrieved payment instruments from local storage |
**Sample**
```kotlin
fun getAllPaymentInstrument() {
ucpApi.ewsService
.getAllPaymentInstruments(
{ paymentInstruments ->
//List of PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getEncryptedPin**
| Asynchronous. Offline.\ |
Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| pin |
CharArray |
PIN to encrypt. |
Not empty. |
**Output**
| Success callback with encrypted mobile PIN. |
| Parameter |
Type |
Description |
| encryptedMobilePin |
String |
Hex encoded encrypted mobile PIN. |
**Sample**
```kotlin
fun getEncryptedPin(pin: CharArray) {
ucpApi
.ewsService
.getEncryptedPin(pin, { encryptedPin ->
//call to Wallet Server with new created encrypted mobile PIN
//when updated call onMobilePinChanged method
}, {
//Something went wrong, check exception with documentation
})
}
```
### **onMobilePinChanged**
Asynchronous. Online.
Method for informing SDK about mobilePin change.
Should be used when mobilePin changed.
The result of action is deletion of existing transaction credentials and replenish. |
**Input**
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun reactOnMobilePinChanged() {
ucpApi
.ewsService
.onMobilePinChanged(
{
// Informing SDK about changing mobile pin processed succesfully.
// SDK should delete and next replenish transaction credentials.
// Listen for UcpPaymentInstrumentEventListener events
}, { throwable ->
// Something went wrong, check exception with documentation.
})
}
```
### **delete**
Asynchronous. Online.
Method to removing PaymentInstrument.
Removed transaction credentials and PaymentInstrument from local storage and in MDES.
When success PaymentInstrument will be no longer available in getPaymentInstrument and getPaymentInstruments methods. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to delete. |
Not empty. |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String) {
ucpApi
.ewsService
.delete(paymentInstrumentId,
{
//Selected Payment instrument is removed
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Assets Domain
### **getAsset**
Asynchronous. Online.
Method for getting all assets for selected assetId. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| assetId |
String |
Id of assets to retrive |
Not empty |
**Output**
| Success callback with list of Assets objects. |
| Parameter |
Type |
Description |
| ucpAsset |
UcpAsset |
Plain UcpAsset object |
UcpAsset object contains following field
| Parameter |
Type |
Description |
| content |
List |
Plain list of UcpAssetContent objects |
UcpAssetContent contains following fields.
| Parameter |
Type |
Description |
| data |
String |
The data for this asset. Base64-encoded data, given in the format as specified in type. |
| type |
String |
The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. |
| width |
Long? |
For image assets, the width of this image. Specified in pixels. |
| height |
Long? |
For image assets, the width of this image. Specified in pixels. |
**Sample**
```kotlin
fun getAsset(assetId: String) {
ucpApi.assetsService
.getAssets( assetId,
{ ucpAsset ->
//List of assets of selected assetId
val ucpAssetContentList = ucpAsset.content
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Document changelog
Vesion 2.10.10
- Added new field for digitization: *formFactor*
- Mobile DC updated to 2.17.3
Vesion 2.10.0
- Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes)
- Security tools updated to newest version
- Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22)
- AGP updated to 8.11.1
- Mobile DC updated to 2.17.0
Version 2.9.10
- Added new parameter *transactionId* to method *onContactlessPaymentCompleted* for Mastercard transactions.
New transaction identifier allow to match transaction with processed transaction notification *MobileDC::EventNewTransaction::clientTransactionId.*
- Mobile DC updated to 2.16.12
Version 2.9.8
- **IMPORTANT: Security tools updated to newest version. Recommneded update when using version 2.9.x due to changes fixes in security tools.**
- Visa SDK updated to 6.4.0
- Mobile DC updated to 2.16.10
Version 2.9.5
- Added MC *mtf* host name
- Update Mobile DC to 2.16.5
Version 2.9.4
- **Important:** Apply security and functional certification changes related to intruduction new security tools. Changes in security thread management and working in background
- Update Mobile DC to 2.16.4
Version 2.8.7
- Update Mobile DC to 2.15.8
Version 2.8.6
- Small fixes to 2.8.5
Version 2.8.5
- Update Proguard rules related to R8 changes
Version 2.8.2
- Added new field "externalPaymentTokenId" in DigitizationGreenPath, DigitizationRequest and DigitizationResult models.
- Added new optional configuration withOptionalWalletMcbpHttpExecutor
- Marked configuration withUcpTransactionEventListener from UcpConfigurationBuilder as deprecated. Use MobileDcTransactionEventListener.optionalMobileDcTransactionEventListener from MDC SDK instead.
Version 2.7.4
- Added new field "paymentTokenExpirationDate" in PaymentInstrument model.
Version 2.7.3
- update MobileDC dependency to 2.15.3
Version 2.7.1
- update MobileDC dependency to 2.15.1
Version 2.7.0
- update MobileDC dependency to 2.15.0
Version 2.6.9.2
- update MobileDC dependency to 2.14.7.2
Version 2.6.9.1 - Hotfix possible OutOfMemoryException in MDC 2.14.7
- update MobileDC dependency to 2.14.7.1
Version 2.6.9 - don't use, could cause OOM Exception
- Updated Mobile DC dependency to 2.14.7.
- Updated *processDsrpTransaction* method.
Version 2.6.7
- Updated Mobile DC dependency to 2.14.6
- Added support for Mastercard India datacenter.
- **important** Added new method to UcpTransactionEventListener - *onContactlessPaymentStarted()***.** Callback allows application to get event about new transaction and it's a best place for token selection and user authentication. Read more in Product Overview.
- Due to adding new place for contactless payment authentiocation also updated code samples for *HostApduSevice* implementation and method *setUserAuthenthenticatedForPayment()*
- **Important** CloudMessagingService:process became deprecated due to introducing delivery message from server service. Read more in Product Overview and Mobile DC specification.
- **Important** Added new status *AbortReason:CONNECTION\_LOST* for *UcpTransactionEventListener:onContactlessPaymentAborted.* Status TERMINAL\_INACTIVITY\_TIMEOUT became deprecated. Change significally improves contactless payment UX. Method works immediatelly when connection between device and terminal is lost.
- **Important** Aded new optional configuration for *UcpTransactionConfiguration* with field *enableTransactionAuthenticationTimer.* Timer is now disabled by default, previously was always enabled and could cause problems when authentication time leading to zero and user performs transaction. It could cause clearing user authentication during processing payment on terminal. Change is related to other payments optimizations and introducing *onContactlessPaymentStarted()* and new *AbortReason CONNECTION\_LOST.* Please align your code to new changes, enabling timer is not recommended.
- Updated Mobile DC dependency to 2.13.7
- Resolved Google Play Console Security warning
- Updated Mobile DC dependency to 2.13.6
Version 2.5.5
- Wrap in try-catch block callbacks from SDK *setup()* method to prevent breaking process in SDK. Read more in *setup*() method description.
Version 2.5.3
- Update internal libraries. **IMPORTANT** Read more in Mobile DC changelog for version 2.13.3
Version 2.5.2
- Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality
Version 2.5.1
- Methods marked as deprecated:
- reset (use restart instead)
- getPaymentInstrument (use getAllPaymentInstruments instead)
- setDefaultForRemote (usage is redundant)
- getDefaultForRemote (usage is redundant)
- processDsrpTransaction(use new processDsrpTransaction method with *ProcessDsrpTransaction* added model)
- Added new methods related to OTP authentication code:
- requestAuthenticationCodeForPayment
- validateAuthenticationCodeForPayment
- Added new methods for supporting yellow-path token activation:
- checkEligibility
- digitize (new version with support for checkEligibility usage)
- submitTokenAuthenticationMethod
- submitTokenAuthenticationValue
- getAdditionalAuthenticationMethods
- Fixed getPaymentInstrument method (case invalid error when session expired error occurred).
- Updated Kotlin version to 1.5.31 and Koin to 2.1.6.
- Removed unused permissions *ACCESS\_FINE\_LOCATION* and *com.google.android.c2dm.permission.RECEIVE .*
- Added logs for all facade methods (available in SDK debug version).
Version 2.4.4
- Updated MDC SDK to 2.12.1 - fixed aggressive security process check
- Updated documentation for TransactionAbortReason:TERMINAL\_INACTIVITY\_TIMEOUT model
Version 2.4.3
- IMPORTANT Update security tools after EMV Security Evaluation - refer to Mobile DC technical documentation version changelog (version 2.12.0)
- Update Gradle and R8 tools
- Handled authentication flow for ContactlessRichTransactionType REFUND. SDK requires authentication if not provided.
- Improved description for ContactlesssTransactionResult model in documentation.
- Added new ContactlessRichTransactionType: WITHDRAWAL and ATM\_CONTACTLESS
Version 2.3.24
- Added new state for TransactionAbortReason::TERMINAL\_INACTIVITY\_TIMEOUT. Previously status was part of TransactionAbortReason::TERMINAL\_ERROR and produces contactless payment aborted handling problems. Status is used in onContactlessPaymentAborted callback. Application can ignore this state and do not perform any action.
- Added method on UcpApi for SDK restart(). Unlike reset() new method is asynchronous and allows to usage VCP SDK without application kill. Method clears all VCP SDK data and restarts to initial state.
- Introduced new approach to handling security issue. When application will call any SDK method after security issue reporting, UcpSkdExpcetion with SECURITY\_EVENT\_OCCURRED will be returned. Previously APPLICATION\_PROCESS\_NOT\_KILLED was returned. Change doesn't impact onSecurityIssue callback.
- Added Assets Domain and getAsset() method.
- Added verification of input parameters in token profile and transaction credentials replenish.
- Added more details in callbacks onProvisioningFailure and onReplenishFailure about errors in token related operations.
Version 2.3.22.2 - hotfix
- Added more validation for input parameters for External Wallet Server service
- Added data verification before accessing data in CMS-D processes
- Improved catching exceptions for MCBP processes
- Improved flow for reset() method - added protection agains processing messaging after SDK reset()
- Changed algorithm for calculating publicKeyCertificateFingerprint in PrepareRegistrationDataResponse. From hex(sha1(certificate.publicKey.encoded)) to hex(sha1(certificate.encoded))
- Added support for multiple calling setUserAuthenticatedForPayment() method
Version 2.3.22
- Improved internal SDK logs reporting
- Using androidX in end project is necessary now
- Improved automatic replenish credentials process
- Added handling ReDigititzation process in SDK. Use withOptionalReProvisionEventListener method in SDK setup method to observe PaymentInstrument changes
Version 2.3.21
- Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration
- Replenish process optimization
Version 2.3.18
- Updated security libraries
Version 2.3.17
- Fixed parsing merchantAndLocation field from ContactlessTransactionData.
- Added EWS configuration parameter in setup.
Version 2.3.13
- Added new parameter *result* to IbanDigitizationResult model
- Parameter *cloudDigitizationSuccess* in IbanDigitizationResult is now deprecated
Version 2.3.12
- Core module with update.
- Added new reports to Wallet Server.
Version 2.3.11
- Added new method in Payment Service: processDsrpTransaction
- Added new method in User Service: resendOtp
- Added new paremeter in createPaymentData IbanInfo model: userId
- Improved default PaymentInstrument management
- Fixed clearing SDK state when unpairing device (MobileDC unPair method)
Version 2.3.8
- Improved facade exception throwing, now contains more details about error.
- Removing whitespaces from merchantAndLocation in ContectlessTransactionData model
- Updated security harmful process check mechanism
- Added MCBP cloud messaging queue handling to prevent processing errors
Version 2.3.2
- Fixed SDK provisionning process on Google Pixel devices
- Improved default Payment Instrument management
- Updated security harmful process check mechanism
Version 2.3.1
- Added *delete* method in External Wallet Server domain
- Added more detailed descriptions for methods from External Wallet Server domain
- Added more information about models related to payment processing
Version 2.2.7
- Added reset functionality.
- Addded method in Ibans service createPaymentDat.
- Method createTVC iban service is now deprecated.
- Added global listener for most important internal SDK actions related to token managem
Version 2.2.6
- Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure
- Fixed problem with flow cutting on digitalization process
Version 2.2.4
- Added new enum state TransactionAbortReason.NO\_CARDS. Callback onContactlessPaymentAborted is now called when no card is available for payment.
- Added new model ContactlessTransactionData with better formatting terminal data. New object is added for events EventGetFinalDecision, EventAuthRequiredForContactless, EventContactlessPaymentCompleted.
- ContactlessTransactionInformation is now deprecated.
Version 2.2.3
- Fixed setting default PaymentInstrument after activation
- Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status
Version 2.2.2
- Fixed dependencies conflicts
- Consumer Proguard rules update
- Certificate pinning implementation improvement
Version 2.2.0
- Added new method in EWS Service - getEncryptedPin
- SDK startup optimization
Version 2.1.1
- Fixed dependencies for release version
- Added information about SDK size
- Added information about SDK integration on lower Android API level
Version 2.1.0
- Added new methods in External Wallet Server domain (activate, suspend, getPaymentInstrument, getPaymentInstruments, onMobilePinChanged)
Version 2.0.0
- Changed approach to SDK setup
- Added UcpSdkException
- Added new reason codes to existing exceptions
- New methods in cards domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in ibans domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in cloud messaging domain: processMcbpNotificationData
- New methods in payment domain: abortUserAuthenticationForPayment, replenishCredentials, restartContactlessTimer
- New methods in external wallet server domain: prepareRegistrationData, register
Version 1.0.1
- Created
# Watch integration
Version 1.0
June 2025
---
The Watch Payment product allows payments using Watch connected to Android and iOS smartphones.
Payments are based on the MDES Token Requestor solution from Mastercard.
Contactless payments are possible without a constant internet connection—both on the smartphone and the smartwatch.
The core payment and token provisioning process is based on the [Token Requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet) product and requires an active project with Mastercard.
VCPSDK is a certified and secure product, approved by EMVCo and Mastercard, and has been launched in multiple banking and partner applications.
## 1. Introduction
### Basic information
The Wearables SDK is an SDK designed to integrate with Watch as Payment Instrument.
Wearables SDK enabling direct communication between smartwatches and payment systems.
It allows to create applications that support contactless payments directly from the Watch, eliminating the need for a paired smartphone during transactions.
This streamlined integration offers a secure and efficient way for users to make payments simply by wearing their smartwatch.
Product is based on Verestro Cloud Payment solutions for NFC Issuer Wallet with Mobile MasterCard MCBP 2.1 SDK.
See Verestro Product description here [Token Requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet).
### Requirements
- Verestro Cloud Payment solutions for NFC Issuer Wallet integration as
described [Token Requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet)
- Verestro Wearables SDK for [Android](https://developer-android.verestro.com/wearablessdk/latest/documentation/) or [iOS ](https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/)
- Integration with Watch Manufacturer
SDK references (to review): Wearables SDK documentation is available for Android and iOS. SDK artifacts and project access details are provided during onboarding together with the related Wallet SDK artifacts.
### Components
- **Mobile Payment Application (MPA)** - application for integrating Verestro Cloud Payments for safe device&user authentication, card management and tokenization
- **User management MDC SDK (Mobile DC SDK)** - Verestro SDK for device, user and cards management
- **Token Requestor SDK (VCP SDK)** - Verestro SDK for tokenization, token management and payment
- **Wearengine SDK (Wearables SDK)** - Verestro SDK for enabling VCP SDK tokenization on Watch SDK
- **Watch payment SDK** - Verestro SDK for token management and payment on Watch
- **Watch communication SDK** - SDK on the watch for communication with watch.
- **Watch Application** - Verestro integration layer integrated directly to Client's watch
application for communication with Wearables SDK and Watch SDK
### Architecture
## 2. Use Cases
### 2.1. Watch integration
Connection to Watch is usually realized by Watch's manufacturer application which allow to create connection and pair Watch device with Android/iOS Phone.
Development requires additional configuration on Watch manufacturer store. In order to start integrate Watch in client Mobile Payment Application (MPA) client need to:
- create account on Watch manufacturer Store
- add MPA packageId or bundleId
- configure MPA trusted certificates for signing
### 2.2 MPA to Watch Connection
Connection from MPA to Watch is realized by Watch's manufacturer Library.
Wearables SDK allows to simply use Watch library along Verestro UCP SDK.
### 2.3. MPA to Watch Pairing
Once Watch is connected with MPA it can be used with Watch application for communication with Wearables SDK.
In order to create secure channel to WatchSDK bundled with Watch application UCP SDK must exchange pairing data with WatchSDK.
### 2.4. Secure channel for data sending
During this process Wearables SDK create secure connection between UCP SDK and Watch SDK to send card profile and transaction credentials.
Every data synchronization requires to create new secure channel.
Both sender and receiver is verified during connection.
Process is transparent for MPA.
### 2.5. Token creation
During this process new Token is created for usage on dedicated Watch device.
Verestro SDK allow to create multiple Device along one SDK instance and tokenize same Card for each device.
Read more about Verestro SDK integration in order to tokenization: [https://developer.verestro.com/books/token-requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet).
### 2.6. Add Token to Watch
During this process new created token for unique device (Watch) is transferred from certified UCP SDK to Watch SDK using a secure channel (to review).
Transferred Token contains token data to show on Watch UI like last four digits, expiration date and card visual.
### 2.7. Add Token Credentials to Watch
During this process encrypted transaction credentials are transferred to Watch SDK and assigned to Token making it ready for contactless payments.
These credentials are stored on the device, enabling payments even without a constant internet connection or a direct link to the phone.
Process is used both for credentials add after sending token and for data synchronization between UCP SDK and Watch SDK.
### 2.8. Token data synchronization
This process ensures that all token and payment-related data on the watch remains up to date.
During synchronization, both the MPA and the Watch application update the token status (active, suspended, or deleted) and the status of transaction credentials within the Watch SDK.
The Wearables SDK is responsible for maintaining the maximum number of transaction credentials on the Watch SDK to enable standalone payments directly from the watch.
Token and transaction credentials synchronization can be initiated by either the MPA or Watch application and should be performed every time the application is launched.
Additional Token synchronization use cases:
- token managed by MPA or Client's Admin Panel
- token updated by MasterCard with re-digitization
- application and related tokens ares removed on Phone or Watch
Additional transaction credentials synchronization use cases:
- sending new transaction credentials along with associated Token
- transaction is performed on Terminal and Watch request synchronization
- finished replenish credentials process on MPA
##### Synchronization
Standard communication between MPA and Watch in order to keep both up to date.
##### Token status update
Invoked on MPA or remote (Admin Panel) action related to Token.
### 2.9. Watch Payment
Process describes Payment flow on Watch.
- User must unlock Watch to process payment and open Payment application.
- Once the Payment Token is selected, the user can Tap & Pay on a terminal.
- After the payment, the watch should attempt to communicate with the MPA to synchronize the credential state.
#### Payment authentication
Transactions must be authenticated, but this does not mean that every transaction requires separate confirmation.
The application uses Consumer Device Cardholder Verification Method (CDCVM) to authenticate the user. Depending on specific circumstances, the app may request biometric authentication or a PIN.
Since the service uses on-device authentication, no additional security mechanisms need to be implemented by the integrator.
### 2.10. Disabling Payments
If the watch is unpaired from the phone via the Wearable Provider's app or the payment app, it will no longer be able to process payments.
If the watch was connected to the phone at the time of unpairing, its stored payment data will be automatically deleted.
There is no possibility to transfer payment data between devices or retain it on the watch after switching to a new phone.
Blocking payments on both the phone and watch is possible through the [Admin Panel - card issuer’s administrative panel](https://developer.verestro.com/books/administration-panel?shelf=6).
The user can also remove the watch pairing from the mobile application, which will disable smartwatch payments.
# Quick introduction to Payments Tokenization
#### NFC Payments and Issuer Wallets: Simplicity Through Experience
NFC payments and issuer wallets are among the most complex and often misunderstood areas in the world of digital finance. Mastering them requires not only deep technological knowledge but also expertise that goes far beyond traditional payment processing. What’s more, because these solutions provide direct access to processed funds, they demand the highest standards of security and compliance.
At Verestro, we have learned all these lessons the hard way—and we’ve encapsulated our expertise into easy-to-integrate SDKs. This means that entering the world of NFC payments and issuer wallets with us is as simple as it gets.
We guide our clients through every step:
- launching projects with Mastercard and Visa,
- configuring project requirements,
- outlining the needs of every component in the process,
- enabling services even in locations with legal restrictio.
Our SDKs are designed for seamless integration into client applications, and our team is ready to help with even the most complex internal processes. None of these challenges are new to us—we’ve successfully navigated them many times before.
We have real-world experience enabling contactless payments on Android and iOS devices, and even on wearables running dedicated operating systems.
**With Verestro, it’s possible! Let us make NFC payments and issuer wallets easy for you.**
# Watch integration - FAQ
#### Supported Smartwatch Models
Which smartwatches are supported?
The following models are supported:
- Huawei Watch Ultimate Green
- All models of Huawei Watch 5
- All models of Huawei Watch GT5 and GT5 Pro
- All models of Huawei Fit4 and Fit4 Pro
#### Verestro Components Required
What Verestro components are required to enable smartwatch payments?
To enable secure smartwatch payments, the following components are required:
- [Watch payment ](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/watch-integration)with Wearengine SDK - SDK for integration and communication to the Watch (Android and [iOS](https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/))
- [LifeCycle](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/overview) - for secure card data storage
- [Transaction History Core](https://developer.verestro.com/books/transaction-history-api) - for processing transaction history
- VCP Wallet Server - server-side component of the Verestro Contactless Platform (VCP)
- [MDC SDK](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/technical-documentation-mdc-sdk) and VCP SDK - to be integrated into the mobile application ([Android](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/technical-documentation-vcp-sdk) or [iOS](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/technical-documentation-vcp-sdk-ios))
- [Token Management Platform](https://developer.verestro.com/books/token-management-platform) - required for Issuer Wallet service
#### Third-party Integrations
What third-party integrations are needed?
To tokenize payment cards, active connectivity with Mastercard MDES or Visa VTS is required. Each token requestor (bank) must have their own access. Existing connections can be reused if already in place.
#### AppGallery Connect (AGC)
How do I create an account on AGC (AppGallery Connect)?
Follow steps on [Appgallery Connect Registration Page](https://id7.cloud.huawei.com/CAS/portal/userRegister/regbyemail.html)
What data from AGC is required for smartwatch payment integration?
After creating the application in AGC, the following identifiers will be available:
- MPA packageID
- bundleID
These are used to associate the smartwatch app with the mobile application.
#### Component Substitution
Can I replace Verestro components with my own?
The fastest integration path is through the use of all Verestro components. However:
- A different Token Management Platform can be used
- Replacing the Wallet Server is possible if adapted to work with the VCP SDK
#### Device Pairing Limitations
Can I pair multiple smartwatches with a single smartphone?
No. Only one active smartwatch can be connected to a smartphone at a time. Connecting a new watch will disconnect the previous one.
Can I pair one smartwatch with multiple smartphones?
No. A smartwatch can be connected to only one smartphone at any given time. Pairing with another smartphone will disconnect it from the first one.
#### Required Setup Processes
What processes must be completed to enable smartwatch payments?
- User registration - via manual registration or using LifeCycle API provided by the partner.
- User authentication - via password, PIN, or Trusted Identity in case of SDK integration with a partner app.
- Card provisioning - either by importing existing card data or creating a new card via Card Issuing.
- Card digitization - token creation through MDES or VTS. This must be performed separately for smartphone and smartwatch, but can be unified via mobile app UI.
- Smartwatch provisioning - data provisioning and synchronization with the watch.
There are multiple ways to fulfill these requirements. A proper analysis will help determine the most effective approach.
#### Activating Payments on Smartwatch
How does a user activate smartwatch payments, step by step?
1. The user installs the payment app on both the smartphone and the smartwatch.
2. If the watch is unsupported, no payment app will be available for download.
3. The user sets the payment app as the default app on the watch and optionally enables double-press shortcut via the hardware button.
4. The user completes required onboarding steps (registration, KYC)
5. Card is created or delivered to Veresto VCP Wallet Server
6. Applications on smartphone and watch deliver payment tokens with processes digitization and provisioning
##### Supported Smartphone OS Versions
What smartphone operating system versions are supported?
The last 3 major versions from the current system version are supported. Using the latest available version for a given device is recommended.
#### Installing the Smartwatch App
How can I install the payment app on my smartwatch?
Use the Huawei Health application to install the payment app on the smartwatch.
#### Security & Card Management
Is the solution secure?
Yes. The service is regularly audited by accredited organizations on behalf of Mastercard and Visa.
What if the smartwatch is lost?
The watch can be remotely removed (unpaired) from the paired mobile application. Customer Service can also assist in watch removal. After removal, no transactions initiated from the lost watch will be accepted.
Can I store multiple cards on one smartwatch?
Yes, each card issued within the Issuer Wallet can be added to the smartwatch, unless restricted by project-specific configurations.
#### Compatibility with Apple Pay and Google Pay
Is this solution compatible with Apple Pay or Google Pay?
No. Issuer Wallet is an alternative to Apple and Google Pay. Cards issued or managed within Verestro services cannot be added to Apple Pay or Google Pay, and vice versa.
#### Setting as Default Payment App
How do I set this solution as the default payment app?
The default payment app can be set in the system settings of the smartphone or smartwatch. Alternatively, a one-time payment can be initiated directly from the partner app without changing the default payment app.
# Technical Documentation VCP SDK - iOS
SDK for smartphones: [https://developer-ios.verestro.com/vcpsdk/latest/documentation/](https://developer-ios.verestro.com/vcpsdk/latest/documentation/)
SDK for communciation to the Watch: [https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/](https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/)
# Technical Documentation MDC SDK
| ### MDC - Basic application flow
|
| **Android** [Link to Mobile DC SDK technical documentation](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/technical-documentation-mdc-sdk "User Lifecycle & Card Management API & SDK") |
| **iOS** [https://developer-ios.verestro.com/mobiledcsdk/latest/documentation/](https://developer-ios.verestro.com/mobiledcsdk/latest/documentation/) |
# Technical documentation VCP External API
Technical Documentation VCP External API
@swagger="https://services.upaidtest.pl/ucp/doc.yaml/external"
# DRAFT W MD Technical Documentation VCP SDK
VCP SDK Introduction
### **Basic abbreviations and definitions**
| **Field** | **Description** |
| :---- | :--- |
| CDCVM | Consumer Device Cardholder Verification Method |
| CVM | Cardholder Verification Method |
| Contactless | Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to VCP SDK. HCE support is required for contactless transactions |
| DSRP | Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions |
| FCM | Firebase Cloud Messaging |
| HCE | Host Card Emulation |
| IBAN | Bank Account Number |
| MCBP | Mastercard Cloud Based Payments |
| MDC | Mobile Data Core. Verestro core library. |
| MPA | Mobile Payment Application - an application that uses VCP SDK for payments |
| NFC | Near Field Communication |
| One tap | Flow in a contactless transaction, in which the consumer after authentication (using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data |
| PAN | Primary account number. Know as a card number. |
| Payment Instrument | Model keeping all data considering entity used for payments |
| POS | Point Of Sale |
| SUK | Single Use Key - unique credential used for single transaction for Mastercard |
| LUK | Limited Use Key - payment credential for usage with Visa |
| Two tap | Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates (using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data |
| TVC | Token Verification Code |
| EWS | External Wallet Server |
| VCP | Verestro Cloud Payment |
### **What is VCP SDK?**
The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.
### **How VCP SDK works?**
Provides methods to manage digitization using main domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
*Depending on the selected payment instrument source (Card, Iban, External Wallet Server) VCP SDK allows to digitize it and provide methods for the payment process. Usage of the following domains depends on client requirements.*
### **Versioning and backward compatibility**
SDK version contains three digits. For example: `1.0.0`.
| **Version digit** | **Description** | **Update requirement** |
| :--- | :--- | :--- |
| **First** | Tracks compatibility-breaking changes in SDK public APIs. | 🔴 **Mandatory** to update the application code to use SDK when this is incremented. |
| **Second** | Tracks new, not compatibility-breaking changes in public API of SDK. | 🟡 **Optional** to update the application code when this digit is incremented. |
| **Third** | Tracks internal changes in SDK. | 🟢 **No updates** in application code are necessary to update to the version, which has this number incremented. |
Changes not breaking compatibility:
* Adding a new optional interface to SDK setup
* Adding a new method to any domain
* Adding a new ENUM value to input or output
* Adding a new field in the input or output model
Technical overview
### **SDK Basic configuration**
The `minSdkVersion` must be at least 23 (Android 6.0). The application must use AndroidX.
SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system. **The username and password are provided by Verestro.**
```gradle
repositories{
maven {
credentials {
username ""
password ""
}
url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
//if the sync time takes too long, add filters to match the repository with specific modules as below
content {
includeGroupByRegex "pl.upaid.*"
includeGroup "com.mastercard"
includeGroup "com.visa" //Only when Visa is used
}
}
}
```
VCP SDK is available in two versions: **debug** and **release**.
Debug version is ended with appendix "-debug" in version name. Samples below:
**For release version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**For debug version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}-debug'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}-debug'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**Min SDK version:**
The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.
```gradle
```
SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it.
### **VCP SDK Application Signing requirements**
Mastercard:
There is no requirement related to Application signing.
Visa:
Both sandbox (test) and production environment require APK signed with valid key. To add Application as Trusted in Visa services please provide Signing Key Certificate from chain in PEM format using below script:
```bash
keytool -exportcert -keystore your_apk_keystore.jks -alias your_keystore_key_alias -rfc -file certificate.pem
```
Output will be provided in certificate.pem file.
Please provide an result to Verestro representative with related applicationId (package).
Note: When using only Google Play signing key tests local tests related to Visa tokenization and payments will be not possible.
### **VCP SDK Size**
The size of SDK is dependent on its distribution system.
The table below shows the size of the module for the ask and bundle file.
| **Format** | **Size increment** | **Notes** |
| :--- | :--- | :--- |
| APK all architectures | ~13,6 MB | Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
| APK Arm64 | ~2.8 MB | Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
**VCP size already includes Mobile DC SDK size.**
Additional information:
- size from the table above is referred to release version;
- size depends on configured proguard;
### **VCP SDK Usage**
This chapter describes the structure and basic usage of VCP SDK.
#### ▹ **Domains**
#### **— Domains**
#### **· Domains**
#### **› Domains**
#### **▸ Domains**
#### ▸ Domains
#### **Domains**
Every of the described facades is divided into domains with different responsibilities. Available domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
* [x] **Every domain contains domain-related methods**
#### **Error handling**
Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods.
SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message.
Note: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.
| **Exception type** | **Exception class** | **Description** |
| :--- | :--- | :--- |
| SDK validation | ValidationException | Additional reason codes for ValidationException used in Mobile DC SDK |
| Backend exception | BackendException | Additional reason codes for BackendException used in Mobile DC SDK.
**Note:** Not applicable for[ External Wallet Server domain ](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain) |
| SDK exception | UcpSdkException | Something went wrong on the SDK side, check the table below with possible reasons |
| Process related | - | As every process is different some methods could throw a specified exception
Types of possible exceptions are described in the method description |
Additional BackendException reason codes:
| **Reason** | **Description** |
| :--- | :--- |
| INTERNAL\_ERROR | Error occurred on server |
| VALIDATION\_ERROR | Client sent invalid data |
| CRYPTOGRAPHY\_ERROR | Error occurred during cryptography operation |
| PAYMENT\_CARD\_PREDIGITIZE\_ERROR | Predigitize of payment card failed |
| PAYMENT\_IBAN\_PREDIGITIZE\_ERROR | Predigitize of payment IBAN failed |
| PAYMENT\_CARD\_DIGITIZE\_ERROR | Digitize of payment card failed |
| PAYMENT\_IBAN\_DIGITIZE\_ERROR | Digitize of payment IBAN failed |
| PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED | Predigitize for payment card must be executed |
| PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED | Predigitize for payment IBAN must be executed |
| CLIENT\_UNAUTHORIZED | Client of the API is unauthorized |
| USER\_UNAUTHORIZED | User is unauthorized |
| CANT\_FIND\_USER | Cannot find user |
| CANT\_FIND\_DEVICE | Cannot find device |
| CANT\_FIND\_IBAN | Cannot find payment IBAN |
| CANT\_FIND\_CARD | Cannot find payment card |
| CANT\_FIND\_PAYMENT\_TOKEN | Cannot find payment token |
| OPERATION\_NOT\_SUPPORTED | Requested operation is not supported |
| OPERATION\_NOT\_ALLOWED | Requested operation is not allowed |
| DEVICE\_TEMPORARILY\_LOCKED | Device is temporarily locked |
| DEVICE\_PERMANENTLY\_LOCKED | Device is permanently locked |
| INVALID\_PAN | The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly |
| MISSING\_EXPIRY\_DATE | The expiry date is required for this product but was missing |
| PAN\_INELIGIBLE | The PAN is not in an approved account range for TSP |
| DEVICE\_INELIGIBLE | The device is not supported for use |
| PAN\_INELIGIBLE\_FOR\_DEVICE | The PAN is not allowed to be provisioned to the device because of Issuer rules |
| IBAN\_INELIGIBLE | The financial account does not have an associated account range in TSP |
| PARALLEL\_REQUESTS\_ATTEMPTS | Action is already processing. Please try again after the time included in headers |
| INVALID\_JWS\_TOKEN | Specified JWS token is invalid |
Additional ValidationException reason codes:
| **Reason** | **Description** |
| :--- | :--- |
| INVALID\_SECURITY\_CODE | Security code is empty |
| INVALID\_LANGUAGE\_CODE | Language code is empty |
| INVALID\_PAYMENT\_INSTRUMENT\_ID | Payment instrument id is empty |
UcpSdkException reason codes:
| **Reason** | **Description** |
| :--- | :--- |
| PUSH\_INVALID\_SOURCE | Relates to push processing process. Push message should be consumed in another module |
| PUSH\_INVALID\_PUSH\_CONTENT | Cannot process push message. The message is invalid or some process failed |
| PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND | Cannot find default PaymentInstrument |
| PAYMENT\_INSTRUMENT\_NOT\_FOUND | Selected PaymentInstrument cannot be found, is not digitized or active |
| APPLICATION\_PROCESS\_NOT\_KILLED | Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process |
#### **Facade**
The facade is an entry point to communication with VCP SDK.
Contains SDK initialization method and domains which allows for payment instrument management.
#### **Method structure**
Please read Mobile DC Documentation for details.
#### **Multiple facade types**
VCP SDK provides three public APIs with the same functionalities, the APIs are:
- UcpJavaApi for projects which use Java programming language.
- UcpKotlinApi for projects which use Kotlin programming language.
The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same.
This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark).
#### **HceApduService registration**
To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service.
Properly configured meta-data in service will also register an application as tap&pay ready.
Exemplary service below:
```xml
```
Below listing of the default source file hce\_apud\_service.xml:
```xml
```
Check if the application is set as default for payment.
```kotlin
fun isSystemDefault(): Boolean {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
return cardEmulation.isDefaultServiceForCategory(
WalletHceService::class.java,
CardEmulation.CATEGORY_PAYMENT
)
}
```
Request for set your application as default for payment - will show a dialog for the user to approve the changes.
```kotlin
fun requestForSystemDefault() {
val intent = Intent().apply {
action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
putExtra("component", WalletHceService::class.java)
putExtra("category", CardEmulation.CATEGORY_PAYMENT)
}
context.startActivity(intent)
}
```
If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.
```kotlin
fun registerAsOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.setPreferredService(
activity, ComponentName(activity, WalletHceService::class.java)
)
}
fun unregisterFromOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.unsetPreferredService(activity)
}
```
#### **Models**
##### **PaymentInstrument**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| id | String | Id of payment instrument. For card it is cardId, for IBAN sha256Hex.
In the context of the External Wallet Server use tokenUniqueReference from MDES |
| paymentTokenId | String | Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id |
| displayablePanDigits | String | Token last 4 digits which can be used to display |
| paymentInstrumentStatus | PaymentInstrumentStatus | Enum with status of payment instrument. |
| contactlessSupported | Boolean | Information if payment instrument supports contactless transactions. |
| dsrpSupported | Boolean | Information if the payment instrument supports DSRP transactions. |
| qrcSupported | Boolean | Information if the payment instrument supports QR transactions. |
| onDeviceCvmSupported | Boolean | Information about supporting CVM on device. |
| credentialsCount | Int | Amount of credentials that can be used for payments.
Always 0 for Visa Cards. |
| isDefaultForContactlessPayment | Boolean | Information if payment instrument is default for contactless payments. |
| isDefaultForRemotePayment | Boolean | Information if payment instrument is default for remote payments. |
| additionalAuthenticationRequired | Boolean | Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods |
| tokenLastFourDigits | String? | Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentExpirationDate | String? | Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentLastFourDigits | String? | Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| productConfig | ProductConfig? | Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| provisioningStatus | String | Current state of provisioning process. One of:
IN\_PROGRESS - in case of waiting for *onProvisioningSuccess*(),
SUCCESS - when token is provisioned. |
| paymentTokenExpirationDate | String? | Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled. |
##### **PaymentInstrumentStatus**
| **Field** | **Description** |
| :--- | :--- |
| INACTIVE | Payment instrument is not active, it can not be used for transactions.
The activation process depends on integration. Read the product overview for more information. |
| ACTIVE | Payment instrument is active and it can be used for transactions. |
| SUSPENDED | Payment instrument is suspended. |
| DELETED | Payment instrument is DELETED. |
| UNKNOWN | Payment instrument status is unknown. |
##### **AdditionalAuthenticationMethod**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| id | String | Identifier of additional authentication method |
| name | String | Method name. One of:
OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER |
| value | String | Value depends on method name. Described below. |
| issuerParameters | AuthMethodsIssuerParameters? | Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION |
##### **Additional authentication method values:**
| **Method** | **Value** | **Description** |
| :--- | :--- | :--- |
| `OTP_TO_CARDHOLDER_NUMBER` | Masked phone number | Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number. |
| `OTP_TO_CARDHOLDER_EMAIL` | Masked email | Email to Account holder’s email address. The value will be the Account holder’s masked email address. |
| `CARDHOLDER_TO_CALL_CUSTOMER_SERVICE` | Phone number | Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service. |
| `CARDHOLDER_TO_VISIT_WEBSITE` | Website URL | Account holder to visit a website. The value will be the website URL. |
| `CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION` | Application name | (Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS. |
| `ISSUER_TO_CALL_CARDHOLDER_NUMBER` | Masked phone number | Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number. |
##### **AuthMethodsIssuerParameters contains the following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| mdes | AuthMethodsIssuerParametersMdes? | Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token |
| vts | AuthMethodsIssuerParametersVts? | Required for VTS Payment token |
##### **AuthMethodsIssuerParametersMdes contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| android | AuthMethodsIssuerParametersMdesAndroid | Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device |
| ios | AuthMethodsIssuerParametersMdesIos | Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device |
##### **AuthMethodsIssuerParametersMdesAndroid contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| action | String? | Name of the action to be performed |
| packageName | String? | The package name of the issuer's mobile app |
| extraTextValue | String? | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app |
##### **AuthMethodsIssuerParametersMdesIos contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deepLinkingUrl | String? | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. |
| extraTextValue | String? | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. |
##### **AuthMethodsIssuerParametersVts contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| android | AuthMethodsIssuerParametersVtsAndroid? | Plain AuthMethodsIssuerParametersVtsAndroid object.
Required for Android devices |
| ios | AuthMethodsIssuerParametersVtsIos? | Plain AuthMethodsIssuerParametersVtsIos object.
Required for IOS devices |
##### **AuthMethodsIssuerParametersVtsAndroid contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **AuthMethodsIssuerParametersVtsIos contains following fields:**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| appId | String? | Unique identifier for the application within the application store. |
| appUrl | String? | URL of the application in the application store. |
| intentUrl | String? | URL of banking app designed to respond to authentication code handling. |
| requestPayload | String? | The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **ContactlessTransactionInformation**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| currencyCode | ByteArray | Code of currency, that was used in transaction. Formatted in ISO 4271. |
| amount | ByteArray | Transaction amount in bytes. Can be formatted as Int in pennies. |
| transactionRange | ContactlessTransactionRange | Type of transaction range. |
| richTransactionType | ContactlessRichTransactionType | Rich transaction type. |
| merchantAndLocation | ByteArray | Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset. |
**ContactlessTransactionRange**
| **Value** | **Description** |
| :--- | :--- |
| LVT | Low value transaction |
| HVT | High value transaction |
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| **Value** |
| :--- |
| PURCHASE |
| REFUND |
| CASH |
| TRANSIT |
| PURCHASE\_WITH\_CASHBACK |
| UNKNOWN |
##### **DsrpTransactionInfo**
| **Parameter** | **Type** | **Descruption** |
| :--- | :--- | :--- |
| amount | Long | Transaction amount |
| currencyCode | Int | Code of currency, that was used in transaction. |
| countryCode | Int | Code of country. |
| issuerCryptogramType | String | Cryptogram type. |
##### **TransactionAbortReason**
| **Value** | **Description** |
| :--- | :--- |
| WALLET\_CANCEL\_REQUEST | Indicates that the wallet has requested a transaction cancellation during payment. |
| CARD\_ERROR | This indicates that a problem has been detected in the MChipEngine processing.
In some implementations, this can indicate badly formatted card profile data. |
| TERMINAL\_ERROR | This indicates incorrect terminal behavior. |
| NO\_TRANSACTION\_CREDENTIALS | There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility. |
| NO\_CARDS | There is no active PaymentInstrument to start payment. Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). |
| TERMINAL\_INACTIVITY\_TIMEOUT | There is a problem with communication between the terminal and payment device.
For example, the terminal could abort communication with the mobile device for
a long period of time and then trigger a timeout.
Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal.
The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment.
**Note:** When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again.
**Note:** Deprecated in 2.6.7, no longer used due to time difference between connection lost and providing result to application. Replaced by CONNECTION\_LOST which works immediatelly. |
| CONNECTION\_LOST | Connection between terminal and device is lost and payment is terminated. |
| PAYMENT\_NOT\_ALLOWED | Payment is not allowed at this moment.
For Mastercard Card application should show error and user should retry payment.
For Visa Card application should wait for UcpVtsPaymentAllowedListener::onPaymentAllowed() |
##### **NewTransaction**
| **Field** | **Type** | **Description** |
| :--- | :--- | :--- |
| clientTransactionId | String? | Identifier of transaction in TSP |
| type | String | The transaction type. One of: \[UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER\] |
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example,
`EUR 2.35' will return 235, and `BHD -1.345' will return -1345 |
| currency | String | 3-digit ISO 4217 currency code |
| timestamp | String | The date/time when the transaction occurred. In ISO 8601 extended format |
| merchantName | String? | The merchant (``doing business as'') name |
| merchantPostalCode | String? | The postal code of the merchant |
| transactionCountryCode | String? | The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1 |
| comboCardAccountType | String? | An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: \[UNKNOWN, CREDIT, DEBIT\] |
| issuerResponseInformation | String? | Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: \[UNKNOWN, INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION\] |
| status | String | The authorization status of the transaction. One of: \[AUTHORIZED, DECLINED, CLEARED, REVERSED\] |
| paymentTokenId | String | Identifier of payment token in VCP |
##### **ContactlessTransactionData**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| currencyNumber | Int | Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. |
| currencyCode | String? | Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN
Could be null as the terminal provides only the currencyNumber and a valid code could be not found. |
| amountMinor | Long | The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, |
| transactionRange | ContactlessTransactionRange | Type of transaction range. |
| richTransactionType | ContactlessRichTransactionType | Rich transaction type. |
| merchantAndLocation | String | Merchant and location data from terminal.
**Deprecated** - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data. |
**ContactlessTransactionRange**
| **Value** | **Description** |
| :--- | :--- |
| LVT | Low value transaction |
| HVT | High value transaction |
| UNKNOWN | Unknown |
**ContactlessRichTransactionType**
| **Value** | **Description** |
| :--- | :--- |
| PURCHASE | |
| REFUND | |
| CASH | |
| TRANSIT | |
| PURCHASE\_WITH\_CASHBACK | |
| UNKNOWN | |
| WITHDRAWAL | |
| ATM\_CONTACTLESS | |
##### **Report**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| name | String | Action name |
| description | String | Action details message. |
| isSuccess | Boolean | Result of action. True when action is finished successfully, false otherwise. |
| timestamp | Long | Time when the action occurred. |
| errorMessage | String? | Detailed error message when isSuccess is false. |
##### **ContactlessAdvice**
| **Parameter** | **Description** |
| :--- | :--- |
| DECLINE | Declines a processing transaction.
When provided by SDK in *getFinalDecisionForTransaction* wallet should not overrule a DECLINE.
If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response. |
| AUTHENTICATION\_REQUIRED | An user authentication is required for transaction processing, which could be overruled on the MPA side.
When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the *onAuthRequiredForContactless* method. |
| PROCEED | Transaction can be processed. |
##### **ContactlessTransactionResult**
Important! MPA should always refer to transaction results on the terminal.
| **Value** | **Description** | **Is success on MPA side** |
| :--- | :--- | :--- |
| AUTHORIZE\_ONLINE | This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization.
The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal.
Should be treated as transaction success on the MPA side. | Yes |
| AUTHENTICATE\_OFFLINE | This indicates that the POS requested a decline (AAC) with a CDA signature.
SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature.
Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization.
Should be treated as transaction success on the MPA side. | Yes |
| DECLINE\_BY\_TERMINAL | The POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request.
Paying on the terminal with offline-only network connectivity can also return this callback.
Application Cryptogram was generated with genuine credentials.
Should be treated as transaction success on the MPA side. | Yes |
| DECLINE\_BY\_CARD | The digitized card has declined the transaction. A non-exhaustive list of possible reasons may be:
- Context mismatch between first and second tap
- Terminal is offline-only
- Terminal is a transit gate, and transit transactions are not allowed by the card profile
- Transaction is international, while the card profile is domestic-only | No |
| WALLET\_ACTION\_REQUIRED | If the *getFinalDecisionForTransaction* returns an AUTHENTICATION\_REQUIRED status then this result will be returned.
The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap.
If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place. | No |
#### **External libraries**
The SDK uses several external Apache 2.0 libraries:
- com.nimbusds:nimbus-jose-jwt
- commons-codec:commons-codec
- com.fasterxml.jackson.core:jackson-core
- com.fasterxml.jackson.core:jackson-annotations
- com.fasterxml.jackson.core:jackson-databind
- com.fasterxml.jackson.module:jackson-module-kotlin
- io.insert-koin:koin-android
- io.reactivex.rxjava2:rxjava
- io.reactivex.rxjava2:rxandroid
- com.squareup.retrofit2:adapter-rxjava2
- com.squareup.retrofit2:retrofit
- com.squareup.retrofit2:converter
- com.squareup.okhttp3:logging
- com.squareup.okhttp3:okhttp
VCP SDK Setup
VCP SDK has to be configured every time when is used. Before VCP SDK usage Mobile DC SDK should be already configured.
### **setup**
| Synchronous. Offline.
:--- |
Note: Contains all the necessary data to configure SDK.
Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method.
Requires MobileDC setup() already finished
Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished.
When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand.
Important! Before calling VCP SDK setup you must call setup from Mobile DC SDK.
Note: Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment and loading first aplication screen.
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| ucpConfiguration | UcpConfiguration | VCP configuration provided in builder described below. | Not empty. |
**UcpConfigurationBuilder** contains the following methods:
| **Metod** | **Parameter** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| withApplication | Application | Application context. | Not empty |
| withCvmModel | WalletCvmModel (enum) | Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE | Not empty |
| withUserAuthMode | WalletAuthMode (enum) | User authentication mode: WALLET\_PIN, CUSTOM, NONE
Contact Verestro to select proper configuration | Not empty |
| withUcpPaymentInstrument
EventListener | UcpPaymentInstrument
EventListener | Global listener for actions on PaymentInstrument. | Not empty |
| withUcpTransaction
EventListener | UcpTransactionEventListener | Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing | Not empty |
| withTransactionAcceptance
EventListener | UcpTransactionAcceptance
EventListener | Global listener which allow application take final decision about transaction acceptance during transaction | Not empty |
| withReplenishThreshold | Int | Number of credentials below which replenish process will automatically begin | Not empty |
| withMcbpPinningCertificates | List | List of public key certificates in PEM format.
Pass list with empty String if *withOptionalUcpMcbpHttpExecutor* mentioned below is used with custom HTTP communication. | Not empty List |
| withOptionalEventsReports | UcpEventReportListener | Global listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. | Optional |
| withOptional
ExternalWalletServer | | Prepares SDK for using external wallet server. | Optional |
| withOptional
UcpMcbpHttpExecutor | UcpMcbpHttpExecutor/
DefaultUcpMcbpHttpExecutor | Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. | Optional |
| withOptional
UcpReProvisionEventListener | UcpReProvisionEventListener | Global listener for actions during reprovisioning. | Optional |
| withOptional
UcpTransactionConfiguration | UcpTransactionConfiguration | Transaction configuration. Allow to enable deprecated authentication timer called when authentication is peformed.
Timer is disabled by default, usage is not recomended. | Optional |
| withOptionalWallet
McbpHttpExecutor | | Prepares SDK for processing CMS-D HTTP requests with Wallet Server proxy. | Optional |
| withOptionalEnableVisaSDK | | Enables Visa SDK usage, requires gradle dependencies configuration | Optional |
| withOptionalVtsPayment
ReadyCallback | UcpVtsPaymentAllowedListener | Provides information if payment with Visa Token is allowed with callback onPaymentAllowed().
Application should wait for callback when Visa Card is used. | Optional |
**UcpPaymentInstrumentEventListener**
Contains callbacks for PaymentInstrument.
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onProvisioning
Success | paymentInstrument: PaymentInstrument | Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below |
| onProvisioning
Failure | errorMessage: String?,
exception: Exception? | Method called after provisioning failure. Try processing digitization again |
| onReplenish
Success | paymentInstrument: PaymentInstrument
numberOfTransactionCredentials: Int | Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials.
Depending on flow is called after activation process and when requested by SDK based on *replenishThreshold* configuration.
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
| onReplenish
Failure | paymentInstrument: PaymentInstrument,
errorMessage: String?,
exception: Exception? | Method called after replenish failure with PaymentInstrument
**Note:** Replenish could be called just after transaction based on *withRplenishThreshold* configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
| onPayment
Instrument
StatusChanged | newStatus: PaymentInstrument
Status
paymentInstrumentId: String | Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id |
| onNewTransaction | newTransaction: NewTransaction | Provides online result with details of transaction processed in VCP
Works only when application is online |
**UcpTransactionEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onAuthRequired
ForContactless | paymentInstrument: PaymentInstrument, transactionInformation:
ContactlessTransactionInformation
transactionData: ContactlessTransactionData | Called when user authentication is required during contactless transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
| onAuthRequired
ForDsrp | paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo | Called when user authentication is required during Dsrp transaction |
| onAuthTimer
Updated | secondsRemaining: Int | Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration.
Note: Deprecated and disabled by default in version 2.6.7.
To enable use configuration avaialble in SDK *setup::withOptionalUcpTransactionConfiguration.* |
| onContactless
PaymentStarted | \- | Called on very beginnging of every transaction start (SELECT\_PPSE APDU command). E.g. first tap to terminal or second tap if *onAuthRequiredForContactless* method was called.
Locks communication until method is finished.
Method duration directly impacts on transaction time. |
| onContactless
Payment
Completed | paymentInstrument: PaymentInstrument
transactionInformation:
ContactlessTransactionInformation
transactionResult: ContactlessTransactionResult
transactionData : ContactlessTransactionData,
transactionId:String | Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
transactionId - transaction identifier for Mastercard transactions, allow to match transaction with processed transaction notification from Mobile DC SDK: *EventNewTransaction::clientTransactionId.* |
| onContactless
Payment
Incident | paymentInstrument: PaymentInstrument,
exception: Exception | Called when something went wrong during transaction and Mastercard marked transaction as incident |
| onContactless
Payment
Aborted | paymentInstrument: PaymentInstrument?,
abortReason: TransactionAbortReason,
exception: Exception | Called when transaction is aborted during payment from some reason described in method parameter
PaymentInstrument could be null if abortReason = TransactionAbortReason.NO\_CARDS is returned.
Note: SDK clears passed selected card with method *selectForPayment()* and authentication with *setUserAuthenticatedForPayment()* |
| onTransaction
Stopped | | Method called on transaction stopped by SDK.
Deprecated in version 2.6.7, no longer used. |
**UcpTransactionAcceptanceEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| getFinal
Decision
ForTransaction | isUserAuthenticated : Boolean
recommendedAdvice : ContactlessAdvice
trasactionInformation :
ContactlessTransactionInformation
transactionData : ContactlessTransactionData | Called on every transaction for the final decision about transaction processing
An application can decide based on information about authentication, transaction details like amount, currency, and transaction types
The method also provide recommended by MCBP advice based on transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
**UcpEventReportsListener**
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onNewReport | report: Report | Return logs related to token management. |
**UcpReProvisionEventListener**
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
| **Method Name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| onReProvisionSuccess | paymentInstrument: PaymentInstrument | Method called after reProvisioning process.
Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback. |
| onReProvisionFailure | paymentInstrument : PaymentInstrument
errorMessage : String?
exception : Exception? | Method called after reProvisioning failure. Try again. |
**UcpMcbpHttpExecutor**
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| execute | ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod:
UcpMcbpHttpMethod,
url: String,
requestData:Any,
requestProperties:
Map | Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
``` |
**DefaultUcpMcbpHttpExecutor**
| **Method name** | **Parameters** | **Description** |
| :--- | :--- | :--- |
| execute | ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType
ucpMcbpHttpMethod: UcpMcbpHttpMethod
url: String
requestData: Any
requestProperties: Map | Called on every time if SDK want to connect to MasterCard and should return super.execute method.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
``` |
**UcpTransactionConfiguration**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| enableTransaction
AuthenticationTimer | Boolean | Allows to enable deprecated authentication timer.
Timer is started along *setUserAuthenticatedForPayment(),* result is available in *onAuthTimerUpdated().* |
**Callback samples:**
**UcpTransactionEventListener**
```
// UcpTransactionEventListener comments
class BankingAppUcpTransactionEventListener : UcpTransactionEventListener {
override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and ContactlessTransactionData available in event object
showPaymentScreen(event.paymentInstrument, event.transactionData)
}
override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and DSRP transaction information available in event object
showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo)
}
override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) {
//check if user is on payment screen and update timer
//when timer is 0, application should close payment with failure
//deprcated, disabled by default, read method description how to enable
}
override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) {
//looks like payment is aborted, can provide result to payment screen
//and show user what is abort reason
}
override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) {
//payment completed, provide result to payment information
//REMEMBER Transaction is processed on terminal and this is where
//you will see final transaction result
}
override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) {
//something went wrong during transaction, provide result to user
}
override fun onTransactionStopped() {
//deprecated, not used anymore,
}
override fun onContactlessPaymentStarted() {
//Payment started or resumed after callback onAuthReqiredForContactless
//Best place for checking if user is authenticated for payment and call
//setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected
}
}
```
**UcpPaymentInstrumentEventListener**
```
class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener {
override fun onNewTransaction(event: EventNewTransaction) {
//information about new transaction processed by issuer
}
override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
//status of payment instrument was changed, refresh list, inform user about new status
}
override fun onProvisioningFailure(event: EventProvisioningFailure) {
//provisioning failed, try again
}
override fun onProvisioningSuccess(event: EventProvisioningSuccess) {
//provisioning success, wait for status and replenish changes until user can pay
//or provide activation method when required
}
override fun onReplenishFailure(event: EventReplenishFailure) {
//transaction credentials replenish failed
}
override fun onReplenishSuccess(event: EventReplenishSuccess) {
//transaction credentials replenish success
}
}
```
**UcpTransactionAcceptanceEventListener**
```
class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener {
//Sample implementation of transaction acceptance listener
//For the scanario when authentication is required on issuer side for every transaction
//field even.isUserAuthenticated must be always true, otherwise
//ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned
override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice {
val isScreenUnlocked = isScreenUnlocked()
val isScreenProtectedByKeyguard = isScreenUnlocked()
val isLvtTransaction =
event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT
//discard all Transit transaction
if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) {
return ContactlessAdvice.DECLINE
}
//allow for transaction when user is authenticated for payment and screen unlocked
if (event.isUserAuthenticated && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
//allow for LVT transaction on unlocked screen when protected and don't require authentication
if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
// ...
// much more cases
//require authentication anyway
return ContactlessAdvice.AUTHENTICATION_REQUIRED
}
}
```
**UcpEventReportsListener**
```
class BankReportEventListener : UcpEventReportsListener {
override fun onNewReport(report: Report) {
//may be used for debugging SDK or gathering reports on client's app or backend
}
}
```
**UcpMcbpHttpExecutor**
```
//Use UcpMcbpHTtpExecutor as supertype if you want to replace connection
class BankUcpMcbpHttpExecutor : UcpMcbpHttpExecutor {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
//invoke connect by custom connector
return when (ucpMcbpRequestType) {
UcpMcbpHttpExecutorRequestType.REQUEST_SESSION -> {
executeRequestSession(ucpMcbpHttpMethod, url, requestData as UcpMcbpRequestSessionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.PROVISION -> {
executeProvision(ucpMcbpHttpMethod, url, requestData as UcpMcbpProvisionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.REPLENISH -> {
executeReplenish(ucpMcbpHttpMethod, url, requestData as UcpMcbpReplenishRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.NOTIFY_PROVISIONING_RESULT -> {
executeNotifyProvisioningResult(ucpMcbpHttpMethod, url,
requestData as UcpMcbpNotifyProvisioningResultRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.CHANGE_MOBILE_PIN -> {
executeChangeMobilePin(ucpMcbpHttpMethod, url,
requestData as UcpMcbpChangeMobilePinRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.DELETE -> {
executeDelete(ucpMcbpHttpMethod, url, requestData as UcpMcbpDeleteRequestData,
requestProperties)
}
}
}
}
```
**DefaultUcpMcbpHttpExecutor**
```
//Use DefaultUcpMcbpHTtpExecutor as supertype if you want to only add some action before connection
class BankDefaultUcpMcbpHttpExecutor : DefaultUcpMcbpHttpExecutor() {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
return super.execute(
ucpMcbpRequestType,
ucpMcbpHttpMethod,
url,
requestData,
requestProperties
)
}
}
```
**UcpReProvisionEventListener**
```
class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() {
override fun onReProvisionSuccess(event: EventReProvisionSuccess) {
//reProvisioning success, wait for status and replenish changes until user can pay
}
override fun onReProvisionFailure(event: EventReProvisionFailure) {
//reProvisioning failed, try again.
}
}
```
**UcpTransactionConfiguration**
```
class BankingAppUcpTransactionConfiguration : UcpTransactionConfiguration {
override val enableTransactionAuthenticationTimer: Boolean = false
}
```
**UcpVtsPaymentAllowedListener**
```
class BankingAppUcpVtsPaymentAllowedListener : UcpVtsPaymentAllowedListener {
override fun onPaymentAllowed() {
//when during a payment an status of PAYMENT_NOT_ALLOWED is received
//Application UI should show transaction error and wait for onPaymentAllowed() callback
//When received callback shouuld inform UI to process transaction again
}}
```
**Sample VCP SDK setup implementation**
Mobile DC setup() and VCP setup() method could be called on MainThread in Application:onCreate as blocking or another thread.
When applicaiton has multiple dependencies there is possible to call both setup() methods on another thread (MobileDC setup() method must be already finished until VCP setup() is called).
Important: In case of loading SDK on another thread and using contactless payments HostApduService must be used asynchronous way to prevet using SDK until loading is finished - check sample for method *PaymentService:processHceApduCommand*.
```kotlin
fun setup(
application: Application,
walletCvmModel: WalletCvmModel,
walletAuthUserMode: WalletAuthUserMode,
mcbpPinningCertificates: List,
replenishThreshold: Int
) {
val ucpConfiguration = UcpConfiguration.create(
UcpConfigurationBuilder()
.withApplication(application)
.withCvmModel(walletCvmModel)
.withUserAuthMode(walletAuthUserMode)
//marked as deprecated - see description above
.withUcpTransactionEventListener(BankingAppUcpTransactionEventListener())
.withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener())
.withMcbpPinningCertificates(mcbpPinningCertificates)
.withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener())
.withReplenishThreshold(replenishThreshold)
.withOptionalEventsReports(BankReportEventListener())
.withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor())
//if you want to only add additional action before connection use below implementation
//.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor())
.withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener())
//if you want to change standard transaction configuration use configuration below
.withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration())
//.withOptionalEnableVisaSDK() //optional when Visa is used
//.withOptionalVtsPaymentReadyCallback(BankingAppUcpVtsPaymentAllowedListener()) //optional when Visa is used
)
UcpApiKotlin().setup(ucpConfiguration)
}
```
### **reset (DEPRECATED - use restart instead)**
| Synchronous. Offline.
Method for resetting SDK to uninitialized state.
|
| :--- |
Note: According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. Please kill application process after using this method. Trying using any facade method without stopping application process will cause throwing UcpSdkException.
To avoid closing application use restart() methods.
**Input**
No input.
**Output**
No output.
**Sample**
**Sample VCP SDK reset implementation:**
```kotlin
fun reset() {
UcpApiKotlin().reset()
//Terminating JVM according to MC SDK Sample Application
Runtime.getRuntime().exit(0);
}
```
### **restart**
| Synchronous. Offline.
Method for resetting SDK to uninitialized state.
Replaces reset() method which requires killing application process.
When restart finishes with error, application should repeat action. |
| :--- |
Note: SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again.
**Input**
No input.
**Output**
Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods.
Failure callback when something went wrong during restart. Application should repeat action.
**Sample**
**Sample VCP SDK reset implementation:**
```
UcpApiKotlin().restart({
//restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods
}, {
//some error occured, please repeat action
})
```
Cards domain
### **delete**
| Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
:--- |
Result of action will be notified with onPaymentInstrumentStatusChanged.
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of PaymentInstrument to delete | Not empty. |
| reason | CharArray? | Optional reason of deletion | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.cardsService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
### **checkEligibility**
| Asynchronous. Online.
Check eligibility required to process digitize. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| checkEligibility | CheckEligibility | CheckEligibility object |
CheckEligibility
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] |
| userLanguage | String | User language |
| userCountry | String | User country |
**Output**
| Success callback with CheckEligibilityResult. |
| :--- |
CheckEligibilityResult
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| termsAndConditionsAssetId | String | Identifier of Terms and Conditions asset |
| Failure callback |
| :--- |
**Sample**
```
private fun checkEligibility(
paymentInstrumentId: String,
paymentInstrumentType: PaymentInstrumentType,
userLanguage: String,
userCountry: String
) {
ucpApi.cardsService
.checkEligibility(
CheckEligibility(
paymentInstrumentId,
paymentInstrumentType,
userLanguage,
userCountry
),
{ checkEligibilityResult ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
| Asynchronous. Online.
Use only when *checkEligibility* method is used.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| digitizationRequest | DigitizationRequest | Plain object of DigitizationRequest | Not empty |
DigitizationRequest object contains following fields:
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] | Not empty |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized | |
| externalPaymentTokenId | String? | Optional. Unique external identifier of Payment Token | |
**Output**
Success callback with DigitizationResult object
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| digitizationResult | DigitizationResult | Plain object of DigitizationResult |
DigitizationResult contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Plain object of PaymentInstrument |
| additionalAuthenticationMethods | List? | All available additional authentication method |
| productConfig | ProductConfig | Plain object of ProductConfig, contains Payment Token configuration |
| externalPaymentTokenId | String? | Optional. External payment token id configured by the consumer. In case of identifier duplicate an random id is generated |
ProductConfig contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| isCoBranded | Boolean | Whether the product is co-branded |
| coBrandName | String? | Name of the co-branded partner |
| foregroundColor | String | Foreground color, used to overlay text on top of the card image |
| backgroundColor | String | Background color, used to overlay text on top of the card image |
| labelColor | String? | Label color of the mobile wallet entry for the card |
| issuerName | String | Name of the issuing bank |
| shortDescription | String | A short description for this product |
| longDescription | String? | A long description for this product |
| custoremServiceUrl | String? | Customer service website of the issuing bank |
| customerServiceEmail | String? | Customer service email address of issuing bank |
| customerServicePhoneNumber | String? | Customer service phone number of the issuing bank |
| productConfigIssuer | ProductConfigIssuer? | Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app |
| onlineBankingLoginUrl | String? | Login URL for the issuing bank's online banking website |
| termsAndConditionsUrl | String? | URL linking to the issuing bank's terms and conditions for this product |
| privacyPolicyUrl | String? | URL linking to the issuing bank's privacy policy for this product |
| issuerProductConfigCode | String? | Freeform identifier for this product configuration as assigned by the issuer |
| contactName | String? | Name of the issuing bank |
| bankAppName | String? | Name of banking application for display |
| bankAppAddress | String? | The package name for the destination mobile application |
| unsupportedPresentationTypes | String? | The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request |
| unsupportedCardVerificationTypes | String? | The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) |
| issuerFlags | List? | List of plain ProductConfigIssuerFlags object. Contains issuer flags |
| brandLogoAssetId | String | The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID |
| issuerLogoAssetId | String | The logo of the issuing bank. Provided as a Asset ID |
| coBrandLogoAssetId | String? | The co-brand logo (if any) for this product. Provided as an Asset ID |
| cardBackgroundCombinedAssetId | String? | The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID |
| cardBackgroundAssetId | String? | The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID |
| iconAssetId | String | The icon representing the primary brand(s) associated with this product. Provided as an Asset ID |
ProductConfigIssuer contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| openIssuerAndroidIntent | ProductConfigOpenIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| activateWithIssuerAndroidIntent | ProductConfigActivateWithIssuerAndroidIntent? | AndroidIntent object can be used to open the issuer mobile app |
| openIssuerIOSDeepLinkingUrl | ProductConfigOpenIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| activateWithIssuerIOSDeepLinkingUrl | ProductConfigActivateWithIssuerIOSDeepLinkingUrl? | IOSDeepLinkingUrl object can be used to open the issuer mobile app |
ProductConfigOpenIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerAndroidIntent contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| action | String | The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName | String | The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deepLinkinUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deepLinkingUrl | String | The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue | String | Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigIssuerFlags contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deviceBinding | Boolean | Device binding |
| cardholderVerification | Boolean | Whether the issuer participating in step-up flow |
| trustedBeneficiaryEnrollment | Boolean | Whether this is a trusted beneficiary enrollment |
| delegateAuthenticationSupported | String | Whether issuer supports delegated authentication |
| Failure callback |
| :--- |
Sample
```kotlin
fun digitizeCard(digitizationRequest: DigitizationRequest) {
ucpApi.cardsService
.digitize( digitizationRequest,
{ digitizationResult ->
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize (deprecated)**
| Asynchronous. Online. |
| :--- |
Deprecated - use digitize(DigitizationGreenPath) instead.
| Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty. |
| userLanguage | String | Language preference selected by the consumer. Formatted as an
ISO-639-1 two letter language code | Not empty. |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun digitizeCard(
paymentInstrumentId: String,
languageCode: String,
securityCode: CharArray) {
ucpApi.cardsService
.digitize(paymentInstrumentId, languageCode, securityCode,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
| Asynchronous. Online.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| digitizationGreenPath | DigitizationGreenPath | Plain object of DigitizationGreenPath | Not empty |
DigitizationGreenPath contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| paymentInstrumentType | PaymentInstrumentType | Payment instrument type. One of: \[MASTERCARD,VISA\] |
| securityCode | CharArray? | Optional. The CVC2 for the card to be digitized |
| userLanguage | String | User language |
| userCountry | String | User country |
| externalPaymentTokenId | String? | Optional. Unique external identifier of Payment Token |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```
fun digitizeCard(digitizationGreenPath: DigitizationGreenPath) {
ucpApi.cardsService
.digitize(digitizationGreenPath,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAdditionalAuthenticationMethods**
| Asynchronous. Online.
Retrieves additional user authentication methods. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| getAdditionalAuthenticationMethods | GetAdditionalAuthenticationMethods | Plain object of GetAdditionalAuthenticationMethods | Not empty |
Fields of GetAdditionalAuthenticationMethods object:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
**Output**
| Success callback with AdditionalAuthenticationMethods object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| additionalAuthenticationMethods | AdditionalAuthenticationMethods | Object carrying list of AdditionalAuthenticationMethod |
AdditionalAuthenticationMethods contains following value:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| additionalAuthenticationMethods | List | List of AdditionalAuthenticationMethod objects |
| Failure callback. |
| :--- |
**Sample**
```
private fun getAdditionalAuthenticationMethods() {
val getAdditionalAuthenticationMethod =
GetAdditionalAuthenticationMethods("paymentInstrumentId")
ucpApi
.cardsService
.getAdditionalAuthenticationMethods(
getAdditionalAuthenticationMethod,
{ additionalAuthenticationMethods ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **submitTokenAuthenticationValue**
| Asynchronous. Online.
Submit authentication code when additional user authentication is required. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| authenticationCode | String | Authentication code |
**Output**
| Success callback/failure callback. |
| :--- |
**Sample**
```
private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) {
ucpApi.cardsService
.submitAuthenticationValue(
SubmitAuthenticationValue(
paymentInstrumentId,
authenticationCode
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **submitTokenAuthenticationMethod**
| Asynchronous. Online.
Submit authentication method when additional user authentication is required. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument |
| authenticationMethodId | String | Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. |
**Output**
| Success callback/failure callback. |
| :--- |
**Sample**
```
private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) {
ucpApi.cardsService
.submitAuthenticationMethod(
SubmitAuthenticationMethod(
paymentInstrumentId,
authenticationMethodId
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
| Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to increase UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network and user session required) | |
**Output**
| Success callback with list of PaymentInstrument objects. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstruments | List | List of retrieved payment instruments from local or remote storage |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.cardsService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument (deprecated)**
| Asynchronous. Online/Offline.
Deprecated - use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of instrument to retrieve | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) | |
**Output**
| Success callback with PaymentInstument object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.cardsService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
IBANs domain
### **digitize**
| Asynchronous. Online.
Registers user and device if already not registered in VCP backend. Creates payment token in VCP backend.
Expect push after successfull finish and then proceed using process method in Cloud Messaging domain. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| signedAccountInfo | String | Signed AccountInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
| fcmRegistrationToken | CharArray | FCM Cloud messaging registration token | Not empty. |
| languageCode | String | Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code | Not empty. |
**AccountInfo:**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| userId | String | External user id | Not empty. |
| iban | String | Bank Account Number | Not empty. |
| countryCode | String | The country of the financial account
Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 | Not empty. |
**Output**
| Success callback. Called when device token digitization finished with success .Result contains *IbanDigitizationResult* object.
Note: Cloud token digitization fail doesn't affect on success/failure callback. |
| :--- |
IbanDigitizationResult contains following fields:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| (DEPRECATED) cloudDigitizationSuccess | Boolean | Cloud Token Digitization Details |
| result | CloudDigitizationResult | Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN |
| Failure callback. Called when **device token** digitization finished with failure. |
| :--- |
**Sample**
Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAccountInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("userId", "externalUserId")
.claim("iban", "IN15HIND23467433866365")
.claim("countryCode", "IND")
.build()
val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey)
// ...
}
```
```kotlin
fun digitizeIban(
signedAccountInfo: String,
fcmRegistrationToken: CharArray,
languageCode: String) {
ucpApi.ibansService
.digitize(signedAccountInfo, fcmRegistrationToken, languageCode,
{ ibanDigitizationResult ->
//Device token digitization finished with success
//wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success
val cloudDigitizationResult = ibanDigitizationResult.result
//check status of Cloud Token
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **createTVC**
| Asynchronous. Online.
Provides Transaction Verification Code required to process cloud payments. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* | Not empty. |
**Output**
| Success callback with Tvc object or encrypted Tvc object as String. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| plainTvc | PlainTvc? | Plain PlainTvc object |
| encryptedTvc | CharArray? | Encrypted PlainTvc object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation |
PlainTvc object contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| accountNumber | CharArray | Primary Account Number for the transaction – this is the Token PAN |
| dynamicExpiryDate | CharArray | Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC | CharArray | Dynamic CVC |
| Failure callback when TVC cannot be created. |
| :--- |
**Sample**
Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createTvc(signedIbanInfo: String) {
ucpApi.ibansService
.createTVC(signedIbanInfo, { tvc ->
//result object could contains encrypted TVC
val encryptedTvc: String? = tvc.encryptedTvc
//or decrypted(plain) TVC object with parameters described in documentation
val plainTvc = tvc.plainTvc
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **createPaymentData**
| Asynchronous. Online.
This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| signedIbanInfo | String | Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in *Data signing and encryption* chapter in Mobile DC documentation | Not empty. |
IbanInfo
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| ibanId | String | Iban id returned in *addUserWithIban* methdod or *sha256Hex(iban)* | Not empty. |
| userId | String | External user id given by the client | Not empty. |
**Output**
| Success callback with PaymentData object or encrypted payment data object as String. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| plainPaymentData | PlainPaymentData? | Plain PlainPaymentData object |
| encryptedPaymentData | String? | Encrypted PlainPaymentData object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in *Data signing and encryption* chapter in Mobile DC documentation |
PlainPaymentData object contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| accountNumber | String | Primary Account Number for the transaction – this is the Token PAN |
| applicationExpiryDate | String? | Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format |
| panSequenceNumber | String? | Rrquired only for UCAF. Application PAN sequence number for the Token |
| track2Equivalent | String? | Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed |
| ucafCryptogram | String? | Required only for UCAF. UCAF cryptogram |
| dynamicExpiryDate | String? | Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC | String? | Dynamic CVC |
| Failure callback when PaymentData cannot be created. |
| :--- |
**Sample**
Sample generation of *signedIbanInfo* (see [Data signing and encryption](https://wiki.verestro.com/display/UCP/Data+signing+and+encryption) chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.claim("userId", "123")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createPaymentData(signedIbanInfo: String) {
ucpApi.ibansService
.createPaymentData(signedIbanInfo, { paymentData ->
//result object could contains encrypted PaymentData
val encryptedPaymentData: String? = paymentData.encryptedPaymentData
//or decrypted(plain) PaymentData object with parameters described in documentation
val plainPaymentData = paymentData.plainPaymentData
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getAllPaymentInstruments**
| Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| refresh | Boolean | Refresh all PaymentInstrument objects state with remote VCP server (network required) | |
**Output**
| Success callback with list of PaymentInstrument objects |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstruments | List | List of retrieved payment instruments |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.ibansService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument(deprecated)**
| Asynchronous. Online/Offline.
Use *getAllPaymentInstruments* instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of instrument to retrieve. | Not empty |
| refresh | Boolean | Refresh selected PaymentInstrument state with remote VCP server (network required) | |
**Output**
| Success callback with PaymentInstument object |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Retrieved payment instrument |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.ibansService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **delete**
| Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with *onPaymentInstrumentStatusChanged*. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of PaymentInstrument to delete | Not empty. |
| reason | CharArray? | Optional reason of deletion | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.ibansService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
Payment domain
### **setDefaultForContactless**
| Asynchronous. Offline.
Sets payment instrument as default for contactless payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically after linking with PoS terminal.
Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun setDefaultForContactless(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) {
//make sure selected PaymentInstrument can be seta as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForContactless(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForContactless**
| Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success callback with id new default PaymentInstrument |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Default Payment instrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getDefaultForContactless() {
ucpApi.paymentService
.getDefaultForContactless({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **setDefaultForRemote (deprecated)**
| Asynchronous. Offline.
Sets payment instrument as default for DSRP payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically to remote payments. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun setDefaultForRemote(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
&& !paymentInstrument.dsrpSupported) {
//make sure selected PaymentInstrument can be set as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForRemote(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForRemote (deprecated)**
| Asynchronous. Offline.
Provides default PaymentInstrument for remote payments.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success callback with id new default PaymentInstrument |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Default Payment instrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getDefaultForRemote() {
ucpApi.paymentService
.getDefaultForRemote({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **selectForPayment**
| Asynchronous. Offline.
Sets payment instrument as primary for next incoming payment. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentd | String | Payment instrument identity | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
| **Note:** This is only sample payment scenation |
| :--- |
```
//sample scenario of starting payment with authentication before payment
fun startPayment(paymentInstrument: PaymentInstrument) {
//checking conditions before payment
val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
val isContactlessSupported = paymentInstrument.contactlessSupported
val hasTransactionCredentials = paymentInstrument.credentialsCount > 0
if (!isActive || !isContactlessSupported || !hasTransactionCredentials) {
//PaymentInstrument doesn't meet requirements for payment
return
}
//selecting PaymentInstrument to payment
ucpApi.paymentService
.selectForPayment(paymentInstrument.id, {
//selection success
//request user authentication when
//... authentication presented
//use setUserAuthenticatedForPayment method
}, { throwable ->
//something went wrong, check exception with documentation
})
}
```
### **setUserAuthenticatedForPayment**
| Asynchronous. Offline.
Sets user as authenticated to payment with provided payment instrument.
Authentication clearing depends on authentication timer configuration in *UcpTransactionConfiguration:enableTransactionAuthenticationTimer*.
By default timer is disabled and authentication is cancelled when user perform transaction and SDK send callback *onContactlessPaymentCompleted/Aborted/Incident* from *UcpTransactionEventListener*.
When timer is enabled authentication is cleared when auth timer finishes - it could casue problems when user start to pay just before timer finish. Authentication could be cleared by SDK during payement.
If application call *setUserAuthenticatedForPayment* without contactless payment context and authentication timer is disabled, authentication is never cleared by SDK. To clear authentication use *abortUserAuthenticationForPayment.*
*UcpTransactionEventListener:onContactlessPaymentStarted* is recommended place for payment authentication.
**Note:** User can be authenticated based on conditions like screen unlock. Method must be called before payment in method UcpTransactionEventListener:onContactlessPaymentStarted()
Make sure that authentication on this step is done securely. Transaction information is not available on this step. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
| pin | CharArray? | PIN or null for CUSTOM WalletAuthUserMode | |
**Output**
| Success / failure callback |
| :--- |
**Sample**
Basic user authentication usage below, call when user is authenticated.
```
private fun setUserAuthenticatedForPayment(
paymentInstrument: PaymentInstrument,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser,
{
//user authentication provided
//start one tap payment or continue two tap with 2nd tap to terminal after authentication
//listen for auth timer changes
//user abortUserAuthentication method when transaction cancelled by user
}, { throwable ->
//some error, check exception
})
}
```
Optional authentication before making transaction based on custom conditions.
```
override fun onContactlessPaymentStarted() {
//check internal conditions
//like user performed authentication, is logged in application, is device unlocked etc
val isUserAuthenticated = true
//check if use selected any token for payment and select it in UCP SDK
//otherwise default token will be used
if (getSelectedPaymentInstrumentId() != null) {
ucpApi
.paymentService
.selectForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
success = {
//token will be used for actual payment
//call setUserAuthenticatedForPayment here - sample below in "else" block
},
failure = { throwable ->
//something went wrong, check throwable with documentation
}
)
} else {
if (isUserAuthenticated) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
pin = null, //or pin if MobilePin is used
success =
//user authenticated in SDK
}, failure = {
//authentication failure, check exception
}
)
}
}
}
```
### **abortUserAuthenticationForPayment**
| Asynchronous. Offline.
Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun abortUserAuthenticationForPayment() {
ucpApi
.paymentService
.abortUserAuthenticationForPayment(
{
//user authentication aborted
//listen for auth timer changes
},
{ throwable ->
//some error, check exception
})
}
```
### **processHceApduCommand**
| Synchronous. Offline.
Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS.
Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| context | Context | Application context, can be provided from HostApduService | Not empty |
| apdu | ByteArray | APDU command from HostApduService::processCommandApdu method parameter | Not empty |
| extras | Bundle? | Extras object from HostApduService::processCom mandApdu method parameter | |
**Output**
| Apdu result - method called synchronous without callback |
| :--- |
| **Parameter.** | **Type** | **Description** |
| :--- | :--- | :--- |
| apdu | ByteArray | APDU command to return in implementation of overridden processCommandApdu method |
**Sample (synchronized HostApduService)**
Use this version if MobileDC:setup and UCP:setup() method is called in Application:onCreate on Main Thread.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(this, commandApdu, extras)
}
//..
}
```
**Sample (aynchronous HostApduService)**
Use this version if SDK is called on another thread and HostApduService can receive APDU until VCP SDK is still in loading state.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
//UcpSdkStateApplicationSingleton is sample class which keep SDK state and allow to observe when SDK load is finished
if (UcpSdkStateApplicationSingleton.isLoaded()) {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
} else {
sendResponseApdu(null)
UcpSdkStateApplicationSingleton.listenForSdkReady(
onSdkLoadListener = {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
}
)
}
return null
}
override fun onDeactivated(reason: Int) {
if (UcpSdkStateApplicationSingleton.isLoaded()) {
return ucpApi
.paymentService
.handleHceApduDeactivationEvent(reason)
}
}
private fun processCommandApduInUcpSdk(
context: Context,
commandApdu: ByteArray,
extras: Bundle?
): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(context, commandApdu, extras)
}
}
//sample objec which helps to listen SDK state
object UcpSdkStateApplicationSingleton : UcpSdkState {
//flag could be synchronized
private var isLoaded = false
private var onSdkLoadListener: (() -> Unit)? = null
override fun listenForSdkReady(onSdkLoadListener: () -> Unit) {
this.onSdkLoadListener = onSdkLoadListener
if (isLoaded) this.onSdkLoadListener?.invoke()
}
//call when SDK loading thread is finished
//setupMdc() -> setupUcp() -> UcpSdkStateApplicationSingleton.onUcpSdkLoaded()
override fun onUcpSdkLoaded() {
isLoaded = true
onSdkLoadListener?.invoke()
}
override fun isLoaded(): Boolean {
return isLoaded
}
}
```
### **replenishCredentials**
| Asynchronous. Online. User login session not required.
Method for manually replenishing payment credentials.
Application will receive push notification and notified about replenish process with global callback described in *setup* chapter. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument that needs it credentials replenished | Not empty |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun replenishCredentials(paymentInstrumentId: String) {
ucpApi.paymentService
.replenishCredentials(paymentInstrumentId,
{
//request for credentials replenish finished with success
//wait for push notification and pass to valid module
//when push processed application will be informed about replenish success/failure
//read chapter with setup for more information
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **restartContactlessAuthTimer**
| Asynchronous. Offline.
Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile.
Default auth time is provided by card profile. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success / failure callback |
| :--- |
### **requestAuthenticationCodeForPayment**
| Asynchronous. Online.
Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| requestAuthenticationCodeForPayment | RequestAuthenticationCodeForPayment | Plain RequestAuthenticationCodeForPayment object | Not empty |
RequestAuthenticationCodeForPayment object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| authenticationRequestId | String | Authentication request id up to 64 alphanumeric characters long.
A new id should be used for each instance than an account holder needs to be authenticated | Not empty |
**Output**
| Success callback/failure callback. |
| :--- |
**Sample**
```kotlin
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) {
ucpApi.paymentService
.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//Requesting Authentication Code went successfully.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **validateAuthenticationCodeForPayment**
| Asynchronous. Online.
Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| validateAuthenticationCodeForPayment | ValidateAuthenticationCodeForPayment | Plain ValidateAuthenticationCodeForPayment object | Not empty |
ValidateAuthenticationCodeForPayment object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| authenticationRequestId | String | Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. | Not empty |
| authenticationCode | String | Authentication Code to authenticate the account holder | Not empty |
**Output**
| Success callback with ValidateAuthenticationCodeForPaymentResult object. |
| :--- |
ValidateAuthenticationCodeForPaymentResult object contains following field
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| signedAuthenticationProcessData | String | Signed AuthenticationProcessData per RFC 7519 |
AuthenticationProcessData model
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| authenticationRequestId | String | Authentication request id |
**Sample**
```kotlin
fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) {
ucpApi.paymentService
.validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment,
{ validateAuthenticationCodeForPaymentResult ->
//ValidateAuthenticationCodeForPaymentResult plain object,
//contains data to validate on backend
val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult
.signedAuthenticationProcessData
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAuthenticationProcessData {
fun verifyAndGetAuthenticationRequestID() {
val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600);
val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId")
// ...
}
}
```
### **processDsrpTransaction(deprecated)**
| Asynchronous. Online. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Payment instrument identity | Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | | |
**Output**
| Success callback with cryptogram for payment |
| :--- |
| Failure callback |
| :--- |
### **processDsrpTransaction**
| Asynchronous. Offline.
Method dedicated for starting DSRP transaction.
Every DSRP transaction has to be authenticated before processing.
Depending on implementation payment can be process with OTP authentication or device level authentication. |
| :--- |
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| processDsrpTransaction | ProcessDsrpTransaction | Plain ProcessDsrpTransaction object | Not empty |
ProcessDsrpTranasction object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Identifier of payment instrument | Not empty |
| dsrpTransactionInfo | DsrpTransactionInfo | Plain DsrpTransactionInfo object | Not empty |
DsrpTransactionInfo object contains following fields
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| amountMinor | Long | A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 | Not empty |
| currencyCode | String | A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. | Not empty |
| countryCode | String? | A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. | |
| issuer
Cryptogram
Type | DsrpIssuer
Cryptogram
Type | Enum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. | Not empty |
| unpredictable
Number | Long | A long representing the random number generated by the merchant or by the Payment Gateway. The maximum value is 4,294,967,295. | Not empty |
| transactionType | Dsrp
Transaction
Type | A type of financial transaction, one of: PURCHASE, CASH, PURCHASE\_WITH\_CASHBACK, REFUND | Not empty |
| transactionDate | Date? | A Date object indicating date of transaction. | |
**Output**
| Success callback with ProcessDsrpTransactionResult object. |
| :--- |
ProcessDsrpTransactionResult object contains following field
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| transaction
Cryptogram
Data | ByteArray | A byte array containing a formatted response, either UCAF or a set of TLV data for the merchant to populate DE55 data. |
| pan | String | String containing the PAN of the card used. |
| panSequence
Number | Int | An integer value specifying the PAN Sequence Number (PSN) of the card used. |
| cryptogramType | DsrpIssuer
Cryptogram
Type | Enum value as UCAF or DE55 depending on cryptogram data format is used. |
| track2Data | String | String containing the data elements of track 2 according to ISO/IEC 7813. |
| par | String | String representation of byte array of permanent account reference. A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens. |
| expirationDate | String | Date in ISO-8601 (YYYY-MM-DD) format indicating expiry date of the card. |
| transactionId | String | Hexed byte array containing a Transaction Identifier. |
**Errors**
DsrpPaymentException exception throwed on error in DSRP processing
| **DsrpPaymentException.reason** | **Description** |
| :--- | :--- |
| DSRP\_INVALID\_INPUT | Invalid input data. |
| DSRP\_UNEXPECTED\_DATA | Provided data is valid in context of validation, but doesn't mee |
| DSRP\_AUTHENTICATION\_REQUIRED | Authentication is not provided for DSRP payment. Authenticate and process DSRP transaction again. |
| DSRP\_TOKEN\_INACTIVE | Token used for DSRP is inactive. |
| DSRP\_NO\_TRANSACTION\_CREDENTIALS | There is no transaction credentials to procees DSRP payment |
| DSRP\_NOT\_SUPPORTED\_BY\_CARD | DSRP is not suported by Card. |
| DSRP\_TRANSACTION\_DECLINED | Transaction is declined by Card. |
| DSRP\_INCOMPATIBLE\_PROFILE | Card profile is incomaptible with DSRP. |
| DSRP\_WRONG\_STATE | DSRP transaction is in wrong state. |
| DSRP\_INTERNAL\_ERROR | Unknowne error during DSRP processing. |
**Sample** **DSRP transaction with device level authentication**
```
// After Merchant App delivers DSRP data application should authenticate user with device level authentication
// and next execute setUserAuthenticationForPayment().
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTranasctionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample DSRP transaction with OTP authentication**
```
// After Merchant App delivers DSRP data user should request authentication
// code for payment with selected paymentInstrument.
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment =
RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId)
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) {
ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//When requesting went successfully User will get authentication code.
//In next step authentication code should be passed to MPA and application
//should validate this code with validateAuthenticationCode() method
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
val validateAuthenticationCode: ValidateAuthenticationCode =
ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser)
fun validateAuthenticationCode(validateAuthenticationCode) {
ucpApi.paymentService
.validateAuthenticationCode( validateAuthenticationCode,
{ validateAuthenticationCodeResulty ->
//ValidateAuthenticationCodeResult plain object
val signedAuthenticationProcessData = validateAuthenticationCodeResulty
.signedAuthenticationProcessData
//If validation went successfully MPA should show authentication view,
//and after valid authentication MPA should execute setUserAuthenticatedForPayment()
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTransactionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample input and output DSRP data:**
```Java
Input:
amountMinor: 4321,
countryCode: 840,
currencyCode: 840,
issuerCryptogramType: UCAF,
transactionDate: Apr 25, 2023 09:41:05, //Date() toString() format
transactionType: PURCHASE,
unpredictableNumber: 29496729
Output:
pan: 5204830959972699
track2Data: 5204830959972699D26052010000000000000
expirationDate: 2026-05-31 //YYYY-MM-DD
par: 500170A4PEV2GLWPFD00N6H5AX2YB
panSequenceNumber: 0
transactionId: df25a522a075680acbaa407fdc8a0348a321f77afa2f0231cd38f28e7ae691e2
cryptogramType: UCAF
transactionCryptogramData: 414d506a6d4a474650306149414155427768575a47674144464b553d //in Hex
```
Cloud messaging domain
### **process (deprecated in 2.6.7)**
| Asynchronous. Online. User login session not required.
Processes data sent by VCP backend (push notification data).
Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method.
Method can throw InvalidPushException in case of invalid push content passed to it.
Refer Mobile DC documentation how to handle push.
Deprecated in 2.6.7, use MobileDC:CloudMessaging:process() instead. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| pushData | Map | Data received from notification service in object RemoteMessage object | Not empty |
**Output**
| Success / failure callback. When request fails try again |
| :--- |
**Sample**
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map) {
ucpApi
.cloudMessagingService
.process(pushData, {
//push processed in Mobile DC
}, {
//some error
})
}
```
### **processMcbpNotificationData**
| Asynchronous. Offline.
Processes data sent by MCBP.
Application should check senderId in RemoteMessage object before passing data to VCP SDK.
Basic configuration for push processing from External Wallet Server: [External Wallet Server domain](https://wiki.verestro.com/display/UCP/External+Wallet+Server+domain).
Method can throw InvalidPushException in case of invalid push content passed to it.
**Note:** External Wallet Server Registration process mus be finished before push processing. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| encryptedPayload | String | Data received from notification service in object RemoteMessage object | Not empty |
**Output**
| Success / failure callback |
| :--- |
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String? = remoteMessage.from
val pushData = remoteMessage.data
//check push source based on senderId
if (isVerestroSenderId(senderId)) {
val verestroPayload: String = readVerestrpPushContent(pushData)
ucpApi
.cloudMessagingService
.processMcbpNotificationData(verestroPayload, {
//push processed in VCP
}, {
//some error
})
} else {
//proceed push from another source
}
}
```
External Wallet Server domain
Chapter contains method for SDK when External Wallet Server is used.
Usage of method requires additional configuration with external API.
Basic MDES cloud messaging configuration:
| **Environment** | **FCM Sender Id** |
| :--- | :--- |
| MTF | 502118574555 |
| PRODUCTION | 993764297204 |
### **prepareRegistrationData**
| Asynchronous. Offline.
Method for preparing data used for activation.
Should be used before calling register method. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentAppInstanceId | String | Identifier for the specific Mobile Payment App instance | Not empty |
| paymentAppProviderId | String | Globally unique identifier for the Wallet Provider, as assigned by MDES | Not empty |
| publicKeyCertificate | String | CMS-D public key certificate in pem format | Not empty |
| mobilePin | CharArray? | Mobile PIN used to payment confirmation | |
**Output**
| Success callback with PrepareRegistrationResponse object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| publicKeyCertificateFingerprint | String | CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) |
| encryptedRgk | String | Encrypted randomly-generated 128-bit AES key. |
| deviceInfo | EwsDeviceInfo | Device info. |
| deviceFingerprint | String | Unique device fingerprint. |
| encryptedPin | String? | Encrypted pin (if passed in input). |
EwsDeviceInfo model:
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| deviceName | String | Device model name. |
| formFactor | String | The form factor of the target provisioned device. |
| storageTechnology | String | The architecture or technology used for token storage. |
| osName | String | The name of the operating system of the target provisioned device. |
| osVersion | String | The version of the operating system of the target provisioned device. |
| nfcCapable | Boolean | Whether the target provisioned device has NFC capability. |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun prepareRegistrationData(
paymentAppInstanceId: String,
paymentAppProviderId: String,
publicKeyCertificate: String,
mobilePin: CharArray?) {
ucpApi
.ewsService
.prepareRegistrationData(paymentAppInstanceId,
paymentAppProviderId,
publicKeyCertificate,
mobilePin,
{ prepareRegistrationResponse ->
//Prepared data for registration including encryptedMobilePin if mobilePin is used
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **register**
| Asynchronous. Online.
Method used for registration new Mobile Payment App instance with MDES for use. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| mobileKeysetId | String | Identifies the Mobile Keys used for this remote management session | Not empty |
| ewsMobileKeys | EwsMobileKeys | Contains the mobile keys used to secure the communication during subsequent remote management sessions | Not empty |
| remoteManagementUrl | String | The URL endpoint for subsequent remote management sessions
The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions | Not empty |
EwsMobileKeys
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| transportKey | String | The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES |
| macKey | String | The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES |
| dataEncryptionKey | String | The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun register(
mobileKeysetId: String,
ewsMobileKeys: EwsMobileKeys,
remoteManagementUrl: String) {
ucpApi
.ewsService
.register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl,
{
//Device registration success
//application should listen to push messages and UcpPaymentInstrumentEventListener callbacks
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **activate**
| Asynchronous. Online.
Method to activate PaymentInstrument.
Should be used only on PaymentInstrumens which PaymentInstrumentStatus is SUSPENDED or INACTIVE.
Changes PaymentInstrumentStatus to ACTIVE, calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available.
Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to activate. | Not empty. |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun activate(paymentInstrumentId: String) {
ucpApi
.ewsService
.activate(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to ACTIVE, set card as default for payment if another
//is not already setted Performing replenish,
//application should listen to push message with information about replenish success/failure
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **suspend**
| Asynchronous. Offline.
Method for suspending paymentInstrument.
Changes PaymentInstrumentStatus to SUSPENDED.
Use activate method to allow payments again. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to suspend. | Not empty. |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun suspend(paymentInstrumentId: String) {
ucpApi
.ewsService
.suspend(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to SUSPENDED.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument**
| Asynchronous. Offline.
Method for getting single PaymentInstrument from local storage object based on id. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to get. | Not empty. |
**Output**
| Success callback with PaymentInstrument object. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstrument | PaymentInstrument | Retrieved paymentInstrument |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String) {
ucpApi.ewsService
.getPaymentInstrument(paymentInstrumentId,
{ paymentInstrument ->
//PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
| Asynchronous. Offline.
Method for getting all payment instruments from local storage. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success callback with list of PaymentInstrument objects. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| paymentInstruments | List | List of retrieved payment instruments from local storage |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getAllPaymentInstrument() {
ucpApi.ewsService
.getAllPaymentInstruments(
{ paymentInstruments ->
//List of PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getEncryptedPin**
| Asynchronous. Offline.\|
Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| pin | CharArray | PIN to encrypt. | Not empty. |
**Output**
| Success callback with encrypted mobile PIN. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| encryptedMobilePin | String | Hex encoded encrypted mobile PIN. |
| Failure callback. |
| :--- |
**Sample**
```kotlin
fun getEncryptedPin(pin: CharArray) {
ucpApi
.ewsService
.getEncryptedPin(pin, { encryptedPin ->
//call to Wallet Server with new created encrypted mobile PIN
//when updated call onMobilePinChanged method
}, {
//Something went wrong, check exception with documentation
})
}
```
### **onMobilePinChanged**
| Asynchronous. Online.
Method for informing SDK about mobilePin change.
Should be used when mobilePin changed.
The result of action is deletion of existing transaction credentials and replenish. |
| :--- |
**Input**
| No input parameters |
| :--- |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun reactOnMobilePinChanged() {
ucpApi
.ewsService
.onMobilePinChanged(
{
// Informing SDK about changing mobile pin processed succesfully.
// SDK should delete and next replenish transaction credentials.
// Listen for UcpPaymentInstrumentEventListener events
}, { throwable ->
// Something went wrong, check exception with documentation.
})
}
```
### **delete**
| Asynchronous. Online.
Method to removing PaymentInstrument.
Removed transaction credentials and PaymentInstrument from local storage and in MDES.
When success PaymentInstrument will be no longer available in *getPaymentInstrument* and *getPaymentInstruments* methods. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| paymentInstrumentId | String | Id of paymentInstrument to delete. | Not empty. |
**Output**
| Success / failure callback |
| :--- |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String) {
ucpApi
.ewsService
.delete(paymentInstrumentId,
{
//Selected Payment instrument is removed
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Assets Domain
### **getAsset**
| Asynchronous. Online.
Method for getting all assets for selected assetId. |
| :--- |
**Input**
| **Parameter** | **Type** | **Description** | **Validation conditions** |
| :--- | :--- | :--- | :--- |
| assetId | String | Id of assets to retrive | Not empty |
**Output**
| Success callback with list of Assets objects. |
| :--- |
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| ucpAsset | UcpAsset | Plain UcpAsset object |
UcpAsset object contains following field
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| content | List | Plain list of UcpAssetContent objects |
UcpAssetContent contains following fields.
| **Parameter** | **Type** | **Description** |
| :--- | :--- | :--- |
| data | String | The data for this asset. Base64-encoded data, given in the format as specified in type. |
| type | String | The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. |
| width | Long? | For image assets, the width of this image. Specified in pixels. |
| height | Long? | For image assets, the width of this image. Specified in pixels. |
| Failure callback |
| :--- |
**Sample**
```kotlin
fun getAsset(assetId: String) {
ucpApi.assetsService
.getAssets( assetId,
{ ucpAsset ->
//List of assets of selected assetId
val ucpAssetContentList = ucpAsset.content
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Document changelog
Vesion 2.10.10
- Added new field for digitization: *formFactor*
- Mobile DC updated to 2.17.3
Vesion 2.10.0
- Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes)
- Security tools updated to newest version
- Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22)
- AGP updated to 8.11.1
- Mobile DC updated to 2.17.0
Version 2.9.10
- Added new parameter *transactionId* to method *onContactlessPaymentCompleted* for Mastercard transactions.
New transaction identifier allow to match transaction with processed transaction notification *MobileDC::EventNewTransaction::clientTransactionId.*
- Mobile DC updated to 2.16.12
Version 2.9.8
- **IMPORTANT: Security tools updated to newest version. Recommneded update when using version 2.9.x due to changes fixes in security tools.**
- Visa SDK updated to 6.4.0
- Mobile DC updated to 2.16.10
Version 2.9.5
- Added MC *mtf* host name
- Update Mobile DC to 2.16.5
Version 2.9.4
- **Important:** Apply security and functional certification changes related to intruduction new security tools. Changes in security thread management and working in background
- Update Mobile DC to 2.16.4
Version 2.8.7
- Update Mobile DC to 2.15.8
Version 2.8.6
- Small fixes to 2.8.5
Version 2.8.5
- Update Proguard rules related to R8 changes
Version 2.8.2
- Added new field "externalPaymentTokenId" in DigitizationGreenPath, DigitizationRequest and DigitizationResult models.
- Added new optional configuration withOptionalWalletMcbpHttpExecutor
- Marked configuration withUcpTransactionEventListener from UcpConfigurationBuilder as deprecated. Use MobileDcTransactionEventListener.optionalMobileDcTransactionEventListener from MDC SDK instead.
Version 2.7.4
- Added new field "paymentTokenExpirationDate" in PaymentInstrument model.
Version 2.7.3
- update MobileDC dependency to 2.15.3
Version 2.7.1
- update MobileDC dependency to 2.15.1
Version 2.7.0
- update MobileDC dependency to 2.15.0
Version 2.6.9.2
- update MobileDC dependency to 2.14.7.2
Version 2.6.9.1 - Hotfix possible OutOfMemoryException in MDC 2.14.7
- update MobileDC dependency to 2.14.7.1
Version 2.6.9 - don't use, could cause OOM Exception
- Updated Mobile DC dependency to 2.14.7.
- Updated *processDsrpTransaction* method.
Version 2.6.7
- Updated Mobile DC dependency to 2.14.6
- Added support for Mastercard India datacenter.
- **important** Added new method to UcpTransactionEventListener - *onContactlessPaymentStarted()***.** Callback allows application to get event about new transaction and it's a best place for token selection and user authentication. Read more in Product Overview.
- Due to adding new place for contactless payment authentiocation also updated code samples for *HostApduSevice* implementation and method *setUserAuthenthenticatedForPayment()*
- **Important** CloudMessagingService:process became deprecated due to introducing delivery message from server service. Read more in Product Overview and Mobile DC specification.
- **Important** Added new status *AbortReason:CONNECTION\_LOST* for *UcpTransactionEventListener:onContactlessPaymentAborted.* Status TERMINAL\_INACTIVITY\_TIMEOUT became deprecated. Change significally improves contactless payment UX. Method works immediatelly when connection between device and terminal is lost.
- **Important** Aded new optional configuration for *UcpTransactionConfiguration* with field *enableTransactionAuthenticationTimer.* Timer is now disabled by default, previously was always enabled and could cause problems when authentication time leading to zero and user performs transaction. It could cause clearing user authentication during processing payment on terminal. Change is related to other payments optimizations and introducing *onContactlessPaymentStarted()* and new *AbortReason CONNECTION\_LOST.* Please align your code to new changes, enabling timer is not recommended.
- Updated Mobile DC dependency to 2.13.7
- Resolved Google Play Console Security warning
- Updated Mobile DC dependency to 2.13.6
Version 2.5.5
- Wrap in try-catch block callbacks from SDK *setup()* method to prevent breaking process in SDK. Read more in *setup*() method description.
Version 2.5.3
- Update internal libraries. **IMPORTANT** Read more in Mobile DC changelog for version 2.13.3
Version 2.5.2
- Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality
Version 2.5.1
- Methods marked as deprecated:
- reset (use restart instead)
- getPaymentInstrument (use getAllPaymentInstruments instead)
- setDefaultForRemote (usage is redundant)
- getDefaultForRemote (usage is redundant)
- processDsrpTransaction(use new processDsrpTransaction method with *ProcessDsrpTransaction* added model)
- Added new methods related to OTP authentication code:
- requestAuthenticationCodeForPayment
- validateAuthenticationCodeForPayment
- Added new methods for supporting yellow-path token activation:
- checkEligibility
- digitize (new version with support for checkEligibility usage)
- submitTokenAuthenticationMethod
- submitTokenAuthenticationValue
- getAdditionalAuthenticationMethods
- Fixed getPaymentInstrument method (case invalid error when session expired error occurred).
- Updated Kotlin version to 1.5.31 and Koin to 2.1.6.
- Removed unused permissions *ACCESS\_FINE\_LOCATION* and *com.google.android.c2dm.permission.RECEIVE .*
- Added logs for all facade methods (available in SDK debug version).
Version 2.4.4
- Updated MDC SDK to 2.12.1 - fixed aggressive security process check
- Updated documentation for TransactionAbortReason:TERMINAL\_INACTIVITY\_TIMEOUT model
Version 2.4.3
- IMPORTANT Update security tools after EMV Security Evaluation - refer to Mobile DC technical documentation version changelog (version 2.12.0)
- Update Gradle and R8 tools
- Handled authentication flow for ContactlessRichTransactionType REFUND. SDK requires authentication if not provided.
- Improved description for ContactlesssTransactionResult model in documentation.
- Added new ContactlessRichTransactionType: WITHDRAWAL and ATM\_CONTACTLESS
Version 2.3.24
- Added new state for TransactionAbortReason::TERMINAL\_INACTIVITY\_TIMEOUT. Previously status was part of TransactionAbortReason::TERMINAL\_ERROR and produces contactless payment aborted handling problems. Status is used in onContactlessPaymentAborted callback. Application can ignore this state and do not perform any action.
- Added method on UcpApi for SDK restart(). Unlike reset() new method is asynchronous and allows to usage VCP SDK without application kill. Method clears all VCP SDK data and restarts to initial state.
- Introduced new approach to handling security issue. When application will call any SDK method after security issue reporting, UcpSkdExpcetion with SECURITY\_EVENT\_OCCURRED will be returned. Previously APPLICATION\_PROCESS\_NOT\_KILLED was returned. Change doesn't impact onSecurityIssue callback.
- Added Assets Domain and getAsset() method.
- Added verification of input parameters in token profile and transaction credentials replenish.
- Added more details in callbacks onProvisioningFailure and onReplenishFailure about errors in token related operations.
Version 2.3.22.2 - hotfix
- Added more validation for input parameters for External Wallet Server service
- Added data verification before accessing data in CMS-D processes
- Improved catching exceptions for MCBP processes
- Improved flow for reset() method - added protection agains processing messaging after SDK reset()
- Changed algorithm for calculating publicKeyCertificateFingerprint in PrepareRegistrationDataResponse. From hex(sha1(certificate.publicKey.encoded)) to hex(sha1(certificate.encoded))
- Added support for multiple calling setUserAuthenticatedForPayment() method
Version 2.3.22
- Improved internal SDK logs reporting
- Using androidX in end project is necessary now
- Improved automatic replenish credentials process
- Added handling ReDigititzation process in SDK. Use withOptionalReProvisionEventListener method in SDK setup method to observe PaymentInstrument changes
Version 2.3.21
- Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration
- Replenish process optimization
Version 2.3.18
- Updated security libraries
Version 2.3.17
- Fixed parsing merchantAndLocation field from ContactlessTransactionData.
- Added EWS configuration parameter in setup.
Version 2.3.13
- Added new parameter *result* to IbanDigitizationResult model
- Parameter *cloudDigitizationSuccess* in IbanDigitizationResult is now deprecated
Version 2.3.12
- Core module with update.
- Added new reports to Wallet Server.
Version 2.3.11
- Added new method in Payment Service: processDsrpTransaction
- Added new method in User Service: resendOtp
- Added new paremeter in createPaymentData IbanInfo model: userId
- Improved default PaymentInstrument management
- Fixed clearing SDK state when unpairing device (MobileDC unPair method)
Version 2.3.8
- Improved facade exception throwing, now contains more details about error.
- Removing whitespaces from merchantAndLocation in ContectlessTransactionData model
- Updated security harmful process check mechanism
- Added MCBP cloud messaging queue handling to prevent processing errors
Version 2.3.2
- Fixed SDK provisionning process on Google Pixel devices
- Improved default Payment Instrument management
- Updated security harmful process check mechanism
Version 2.3.1
- Added *delete* method in External Wallet Server domain
- Added more detailed descriptions for methods from External Wallet Server domain
- Added more information about models related to payment processing
Version 2.2.7
- Added reset functionality.
- Addded method in Ibans service createPaymentDat.
- Method createTVC iban service is now deprecated.
- Added global listener for most important internal SDK actions related to token managem
Version 2.2.6
- Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure
- Fixed problem with flow cutting on digitalization process
Version 2.2.4
- Added new enum state TransactionAbortReason.NO\_CARDS. Callback onContactlessPaymentAborted is now called when no card is available for payment.
- Added new model ContactlessTransactionData with better formatting terminal data. New object is added for events EventGetFinalDecision, EventAuthRequiredForContactless, EventContactlessPaymentCompleted.
- ContactlessTransactionInformation is now deprecated.
Version 2.2.3
- Fixed setting default PaymentInstrument after activation
- Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status
Version 2.2.2
- Fixed dependencies conflicts
- Consumer Proguard rules update
- Certificate pinning implementation improvement
Version 2.2.0
- Added new method in EWS Service - getEncryptedPin
- SDK startup optimization
Version 2.1.1
- Fixed dependencies for release version
- Added information about SDK size
- Added information about SDK integration on lower Android API level
Version 2.1.0
- Added new methods in External Wallet Server domain (activate, suspend, getPaymentInstrument, getPaymentInstruments, onMobilePinChanged)
Version 2.0.0
- Changed approach to SDK setup
- Added UcpSdkException
- Added new reason codes to existing exceptions
- New methods in cards domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in ibans domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in cloud messaging domain: processMcbpNotificationData
- New methods in payment domain: abortUserAuthenticationForPayment, replenishCredentials, restartContactlessTimer
- New methods in external wallet server domain: prepareRegistrationData, register
Version 1.0.1
- Created
# draft v2
VCP SDK Introduction
### **Basic abbreviations and definitions**
| Field |
Description |
| CDCVM |
Consumer Device Cardholder Verification Method |
| CVM |
Cardholder Verification Method |
| Contactless |
Transactions performed by tapping the mobile device on a POS, which starts data exchange. On the Android device operating system passes received data from POS to the HCE service, implemented in the MPA, and then to VCP SDK. HCE support is required for contactless transactions |
| DSRP |
Digital Secure Remote Payments - transactions initiated from a mobile device, engaging interaction with the remote merchant system. HCE support is not required for DSRP transactions |
| FCM |
Firebase Cloud Messaging |
| HCE |
Host Card Emulation |
| IBAN |
Bank Account Number |
| MCBP |
Mastercard Cloud Based Payments |
| MDC |
Mobile Data Core. Verestro core library. |
| MPA |
Mobile Payment Application - an application that uses VCP SDK for payments |
| NFC |
Near Field Communication |
| One tap |
Flow in a contactless transaction, in which the consumer after authentication (using the PIN, fingerprint, etc.) taps the device to POS to start exchanging data |
| PAN |
Primary account number. Know as a card number. |
| Payment Instrument |
Model keeping all data considering entity used for payments |
| POS |
Point Of Sale |
| SUK |
Single Use Key - unique credential used for single transaction for Mastercard |
| LUK |
Limited Use Key - payment credential for usage with Visa |
| Two tap |
Flow in a contactless transaction, in which consumer firstly taps device to POS, authenticates (using the PIN, fingerprint, etc.), then taps to POS one more time for exchanging data |
| TVC |
Token Verification Code |
| EWS |
External Wallet Server |
| VCP |
Verestro Cloud Payment |
### **What is VCP SDK?**
The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.
### **How VCP SDK works?**
Provides methods to manage digitization using main domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
*Depending on the selected payment instrument source (Card, Iban, External Wallet Server) VCP SDK allows to digitize it and provide methods for the payment process. Usage of the following domains depends on client requirements.*
### **Versioning and backward compatibility**
SDK version contains three digits. For example: `1.0.0`.
| Version digit |
Description |
Update requirement |
| First |
Tracks compatibility-breaking changes in SDK public APIs. |
🔴 Mandatory to update the application code to use SDK when this is incremented. |
| Second |
Tracks new, not compatibility-breaking changes in public API of SDK. |
🟡 Optional to update the application code when this digit is incremented. |
| Third |
Tracks internal changes in SDK. |
🟢 No updates in application code are necessary to update to the version, which has this number incremented. |
Changes not breaking compatibility:
* Adding a new optional interface to SDK setup
* Adding a new method to any domain
* Adding a new ENUM value to input or output
* Adding a new field in the input or output model
Technical overview
### **SDK Basic configuration**
The `minSdkVersion` must be at least 23 (Android 6.0). The application must use AndroidX.
SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system. **The username and password are provided by Verestro.**
```gradle
repositories{
maven {
credentials {
username ""
password ""
}
url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
//if the sync time takes too long, add filters to match the repository with specific modules as below
content {
includeGroupByRegex "pl.upaid.*"
includeGroup "com.mastercard"
includeGroup "com.visa" //Only when Visa is used
}
}
}
```
VCP SDK is available in two versions: **debug** and **release**.
Debug version is ended with appendix "-debug" in version name. Samples below:
**For release version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**For debug version:**
```gradle
dependencies{
implementation 'pl.upaid.module:ucpsdk:{version}-debug'
//Use below code ONLY if using Visa
//implementation 'pl.upaid.internal.module:vts_v6:{verestroVtsModuleVersion}-debug'
//def strictVtsVersionBeta = "6.4.0-sandbox"
//def strictVtsVersionProduction = "6.4.0-production"
//implementation('com.visa:cbp') {
// version { strictly strictVtsVersionBeta }
//}
}
```
**Min SDK version:**
The minSdkVersion must be at least 23 (Android 6.0). In case of using SDK on lower Android API version declare in the application manifest.
```gradle
```
SDK cannot be initialized on a lower Android API version, and none of the SDK methods should be used on it.
### **VCP SDK Application Signing requirements**
Mastercard:
There is no requirement related to Application signing.
Visa:
Both sandbox (test) and production environment require APK signed with valid key. To add Application as Trusted in Visa services please provide Signing Key Certificate from chain in PEM format using below script:
```bash
keytool -exportcert -keystore your_apk_keystore.jks -alias your_keystore_key_alias -rfc -file certificate.pem
```
Output will be provided in certificate.pem file.
Please provide an result to Verestro representative with related applicationId (package).
Note: When using only Google Play signing key tests local tests related to Visa tokenization and payments will be not possible.
### **VCP SDK Size**
The size of SDK is dependent on its distribution system.
The table below shows the size of the module for the ask and bundle file.
| Format |
Size increment |
Notes |
| APK all architectures |
~13,6 MB |
Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
| APK Arm64 |
~2.8 MB |
Size compared to empty application. Size already include Mobile DC library size as it's required dependency. |
**VCP size already includes Mobile DC SDK size.**
Additional information:
- size from the table above is referred to release version;
- size depends on configured proguard;
### **VCP SDK Usage**
This chapter describes the structure and basic usage of VCP SDK.
#### **· Domains**
Every of the described facades is divided into domains with different responsibilities. Available domains:
* [x] **IBANs**
* [x] **Payment**
* [x] **Cloud Messaging**
* [x] **Cards**
* [x] **External Wallet Server**
* [x] **Every domain contains domain-related methods**
#### **· Error handling**
Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods.
SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message.
Note: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.
| Exception type |
Exception class |
Description |
| SDK validation |
ValidationException |
Additional reason codes for ValidationException used in Mobile DC SDK |
| Backend exception |
BackendException |
Additional reason codes for BackendException used in Mobile DC SDK.
Note: Not applicable for External Wallet Server domain |
| SDK exception |
UcpSdkException |
Something went wrong on the SDK side, check the table below with possible reasons |
| Process related |
- |
As every process is different some methods could throw a specified exception
Types of possible exceptions are described in the method description |
Additional BackendException reason codes:
| Reason |
Description |
| INTERNAL\_ERROR |
Error occurred on server |
| VALIDATION\_ERROR |
Client sent invalid data |
| CRYPTOGRAPHY\_ERROR |
Error occurred during cryptography operation |
| PAYMENT\_CARD\_PREDIGITIZE\_ERROR |
Predigitize of payment card failed |
| PAYMENT\_IBAN\_PREDIGITIZE\_ERROR |
Predigitize of payment IBAN failed |
| PAYMENT\_CARD\_DIGITIZE\_ERROR |
Digitize of payment card failed |
| PAYMENT\_IBAN\_DIGITIZE\_ERROR |
Digitize of payment IBAN failed |
| PAYMENT\_CARD\_PREDIGITIZE\_NOT\_EXECUTED |
Predigitize for payment card must be executed |
| PAYMENT\_IBAN\_PREDIGITIZE\_NOT\_EXECUTED |
Predigitize for payment IBAN must be executed |
| CLIENT\_UNAUTHORIZED |
Client of the API is unauthorized |
| USER\_UNAUTHORIZED |
User is unauthorized |
| CANT\_FIND\_USER |
Cannot find user |
| CANT\_FIND\_DEVICE |
Cannot find device |
| CANT\_FIND\_IBAN |
Cannot find payment IBAN |
| CANT\_FIND\_CARD |
Cannot find payment card |
| CANT\_FIND\_PAYMENT\_TOKEN |
Cannot find payment token |
| OPERATION\_NOT\_SUPPORTED |
Requested operation is not supported |
| OPERATION\_NOT\_ALLOWED |
Requested operation is not allowed |
| DEVICE\_TEMPORARILY\_LOCKED |
Device is temporarily locked |
| DEVICE\_PERMANENTLY\_LOCKED |
Device is permanently locked |
| INVALID\_PAN |
The PAN format is not valid, or other data associated with the PAN was incorrect or entered incorrectly |
| MISSING\_EXPIRY\_DATE |
The expiry date is required for this product but was missing |
| PAN\_INELIGIBLE |
The PAN is not in an approved account range for TSP |
| DEVICE\_INELIGIBLE |
The device is not supported for use |
| PAN\_INELIGIBLE\_FOR\_DEVICE |
The PAN is not allowed to be provisioned to the device because of Issuer rules |
| IBAN\_INELIGIBLE |
The financial account does not have an associated account range in TSP |
| PARALLEL\_REQUESTS\_ATTEMPTS |
Action is already processing. Please try again after the time included in headers |
| INVALID\_JWS\_TOKEN |
Specified JWS token is invalid |
Additional ValidationException reason codes:
| Reason |
Description |
| INVALID\_SECURITY\_CODE |
Security code is empty |
| INVALID\_LANGUAGE\_CODE |
Language code is empty |
| INVALID\_PAYMENT\_INSTRUMENT\_ID |
Payment instrument id is empty |
UcpSdkException reason codes:
| Reason |
Description |
| PUSH\_INVALID\_SOURCE |
Relates to push processing process. Push message should be consumed in another module |
| PUSH\_INVALID\_PUSH\_CONTENT |
Cannot process push message. The message is invalid or some process failed |
| PAYMENT\_INSTRUMENT\_DEFAULT\_NOT\_FOUND |
Cannot find default PaymentInstrument |
| PAYMENT\_INSTRUMENT\_NOT\_FOUND |
Selected PaymentInstrument cannot be found, is not digitized or active |
| APPLICATION\_PROCESS\_NOT\_KILLED |
Occurs when after using the reset method, there is a try of using any of the facade methods without previously stopping the application process |
#### **· Facade**
The facade is an entry point to communication with VCP SDK.
Contains SDK initialization method and domains which allows for payment instrument management.
#### **· Method structure**
Please read Mobile DC Documentation for details.
#### **· Multiple facade types**
VCP SDK provides three public APIs with the same functionalities, the APIs are:
- UcpJavaApi for projects which use Java programming language.
- UcpKotlinApi for projects which use Kotlin programming language.
The difference between the APIs is a way of providing data to SDK methods and getting the results from them. Input and output as information data are the same.
This documentation presents I/O types in a Kotlin way as it’s easier to mark nullable fields (as a question mark).
#### **· HceApduService registration**
To register HceApduService firstly it needs to be created a class that extends a default HostApduService. Added class needs to be added to the manifest file as a service.
Properly configured meta-data in service will also register an application as tap&pay ready.
Exemplary service below:
```xml
```
Below listing of the default source file hce\_apud\_service.xml:
```xml
```
Check if the application is set as default for payment.
```kotlin
fun isSystemDefault(): Boolean {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
return cardEmulation.isDefaultServiceForCategory(
WalletHceService::class.java,
CardEmulation.CATEGORY_PAYMENT
)
}
```
Request for set your application as default for payment - will show a dialog for the user to approve the changes.
```kotlin
fun requestForSystemDefault() {
val intent = Intent().apply {
action = "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT"
putExtra("component", WalletHceService::class.java)
putExtra("category", CardEmulation.CATEGORY_PAYMENT)
}
context.startActivity(intent)
}
```
If the application is not set as default for payment and wants to make payment from opened application needs to set the preferred service. Requires system option "On top application is the default for HCE" enabled.
```kotlin
fun registerAsOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.setPreferredService(
activity, ComponentName(activity, WalletHceService::class.java)
)
}
fun unregisterFromOnTopHceApplication() {
val cardEmulation = CardEmulation.getInstance(NfcAdapter.getDefaultAdapter(context))
cardEmulation.unsetPreferredService(activity)
}
```
#### **· Models**
##### **PaymentInstrument**
| Parameter |
Type |
Description |
| id |
String |
Id of payment instrument. For card it is cardId, for IBAN sha256Hex.
In the context of the External Wallet Server use tokenUniqueReference from MDES |
| paymentTokenId |
String |
Id of payment token. Used for getting transactions history (see Mobile DC documentation) only for selected token id |
| displayablePanDigits |
String |
Token last 4 digits which can be used to display |
| paymentInstrumentStatus |
PaymentInstrumentStatus |
Enum with status of payment instrument. |
| contactlessSupported |
Boolean |
Information if payment instrument supports contactless transactions. |
| dsrpSupported |
Boolean |
Information if the payment instrument supports DSRP transactions. |
| qrcSupported |
Boolean |
Information if the payment instrument supports QR transactions. |
| onDeviceCvmSupported |
Boolean |
Information about supporting CVM on device. |
| credentialsCount |
Int |
Amount of credentials that can be used for payments.
Always 0 for Visa Cards. |
| isDefaultForContactlessPayment |
Boolean |
Information if payment instrument is default for contactless payments. |
| isDefaultForRemotePayment |
Boolean |
Information if payment instrument is default for remote payments. |
| additionalAuthenticationRequired |
Boolean |
Is additional authentication for payment token activation required. If true, available authentication methods can be obtained using getAdditionalAuthenticationMethods |
| tokenLastFourDigits |
String? |
Payment Token last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentExpirationDate |
String? |
Payment instrument expiry date in format MM/YY. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| paymentInstrumentLastFourDigits |
String? |
Payment instrument last four digits. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| productConfig |
ProductConfig? |
Payment Token configuration. Present only when multistep digitization is used(checkEligibility and digitize called separately). |
| provisioningStatus |
String |
Current state of provisioning process. One of:
IN\_PROGRESS - in case of waiting for onProvisioningSuccess(),
SUCCESS - when token is provisioned. |
| paymentTokenExpirationDate |
String? |
Payment token expiry date in format MM/YY. Not present when External Wallet Server is enabled. |
##### **PaymentInstrumentStatus**
| Field |
Description |
| INACTIVE |
Payment instrument is not active, it can not be used for transactions.
The activation process depends on integration. Read the product overview for more information. |
| ACTIVE |
Payment instrument is active and it can be used for transactions. |
| SUSPENDED |
Payment instrument is suspended. |
| DELETED |
Payment instrument is DELETED. |
| UNKNOWN |
Payment instrument status is unknown. |
##### **AdditionalAuthenticationMethod**
| Parameter |
Type |
Description |
| id |
String |
Identifier of additional authentication method |
| name |
String |
Method name. One of:
OTP\_TO\_CARDHOLDER\_NUMBER, OTP\_TO\_CARDHOLDER\_EMAIL, CARDHOLDER\_TO\_CALL\_CUSTOMER\_SERVICE, CARDHOLDER\_TO\_VISIT\_WEBSITE, CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION, ISSUER\_TO\_CALL\_CARDHOLDER\_NUMBER |
| value |
String |
Value depends on method name. Described below. |
| issuerParameters |
AuthMethodsIssuerParameters? |
Non null if method is CARDHOLDER\_TO\_USE\_ISSUER\_MOBILE\_APPLICATION |
##### **Additional authentication method values:**
| Method |
Value |
Description |
OTP_TO_CARDHOLDER_NUMBER |
Masked phone number |
Text message to Account holder’s mobile phone number. The value will be the Account holder’s masked mobile phone number. |
OTP_TO_CARDHOLDER_EMAIL |
Masked email |
Email to Account holder’s email address. The value will be the Account holder’s masked email address. |
CARDHOLDER_TO_CALL_CUSTOMER_SERVICE |
Phone number |
Account holder-initiated call. The value will be the phone number for the Account holder to call Customer Service. |
CARDHOLDER_TO_VISIT_WEBSITE |
Website URL |
Account holder to visit a website. The value will be the website URL. |
CARDHOLDER_TO_USE_ISSUER_MOBILE_APPLICATION |
Application name |
(Conditional) Issuer’s mobile app name. The method is available for both MDES and VTS but the value will be presented only for VTS. |
ISSUER_TO_CALL_CARDHOLDER_NUMBER |
Masked phone number |
Issuer-initiated voice call to Account holder’s phone. The value will be the Account holder’s masked voice call phone number. |
##### **AuthMethodsIssuerParameters contains the following fields:**
| Parameter |
Type |
Description |
| mdes |
AuthMethodsIssuerParametersMdes? |
Plain AuthMethodsIssuerParametersMdes object, required for MDES Payment Token |
| vts |
AuthMethodsIssuerParametersVts? |
Required for VTS Payment token |
##### **AuthMethodsIssuerParametersMdes contains following fields:**
| Parameter |
Type |
Description |
| android |
AuthMethodsIssuerParametersMdesAndroid |
Plain AuthMethodsIssuerParametersMdesAndroid object. Required for Android device |
| ios |
AuthMethodsIssuerParametersMdesIos |
Plain AuthMethodsIssuerParametersMdesIos object. Required for IOS device |
##### **AuthMethodsIssuerParametersMdesAndroid contains following fields:**
| Parameter |
Type |
Description |
| action |
String? |
Name of the action to be performed |
| packageName |
String? |
The package name of the issuer's mobile app |
| extraTextValue |
String? |
Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app |
##### **AuthMethodsIssuerParametersMdesIos contains following fields:**
| Parameter |
Type |
Description |
| deepLinkingUrl |
String? |
The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app. |
| extraTextValue |
String? |
Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object of the MobileAppActivationParameters. This object is not described since the whole payload is passed to the issuer app. |
##### **AuthMethodsIssuerParametersVts contains following fields:**
| Parameter |
Type |
Description |
| android |
AuthMethodsIssuerParametersVtsAndroid? |
Plain AuthMethodsIssuerParametersVtsAndroid object.
Required for Android devices |
| ios |
AuthMethodsIssuerParametersVtsIos? |
Plain AuthMethodsIssuerParametersVtsIos object.
Required for IOS devices |
##### **AuthMethodsIssuerParametersVtsAndroid contains following fields:**
| Parameter |
Type |
Description |
| appId |
String? |
Unique identifier for the application within the application store. |
| appUrl |
String? |
URL of the application in the application store. |
| intentUrl |
String? |
URL of banking app designed to respond to authentication code handling. |
| requestPayload |
String? |
The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **AuthMethodsIssuerParametersVtsIos contains following fields:**
| Parameter |
Type |
Description |
| appId |
String? |
Unique identifier for the application within the application store. |
| appUrl |
String? |
URL of the application in the application store. |
| intentUrl |
String? |
URL of banking app designed to respond to authentication code handling. |
| requestPayload |
String? |
The request payload is to be sent to the banking application on behalf of Visa.
This field is opaque to wallet providers. |
##### **ContactlessTransactionInformation**
| Parameter |
Type |
Description |
| currencyCode |
ByteArray |
Code of currency, that was used in transaction. Formatted in ISO 4271. |
| amount |
ByteArray |
Transaction amount in bytes. Can be formatted as Int in pennies. |
| transactionRange |
ContactlessTransactionRange |
Type of transaction range. |
| richTransactionType |
ContactlessRichTransactionType |
Rich transaction type. |
| merchantAndLocation |
ByteArray |
Merchant and location data from terminal. Can be formatted as String, by using UTF\_8 Charset. |
**ContactlessTransactionRange**
| Value |
Description |
| LVT |
Low value transaction |
| HVT |
High value transaction |
| UNKNOWN |
Unknown |
**ContactlessRichTransactionType**
| Value |
| PURCHASE |
| REFUND |
| CASH |
| TRANSIT |
| PURCHASE\_WITH\_CASHBACK |
| UNKNOWN |
##### **DsrpTransactionInfo**
| Parameter |
Type |
Descruption |
| amount |
Long |
Transaction amount |
| currencyCode |
Int |
Code of currency, that was used in transaction. |
| countryCode |
Int |
Code of country. |
| issuerCryptogramType |
String |
Cryptogram type. |
##### **TransactionAbortReason**
| Value |
Description |
| WALLET\_CANCEL\_REQUEST |
Indicates that the wallet has requested a transaction cancellation during payment. |
| CARD\_ERROR |
This indicates that a problem has been detected in the MChipEngine processing.
In some implementations, this can indicate badly formatted card profile data. |
| TERMINAL\_ERROR |
This indicates incorrect terminal behavior. |
| NO\_TRANSACTION\_CREDENTIALS |
There are no transaction credentials to finalize payment. The application should call replenish Credentials method to enable payment possibility. |
| NO\_CARDS |
There is no active PaymentInstrument to start payment. Called when no card is added to Wallet or SDK is cleared by Security Issue (onSecurityIssueAppeared event). |
| TERMINAL\_INACTIVITY\_TIMEOUT |
There is a problem with communication between the terminal and payment device.
For example, the terminal could abort communication with the mobile device for
a long period of time and then trigger a timeout.
Usually, a mobile device loses connection during payment due to a wrong or too short tap on the terminal.
The application should ignore this status as SDK waits for connection establishment and it could produce getting duplicate callbacks during payment.
Note: When user authentication is already provided it could be cleared - the application should handle card selection (if a non-default card is selected) and payment authentication again.
Note: Deprecated in 2.6.7, no longer used due to time difference between connection lost and providing result to application. Replaced by CONNECTION\_LOST which works immediatelly. |
| CONNECTION\_LOST |
Connection between terminal and device is lost and payment is terminated. |
| PAYMENT\_NOT\_ALLOWED |
Payment is not allowed at this moment.
For Mastercard Card application should show error and user should retry payment.
For Visa Card application should wait for UcpVtsPaymentAllowedListener::onPaymentAllowed() |
##### **NewTransaction**
| Field |
Type |
Description |
| clientTransactionId |
String? |
Identifier of transaction in TSP |
| type |
String |
The transaction type. One of: \[UNKNOWN, PURCHASE, REFUND, PAYMENT, ATM\_WITHDRAWAL, CASH\_DISBURSEMENT, ATM\_DEPOSIT, ATM\_TRANSFER\] |
| amountMinor |
Long |
The monetary amount in terms of the minor units of the currency. For example,
EUR 2.35' will return 235, and BHD -1.345' will return -1345 |
| currency |
String |
3-digit ISO 4217 currency code |
| timestamp |
String |
The date/time when the transaction occurred. In ISO 8601 extended format |
| merchantName |
String? |
The merchant (``doing business as'') name |
| merchantPostalCode |
String? |
The postal code of the merchant |
| transactionCountryCode |
String? |
The country in which the transaction was performed. Expressed as a 3-letter (alpha-3) country code as defined in ISO 3166-1 |
| comboCardAccountType |
String? |
An indicator if Credit or Debit was chosen for a tokenized combo card at the time of the transaction. One of: \[UNKNOWN, CREDIT, DEBIT\] |
| issuerResponseInformation |
String? |
Additional information is provided by the issuer for a declined transaction. Only returned if the transaction is declined. One of: \[UNKNOWN, INVALID\_CARD\_NUMBER, FORMAT\_ERROR, MAX\_AMOUNT\_EXCEEDED, EXPIRED\_CARD, PIN\_AUTHORIZATION\_FAILED, TRANSACTION\_NOT\_PERMITTED, WITHDRAWL\_AMOUNT\_EXCEEDED, RESTRICTED\_CARD, WITHDRAWL\_COUNT\_EXCEEDED, PIN\_TRIES\_NUMBER\_EXCEEDED, INCORRECT\_PIN, DUPLICATE\_TRANSMISSION\] |
| status |
String |
The authorization status of the transaction. One of: \[AUTHORIZED, DECLINED, CLEARED, REVERSED\] |
| paymentTokenId |
String |
Identifier of payment token in VCP |
##### **ContactlessTransactionData**
| Parameter |
Type |
Description |
| currencyNumber |
Int |
Currency number assigned to the currencyCode in ISO 4271 e.g.: for PLN is 985. |
| currencyCode |
String? |
Code of currency, that was used in transaction formatted in ISO 4271. e.g.: PLN
Could be null as the terminal provides only the currencyNumber and a valid code could be not found. |
| amountMinor |
Long |
The monetary amount in terms of the minor units of the currency. For example, `EUR 2.35' will return 235, |
| transactionRange |
ContactlessTransactionRange |
Type of transaction range. |
| richTransactionType |
ContactlessRichTransactionType |
Rich transaction type. |
| merchantAndLocation |
String |
Merchant and location data from terminal.
Deprecated - field shouldn't be used as it could be not configured in terminal configuration or provides invalid data. |
**ContactlessTransactionRange**
| Value |
Description |
| LVT |
Low value transaction |
| HVT |
High value transaction |
| UNKNOWN |
Unknown |
**ContactlessRichTransactionType**
| Value |
Description |
| PURCHASE |
|
| REFUND |
|
| CASH |
|
| TRANSIT |
|
| PURCHASE\_WITH\_CASHBACK |
|
| UNKNOWN |
|
| WITHDRAWAL |
|
| ATM\_CONTACTLESS |
|
##### **Report**
| Parameter |
Type |
Description |
| name |
String |
Action name |
| description |
String |
Action details message. |
| isSuccess |
Boolean |
Result of action. True when action is finished successfully, false otherwise. |
| timestamp |
Long |
Time when the action occurred. |
| errorMessage |
String? |
Detailed error message when isSuccess is false. |
##### **ContactlessAdvice**
| Parameter |
Description |
| DECLINE |
Declines a processing transaction.
When provided by SDK in getFinalDecisionForTransaction wallet should not overrule a DECLINE.
If the MPA overrules a DECLINE (and forces it into PROCEED), the transaction is likely to be declined by the issuer in the authorization response. |
| AUTHENTICATION\_REQUIRED |
An user authentication is required for transaction processing, which could be overruled on the MPA side.
When the MPA decision is AUTHENTICATION\_REQUIRED, SDK will ask for user authentication in the onAuthRequiredForContactless method. |
| PROCEED |
Transaction can be processed. |
##### **ContactlessTransactionResult**
Important! MPA should always refer to transaction results on the terminal.
| Value |
Description |
Is success on MPA side |
| AUTHORIZE\_ONLINE |
This indicates that the SDK returned an ARQC cryptogram using valid credentials and the POS will send the transaction online for authorization.
The SDK is not informed whether or not the issuer actually approved or declined the transaction since this information is only returned to the terminal.
Should be treated as transaction success on the MPA side. |
Yes |
| AUTHENTICATE\_OFFLINE |
This indicates that the POS requested a decline (AAC) with a CDA signature.
SDK will have returned a cryptogram using valid credentials and the POS can authenticate the card offline using the CDA signature.
Typically a POS will request a decline when it simply wants to authenticate that a legitimate digital card is being used without requesting any authorization.
Should be treated as transaction success on the MPA side. |
Yes |
| DECLINE\_BY\_TERMINAL |
The POS has requested a decline without a CDA signature. This may correspond to a real decline by the terminal, or (in rare cases) to an online authentication request.
Paying on the terminal with offline-only network connectivity can also return this callback.
Application Cryptogram was generated with genuine credentials.
Should be treated as transaction success on the MPA side. |
Yes |
| DECLINE\_BY\_CARD |
The digitized card has declined the transaction. A non-exhaustive list of possible reasons may be:
- Context mismatch between first and second tap
- Terminal is offline-only
- Terminal is a transit gate, and transit transactions are not allowed by the card profile
- Transaction is international, while the card profile is domestic-only |
No |
| WALLET\_ACTION\_REQUIRED |
If the getFinalDecisionForTransaction returns an AUTHENTICATION\_REQUIRED status then this result will be returned.
The SDK will have declined the transaction but requested that the POS should keep the context active for a subsequent tap.
If the POS does not support mobile devices then the merchant may need to repeat the transaction with the same amount so that the second tap can take place. |
No |
#### **· External libraries**
The SDK uses several external Apache 2.0 libraries:
- com.nimbusds:nimbus-jose-jwt
- commons-codec:commons-codec
- com.fasterxml.jackson.core:jackson-core
- com.fasterxml.jackson.core:jackson-annotations
- com.fasterxml.jackson.core:jackson-databind
- com.fasterxml.jackson.module:jackson-module-kotlin
- io.insert-koin:koin-android
- io.reactivex.rxjava2:rxjava
- io.reactivex.rxjava2:rxandroid
- com.squareup.retrofit2:adapter-rxjava2
- com.squareup.retrofit2:retrofit
- com.squareup.retrofit2:converter
- com.squareup.okhttp3:logging
- com.squareup.okhttp3:okhttp
VCP SDK Setup
VCP SDK has to be configured every time when is used. Before VCP SDK usage Mobile DC SDK should be already configured.
### **setup**
Note: Contains all the necessary data to configure SDK.
Should be called at the very beginning of the application lifecycle. For example in the Android Application::onCreate method.
Requires MobileDC setup() already finished
Setup methods could be called in another thread then Main to improve application start time. In case of calling setup method in another thread application must check before every SDK usage if setup method is already finished.
When SDK is integrated into the app and user can enable or disable it as a featere - the SDK setup can be ommited during Application start and loaded on demand.
Important! Before calling VCP SDK setup you must call setup from Mobile DC SDK.
Note: Implementation of Application::on Create should be as quick as possible. Invocation time directly impacts on the performance of payment and loading first aplication screen.
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| ucpConfiguration |
UcpConfiguration |
VCP configuration provided in builder described below. |
Not empty. |
**UcpConfigurationBuilder** contains the following methods:
| Metod |
Parameter |
Description |
Validation conditions |
| withApplication |
Application |
Application context. |
Not empty |
| withCvmModel |
WalletCvmModel (enum) |
Customer Verification Method: CDCVM\_ALWAYS, FLEXIBLE\_CDCVM, CARD\_LIKE |
Not empty |
| withUserAuthMode |
WalletAuthMode (enum) |
User authentication mode: WALLET\_PIN, CUSTOM, NONE
Contact Verestro to select proper configuration |
Not empty |
withUcpPaymentInstrument
EventListener |
UcpPaymentInstrument
EventListener |
Global listener for actions on PaymentInstrument. |
Not empty |
withUcpTransaction
EventListener |
UcpTransactionEventListener |
Deprecated - use MobileDcApiConfigurationBuilder.withOptionalMobileDcTransactionEventListener from MDC SDK instead. Global listener for actions during transaction processing |
Not empty |
withTransactionAcceptance
EventListener |
UcpTransactionAcceptance
EventListener |
Global listener which allow application take final decision about transaction acceptance during transaction |
Not empty |
| withReplenishThreshold |
Int |
Number of credentials below which replenish process will automatically begin |
Not empty |
| withMcbpPinningCertificates |
List |
List of public key certificates in PEM format.
Pass list with empty String if withOptionalUcpMcbpHttpExecutor mentioned below is used with custom HTTP communication. |
Not empty List |
| withOptionalEventsReports |
UcpEventReportListener |
Global listener for most important internal SDK actions related to token management. Could be useful for logs grabbing and debugging on debug. |
Optional |
withOptional
ExternalWalletServer |
|
Prepares SDK for using external wallet server. |
Optional |
withOptional
UcpMcbpHttpExecutor |
UcpMcbpHttpExecutor/
DefaultUcpMcbpHttpExecutor |
Global listener for connection between SDK and MasterCards API. Could be use for adding action before connection - use DefaultUcpMcbpHttpExecutor or for completely replace this connection - use UcpMcbpHttpExecutor. |
Optional |
withOptional
UcpReProvisionEventListener |
UcpReProvisionEventListener |
Global listener for actions during reprovisioning. |
Optional |
withOptional
UcpTransactionConfiguration |
UcpTransactionConfiguration |
Transaction configuration. Allow to enable deprecated authentication timer called when authentication is peformed.
Timer is disabled by default, usage is not recomended. |
Optional |
withOptionalWallet
McbpHttpExecutor |
|
Prepares SDK for processing CMS-D HTTP requests with Wallet Server proxy. |
Optional |
| withOptionalEnableVisaSDK |
|
Enables Visa SDK usage, requires gradle dependencies configuration |
Optional |
withOptionalVtsPayment
ReadyCallback |
UcpVtsPaymentAllowedListener |
Provides information if payment with Visa Token is allowed with callback onPaymentAllowed().
Application should wait for callback when Visa Card is used. |
Optional |
**UcpPaymentInstrumentEventListener**
Contains callbacks for PaymentInstrument.
| Method name |
Parameters |
Description |
onProvisioning
Success |
paymentInstrument: PaymentInstrument |
Method called after provisioning process. Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback described below |
onProvisioning
Failure |
errorMessage: String?,
exception: Exception? |
Method called after provisioning failure. Try processing digitization again |
onReplenish
Success |
paymentInstrument: PaymentInstrument
numberOfTransactionCredentials: Int |
Method called after successfully transaction credentials replenish. Provides information about PaymentInstrument and number of new transaction credentials.
Depending on flow is called after activation process and when requested by SDK based on replenishThreshold configuration.
Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
onReplenish
Failure |
paymentInstrument: PaymentInstrument,
errorMessage: String?,
exception: Exception? |
Method called after replenish failure with PaymentInstrument
Note: Replenish could be called just after transaction based on withRplenishThreshold configuration. It's recommended to not do complex process here. It could affect on next transaction processing time when multiple transactions are done in row |
onPayment
Instrument
StatusChanged |
newStatus: PaymentInstrument
Status
paymentInstrumentId: String |
Provides information about PaymentInstrumentStatus state (check model) for selected payment instrument id |
| onNewTransaction |
newTransaction: NewTransaction |
Provides online result with details of transaction processed in VCP
Works only when application is online |
**UcpTransactionEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| Method name |
Parameters |
Description |
onAuthRequired
ForContactless |
paymentInstrument: PaymentInstrument, transactionInformation:
ContactlessTransactionInformation
transactionData: ContactlessTransactionData |
Called when user authentication is required during contactless transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
onAuthRequired
ForDsrp |
paymentInstrument: PaymentInstrument, dsrpTransactionInfo: DsrpTransactionInfo |
Called when user authentication is required during Dsrp transaction |
onAuthTimer
Updated |
secondsRemaining: Int |
Called on every update of remaining time for performing transaction, as SDK starts transaction timer based on card profile configuration.
Note: Deprecated and disabled by default in version 2.6.7.
To enable use configuration avaialble in SDK setup::withOptionalUcpTransactionConfiguration. |
onContactless
PaymentStarted |
\- |
Called on very beginnging of every transaction start (SELECT\_PPSE APDU command). E.g. first tap to terminal or second tap if onAuthRequiredForContactless method was called.
Locks communication until method is finished.
Method duration directly impacts on transaction time. |
onContactless
Payment
Completed |
paymentInstrument: PaymentInstrument
transactionInformation:
ContactlessTransactionInformation
transactionResult: ContactlessTransactionResult
transactionData : ContactlessTransactionData,
transactionId:String |
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
transactionId - transaction identifier for Mastercard transactions, allow to match transaction with processed transaction notification from Mobile DC SDK: EventNewTransaction::clientTransactionId. |
onContactless
Payment
Incident |
paymentInstrument: PaymentInstrument,
exception: Exception |
Called when something went wrong during transaction and Mastercard marked transaction as incident |
onContactless
Payment
Aborted |
paymentInstrument: PaymentInstrument?,
abortReason: TransactionAbortReason,
exception: Exception |
Called when transaction is aborted during payment from some reason described in method parameter
PaymentInstrument could be null if abortReason = TransactionAbortReason.NO\_CARDS is returned.
Note: SDK clears passed selected card with method selectForPayment() and authentication with setUserAuthenticatedForPayment() |
onTransaction
Stopped |
|
Method called on transaction stopped by SDK.
Deprecated in version 2.6.7, no longer used. |
**UcpTransactionAcceptanceEventListener**
Callbacks related to transaction process.
Important! It's recommended to not do complex process in there callbacks. It could significantly affect on transaction processing time.
| Method name |
Parameters |
Description |
getFinal
Decision
ForTransaction |
isUserAuthenticated : Boolean
recommendedAdvice : ContactlessAdvice
trasactionInformation :
ContactlessTransactionInformation
transactionData : ContactlessTransactionData |
Called on every transaction for the final decision about transaction processing
An application can decide based on information about authentication, transaction details like amount, currency, and transaction types
The method also provide recommended by MCBP advice based on transaction
ContactlessTransactionInformation is deprecated in version 2.2.4. |
**UcpEventReportsListener**
| Method name |
Parameters |
Description |
| onNewReport |
report: Report |
Return logs related to token management. |
**UcpReProvisionEventListener**
Called when transaction is completed with information about transaction and result.
ContactlessTransactionInformation is deprecated in version 2.2.4.
| Method Name |
Parameters |
Description |
| onReProvisionSuccess |
paymentInstrument: PaymentInstrument |
Method called after reProvisioning process.
Information about PaymentInstrument activation process will be provided in onPaymentInstrumentStatusChanged callback. |
| onReProvisionFailure |
paymentInstrument : PaymentInstrument
errorMessage : String?
exception : Exception? |
Method called after reProvisioning failure. Try again. |
**UcpMcbpHttpExecutor**
| Method name |
Parameters |
Description |
| execute |
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod:
UcpMcbpHttpMethod,
url: String,
requestData:Any,
requestProperties:
Map |
Called on every time if SDK want to connect to MasterCard and should return UcpMcbpHttpResponse.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
|
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
**DefaultUcpMcbpHttpExecutor**
| Method name |
Parameters |
Description |
| execute |
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType
ucpMcbpHttpMethod: UcpMcbpHttpMethod
url: String
requestData: Any
requestProperties: Map |
Called on every time if SDK want to connect to MasterCard and should return super.execute method.
requestData could be one of request data type: UcpMcbpRequestSessionRequestData,
UcpMcbpReplenishRequestData, UcpMcbpProvisionRequestData, UcpMcbpNotifyProvisioningResultRequestData,
UcpMcbpChangeMobilePinRequestData, UcpMcbpDeleteRequestData.
|
```
ucpMcbpHttpMethod could be one of: POST, GET.
```
```
ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.
```
**UcpTransactionConfiguration**
| Parameter |
Type |
Description |
enableTransaction
AuthenticationTimer |
Boolean |
Allows to enable deprecated authentication timer.
Timer is started along setUserAuthenticatedForPayment(), result is available in onAuthTimerUpdated(). |
**Callback samples:**
**UcpTransactionEventListener**
```
// UcpTransactionEventListener comments
class BankingAppUcpTransactionEventListener : UcpTransactionEventListener {
override fun onAuthRequiredForContactless(event: EventAuthRequiredForContactless) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and ContactlessTransactionData available in event object
showPaymentScreen(event.paymentInstrument, event.transactionData)
}
override fun onAuthRequiredForDsrp(event: EventAuthRequiredForDsrp) {
//authorization is required for transaction, open payment screen with authorization
//show PaymentInstrument and DSRP transaction information available in event object
showPaymentScreen(event.paymentInstrument, event.dsrpTransactionInfo)
}
override fun onAuthTimerUpdated(event: EventAuthTimerUpdated) {
//check if user is on payment screen and update timer
//when timer is 0, application should close payment with failure
//deprcated, disabled by default, read method description how to enable
}
override fun onContactlessPaymentAborted(event: EventContactlessPaymentAborted) {
//looks like payment is aborted, can provide result to payment screen
//and show user what is abort reason
}
override fun onContactlessPaymentCompleted(event: EventContactlessPaymentCompleted) {
//payment completed, provide result to payment information
//REMEMBER Transaction is processed on terminal and this is where
//you will see final transaction result
}
override fun onContactlessPaymentIncident(event: EventContactlessPaymentIncident) {
//something went wrong during transaction, provide result to user
}
override fun onTransactionStopped() {
//deprecated, not used anymore,
}
override fun onContactlessPaymentStarted() {
//Payment started or resumed after callback onAuthReqiredForContactless
//Best place for checking if user is authenticated for payment and call
//setUserAuthenticatedForPayment() and selectForPayment() methods if non-defaut card is selected
}
}
```
**UcpPaymentInstrumentEventListener**
```
class BankingAppPaymentInstrumentEventListener : UcpPaymentInstrumentEventListener {
override fun onNewTransaction(event: EventNewTransaction) {
//information about new transaction processed by issuer
}
override fun onPaymentInstrumentStatusChanged(event: EventPaymentInstrumentStatusChanged) {
//status of payment instrument was changed, refresh list, inform user about new status
}
override fun onProvisioningFailure(event: EventProvisioningFailure) {
//provisioning failed, try again
}
override fun onProvisioningSuccess(event: EventProvisioningSuccess) {
//provisioning success, wait for status and replenish changes until user can pay
//or provide activation method when required
}
override fun onReplenishFailure(event: EventReplenishFailure) {
//transaction credentials replenish failed
}
override fun onReplenishSuccess(event: EventReplenishSuccess) {
//transaction credentials replenish success
}
}
```
**UcpTransactionAcceptanceEventListener**
```
class BankingAppUcpTransactionAcceptanceEventListener : UcpTransactionAcceptanceEventListener {
//Sample implementation of transaction acceptance listener
//For the scanario when authentication is required on issuer side for every transaction
//field even.isUserAuthenticated must be always true, otherwise
//ContactlessAdvice.AUTHENTICATION_REQUIRED should be returned
override fun getFinalDecisionForTransaction(event: EventGetFinalDecision): ContactlessAdvice {
val isScreenUnlocked = isScreenUnlocked()
val isScreenProtectedByKeyguard = isScreenUnlocked()
val isLvtTransaction =
event.transactionInformation.transactionRange == ContactlessTransactionRange.LVT
//discard all Transit transaction
if (event.transactionInformation.richTransactionType == ContactlessRichTransactionType.TRANSIT) {
return ContactlessAdvice.DECLINE
}
//allow for transaction when user is authenticated for payment and screen unlocked
if (event.isUserAuthenticated && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
//allow for LVT transaction on unlocked screen when protected and don't require authentication
if (isLvtTransaction && isScreenProtectedByKeyguard && isScreenUnlocked) {
return ContactlessAdvice.PROCEED
}
// ...
// much more cases
//require authentication anyway
return ContactlessAdvice.AUTHENTICATION_REQUIRED
}
}
```
**UcpEventReportsListener**
```
class BankReportEventListener : UcpEventReportsListener {
override fun onNewReport(report: Report) {
//may be used for debugging SDK or gathering reports on client's app or backend
}
}
```
**UcpMcbpHttpExecutor**
```
//Use UcpMcbpHTtpExecutor as supertype if you want to replace connection
class BankUcpMcbpHttpExecutor : UcpMcbpHttpExecutor {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
//invoke connect by custom connector
return when (ucpMcbpRequestType) {
UcpMcbpHttpExecutorRequestType.REQUEST_SESSION -> {
executeRequestSession(ucpMcbpHttpMethod, url, requestData as UcpMcbpRequestSessionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.PROVISION -> {
executeProvision(ucpMcbpHttpMethod, url, requestData as UcpMcbpProvisionRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.REPLENISH -> {
executeReplenish(ucpMcbpHttpMethod, url, requestData as UcpMcbpReplenishRequestData,
requestProperties)
}
UcpMcbpHttpExecutorRequestType.NOTIFY_PROVISIONING_RESULT -> {
executeNotifyProvisioningResult(ucpMcbpHttpMethod, url,
requestData as UcpMcbpNotifyProvisioningResultRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.CHANGE_MOBILE_PIN -> {
executeChangeMobilePin(ucpMcbpHttpMethod, url,
requestData as UcpMcbpChangeMobilePinRequestData, requestProperties)
}
UcpMcbpHttpExecutorRequestType.DELETE -> {
executeDelete(ucpMcbpHttpMethod, url, requestData as UcpMcbpDeleteRequestData,
requestProperties)
}
}
}
}
```
**DefaultUcpMcbpHttpExecutor**
```
//Use DefaultUcpMcbpHTtpExecutor as supertype if you want to only add some action before connection
class BankDefaultUcpMcbpHttpExecutor : DefaultUcpMcbpHttpExecutor() {
override fun execute(
ucpMcbpRequestType: UcpMcbpHttpExecutorRequestType,
ucpMcbpHttpMethod: UcpMcbpHttpMethod,
url: String,
requestData: Any,
requestProperties: Map
): UcpMcbpHttpResponse {
//additional action before request
return super.execute(
ucpMcbpRequestType,
ucpMcbpHttpMethod,
url,
requestData,
requestProperties
)
}
}
```
**UcpReProvisionEventListener**
```
class BankingAppUcpReProvisiongEventListener : UcpReProvisionEventListener() {
override fun onReProvisionSuccess(event: EventReProvisionSuccess) {
//reProvisioning success, wait for status and replenish changes until user can pay
}
override fun onReProvisionFailure(event: EventReProvisionFailure) {
//reProvisioning failed, try again.
}
}
```
**UcpTransactionConfiguration**
```
class BankingAppUcpTransactionConfiguration : UcpTransactionConfiguration {
override val enableTransactionAuthenticationTimer: Boolean = false
}
```
**UcpVtsPaymentAllowedListener**
```
class BankingAppUcpVtsPaymentAllowedListener : UcpVtsPaymentAllowedListener {
override fun onPaymentAllowed() {
//when during a payment an status of PAYMENT_NOT_ALLOWED is received
//Application UI should show transaction error and wait for onPaymentAllowed() callback
//When received callback shouuld inform UI to process transaction again
}}
```
**Sample VCP SDK setup implementation**
Mobile DC setup() and VCP setup() method could be called on MainThread in Application:onCreate as blocking or another thread.
When applicaiton has multiple dependencies there is possible to call both setup() methods on another thread (MobileDC setup() method must be already finished until VCP setup() is called).
Important: In case of loading SDK on another thread and using contactless payments HostApduService must be used asynchronous way to prevet using SDK until loading is finished - check sample for method *PaymentService:processHceApduCommand*.
```kotlin
fun setup(
application: Application,
walletCvmModel: WalletCvmModel,
walletAuthUserMode: WalletAuthUserMode,
mcbpPinningCertificates: List,
replenishThreshold: Int
) {
val ucpConfiguration = UcpConfiguration.create(
UcpConfigurationBuilder()
.withApplication(application)
.withCvmModel(walletCvmModel)
.withUserAuthMode(walletAuthUserMode)
//marked as deprecated - see description above
.withUcpTransactionEventListener(BankingAppUcpTransactionEventListener())
.withUcpPaymentInstrumentEventListener(BankingAppPaymentInstrumentEventListener())
.withMcbpPinningCertificates(mcbpPinningCertificates)
.withUcpTransactionAcceptanceEventListener(BankingAppUcpTransactionAcceptanceEventListener())
.withReplenishThreshold(replenishThreshold)
.withOptionalEventsReports(BankReportEventListener())
.withOptionalUcpMcbpHttpExecutor(BankUcpMcbpHttpExecutor())
//if you want to only add additional action before connection use below implementation
//.withOptionalUcpMcbpHttpExecutor(BankDefaultUcpMcbpHttpExecutor())
.withOptionalUcpReProvisionEventListener(BankingAppUcpReProvisionEventListener())
//if you want to change standard transaction configuration use configuration below
.withOptionalUcpTransactionConfiguration(BankingAppUcpTransactionConfiguration())
//.withOptionalEnableVisaSDK() //optional when Visa is used
//.withOptionalVtsPaymentReadyCallback(BankingAppUcpVtsPaymentAllowedListener()) //optional when Visa is used
)
UcpApiKotlin().setup(ucpConfiguration)
}
```
### **reset (DEPRECATED - use restart instead)**
Synchronous. Offline.
Method for resetting SDK to uninitialized state.
|
Note: According to MCBP Deployment team there is no possibility for resetting SDK without killing application process for clearing all MC SDK local variables. Please kill application process after using this method. Trying using any facade method without stopping application process will cause throwing UcpSdkException.
To avoid closing application use restart() methods.
**Input**
No input.
**Output**
No output.
**Sample**
**Sample VCP SDK reset implementation:**
```kotlin
fun reset() {
UcpApiKotlin().reset()
//Terminating JVM according to MC SDK Sample Application
Runtime.getRuntime().exit(0);
}
```
### **restart**
Synchronous. Offline.
Method for resetting SDK to uninitialized state.
Replaces reset() method which requires killing application process.
When restart finishes with error, application should repeat action. |
Note: SDK must be already initialized to call restart() method. During restart() SDK internally initializes SDK again.
**Input**
No input.
**Output**
Success callback when SDK data is cleared and SDK is ready to use again. No any action is required to call facade methods.
Failure callback when something went wrong during restart. Application should repeat action.
**Sample**
**Sample VCP SDK reset implementation:**
```
UcpApiKotlin().restart({
//restart finished with success. UCP & MDC data is cleared, SDK is now ready to use without calling MDC & UCP setup methods
}, {
//some error occured, please repeat action
})
```
Cards domain
### **delete**
Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
|
Result of action will be notified with onPaymentInstrumentStatusChanged.
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of PaymentInstrument to delete |
Not empty. |
| reason |
CharArray? |
Optional reason of deletion |
|
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.cardsService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
### **checkEligibility**
Asynchronous. Online.
Check eligibility required to process digitize. |
**Input**
| Parameter |
Type |
Description |
| checkEligibility |
CheckEligibility |
CheckEligibility object |
CheckEligibility
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| paymentInstrumentType |
PaymentInstrumentType |
Payment instrument type. One of: \[MASTERCARD,VISA\] |
| userLanguage |
String |
User language |
| userCountry |
String |
User country |
**Output**
| Success callback with CheckEligibilityResult. |
CheckEligibilityResult
| Parameter |
Type |
Description |
| termsAndConditionsAssetId |
String |
Identifier of Terms and Conditions asset |
**Sample**
```
private fun checkEligibility(
paymentInstrumentId: String,
paymentInstrumentType: PaymentInstrumentType,
userLanguage: String,
userCountry: String
) {
ucpApi.cardsService
.checkEligibility(
CheckEligibility(
paymentInstrumentId,
paymentInstrumentType,
userLanguage,
userCountry
),
{ checkEligibilityResult ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
Asynchronous. Online.
Use only when checkEligibility method is used.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| digitizationRequest |
DigitizationRequest |
Plain object of DigitizationRequest |
Not empty |
DigitizationRequest object contains following fields:
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| paymentInstrumentType |
PaymentInstrumentType |
Payment instrument type. One of: \[MASTERCARD,VISA\] |
Not empty |
| securityCode |
CharArray? |
Optional. The CVC2 for the card to be digitized |
|
| externalPaymentTokenId |
String? |
Optional. Unique external identifier of Payment Token |
|
**Output**
Success callback with DigitizationResult object
| Parameter |
Type |
Description |
| digitizationResult |
DigitizationResult |
Plain object of DigitizationResult |
DigitizationResult contains following fields.
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Plain object of PaymentInstrument |
| additionalAuthenticationMethods |
List? |
All available additional authentication method |
| productConfig |
ProductConfig |
Plain object of ProductConfig, contains Payment Token configuration |
| externalPaymentTokenId |
String? |
Optional. External payment token id configured by the consumer. In case of identifier duplicate an random id is generated |
ProductConfig contains following fields.
| Parameter |
Type |
Description |
| isCoBranded |
Boolean |
Whether the product is co-branded |
| coBrandName |
String? |
Name of the co-branded partner |
| foregroundColor |
String |
Foreground color, used to overlay text on top of the card image |
| backgroundColor |
String |
Background color, used to overlay text on top of the card image |
| labelColor |
String? |
Label color of the mobile wallet entry for the card |
| issuerName |
String |
Name of the issuing bank |
| shortDescription |
String |
A short description for this product |
| longDescription |
String? |
A long description for this product |
| custoremServiceUrl |
String? |
Customer service website of the issuing bank |
| customerServiceEmail |
String? |
Customer service email address of issuing bank |
| customerServicePhoneNumber |
String? |
Customer service phone number of the issuing bank |
| productConfigIssuer |
ProductConfigIssuer? |
Contains one or more mobile app details that may be used to deep link from the Mobile Payment App to the issuer mobile app |
| onlineBankingLoginUrl |
String? |
Login URL for the issuing bank's online banking website |
| termsAndConditionsUrl |
String? |
URL linking to the issuing bank's terms and conditions for this product |
| privacyPolicyUrl |
String? |
URL linking to the issuing bank's privacy policy for this product |
| issuerProductConfigCode |
String? |
Freeform identifier for this product configuration as assigned by the issuer |
| contactName |
String? |
Name of the issuing bank |
| bankAppName |
String? |
Name of banking application for display |
| bankAppAddress |
String? |
The package name for the destination mobile application |
| unsupportedPresentationTypes |
String? |
The presentation types that are not supported such as "MSR" (for example). This is an advisory field to tell the wallet provider that they should not include the unsupported presentation type returned in this field in the provisioning request |
| unsupportedCardVerificationTypes |
String? |
The card verification types that are not supported such as "AVS" (for example). This is an advisory field to let the wallet provider know which card verification services are not supported for a given payment instrument. The wallet provider can use this information to relax any field validations on the Customer UI (such as Address) |
| issuerFlags |
List? |
List of plain ProductConfigIssuerFlags object. Contains issuer flags |
| brandLogoAssetId |
String |
The Mastercard or Maestro brand logo associated with this card. Provided as an Asset ID |
| issuerLogoAssetId |
String |
The logo of the issuing bank. Provided as a Asset ID |
| coBrandLogoAssetId |
String? |
The co-brand logo (if any) for this product. Provided as an Asset ID |
| cardBackgroundCombinedAssetId |
String? |
The card image used to represent the digital card in the wallet. This ‘combined’ option contains the Mastercard, bank and any co-brand logos. Provided as an Asset ID |
| cardBackgroundAssetId |
String? |
The card image used to represent the digital card in the wallet. This ‘non-combined’ option does not contain the Mastercard, bank, or cobrand logos. Provided as an Asset ID |
| iconAssetId |
String |
The icon representing the primary brand(s) associated with this product. Provided as an Asset ID |
ProductConfigIssuer contains following fields.
| Parameter |
Type |
Description |
| openIssuerAndroidIntent |
ProductConfigOpenIssuerAndroidIntent? |
AndroidIntent object can be used to open the issuer mobile app |
| activateWithIssuerAndroidIntent |
ProductConfigActivateWithIssuerAndroidIntent? |
AndroidIntent object can be used to open the issuer mobile app |
| openIssuerIOSDeepLinkingUrl |
ProductConfigOpenIssuerIOSDeepLinkingUrl? |
IOSDeepLinkingUrl object can be used to open the issuer mobile app |
| activateWithIssuerIOSDeepLinkingUrl |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl? |
IOSDeepLinkingUrl object can be used to open the issuer mobile app |
ProductConfigOpenIssuerAndroidIntent contains following fields.
| Parameter |
Type |
Description |
| action |
String |
The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName |
String |
The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerAndroidIntent contains following fields.
| Parameter |
Type |
Description |
| action |
String |
The name of the action to be performed. This is a fully qualified name including the package name in order to create an explicit intent |
| packageName |
String |
The package name of the issuer’s mobile app. This identifies the app that the intent will resolve to. If the app is not installed on the user’s device, this package name can be used to open a link to the appropriate Android app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the intent as an extra key/value pair with key ‘android.intent.extra.TEXT’. This is Base64-encoded data of a JSON object |
ProductConfigOpenIssuerIOSDeepLinkingUrl contains following fields.
| Parameter |
Type |
Description |
| deepLinkinUrl |
String |
The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the deep linking URL as a query parameter.It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigActivateWithIssuerIOSDeepLinkingUrl contains following fields.
| Parameter |
Type |
Description |
| deepLinkingUrl |
String |
The deep linking URL of the issuer’s iOS mobile app. This identifies the app that the URL will resolve to. If the app is not installed on the user’s device, this URL can be used to open a link to the appropriate iOS app store for the user to download and install the app |
| extraTextValue |
String |
Contains the data to be passed through to the target app in the deep linking URL as a query parameter. It should be appended to the deepLinkingUrl when invoked in the format: deepLinkingUrl + ‘?extraTextValue=’ + extraTextValue. This is Base64-encoded data of a JSON object |
ProductConfigIssuerFlags contains following fields.
| Parameter |
Type |
Description |
| deviceBinding |
Boolean |
Device binding |
| cardholderVerification |
Boolean |
Whether the issuer participating in step-up flow |
| trustedBeneficiaryEnrollment |
Boolean |
Whether this is a trusted beneficiary enrollment |
| delegateAuthenticationSupported |
String |
Whether issuer supports delegated authentication |
Sample
```kotlin
fun digitizeCard(digitizationRequest: DigitizationRequest) {
ucpApi.cardsService
.digitize( digitizationRequest,
{ digitizationResult ->
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize (deprecated)**
Deprecated - use digitize(DigitizationGreenPath) instead.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty. |
| userLanguage |
String |
Language preference selected by the consumer. Formatted as an
ISO-639-1 two letter language code |
Not empty. |
| securityCode |
CharArray? |
Optional. The CVC2 for the card to be digitized |
|
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun digitizeCard(
paymentInstrumentId: String,
languageCode: String,
securityCode: CharArray) {
ucpApi.cardsService
.digitize(paymentInstrumentId, languageCode, securityCode,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **digitize**
Asynchronous. Online.
Creates payment token in VCP backend.
Expect push after successful finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| digitizationGreenPath |
DigitizationGreenPath |
Plain object of DigitizationGreenPath |
Not empty |
DigitizationGreenPath contains following fields.
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| paymentInstrumentType |
PaymentInstrumentType |
Payment instrument type. One of: \[MASTERCARD,VISA\] |
| securityCode |
CharArray? |
Optional. The CVC2 for the card to be digitized |
| userLanguage |
String |
User language |
| userCountry |
String |
User country |
| externalPaymentTokenId |
String? |
Optional. Unique external identifier of Payment Token |
**Output**
| Success / failure callback |
**Sample**
```
fun digitizeCard(digitizationGreenPath: DigitizationGreenPath) {
ucpApi.cardsService
.digitize(digitizationGreenPath,
{
//digitization success, provisioning is in progress
//application should listen to push message and provide content to UCP
//refresh you payment instrument list form Cards::getPaymentInstruments
//new PaymentInstrument should be visible with INACTIVE state
//when push processed wait for onProvisioningSuccess or Failure callback
//and status change
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAdditionalAuthenticationMethods**
Asynchronous. Online.
Retrieves additional user authentication methods. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| getAdditionalAuthenticationMethods |
GetAdditionalAuthenticationMethods |
Plain object of GetAdditionalAuthenticationMethods |
Not empty |
Fields of GetAdditionalAuthenticationMethods object:
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
**Output**
| Success callback with AdditionalAuthenticationMethods object. |
| Parameter |
Type |
Description |
| additionalAuthenticationMethods |
AdditionalAuthenticationMethods |
Object carrying list of AdditionalAuthenticationMethod |
AdditionalAuthenticationMethods contains following value:
| Parameter |
Type |
Description |
| additionalAuthenticationMethods |
List |
List of AdditionalAuthenticationMethod objects |
**Sample**
```
private fun getAdditionalAuthenticationMethods() {
val getAdditionalAuthenticationMethod =
GetAdditionalAuthenticationMethods("paymentInstrumentId")
ucpApi
.cardsService
.getAdditionalAuthenticationMethods(
getAdditionalAuthenticationMethod,
{ additionalAuthenticationMethods ->
//Handle result
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **submitTokenAuthenticationValue**
Asynchronous. Online.
Submit authentication code when additional user authentication is required. |
**Input**
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| authenticationCode |
String |
Authentication code |
**Output**
| Success callback/failure callback. |
**Sample**
```
private fun submitAuthenticationValue(paymentInstrumentId: String, authenticationCode: String) {
ucpApi.cardsService
.submitAuthenticationValue(
SubmitAuthenticationValue(
paymentInstrumentId,
authenticationCode
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **submitTokenAuthenticationMethod**
Asynchronous. Online.
Submit authentication method when additional user authentication is required. |
**Input**
| Parameter |
Type |
Description |
| paymentInstrumentId |
String |
Identifier of payment instrument |
| authenticationMethodId |
String |
Id of authentication method. Get it when digitize method return additionalAuthenticationRequired set to true. |
**Output**
| Success callback/failure callback. |
**Sample**
```
private fun submitAuthenticationMethod(paymentInstrumentId: String, authenticationMethodId: String) {
ucpApi.cardsService
.submitAuthenticationMethod(
SubmitAuthenticationMethod(
paymentInstrumentId,
authenticationMethodId
),
{
//Handle success
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to increase UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| refresh |
Boolean |
Refresh all PaymentInstrument objects state with remote VCP server (network and user session required) |
|
**Output**
| Success callback with list of PaymentInstrument objects. |
| Parameter |
Type |
Description |
| paymentInstruments |
List |
List of retrieved payment instruments from local or remote storage |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.cardsService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument (deprecated)**
Asynchronous. Online/Offline.
Deprecated - use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of instrument to retrieve |
Not empty |
| refresh |
Boolean |
Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
| Success callback with PaymentInstument object. |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Retrieved payment instrument |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.cardsService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
IBANs domain
### **digitize**
Asynchronous. Online.
Registers user and device if already not registered in VCP backend. Creates payment token in VCP backend.
Expect push after successfull finish and then proceed using process method in Cloud Messaging domain. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| signedAccountInfo |
String |
Signed AccountInfo per RFC 7519
Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation |
Not empty. |
| fcmRegistrationToken |
CharArray |
FCM Cloud messaging registration token |
Not empty. |
| languageCode |
String |
Language preference selected by the consumer. Formatted as an ISO-639-1 two letter language code |
Not empty. |
**AccountInfo:**
| Parameter |
Type |
Description |
Validation conditions |
| userId |
String |
External user id |
Not empty. |
| iban |
String |
Bank Account Number |
Not empty. |
| countryCode |
String |
The country of the financial account
Expressed as a 3-letter (alpha-3 country code as defined in ISO 3166-1 |
Not empty. |
**Output**
Success callback. Called when device token digitization finished with success .Result contains IbanDigitizationResult object.
Note: Cloud token digitization fail doesn't affect on success/failure callback. |
IbanDigitizationResult contains following fields:
| Parameter |
Type |
Description |
| (DEPRECATED) cloudDigitizationSuccess |
Boolean |
Cloud Token Digitization Details |
| result |
CloudDigitizationResult |
Cloud Token Digitization Details. One of: SUCCEED, FAILED, DISABLED, UNKNOWN |
| Failure callback. Called when device token digitization finished with failure. |
**Sample**
Sample generation of *signedAccountInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAccountInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("userId", "externalUserId")
.claim("iban", "IN15HIND23467433866365")
.claim("countryCode", "IND")
.build()
val signedAccountInfo = JwtGenerator.generate(claims, certificates, privateKey)
// ...
}
```
```kotlin
fun digitizeIban(
signedAccountInfo: String,
fcmRegistrationToken: CharArray,
languageCode: String) {
ucpApi.ibansService
.digitize(signedAccountInfo, fcmRegistrationToken, languageCode,
{ ibanDigitizationResult ->
//Device token digitization finished with success
//wait for onProvisioning(Success/Failure) callback and onTokenStatusChanged when success
val cloudDigitizationResult = ibanDigitizationResult.result
//check status of Cloud Token
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **createTVC**
Asynchronous. Online.
Provides Transaction Verification Code required to process cloud payments. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| signedIbanInfo |
String |
Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation |
Not empty. |
IbanInfo
| Parameter |
Type |
Description |
Validation conditions |
| ibanId |
String |
Iban id returned in addUserWithIban methdod or sha256Hex(iban) |
Not empty. |
**Output**
| Success callback with Tvc object or encrypted Tvc object as String. |
| Parameter |
Type |
Description |
| plainTvc |
PlainTvc? |
Plain PlainTvc object |
| encryptedTvc |
CharArray? |
Encrypted PlainTvc object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation |
PlainTvc object contains following fields.
| Parameter |
Type |
Description |
| accountNumber |
CharArray |
Primary Account Number for the transaction – this is the Token PAN |
| dynamicExpiryDate |
CharArray |
Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC |
CharArray |
Dynamic CVC |
| Failure callback when TVC cannot be created. |
**Sample**
Sample generation of *signedIbanInfo* (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createTvc(signedIbanInfo: String) {
ucpApi.ibansService
.createTVC(signedIbanInfo, { tvc ->
//result object could contains encrypted TVC
val encryptedTvc: String? = tvc.encryptedTvc
//or decrypted(plain) TVC object with parameters described in documentation
val plainTvc = tvc.plainTvc
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **createPaymentData**
Asynchronous. Online.
This method is responsible for creating payment data for given IBAN. Depending on configuration returned data are dedicated for payment using UCAF or TVC. Also depending on configuration payment data are returned in plain or encrypted form. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| signedIbanInfo |
String |
Signed IbanInfo per RFC 7519
Instruction how to sign data with JWT can be found in Data signing and encryption chapter in Mobile DC documentation |
Not empty. |
IbanInfo
| Parameter |
Type |
Description |
Validation conditions |
| ibanId |
String |
Iban id returned in addUserWithIban methdod or sha256Hex(iban) |
Not empty. |
| userId |
String |
External user id given by the client |
Not empty. |
**Output**
| Success callback with PaymentData object or encrypted payment data object as String. |
| Parameter |
Type |
Description |
| plainPaymentData |
PlainPaymentData? |
Plain PlainPaymentData object |
| encryptedPaymentData |
String? |
Encrypted PlainPaymentData object per RFC 7516
Present when client decide to encrypt data. Instruction how tu use JWE can be found in Data signing and encryption chapter in Mobile DC documentation |
PlainPaymentData object contains following fields.
| Parameter |
Type |
Description |
| accountNumber |
String |
Primary Account Number for the transaction – this is the Token PAN |
| applicationExpiryDate |
String? |
Required only for UCAF. Application expiry date for the Token. Expressed in YYMMDD format |
| panSequenceNumber |
String? |
Rrquired only for UCAF. Application PAN sequence number for the Token |
| track2Equivalent |
String? |
Required only for UCAF. Track 2 equivalent data for the Token. Expressed according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), using hex nibble 'D' as field separator, and padded to whole bytes using one hex nibble 'F' as needed |
| ucafCryptogram |
String? |
Required only for UCAF. UCAF cryptogram |
| dynamicExpiryDate |
String? |
Dynamic expiration date for the token. Expressed in YYMM format |
| dynamicCVC |
String? |
Dynamic CVC |
| Failure callback when PaymentData cannot be created. |
**Sample**
Sample generation of *signedIbanInfo* (see [Data signing and encryption](https://wiki.verestro.com/display/UCP/Data+signing+and+encryption) chapter in Mobile DC documentation)
```
class SignedIbanInfo {
fun generate() {
val claims = JWTClaimsSet.Builder()
.claim("ibanId", "798c5c64d93c87b8ed7f108cde4753eb66faff760121ef2a05d0f44fb066b03b")
.claim("userId", "123")
.build();
val signedIbanInfo = JwtGenerator.generate(claims, certificates, privateKey);
// ...
}
}
```
```kotlin
fun createPaymentData(signedIbanInfo: String) {
ucpApi.ibansService
.createPaymentData(signedIbanInfo, { paymentData ->
//result object could contains encrypted PaymentData
val encryptedPaymentData: String? = paymentData.encryptedPaymentData
//or decrypted(plain) PaymentData object with parameters described in documentation
val plainPaymentData = paymentData.plainPaymentData
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getAllPaymentInstruments**
Asynchronous. Online/Offline.
Method for getting all payment instruments from local or remote storage.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| refresh |
Boolean |
Refresh all PaymentInstrument objects state with remote VCP server (network required) |
|
**Output**
| Success callback with list of PaymentInstrument objects |
| Parameter |
Type |
Description |
| paymentInstruments |
List |
List of retrieved payment instruments |
**Sample**
```kotlin
fun getAllPaymentInstrument(refresh: Boolean) {
ucpApi.ibansService
.getAllPaymentInstruments( refresh,
{ paymentInstruments ->
//List of PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument(deprecated)**
Asynchronous. Online/Offline.
Use getAllPaymentInstruments instead.
Method for getting single PaymentInstrument from local or remote storage object based on id.
Local storage is always instant available and should be used to incerese UX.
Use remote way when possible to keep your payment instruments always up to date. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of instrument to retrieve. |
Not empty |
| refresh |
Boolean |
Refresh selected PaymentInstrument state with remote VCP server (network required) |
|
**Output**
| Success callback with PaymentInstument object |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Retrieved payment instrument |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String, refresh: Boolean) {
ucpApi.ibansService
.getPaymentInstrument(paymentInstrumentId, refresh,
{ paymentInstrument ->
//PaymentInstrument from local or remote storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **delete**
Asynchronous. Online.
Method allows delete PaymentInstument from VCP.
Payment token will be removed remote and local storage.
Result of action will be notified with onPaymentInstrumentStatusChanged. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of PaymentInstrument to delete |
Not empty. |
| reason |
CharArray? |
Optional reason of deletion |
|
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String, reason: CharArray?) {
ucpApi.ibansService
.delete(paymentInstrumentId, reason,
{
//PaymentInstrument delete requested
//wait for confirmation from onPaymentInstrumentStatusChanged
},
{ throwable ->
//Something went wrong, check excetpion with documentation
}
)
}
```
Payment domain
### **setDefaultForContactless**
Asynchronous. Offline.
Sets payment instrument as default for contactless payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically after linking with PoS terminal.
Make sure PaymentInstrument status is ACTIVE. Only active payments instruments can be set as default. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun setDefaultForContactless(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE) {
//make sure selected PaymentInstrument can be seta as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForContactless(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForContactless**
Asynchronous. Offline.Provides default PaymentInstrument for contactless payment.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
**Input**
**Output**
| Success callback with id new default PaymentInstrument |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Default Payment instrument |
**Sample**
```kotlin
fun getDefaultForContactless() {
ucpApi.paymentService
.getDefaultForContactless({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **setDefaultForRemote (deprecated)**
Asynchronous. Offline.
Sets payment instrument as default for DSRP payment.
Payment instrument set as default will be used if no other payment instrument was selected by method selectForPayment.
Default payment instrument will be used automatically to remote payments. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun setDefaultForRemote(paymentInstrument: PaymentInstrument) {
if (paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
&& !paymentInstrument.dsrpSupported) {
//make sure selected PaymentInstrument can be set as default
return
}
val paymentInstrumentId = paymentInstrument.id
ucpApi.paymentService
.setDefaultForRemote(paymentInstrumentId, {
//success
}, { throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **getDefaultForRemote (deprecated)**
Asynchronous. Offline.
Provides default PaymentInstrument for remote payments.
Throws DefaultPaymentInstrumentNotFoundException when no PaymentInstrument is set as default. |
**Input**
**Output**
| Success callback with id new default PaymentInstrument |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Default Payment instrument |
**Sample**
```kotlin
fun getDefaultForRemote() {
ucpApi.paymentService
.getDefaultForRemote({ paymentInstrument ->
// use PaymentInstrument
}, { throwable ->
when (throwable) {
is DefaultPaymentInstrumentNotFoundException -> {
//there is no default PaymentInstrument
}
else -> {
//check another exception with documentation
}
}
})
}
```
### **selectForPayment**
Asynchronous. Offline.
Sets payment instrument as primary for next incoming payment. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentd |
String |
Payment instrument identity |
Not empty |
**Output**
| Success / failure callback |
**Sample**
| Note: This is only sample payment scenation |
```
//sample scenario of starting payment with authentication before payment
fun startPayment(paymentInstrument: PaymentInstrument) {
//checking conditions before payment
val isActive = paymentInstrument.status != PaymentInstrumentStatus.ACTIVE
val isContactlessSupported = paymentInstrument.contactlessSupported
val hasTransactionCredentials = paymentInstrument.credentialsCount > 0
if (!isActive || !isContactlessSupported || !hasTransactionCredentials) {
//PaymentInstrument doesn't meet requirements for payment
return
}
//selecting PaymentInstrument to payment
ucpApi.paymentService
.selectForPayment(paymentInstrument.id, {
//selection success
//request user authentication when
//... authentication presented
//use setUserAuthenticatedForPayment method
}, { throwable ->
//something went wrong, check exception with documentation
})
}
```
### **setUserAuthenticatedForPayment**
Asynchronous. Offline.
Sets user as authenticated to payment with provided payment instrument.
Authentication clearing depends on authentication timer configuration in UcpTransactionConfiguration:enableTransactionAuthenticationTimer.
By default timer is disabled and authentication is cancelled when user perform transaction and SDK send callback onContactlessPaymentCompleted/Aborted/Incident from UcpTransactionEventListener.
When timer is enabled authentication is cleared when auth timer finishes - it could casue problems when user start to pay just before timer finish. Authentication could be cleared by SDK during payement.
If application call setUserAuthenticatedForPayment without contactless payment context and authentication timer is disabled, authentication is never cleared by SDK. To clear authentication use abortUserAuthenticationForPayment.
UcpTransactionEventListener:onContactlessPaymentStarted is recommended place for payment authentication.
Note: User can be authenticated based on conditions like screen unlock. Method must be called before payment in method UcpTransactionEventListener:onContactlessPaymentStarted()
Make sure that authentication on this step is done securely. Transaction information is not available on this step. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
| pin |
CharArray? |
PIN or null for CUSTOM WalletAuthUserMode |
|
**Output**
| Success / failure callback |
**Sample**
Basic user authentication usage below, call when user is authenticated.
```
private fun setUserAuthenticatedForPayment(
paymentInstrument: PaymentInstrument,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrument.id, pinProvidedByUser,
{
//user authentication provided
//start one tap payment or continue two tap with 2nd tap to terminal after authentication
//listen for auth timer changes
//user abortUserAuthentication method when transaction cancelled by user
}, { throwable ->
//some error, check exception
})
}
```
Optional authentication before making transaction based on custom conditions.
```
override fun onContactlessPaymentStarted() {
//check internal conditions
//like user performed authentication, is logged in application, is device unlocked etc
val isUserAuthenticated = true
//check if use selected any token for payment and select it in UCP SDK
//otherwise default token will be used
if (getSelectedPaymentInstrumentId() != null) {
ucpApi
.paymentService
.selectForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
success = {
//token will be used for actual payment
//call setUserAuthenticatedForPayment here - sample below in "else" block
},
failure = { throwable ->
//something went wrong, check throwable with documentation
}
)
} else {
if (isUserAuthenticated) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(
paymentInstrumentId = getSelectedPaymentInstrumentId(),
pin = null, //or pin if MobilePin is used
success =
//user authenticated in SDK
}, failure = {
//authentication failure, check exception
}
)
}
}
}
```
### **abortUserAuthenticationForPayment**
Asynchronous. Offline.
Abort user authentication during ongoing transaction. After calling this method transaction is cancelled and timer stopped. |
**Input**
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun abortUserAuthenticationForPayment() {
ucpApi
.paymentService
.abortUserAuthenticationForPayment(
{
//user authentication aborted
//listen for auth timer changes
},
{ throwable ->
//some error, check exception
})
}
```
### **processHceApduCommand**
Synchronous. Offline.
Processes APDU command from Point Of Sale (PoS) terminal. Returns callback APDU command to pass back to PoS.
Should be called inside registered Android Service extending HostApduService in implementation of overridden processCommandApdu method. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| context |
Context |
Application context, can be provided from HostApduService |
Not empty |
| apdu |
ByteArray |
APDU command from HostApduService::processCommandApdu method parameter |
Not empty |
| extras |
Bundle? |
Extras object from HostApduService::processCom mandApdu method parameter |
|
**Output**
| Apdu result - method called synchronous without callback |
| Parameter. |
Type |
Description |
| apdu |
ByteArray |
APDU command to return in implementation of overridden processCommandApdu method |
**Sample (synchronized HostApduService)**
Use this version if MobileDC:setup and UCP:setup() method is called in Application:onCreate on Main Thread.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(this, commandApdu, extras)
}
//..
}
```
**Sample (aynchronous HostApduService)**
Use this version if SDK is called on another thread and HostApduService can receive APDU until VCP SDK is still in loading state.
```
//WalletHceService must be registerd in AndroidManifest as nfc service
class WalletHceService : HostApduService() {
//...
//private val ucpApi = ..
override fun processCommandApdu(commandApdu: ByteArray, extras: Bundle?): ByteArray? {
//UcpSdkStateApplicationSingleton is sample class which keep SDK state and allow to observe when SDK load is finished
if (UcpSdkStateApplicationSingleton.isLoaded()) {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
} else {
sendResponseApdu(null)
UcpSdkStateApplicationSingleton.listenForSdkReady(
onSdkLoadListener = {
val result = processCommandApduInUcpSdk(context, commandApdu, extras)
sendResponseApdu(result)
}
)
}
return null
}
override fun onDeactivated(reason: Int) {
if (UcpSdkStateApplicationSingleton.isLoaded()) {
return ucpApi
.paymentService
.handleHceApduDeactivationEvent(reason)
}
}
private fun processCommandApduInUcpSdk(
context: Context,
commandApdu: ByteArray,
extras: Bundle?
): ByteArray? {
return ucpApi
.paymentService
.processHceApduCommand(context, commandApdu, extras)
}
}
//sample objec which helps to listen SDK state
object UcpSdkStateApplicationSingleton : UcpSdkState {
//flag could be synchronized
private var isLoaded = false
private var onSdkLoadListener: (() -> Unit)? = null
override fun listenForSdkReady(onSdkLoadListener: () -> Unit) {
this.onSdkLoadListener = onSdkLoadListener
if (isLoaded) this.onSdkLoadListener?.invoke()
}
//call when SDK loading thread is finished
//setupMdc() -> setupUcp() -> UcpSdkStateApplicationSingleton.onUcpSdkLoaded()
override fun onUcpSdkLoaded() {
isLoaded = true
onSdkLoadListener?.invoke()
}
override fun isLoaded(): Boolean {
return isLoaded
}
}
```
### **replenishCredentials**
Asynchronous. Online. User login session not required.
Method for manually replenishing payment credentials.
Application will receive push notification and notified about replenish process with global callback described in setup chapter. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument that needs it credentials replenished |
Not empty |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun replenishCredentials(paymentInstrumentId: String) {
ucpApi.paymentService
.replenishCredentials(paymentInstrumentId,
{
//request for credentials replenish finished with success
//wait for push notification and pass to valid module
//when push processed application will be informed about replenish success/failure
//read chapter with setup for more information
},
{ throwable ->
//Something went wrong, check exception with documentation
})
}
```
### **restartContactlessAuthTimer**
Asynchronous. Offline.
Resets auth timer during payment. After calling method auth countdown will start again with default value from card profile.
Default auth time is provided by card profile. |
**Input**
**Output**
| Success / failure callback |
### **requestAuthenticationCodeForPayment**
Asynchronous. Online.
Method dedicated for requesting authentication code for payment. Authentication code is delivered via Issuer. Only one valid Authentication Code can exist at a time for a given paymentInstrumentId and authenticationRequestId. Multiple valid codes can exist for the same token if different authenticationRequestIds are provided each in a different call. Once an Authentication Code has been generated for a given paymentInstrumentId and authenticationRequestId, it will be valid for a limited validity period, after which the code will expire. Method can be called again with the same authenticationRequestId and token unique reference , in order to trigger re-send. When an active authentication code exists for a given paymentInstrumentId and authenticationRequestId it is delivered again to the issuer. If the code has expired or the attempts has been exceeded then new code will be generated. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| requestAuthenticationCodeForPayment |
RequestAuthenticationCodeForPayment |
Plain RequestAuthenticationCodeForPayment object |
Not empty |
RequestAuthenticationCodeForPayment object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| authenticationRequestId |
String |
Authentication request id up to 64 alphanumeric characters long.
A new id should be used for each instance than an account holder needs to be authenticated |
Not empty |
**Output**
| Success callback/failure callback. |
**Sample**
```kotlin
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment) {
ucpApi.paymentService
.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//Requesting Authentication Code went successfully.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **validateAuthenticationCodeForPayment**
Asynchronous. Online.
Method dedicated for validation of an Authentication Code generated by the requestAuthenticationCodeForPayment() method. It is given limited number of attempts to enter a correct Authentication Code(typically 3 attempts), after which the Authentication Code becomes invalid. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| validateAuthenticationCodeForPayment |
ValidateAuthenticationCodeForPayment |
Plain ValidateAuthenticationCodeForPayment object |
Not empty |
ValidateAuthenticationCodeForPayment object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| authenticationRequestId |
String |
Authentication request id provided to the requestAuthenticationCodeForPayment when the authentication code was requested. |
Not empty |
| authenticationCode |
String |
Authentication Code to authenticate the account holder |
Not empty |
**Output**
| Success callback with ValidateAuthenticationCodeForPaymentResult object. |
ValidateAuthenticationCodeForPaymentResult object contains following field
| Parameter |
Type |
Description |
| signedAuthenticationProcessData |
String |
Signed AuthenticationProcessData per RFC 7519 |
AuthenticationProcessData model
| Parameter |
Type |
Description |
| authenticationRequestId |
String |
Authentication request id |
**Sample**
```kotlin
fun validateAuthenticationCodeForPayment(validateAuthenticationCodeForPayment: ValidateAuthenticationCodeForPayment) {
ucpApi.paymentService
.validateAuthenticationCodeForPayment( validateAuthenticationCodeForPayment,
{ validateAuthenticationCodeForPaymentResult ->
//ValidateAuthenticationCodeForPaymentResult plain object,
//contains data to validate on backend
val signedAuthenticationProcessData = ValidateAuthenticationCodeForPaymentResult
.signedAuthenticationProcessData
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Sample verification of signedAuthenticationProcessData (see *Data signing and encryption* chapter in Mobile DC documentation)
```
class SignedAuthenticationProcessData {
fun verifyAndGetAuthenticationRequestID() {
val jwtClaimsSet = JWTVerifier.verify(signedAuthenticationProcessData, rsaPublicKey, 600);
val authenticationRequestId = jwtClaimsSet.getStringClaim("authenticationRequestId")
// ...
}
}
```
### **processDsrpTransaction(deprecated)**
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Payment instrument identity |
Not empty |
| dsrpTransactionInfo |
DsrpTransactionInfo |
|
|
**Output**
| Success callback with cryptogram for payment |
### **processDsrpTransaction**
Asynchronous. Offline.
Method dedicated for starting DSRP transaction.
Every DSRP transaction has to be authenticated before processing.
Depending on implementation payment can be process with OTP authentication or device level authentication. |
| Parameter |
Type |
Description |
Validation conditions |
| processDsrpTransaction |
ProcessDsrpTransaction |
Plain ProcessDsrpTransaction object |
Not empty |
ProcessDsrpTranasction object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Identifier of payment instrument |
Not empty |
| dsrpTransactionInfo |
DsrpTransactionInfo |
Plain DsrpTransactionInfo object |
Not empty |
DsrpTransactionInfo object contains following fields
| Parameter |
Type |
Description |
Validation conditions |
| amountMinor |
Long |
A long representing the transaction amount without the decimal. For instance 119.00 USD will be 11900 |
Not empty |
| currencyCode |
String |
A char (integer) representing the transaction currency code with 3 numeric digits as per ISO 4217. For instance, value will be 840 for USD. The maximum value allowed is 999. |
Not empty |
| countryCode |
String? |
A 3 digit ISO 3166 numeric country code, e.g., 826 for UK. If not sent, this value is initialized with 000. |
|
issuer
Cryptogram
Type |
DsrpIssuer
Cryptogram
Type |
Enum with value represented by "UCAF" or "DE55" depending on cryptogram data format is to be used. |
Not empty |
unpredictable
Number |
Long |
A long representing the random number generated by the merchant or by the Payment Gateway. The maximum value is 4,294,967,295. |
Not empty |
| transactionType |
Dsrp
Transaction
Type |
A type of financial transaction, one of: PURCHASE, CASH, PURCHASE\_WITH\_CASHBACK, REFUND |
Not empty |
| transactionDate |
Date? |
A Date object indicating date of transaction. |
|
**Output**
| Success callback with ProcessDsrpTransactionResult object. |
ProcessDsrpTransactionResult object contains following field
| Parameter |
Type |
Description |
transaction
Cryptogram
Data |
ByteArray |
A byte array containing a formatted response, either UCAF or a set of TLV data for the merchant to populate DE55 data. |
| pan |
String |
String containing the PAN of the card used. |
panSequence
Number |
Int |
An integer value specifying the PAN Sequence Number (PSN) of the card used. |
| cryptogramType |
DsrpIssuer
Cryptogram
Type |
Enum value as UCAF or DE55 depending on cryptogram data format is used. |
| track2Data |
String |
String containing the data elements of track 2 according to ISO/IEC 7813. |
| par |
String |
String representation of byte array of permanent account reference. A non-financial reference assigned to each unique PAN and used to link a Payment Account represented by that PAN to affiliated Payment Tokens. |
| expirationDate |
String |
Date in ISO-8601 (YYYY-MM-DD) format indicating expiry date of the card. |
| transactionId |
String |
Hexed byte array containing a Transaction Identifier. |
**Errors**
DsrpPaymentException exception throwed on error in DSRP processing
| DsrpPaymentException.reason |
Description |
| DSRP\_INVALID\_INPUT |
Invalid input data. |
| DSRP\_UNEXPECTED\_DATA |
Provided data is valid in context of validation, but doesn't mee |
| DSRP\_AUTHENTICATION\_REQUIRED |
Authentication is not provided for DSRP payment. Authenticate and process DSRP transaction again. |
| DSRP\_TOKEN\_INACTIVE |
Token used for DSRP is inactive. |
| DSRP\_NO\_TRANSACTION\_CREDENTIALS |
There is no transaction credentials to procees DSRP payment |
| DSRP\_NOT\_SUPPORTED\_BY\_CARD |
DSRP is not suported by Card. |
| DSRP\_TRANSACTION\_DECLINED |
Transaction is declined by Card. |
| DSRP\_INCOMPATIBLE\_PROFILE |
Card profile is incomaptible with DSRP. |
| DSRP\_WRONG\_STATE |
DSRP transaction is in wrong state. |
| DSRP\_INTERNAL\_ERROR |
Unknowne error during DSRP processing. |
**Sample** **DSRP transaction with device level authentication**
```
// After Merchant App delivers DSRP data application should authenticate user with device level authentication
// and next execute setUserAuthenticationForPayment().
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTranasctionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample DSRP transaction with OTP authentication**
```
// After Merchant App delivers DSRP data user should request authentication
// code for payment with selected paymentInstrument.
// Values for DsrpTransactionInfo delivered by Merchant APP
val dsrpTransactionInfo: DsrpTransactionInfo =
DsrpTransactionInfo(amount, currencyCode, countryCode, issuerCryptographyType)
val processDsrpTransaction: ProcessDsrpTransaction =
ProcessDsrpTransaction(paymentInstrumentId, dsrpTransactionInfo)
val requestAuthenticationCodeForPayment: RequestAuthenticationCodeForPayment =
RequestAuthenticationCodeForPayment(paymentInstrumentId, authenticationRequestId)
fun requestAuthenticationCodeForPayment(requestAuthenticationCodeForPayment) {
ucpApi.paymentService.requestAuthenticationCodeForPayment( requestAuthenticationCodeForPayment,
{
//When requesting went successfully User will get authentication code.
//In next step authentication code should be passed to MPA and application
//should validate this code with validateAuthenticationCode() method
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
val validateAuthenticationCode: ValidateAuthenticationCode =
ValidateAuthenticationCode(paymentInstrumentId, authenticationRequestId, authenticationCodeProvidedByUser)
fun validateAuthenticationCode(validateAuthenticationCode) {
ucpApi.paymentService
.validateAuthenticationCode( validateAuthenticationCode,
{ validateAuthenticationCodeResulty ->
//ValidateAuthenticationCodeResult plain object
val signedAuthenticationProcessData = validateAuthenticationCodeResulty
.signedAuthenticationProcessData
//If validation went successfully MPA should show authentication view,
//and after valid authentication MPA should execute setUserAuthenticatedForPayment()
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
private fun setUserAuthenticatedForPayment(
paymentInstrumentId: String,
pinProvidedByUser: CharArray
) {
ucpApi
.paymentService
.setUserAuthenticatedForPayment(paymentInstrumentId, pinProvidedByUser,
{
//After succesfully authentication for payment MPA should execute processDsrpTransaction()
}, { throwable ->
//some error, check exception
})
}
fun processDsrpTransaction(processDsrpTransaction : ProcessDsrpTransaction) {
ucpApi.paymentService
.processDsrpTransaction( processDsrpTransaction,
{ processDsrpTransactionResult ->
//DSRP transaction result with details went successfully result
//should be delivered to Merchant APP
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
**Sample input and output DSRP data:**
```Java
Input:
amountMinor: 4321,
countryCode: 840,
currencyCode: 840,
issuerCryptogramType: UCAF,
transactionDate: Apr 25, 2023 09:41:05, //Date() toString() format
transactionType: PURCHASE,
unpredictableNumber: 29496729
Output:
pan: 5204830959972699
track2Data: 5204830959972699D26052010000000000000
expirationDate: 2026-05-31 //YYYY-MM-DD
par: 500170A4PEV2GLWPFD00N6H5AX2YB
panSequenceNumber: 0
transactionId: df25a522a075680acbaa407fdc8a0348a321f77afa2f0231cd38f28e7ae691e2
cryptogramType: UCAF
transactionCryptogramData: 414d506a6d4a474650306149414155427768575a47674144464b553d //in Hex
```
Cloud messaging domain
### **process (deprecated in 2.6.7)**
Asynchronous. Online. User login session not required.
Processes data sent by VCP backend (push notification data).
Application should check senderId in RemoteMessage object (RemoteMessage::from method) and check source in Mobile DC SDK before passing data to this method.
Method can throw InvalidPushException in case of invalid push content passed to it.
Refer Mobile DC documentation how to handle push.
Deprecated in 2.6.7, use MobileDC:CloudMessaging:process() instead. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| pushData |
Map |
Data received from notification service in object RemoteMessage object |
Not empty |
**Output**
| Success / failure callback. When request fails try again |
**Sample**
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String = remoteMessage.from
val pushData = remoteMessage.data
//check push source only when push source is uPaid sender Id
if (isUpaidSenderId(senderId)) {
//checking push source and passing to proper uPaid module
mobileDcApi
.cloudMessagingService
.getSource(pushData, { source ->
when (source) {
"UCP" -> processUcpPush(pushData)
}
}, {
//some error
})
} else {
//proceed push from another source
}
}
private fun processUcpPush(pushData: Map) {
ucpApi
.cloudMessagingService
.process(pushData, {
//push processed in Mobile DC
}, {
//some error
})
}
```
### **processMcbpNotificationData**
Asynchronous. Offline.
Processes data sent by MCBP.
Application should check senderId in RemoteMessage object before passing data to VCP SDK.
Basic configuration for push processing from External Wallet Server: External Wallet Server domain.
Method can throw InvalidPushException in case of invalid push content passed to it.
Note: External Wallet Server Registration process mus be finished before push processing. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| encryptedPayload |
String |
Data received from notification service in object RemoteMessage object |
Not empty |
**Output**
| Success / failure callback |
```
//FirebaseMessagingService class from Firebase
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val senderId: String? = remoteMessage.from
val pushData = remoteMessage.data
//check push source based on senderId
if (isVerestroSenderId(senderId)) {
val verestroPayload: String = readVerestrpPushContent(pushData)
ucpApi
.cloudMessagingService
.processMcbpNotificationData(verestroPayload, {
//push processed in VCP
}, {
//some error
})
} else {
//proceed push from another source
}
}
```
External Wallet Server domain
Chapter contains method for SDK when External Wallet Server is used.
Usage of method requires additional configuration with external API.
Basic MDES cloud messaging configuration:
| Environment |
FCM Sender Id |
| MTF |
502118574555 |
| PRODUCTION |
993764297204 |
### **prepareRegistrationData**
Asynchronous. Offline.
Method for preparing data used for activation.
Should be used before calling register method. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentAppInstanceId |
String |
Identifier for the specific Mobile Payment App instance |
Not empty |
| paymentAppProviderId |
String |
Globally unique identifier for the Wallet Provider, as assigned by MDES |
Not empty |
| publicKeyCertificate |
String |
CMS-D public key certificate in pem format |
Not empty |
| mobilePin |
CharArray? |
Mobile PIN used to payment confirmation |
|
**Output**
| Success callback with PrepareRegistrationResponse object. |
| Parameter |
Type |
Description |
| publicKeyCertificateFingerprint |
String |
CMS certificate fingerprint. Used algorithm: hex(sha1(certificate.encoded)) |
| encryptedRgk |
String |
Encrypted randomly-generated 128-bit AES key. |
| deviceInfo |
EwsDeviceInfo |
Device info. |
| deviceFingerprint |
String |
Unique device fingerprint. |
| encryptedPin |
String? |
Encrypted pin (if passed in input). |
EwsDeviceInfo model:
| Parameter |
Type |
Description |
| deviceName |
String |
Device model name. |
| formFactor |
String |
The form factor of the target provisioned device. |
| storageTechnology |
String |
The architecture or technology used for token storage. |
| osName |
String |
The name of the operating system of the target provisioned device. |
| osVersion |
String |
The version of the operating system of the target provisioned device. |
| nfcCapable |
Boolean |
Whether the target provisioned device has NFC capability. |
**Sample**
```kotlin
fun prepareRegistrationData(
paymentAppInstanceId: String,
paymentAppProviderId: String,
publicKeyCertificate: String,
mobilePin: CharArray?) {
ucpApi
.ewsService
.prepareRegistrationData(paymentAppInstanceId,
paymentAppProviderId,
publicKeyCertificate,
mobilePin,
{ prepareRegistrationResponse ->
//Prepared data for registration including encryptedMobilePin if mobilePin is used
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **register**
Asynchronous. Online.
Method used for registration new Mobile Payment App instance with MDES for use. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| mobileKeysetId |
String |
Identifies the Mobile Keys used for this remote management session |
Not empty |
| ewsMobileKeys |
EwsMobileKeys |
Contains the mobile keys used to secure the communication during subsequent remote management sessions |
Not empty |
| remoteManagementUrl |
String |
The URL endpoint for subsequent remote management sessions
The Mobile Payment App must store this URL for future use in order to be able to request new remote management sessions |
Not empty |
EwsMobileKeys
| Parameter |
Type |
Description |
| transportKey |
String |
The Mobile Transport Key used to provide confidentiality of data at the transport level between the Mobile Payment App and MDES |
| macKey |
String |
The Mobile MAC Key used to provide integrity of data at the transport level between the Mobile Payment App and MDES |
| dataEncryptionKey |
String |
The Mobile Data Encryption Key used to encrypt any sensitive data at the data field level between the Mobile Payment App and MDES |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun register(
mobileKeysetId: String,
ewsMobileKeys: EwsMobileKeys,
remoteManagementUrl: String) {
ucpApi
.ewsService
.register(mobileKeysetId, ewsMobileKeys, remoteManagementUrl,
{
//Device registration success
//application should listen to push messages and UcpPaymentInstrumentEventListener callbacks
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **activate**
Asynchronous. Online.
Method to activate PaymentInstrument.
Should be used only on PaymentInstrumens which PaymentInstrumentStatus is SUSPENDED or INACTIVE.
Changes PaymentInstrumentStatus to ACTIVE, calls for transaction credentials replenish and set PaymentInstrument as default for payment when no other PaymentInstrument is available.
Method can be used when onProvisioningSuccess callback is trigerred to instantly activate card. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to activate. |
Not empty. |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun activate(paymentInstrumentId: String) {
ucpApi
.ewsService
.activate(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to ACTIVE, set card as default for payment if another
//is not already setted Performing replenish,
//application should listen to push message with information about replenish success/failure
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **suspend**
Asynchronous. Offline.
Method for suspending paymentInstrument.
Changes PaymentInstrumentStatus to SUSPENDED.
Use activate method to allow payments again. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to suspend. |
Not empty. |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun suspend(paymentInstrumentId: String) {
ucpApi
.ewsService
.suspend(paymentInstrumentId,
{
//Changes PaymentInstrumentStatus to SUSPENDED.
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getPaymentInstrument**
Asynchronous. Offline.
Method for getting single PaymentInstrument from local storage object based on id. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to get. |
Not empty. |
**Output**
| Success callback with PaymentInstrument object. |
| Parameter |
Type |
Description |
| paymentInstrument |
PaymentInstrument |
Retrieved paymentInstrument |
**Sample**
```kotlin
fun getPaymentInstrument(paymentInstrumentId: String) {
ucpApi.ewsService
.getPaymentInstrument(paymentInstrumentId,
{ paymentInstrument ->
//PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getAllPaymentInstruments**
Asynchronous. Offline.
Method for getting all payment instruments from local storage. |
**Input**
**Output**
| Success callback with list of PaymentInstrument objects. |
| Parameter |
Type |
Description |
| paymentInstruments |
List |
List of retrieved payment instruments from local storage |
**Sample**
```kotlin
fun getAllPaymentInstrument() {
ucpApi.ewsService
.getAllPaymentInstruments(
{ paymentInstruments ->
//List of PaymentInstrument from local storage
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
### **getEncryptedPin**
| Asynchronous. Offline.\ |
Method for encrypting mobilePin. When updated on MDES call method onMobilePinChganged. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| pin |
CharArray |
PIN to encrypt. |
Not empty. |
**Output**
| Success callback with encrypted mobile PIN. |
| Parameter |
Type |
Description |
| encryptedMobilePin |
String |
Hex encoded encrypted mobile PIN. |
**Sample**
```kotlin
fun getEncryptedPin(pin: CharArray) {
ucpApi
.ewsService
.getEncryptedPin(pin, { encryptedPin ->
//call to Wallet Server with new created encrypted mobile PIN
//when updated call onMobilePinChanged method
}, {
//Something went wrong, check exception with documentation
})
}
```
### **onMobilePinChanged**
Asynchronous. Online.
Method for informing SDK about mobilePin change.
Should be used when mobilePin changed.
The result of action is deletion of existing transaction credentials and replenish. |
**Input**
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun reactOnMobilePinChanged() {
ucpApi
.ewsService
.onMobilePinChanged(
{
// Informing SDK about changing mobile pin processed succesfully.
// SDK should delete and next replenish transaction credentials.
// Listen for UcpPaymentInstrumentEventListener events
}, { throwable ->
// Something went wrong, check exception with documentation.
})
}
```
### **delete**
Asynchronous. Online.
Method to removing PaymentInstrument.
Removed transaction credentials and PaymentInstrument from local storage and in MDES.
When success PaymentInstrument will be no longer available in getPaymentInstrument and getPaymentInstruments methods. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| paymentInstrumentId |
String |
Id of paymentInstrument to delete. |
Not empty. |
**Output**
| Success / failure callback |
**Sample**
```kotlin
fun delete(paymentInstrumentId: String) {
ucpApi
.ewsService
.delete(paymentInstrumentId,
{
//Selected Payment instrument is removed
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Assets Domain
### **getAsset**
Asynchronous. Online.
Method for getting all assets for selected assetId. |
**Input**
| Parameter |
Type |
Description |
Validation conditions |
| assetId |
String |
Id of assets to retrive |
Not empty |
**Output**
| Success callback with list of Assets objects. |
| Parameter |
Type |
Description |
| ucpAsset |
UcpAsset |
Plain UcpAsset object |
UcpAsset object contains following field
| Parameter |
Type |
Description |
| content |
List |
Plain list of UcpAssetContent objects |
UcpAssetContent contains following fields.
| Parameter |
Type |
Description |
| data |
String |
The data for this asset. Base64-encoded data, given in the format as specified in type. |
| type |
String |
The data MIME type. One of: application/pdf, text/plain, text/html, image/png, image/svg+xml, image/pdf. |
| width |
Long? |
For image assets, the width of this image. Specified in pixels. |
| height |
Long? |
For image assets, the width of this image. Specified in pixels. |
**Sample**
```kotlin
fun getAsset(assetId: String) {
ucpApi.assetsService
.getAssets( assetId,
{ ucpAsset ->
//List of assets of selected assetId
val ucpAssetContentList = ucpAsset.content
},
{ throwable ->
//Something went wrong, check exception with documentation
}
)
}
```
Document changelog
Vesion 2.10.10
- Added new field for digitization: *formFactor*
- Mobile DC updated to 2.17.3
Vesion 2.10.0
- Introduced support for 16kb page sizes: [https://developer.android.com/guide/practices/page-sizes](https://developer.android.com/guide/practices/page-sizes)
- Security tools updated to newest version
- Kotlin version updated to 2.0.21(minimum Kotlin version in an application using SDK is 1.8.22)
- AGP updated to 8.11.1
- Mobile DC updated to 2.17.0
Version 2.9.10
- Added new parameter *transactionId* to method *onContactlessPaymentCompleted* for Mastercard transactions.
New transaction identifier allow to match transaction with processed transaction notification *MobileDC::EventNewTransaction::clientTransactionId.*
- Mobile DC updated to 2.16.12
Version 2.9.8
- **IMPORTANT: Security tools updated to newest version. Recommneded update when using version 2.9.x due to changes fixes in security tools.**
- Visa SDK updated to 6.4.0
- Mobile DC updated to 2.16.10
Version 2.9.5
- Added MC *mtf* host name
- Update Mobile DC to 2.16.5
Version 2.9.4
- **Important:** Apply security and functional certification changes related to intruduction new security tools. Changes in security thread management and working in background
- Update Mobile DC to 2.16.4
Version 2.8.7
- Update Mobile DC to 2.15.8
Version 2.8.6
- Small fixes to 2.8.5
Version 2.8.5
- Update Proguard rules related to R8 changes
Version 2.8.2
- Added new field "externalPaymentTokenId" in DigitizationGreenPath, DigitizationRequest and DigitizationResult models.
- Added new optional configuration withOptionalWalletMcbpHttpExecutor
- Marked configuration withUcpTransactionEventListener from UcpConfigurationBuilder as deprecated. Use MobileDcTransactionEventListener.optionalMobileDcTransactionEventListener from MDC SDK instead.
Version 2.7.4
- Added new field "paymentTokenExpirationDate" in PaymentInstrument model.
Version 2.7.3
- update MobileDC dependency to 2.15.3
Version 2.7.1
- update MobileDC dependency to 2.15.1
Version 2.7.0
- update MobileDC dependency to 2.15.0
Version 2.6.9.2
- update MobileDC dependency to 2.14.7.2
Version 2.6.9.1 - Hotfix possible OutOfMemoryException in MDC 2.14.7
- update MobileDC dependency to 2.14.7.1
Version 2.6.9 - don't use, could cause OOM Exception
- Updated Mobile DC dependency to 2.14.7.
- Updated *processDsrpTransaction* method.
Version 2.6.7
- Updated Mobile DC dependency to 2.14.6
- Added support for Mastercard India datacenter.
- **important** Added new method to UcpTransactionEventListener - *onContactlessPaymentStarted()***.** Callback allows application to get event about new transaction and it's a best place for token selection and user authentication. Read more in Product Overview.
- Due to adding new place for contactless payment authentiocation also updated code samples for *HostApduSevice* implementation and method *setUserAuthenthenticatedForPayment()*
- **Important** CloudMessagingService:process became deprecated due to introducing delivery message from server service. Read more in Product Overview and Mobile DC specification.
- **Important** Added new status *AbortReason:CONNECTION\_LOST* for *UcpTransactionEventListener:onContactlessPaymentAborted.* Status TERMINAL\_INACTIVITY\_TIMEOUT became deprecated. Change significally improves contactless payment UX. Method works immediatelly when connection between device and terminal is lost.
- **Important** Aded new optional configuration for *UcpTransactionConfiguration* with field *enableTransactionAuthenticationTimer.* Timer is now disabled by default, previously was always enabled and could cause problems when authentication time leading to zero and user performs transaction. It could cause clearing user authentication during processing payment on terminal. Change is related to other payments optimizations and introducing *onContactlessPaymentStarted()* and new *AbortReason CONNECTION\_LOST.* Please align your code to new changes, enabling timer is not recommended.
- Updated Mobile DC dependency to 2.13.7
- Resolved Google Play Console Security warning
- Updated Mobile DC dependency to 2.13.6
Version 2.5.5
- Wrap in try-catch block callbacks from SDK *setup()* method to prevent breaking process in SDK. Read more in *setup*() method description.
Version 2.5.3
- Update internal libraries. **IMPORTANT** Read more in Mobile DC changelog for version 2.13.3
Version 2.5.2
- Fixed UcpMcbpHttpExecutor from version 2.5.1. The issue doesn't impact on other functionality
Version 2.5.1
- Methods marked as deprecated:
- reset (use restart instead)
- getPaymentInstrument (use getAllPaymentInstruments instead)
- setDefaultForRemote (usage is redundant)
- getDefaultForRemote (usage is redundant)
- processDsrpTransaction(use new processDsrpTransaction method with *ProcessDsrpTransaction* added model)
- Added new methods related to OTP authentication code:
- requestAuthenticationCodeForPayment
- validateAuthenticationCodeForPayment
- Added new methods for supporting yellow-path token activation:
- checkEligibility
- digitize (new version with support for checkEligibility usage)
- submitTokenAuthenticationMethod
- submitTokenAuthenticationValue
- getAdditionalAuthenticationMethods
- Fixed getPaymentInstrument method (case invalid error when session expired error occurred).
- Updated Kotlin version to 1.5.31 and Koin to 2.1.6.
- Removed unused permissions *ACCESS\_FINE\_LOCATION* and *com.google.android.c2dm.permission.RECEIVE .*
- Added logs for all facade methods (available in SDK debug version).
Version 2.4.4
- Updated MDC SDK to 2.12.1 - fixed aggressive security process check
- Updated documentation for TransactionAbortReason:TERMINAL\_INACTIVITY\_TIMEOUT model
Version 2.4.3
- IMPORTANT Update security tools after EMV Security Evaluation - refer to Mobile DC technical documentation version changelog (version 2.12.0)
- Update Gradle and R8 tools
- Handled authentication flow for ContactlessRichTransactionType REFUND. SDK requires authentication if not provided.
- Improved description for ContactlesssTransactionResult model in documentation.
- Added new ContactlessRichTransactionType: WITHDRAWAL and ATM\_CONTACTLESS
Version 2.3.24
- Added new state for TransactionAbortReason::TERMINAL\_INACTIVITY\_TIMEOUT. Previously status was part of TransactionAbortReason::TERMINAL\_ERROR and produces contactless payment aborted handling problems. Status is used in onContactlessPaymentAborted callback. Application can ignore this state and do not perform any action.
- Added method on UcpApi for SDK restart(). Unlike reset() new method is asynchronous and allows to usage VCP SDK without application kill. Method clears all VCP SDK data and restarts to initial state.
- Introduced new approach to handling security issue. When application will call any SDK method after security issue reporting, UcpSkdExpcetion with SECURITY\_EVENT\_OCCURRED will be returned. Previously APPLICATION\_PROCESS\_NOT\_KILLED was returned. Change doesn't impact onSecurityIssue callback.
- Added Assets Domain and getAsset() method.
- Added verification of input parameters in token profile and transaction credentials replenish.
- Added more details in callbacks onProvisioningFailure and onReplenishFailure about errors in token related operations.
Version 2.3.22.2 - hotfix
- Added more validation for input parameters for External Wallet Server service
- Added data verification before accessing data in CMS-D processes
- Improved catching exceptions for MCBP processes
- Improved flow for reset() method - added protection agains processing messaging after SDK reset()
- Changed algorithm for calculating publicKeyCertificateFingerprint in PrepareRegistrationDataResponse. From hex(sha1(certificate.publicKey.encoded)) to hex(sha1(certificate.encoded))
- Added support for multiple calling setUserAuthenticatedForPayment() method
Version 2.3.22
- Improved internal SDK logs reporting
- Using androidX in end project is necessary now
- Improved automatic replenish credentials process
- Added handling ReDigititzation process in SDK. Use withOptionalReProvisionEventListener method in SDK setup method to observe PaymentInstrument changes
Version 2.3.21
- Added optional UcpHttpExecutor for handling CMS-D communication to UcpConfiguration
- Replenish process optimization
Version 2.3.18
- Updated security libraries
Version 2.3.17
- Fixed parsing merchantAndLocation field from ContactlessTransactionData.
- Added EWS configuration parameter in setup.
Version 2.3.13
- Added new parameter *result* to IbanDigitizationResult model
- Parameter *cloudDigitizationSuccess* in IbanDigitizationResult is now deprecated
Version 2.3.12
- Core module with update.
- Added new reports to Wallet Server.
Version 2.3.11
- Added new method in Payment Service: processDsrpTransaction
- Added new method in User Service: resendOtp
- Added new paremeter in createPaymentData IbanInfo model: userId
- Improved default PaymentInstrument management
- Fixed clearing SDK state when unpairing device (MobileDC unPair method)
Version 2.3.8
- Improved facade exception throwing, now contains more details about error.
- Removing whitespaces from merchantAndLocation in ContectlessTransactionData model
- Updated security harmful process check mechanism
- Added MCBP cloud messaging queue handling to prevent processing errors
Version 2.3.2
- Fixed SDK provisionning process on Google Pixel devices
- Improved default Payment Instrument management
- Updated security harmful process check mechanism
Version 2.3.1
- Added *delete* method in External Wallet Server domain
- Added more detailed descriptions for methods from External Wallet Server domain
- Added more information about models related to payment processing
Version 2.2.7
- Added reset functionality.
- Addded method in Ibans service createPaymentDat.
- Method createTVC iban service is now deprecated.
- Added global listener for most important internal SDK actions related to token managem
Version 2.2.6
- Added new exception parameter to EventContactlessPaymentAborted, EventContactlessPaymentIncident, EventReplenishFailure, EventProvisioningFailure
- Fixed problem with flow cutting on digitalization process
Version 2.2.4
- Added new enum state TransactionAbortReason.NO\_CARDS. Callback onContactlessPaymentAborted is now called when no card is available for payment.
- Added new model ContactlessTransactionData with better formatting terminal data. New object is added for events EventGetFinalDecision, EventAuthRequiredForContactless, EventContactlessPaymentCompleted.
- ContactlessTransactionInformation is now deprecated.
Version 2.2.3
- Fixed setting default PaymentInstrument after activation
- Fixed doubled callback onPaymentInstrumentStatusChanged for DELETED status
Version 2.2.2
- Fixed dependencies conflicts
- Consumer Proguard rules update
- Certificate pinning implementation improvement
Version 2.2.0
- Added new method in EWS Service - getEncryptedPin
- SDK startup optimization
Version 2.1.1
- Fixed dependencies for release version
- Added information about SDK size
- Added information about SDK integration on lower Android API level
Version 2.1.0
- Added new methods in External Wallet Server domain (activate, suspend, getPaymentInstrument, getPaymentInstruments, onMobilePinChanged)
Version 2.0.0
- Changed approach to SDK setup
- Added UcpSdkException
- Added new reason codes to existing exceptions
- New methods in cards domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in ibans domain: digitize, getPaymentInstrument, getAllPaymentInstruments, delete
- New methods in cloud messaging domain: processMcbpNotificationData
- New methods in payment domain: abortUserAuthenticationForPayment, replenishCredentials, restartContactlessTimer
- New methods in external wallet server domain: prepareRegistrationData, register
Version 1.0.1
- Created
# Watch integration
The Watch Payment product allows payments using Watch connected to Android and iOS smartphones. Payments are based on the MDES Token Requestor solution from Mastercard. Contactless payments are possible without a constant internet connection—both on the smartphone and the smartwatch.
The core payment and token provisioning process is based on the [Token Requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet) product and requires an active project with Mastercard. VCPSDK is a certified and secure product, approved by EMVCo and Mastercard, and has been launched in multiple banking and partner applications.
## Introduction
### **Basic information**
**The Wearables SDK** is an SDK designed to integrate with **Watch as Payment Instrument**. Wearables SDK enabling direct communication between smartwatches and payment systems. It allows to create applications that support contactless payments directly from the Watch, eliminating the need for a paired smartphone during transactions. This streamlined integration offers a secure and efficient way for users to make payments simply by wearing their smartwatch.
**Note:** Product is based on Verestro Cloud Payment solutions for NFC Issuer Wallet with Mobile MasterCard MCBP 2.1 SDK.
See Verestro Product description here [Token Requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet).
### **Requirements**
**Issuer Wallet integration**
Verestro Cloud Payment solutions for NFC Issuer Wallet integration as described [Token Requestor](https://developer.verestro.com/books/token-requestor-issuer-wallet)
**Wearables SDK**
Verestro Wearables SDK for [Android](https://developer-android.verestro.com/wearablessdk/latest/documentation/) or [iOS](https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/)
**Watch Manufacturer**
Integration with Watch Manufacturer
### **Components**
- **Mobile Payment Application (MPA)** - application for integrating Verestro Cloud Payments for safe device&user authentication, card management and tokenization
- **User management MDC SDK (Mobile DC SDK)** - Verestro SDK for device, user and cards management
- **Token Requestor SDK (VCP SDK)** - Verestro SDK for tokenization, token management and payment
- **Wearengine SDK (Wearables SDK)** - Verestro SDK for enabling VCP SDK tokenization on Watch SDK
- **Watch payment SDK** - Verestro SDK for token management and payment on Watch
- **Watch communication SDK** - SDK on the watch for communication with watch.
- **Watch Application** - Verestro integration layer integrated directly to Client's watch application for communication with Wearables SDK and Watch SDK
### **Architecture**
## Use Cases
### **Watch integration**
Connection to Watch is usually realized by Watch's manufacturer application which allow to create connection and pair Watch device with Android/iOS Phone.
Development requires additional configuration on Watch manufacturer store. In order to start integrate Watch in client Mobile Payment Application (MPA) client need to:
- create account on Watch manufacturer Store
- add MPA packageId or bundleId
- configure MPA trusted certificates for signing
### **MPA to Watch Connection**
Connection from MPA to Watch is realized by Watch's manufacturer Library.
Wearables SDK allows to simply use Watch library along Verestro UCP SDK.
### **MPA to Watch Pairing**
Once Watch is connected with MPA it can be used with Watch application for communication with Wearables SDK.
In order to create secure channel to WatchSDK bundled with Watch application UCP SDK must exchange pairing data with WatchSDK.
### **Secure channel for data sending**
During this process Wearables SDK create secure connection between UCP SDK and Watch SDK to send card profile and transaction credentials.
- Every data synchronization requires to create new secure channel.
- Both sender and receiver is verified during connection.
- Process is transparent for MPA.
### **Token creation**
During this process new Token is created for usage on dedicated Watch device.
Verestro SDK allow to create multiple Device along one SDK instance and tokenize same Card for each device.
[ Read more](https://developer.verestro.com/books/token-requestor-issuer-wallet) about Verestro SDK integration in order to tokenization.
### **Add Token to Watch**
During this process new created token for unique device (Watch) is transferred from certified UCP SDK to to Watch SDK using a secure channel.
Transferred Token contains token data to show on Watch UI like last four digits, expiration date and card visual.
### **Add Token Credentials to Watch**
During this process encrypted transaction credentials are transferred to Watch SDK and assigned to Token making it ready for contactless payments.
These credentials are stored on the device, enabling payments even without a constant internet connection or a direct link to the phone.
Process is used both for credentials add after sending token and for data synchronization between UCP SDK and Watch SDK.
### **Token data synchronization**
This process ensures that all token and payment-related data on the watch remains up to date.
During synchronization, both the MPA and the Watch application update the token status (active, suspended, or deleted) and the status of transaction credentials within the Watch SDK.
The Wearables SDK is responsible for maintaining the maximum number of transaction credentials on the Watch SDK to enable standalone payments directly from the watch.
Token and transaction credentials synchronization can be initiated by either the MPA or Watch application and should be performed every time the application is launched.
**Additional Token synchronization use cases**
• token managed by MPA or Client's Admin Panel
• token updated by MasterCard with re-digitization
• application and related tokens ares removed on Phone or Watch
**Additional transaction credentials synchronization use cases**
• sending new transaction credentials along with associated Token
• transaction is performed on Terminal and Watch request synchronization
• finished replenish credentials process on MPA
#### **Synchronization**
Standard communication between MPA and Watch in order to keep both up to date.
#### **Token status update**
Invoked on MPA or remote (Admin Panel) action related to Token.
### **Watch Payment**
Process describes Payment flow on Watch.
- User must unlock Watch to process payment and open Payment application.
- Once the Payment Token is selected, the user can Tap & Pay on a terminal.
- After the payment, the watch should attempt to communicate with the MPA to synchronize the credential state.
#### **Payment authentication**
Transactions must be authenticated, but this does not mean that every transaction requires separate confirmation.
The application uses **Consumer Device Cardholder Verification Method (CDCVM)** to authenticate the user. Depending on specific circumstances, the app may request biometric authentication or a PIN.
Since the service uses on-device authentication, no additional security mechanisms need to be implemented by the integrator.
### **Disabling Payments**
The table below summarizes how different unpairing or blocking scenarios affect smartwatch payment availability.
| **Situation** | **Result** | **Payment availability** |
| Watch is unpaired from the phone via the Wearable Provider's app or the payment app | It is no longer able to process payments. | **Not available** |
| Watch was connected to the phone at the time of unpairing | Stored payment data is automatically deleted from the watch | **Not available** |
| User switches to a new phone or another watch | Payment data cannot be transferred between devices or retained on the watch | **Requires new setup** |
| Payments are blocked through the [Admin Panel](https://developer.verestro.com/books/administration-panel?shelf=6) | Payments are blocked on both the phone and watch | **Not available** |
| User removes the watch pairing from the mobile application | Smartwatch payments are disabled | **Not available** |
This FAQ provides answers to the most common questions related to smartwatch payment integration.
##### **Supported Smartwatch Models**
Which smartwatches are supported?
The following models are supported: - Huawei Watch Ultimate Green
- All models of Huawei Watch 5
- All models of Huawei Watch GT5 and GT5 Pro
- All models of Huawei Fit4 and Fit4 Pro
##### **Verestro Components Required**
What Verestro components are required to enable smartwatch payments?
To enable secure smartwatch payments, the following components are required: - [Watch payment](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/watch-integration) with Wearengine SDK - SDK for integration and communication to the Watch (Android and [iOS](https://developer-ios.verestro.com/wearenginewearablessdk/latest/documentation/))
- [LifeCycle](https://developer.verestro.com/books/user-lifecycle-card-management-api-sdk/page/overview) - for secure card data storage
- [Transaction History Core](https://developer.verestro.com/books/transaction-history-api) - for processing transaction history
- VCP Wallet Server - server-side component of the Verestro Contactless Platform (VCP)
- [MDC SDK](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/technical-documentation-mdc-sdk) and VCP SDK - to be integrated into the mobile application ([Android](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/technical-documentation-vcp-sdk) or [iOS](https://developer.verestro.com/books/token-requestor-issuer-wallet/page/technical-documentation-vcp-sdk-ios))
- [Token Management Platform](https://developer.verestro.com/books/token-management-platform) - required for Issuer Wallet service
##### **Third-party Integrations**
What third-party integrations are needed?
To tokenize payment cards, active connectivity with Mastercard MDES or Visa VTS is required. Each token requestor (bank) must have their own access. Existing connections can be reused if already in place.
##### **AppGallery Connect (AGC)**
How do I create an account on AGC (AppGallery Connect)?
Follow steps on [Appgallery Connect Registration Page](https://id7.cloud.huawei.com/CAS/portal/userRegister/regbyemail.html).
What data from AGC is required for smartwatch payment integration?
After creating the application in AGC, the following identifiers will be available: - MPA packageID
- bundleID
These are used to associate the smartwatch app with the mobile application.
##### **Component Substitution**
Can I replace Verestro components with my own?
The fastest integration path is through the use of all Verestro components. However: - A different Token Management Platform can be used
- Replacing the Wallet Server is possible if adapted to work with the VCP SDK
##### **Device Pairing Limitations**
Can I pair multiple smartwatches with a single smartphone?
No. Only one active smartwatch can be connected to a smartphone at a time. Connecting a new watch will disconnect the previous one.
Can I pair one smartwatch with multiple smartphones?
No. A smartwatch can be connected to only one smartphone at any given time. Pairing with another smartphone will disconnect it from the first one.
##### **Required Setup Processes**
What processes must be completed to enable smartwatch payments?
- User registration - via manual registration or using LifeCycle API provided by the partner.
- User authentication - via password, PIN, or Trusted Identity in case of SDK integration with a partner app.
- Card provisioning - either by importing existing card data or creating a new card via Card Issuing.
- Card digitization - token creation through MDES or VTS. This must be performed separately for smartphone and smartwatch, but can be unified via mobile app UI.
- Smartwatch provisioning - data provisioning and synchronization with the watch.
There are multiple ways to fulfill these requirements. A proper analysis will help determine the most effective approach.
##### **Activating Payments on Smartwatch**
How does a user activate smartwatch payments, step by step?
1. The user installs the payment app on both the smartphone and the smartwatch.
2. If the watch is unsupported, no payment app will be available for download.
3. The user sets the payment app as the default app on the watch and optionally enables double-press shortcut via the hardware button.
4. The user completes required onboarding steps (registration, KYC)
5. Card is created or delivered to Veresto VCP Wallet Server
6. Applications on smartphone and watch deliver payment tokens with processes digitization and provisioning
##### **Supported Smartphone OS Versions**
What smartphone operating system versions are supported?
The last 3 major versions from the current system version are supported. Using the latest available version for a given device is recommended.
##### **Installing the Smartwatch App**
How can I install the payment app on my smartwatch?
Use the Huawei Health application to install the payment app on the smartwatch.
##### **Security & Card Management**
Is the solution secure?
Yes. The service is regularly audited by accredited organizations on behalf of Mastercard and Visa.
What if the smartwatch is lost?
The watch can be remotely removed (unpaired) from the paired mobile application. Customer Service can also assist in watch removal. After removal, no transactions initiated from the lost watch will be accepted.
Can I store multiple cards on one smartwatch?
Yes, each card issued within the Issuer Wallet can be added to the smartwatch, unless restricted by project-specific configurations.
##### **Compatibility with Apple Pay and Google Pay**
Is this solution compatible with Apple Pay or Google Pay?
No. Issuer Wallet is an alternative to Apple and Google Pay. Cards issued or managed within Verestro services cannot be added to Apple Pay or Google Pay, and vice versa.
##### **Setting as Default Payment App**
How do I set this solution as the default payment app?
The default payment app can be set in the system settings of the smartphone or smartwatch. Alternatively, a one-time payment can be initiated directly from the partner app without changing the default payment app.
# Quick introduction to Payments Tokenization
##### **NFC Payments and Issuer Wallets: Simplicity Through Experience**
NFC payments and issuer wallets are among the most complex and often misunderstood areas in the world of digital finance. Mastering them requires not only deep technological knowledge but also expertise that goes far beyond traditional payment processing. What’s more, because these solutions provide direct access to processed funds, they demand the highest standards of security and compliance.
At Verestro, we have learned all these lessons the hard way- and we’ve encapsulated our expertise into easy-to-integrate SDKs. This means that entering the world of NFC payments and issuer wallets with us is as simple as it gets.
**We guide our clients through every step:**
- launching projects with Mastercard and Visa,
- configuring project requirements,
- outlining the needs of every component in the process,
- enabling services even in locations with legal restrictio.
Our SDKs are designed for seamless integration into client applications, and our team is ready to help with even the most complex internal processes. None of these challenges are new to us- we’ve successfully navigated them many times before.
We have real-world experience enabling contactless payments on **Android** and **iOS** devices, and even on **wearables** running dedicated operating systems.
**With Verestro, it’s possible! Let us make NFC payments and issuer wallets easy for you.**