Token Requestor / Issuer wallet

• Article
• Issuer Wallet and Apple Pay / Google Pay - Differences
• NFC on iPhone/iOS
• On-device tokenization in India
• Introduction
• Intro slides
• Overview
• Use Cases
• Use Cases (MDES&VTS)
• Technical documentation
• Technical Documentation VCP SDK
• Technical Documentation VCP SDK - iOS
• Technical Documentation MDC SDK
• Technical documentation VCP External API
• Watch integration
• Watch integration - FAQ
• Quick introduction to Payments Tokenization

Article

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, 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

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 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/
• 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.

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.

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

Intro slides

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.

Implementation Steps

Architecture

Overview

Solution Components

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.

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

MCBP Key Components

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.

Architecture

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.

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.

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

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

Always LVT, HVT - double tap

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

Flexible HVT - single tap

Flexible HVT, LVT with Velocity counters - double tap

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

Card like HVT

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

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:

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:

Payment

Solution delivers multiple options to process and complete payments. Contactless smartphone payments, wearable contactless payments, DSRP, one-tap, two-tap.

Payment history (Optional)

It is possible to store transactions on wallet server. Retrieving data is possible using one of SDK functionalities or dedicated API methods.

Main steps and implementation

Use Cases

Version 2.2
October 2025

This section is dedicated for use cases which can be done by different API and initiated from different sources.

Wallet Server LC API Initiated

This section describes use cases which can be initiated using Wallet Server LC API. This API should be used by 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 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 Payment Token. 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 there is no need to show terms and conditions before every digitization or show card art from MDES. 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 conditions 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). 

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 updated. 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, preconfigured during SDK setup, threshold. If yes then SDK will call replenish. During replenish process transaction credentials are being delivered to mobile application.

@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
SDK->SDK: 1. detectTransactionCredentialsRemainingBelowThreshold
alt Request session if required
activate SDK
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 - 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. No action is needed by 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 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 (user is not able to connect with Internet) 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

Contactless transaction uses Android HCE. On MPA side HostApduService should be implemented. Depending on chosen 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 MPA and Terminal. Transaction Processing with Payment Network 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

In the Integrated implementation model User authentication doesn't occur directly on Wallet Server. Wallet Server will require User authentication when some user data will be requested. If User session token is no longer valid, SDK will return USER_UNATHORIZED error. In such case Trusted Identity needs to be prepared on Issuer server and sent via Wallet SDK in loginByTrustedIdentity method. MPA can decide whether ask User to provide authentication data or not. The latter case regards situation when user is already authenticated and Trusted Identity can be immediately returned from Issuer based on already valid session on Issuer side. 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 information like:

• 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

It is possible that transaction history will be stored on Wallet Server for infinite time. This should be specified during onboarding. If this options is enabled, MPA can retrieve transaction history for given user and filtering. 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

Wallet SDK performs some security checks. When any issue is detected, Wallet SDK reports error to Wallet Server and clears own data. Also notification to MPA is called.

@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
SDK -> SDK: 1. detectSecurityIssue
activate SDK
SDK -> SDK: 2. clearSDKData
SDK -> WS: 3. reportSecurityIssue
activate WS
deactivate WS
deactivate SDK
SDK -> MPA: 4. onSecurityIssueAppeared(event)
activate MPA
deactivate MPA
MPA -> User: 5. show information
@enduml

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)

Version 2.2
October 2025

This section is dedicated for use cases which can be done by different API and initiated from different sources.

Wallet Server LC API Initiated

This section describes use cases which can be initiated using Wallet Server LC API. This API should be used by 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 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 Payment Token. 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 there is no need to show terms and conditions before every digitization or show card art from TSP. 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 conditions 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

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 updated. 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, preconfigured during SDK setup, threshold. If yes then SDK will call replenish. During replenish process transaction credentials are being delivered to mobile application.

@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
SDK->SDK: 1. detectTransactionCredentialsRemainingBelowThreshold
alt Request session if required
activate SDK
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 - 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. No action is needed by 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 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 (user is not able to connect with Internet) 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

Contactless transaction uses Android HCE. On MPA side HostApduService should be implemented. Depending on chosen 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 MPA and Terminal. Transaction Processing with Payment Network 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

In the Integrated implementation model User authentication doesn't occur directly on Wallet Server. Wallet Server will require User authentication when some user data will be requested. If User session token is no longer valid, SDK will return USER_UNATHORIZED error. In such case Trusted Identity needs to be prepared on Issuer server and sent via Wallet SDK in loginByTrustedIdentity method. MPA can decide whether ask User to provide authentication data or not. The latter case regards situation when user is already authenticated and Trusted Identity can be immediately returned from Issuer based on already valid session on Issuer side. 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 information like:

• 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

It is possible that transaction history will be stored on Wallet Server for infinite time. This should be specified during onboarding. If this options is enabled, MPA can retrieve transaction history for given user and filtering. 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

Wallet SDK performs some security checks. When any issue is detected, Wallet SDK reports error to Wallet Server and clears own data. Also notification to MPA is called.

@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
SDK -> SDK: 1. detectSecurityIssue
activate SDK
SDK -> SDK: 2. clearSDKData
SDK -> WS: 3. reportSecurityIssue
activate WS
deactivate WS
deactivate SDK
SDK -> MPA: 4. onSecurityIssueAppeared(event)
activate MPA
deactivate MPA
MPA -> User: 5. show information
@enduml

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

Technical Documentation VCP SDK

VCP SDK Introduction

Basic abbreviations and definitions

What is VCP SDK?

The VCP (Verestro Cloud Payments) SDK is a module for digitization, payment, and token management for available payment instruments. Usage of VCP SDK depends on Mobile DC SDK which is the core of the Verestro module. Payment instruments can be provided to VCP SDK using the Mobile DC module.payment

How VCP SDK works?

Provides methods to manage digitization using main domains:

• IBANs
• Payment
• Cloud Messaging
• Cards
• External Wallet Server
  

Depending on the selected payment instrument source (Card, Iban, External Wallet Server) VCP SDK allows to digitize it and provide methods for the payment process.

Usage of the following domains depends on client requirements.

Versioning and backward compatibility

SDK version contains three digits. For example: 1.0.0.

• First version digit tracks compatibility-breaking changes in SDK public APIs. It is mandatory to update the application code to use SDK when this is incremented.
• Second version digit tracks new, not compatibility-breaking changes in public API of SDK. It is optional to update the application code when this digit is incremented.
• Third version digit tracks internal changes in SDK. No updates in application code are necessary to update to the version, which has this number incremented.

Changes not breaking compatibility:

• Adding a new optional interface to SDK setup
• Adding a new method to any domain
• Adding a new ENUM value to input or output

• Adding a new field in the input or output model

Technical overview

SDK Basic configuration

The minSdkVersion must be at least 23 (Android 6.0). The application must use AndroidX. 

SDK is available on the Verestro maven repository and can be configured in a project using the Gradle build system.

The username and password are provided by Verestro.

repositories{
	maven {
		credentials {
			username "<enter_username_here>"
			password "<enter_password_here>"
		}
		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.

<uses-sdk tools:overrideLibrary="pl.upaid.nativesecurity, 
pl.upaid.module.ucpsdk,
pl.upaid.module.mobiledc,
pl.upaid.internal.module.mcbp-v3,
pl.upaid.internal.module:vts_v6,
pl.upaid.internal.module.security, 
pl.upaid.internal.module.worker, 
com.mastercard.mpsdk,
com.visa.cbp" />

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.

VCP size already includes Mobile DC SDK size.

Additional information:

• size from the table above is referred to release version;
• size depends on configured proguard;
  

VCP SDK Usage

This chapter describes the structure and basic usage of VCP SDK.

Domains

Every of the described facades is divided into domains with different responsibilities. Available domains:

• IBANs
• Payment
• Cloud Messaging
• Cards
• External Wallet Server
  

Every domain contains domain-related methods.

Error handling

Works like in Mobile DC SDK, but provides additional BackendException reason codes (only when Verestro Wallet Server is used) and additional exceptions for specific methods.

SDK provides errors by exceptions, which could be caught by the application and shown on UI with a detailed message.

Note: VCP SDK can throw exceptions from Mobile DC SDK as its core of the Verestro module.

Additional BackendException reason codes:

Additional ValidationException reason codes:

UcpSdkException reason codes:

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:

<service
	android:name=".WalletHceService"
	android:exported="true"
	android:permission="android.permission.BIND_NFC_SERVICE">
		
		<intent-filter>
			<action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />		
		</intent-filter>
		
		<meta-data
			android:name="android.nfc.cardemulation.host_apdu_service"
			android:resource="@xml/hce_apdu_service" />
 </service>

Below listing of the default source file hce_apud_service.xml:

<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
	android:apduServiceBanner="@drawable/hce_logo"
	android:description="@string/hce_service_description"
	android:requireDeviceUnlock="false">
	<!-- If the requireDeviceUnlock is set to false, on some phones you can pay if the screen is not awake, 
    but on most devices the screen must be awake to make a payment. -->
	
	<aid-group
    	    android:category="payment"
    	    android:description="@string/aid_description">

		<!-- Following is a PPSE AID. You must always include this AID in order for payments to work-->

	 	<aid-filter android:name="325041592E5359532E4444463031" />

		<!-- Following AID list is specific to the application requirements.
	       If your application supports the type of card that these AID represents,
	       you must include those AID in your configuration file -->

		<aid-filter android:name="A0000000041010" /> <!-- Mastercard DEBIT/CREDIT -->
	    <aid-filter android:name="A0000000042203" /> <!-- Mastercard US DEBIT/CREDIT -->
	    <aid-filter android:name="A0000000043060" /> <!-- Maestro DEBIT -->
	    <aid-filter android:name="A0000000049100" /> <!-- Private label AID-->

        <!-- uncomment only when Visa is used-->
        <!--  <aid-filter android:name="A0000000031010" /> --> <!-- VISA DEBIT/CREDIT -->
        <!--  <aid-filter android:name="A0000000980840" /> --> <!-- US COMMON DEBIT -->
        <!--  <aid-filter android:name="A0000000032020" /> --> <!-- VPAY -->
        <!--  <aid-filter android:name="A0000000032010" /> --> <!-- VISA ELECTRON -->
        <!--  <aid-filter android:name="A0000000033010" /> --> <!-- VISA INTERLINK -->
        <!--  <aid-filter android:name="A00000000307010001" /> --> <!-- PRIVATE LABEL -->
	</aid-group>
</host-apdu-service>

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

PaymentInstrumentStatus

AdditionalAuthenticationMethod

Additional authentication method values:

AuthMethodsIssuerParameters contains the following fields:

AuthMethodsIssuerParametersMdes contains following fields:

AuthMethodsIssuerParametersMdesAndroid contains following fields:

AuthMethodsIssuerParametersMdesIos contains following fields:

AuthMethodsIssuerParametersVts contains following fields:

AuthMethodsIssuerParametersVtsAndroid contains following fields:

AuthMethodsIssuerParametersVtsIos contains following fields:

ContactlessTransactionInformation

ContactlessTransactionRange

ContactlessRichTransactionType

DsrpTransactionInfo

TransactionAbortReason

NewTransaction

ContactlessTransactionData

ContactlessTransactionRange

ContactlessRichTransactionType

Report

ContactlessAdvice

ContactlessTransactionResult

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

External libraries

The SDK uses several external Apache 2.0 libraries:

• com.nimbusds:nimbus-jose-jwt
• commons-codec:commons-codec
• com.fasterxml.jackson.core:jackson-core
• com.fasterxml.jackson.core:jackson-annotations
• com.fasterxml.jackson.core:jackson-databind
• com.fasterxml.jackson.module:jackson-module-kotlin
• io.insert-koin:koin-android
• io.reactivex.rxjava2:rxjava
• io.reactivex.rxjava2:rxandroid
• com.squareup.retrofit2:adapter-rxjava2
• com.squareup.retrofit2:retrofit
• com.squareup.retrofit2:converter
• com.squareup.okhttp3:logging
• com.squareup.okhttp3:okhttp
• com.google.zxing:core
• net.sf.flexjson:flexjson

VCP SDK Setup

VCP SDK has to be configured every time when is used. Before VCP SDK usage Mobile DC SDK should be already configured.

setup

Input

UcpConfigurationBuilder contains the following methods:

UcpPaymentInstrumentEventListener

Contains callbacks for PaymentInstrument.

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.

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.

UcpEventReportsListener

UcpReProvisionEventListener

Called when transaction is completed with information about transaction and result.

ContactlessTransactionInformation is deprecated in version 2.2.4.

UcpMcbpHttpExecutor

ucpMcbpHttpMethod could be one of: POST, GET.

ucpMcbpRequestType could be one of: REQUEST_SESSION, REPLENISH, PROVISION,
NOTIFY_PROVISIONING_RESULT, CHANGE_MOBILE_PIN, DELETE.

DefaultUcpMcbpHttpExecutor