Token Management Platform Integrate MDES, VTS, Apple Pay, Google Pay and other X-pays. Issue and manage card tokens. All content of this book is addressed to issuers and focused on issuer's perspective.  Article You can find more knowledge about products on this site. Tokenization and Contactless Payments - Verestro's competitive advantages The most important reason why you should use the Verestro Tokenization and Contactless Payment Solutions  There are many reasons why to use Tokenization and Contactless Payment solutions provided by Verestro but one of them is definitely the most important. We can give you access to ALL ways of NFC and contactless payments through a single platform and one vendor. There are multiple partners you will have to integrate with and certify. Some processors will enable the majority of them but very few will give you access to all. Some IT companies will tell you that they can do everything and connect to everyone but it is also not true. It takes time and money to get new integrations and certifications.  Examples of questions that you can ask your vendors Imagine that 10% of your users are using Huawei phones. Are you ready to provide contactless payments to their phones now? What if many of your users have cheap Android phones? Will your solution work on this? How many MB are used by your system (in our case below 4MB)? What if you are issuing cards in multiple markets? Is your current solution ready globally? What if you are planning to tokenize bank accounts (not cards but bank accounts) - is your platform ready for this?  Verestro's solutions At Verestro we solve this problem by certifying and standardising integration with all possible ways of payments. We are delivering our tokenization and NFC cloud payment platform globally to multiple bank and payment institutions. Current list of certified solutions is: phones: Apple, Huawei, Pixel, Samsung, LG, Motorola, Xiaomi etc. operating systems: iOS, Android X-pays: Apple Pay, Google Pay, Samsung Pay, Fitbit Pay, Garmin Pay, your own wallet, your own X-Pay payment schemes: VISA, Mastercard, Pay-by-Account, Local scheme countries: global, possibility of local data hosting or transaction processing Business benefits Additional business benefits that make us unique are: possibility of registering individual card visuals delivering the full scope of reporting for Apple and Google inside the Verestro Token Management Platform possibility to organize card registration to Apple or Google with own, proprietary CVC / CVV verification method (no need for integration) cheap and quick - below 20k eur one-time, below 4k eur per month, 2-4 months only Please contact us for more information. Tokenize it! Tokenization in Payments – How It Is Transforming Transactions Tokenization has played a crucial role in contactless payments for years, evolving into a broad concept covering various technologies. Initially, it relied on hardware-based solutions like chips or SIM cards. Today, most systems use a device's standard processor, eliminating the need for dedicated hardware. Every innovation in this field must comply with payment industry standards. Beyond implementation, security and formal approvals are equally critical. While Mastercard and Visa shape the market, tech giants like Apple and Google also drive payment evolution. Regional Challenges and Service Development Not all regions have equal access to payment services. Countries impose regulations requiring localized data processing. India mandates domestic storage of payment data, while Turkey requires accreditation from its central bank (CBRT) for external payment providers. Apple Pay is widely available in regions like the  United States and Europe , as well as in other major markets such as  South Korea, Japan, and Australia . However, its availability is still limited in many parts of the world, meaning thet a significant number of iPhone users do not yet have access to contactless payments. By opening its ecosystem to external wallets, Apple creates new opportunities for banks and payment providers. Alternative mobile payment solutions on iPhones are now a reality. Tokenization in E-Commerce and Mobile Applications Tokenization extends beyond contactless payments, increasingly used in e-commerce and in-app transactions. Systems like DSRP (Digital Secure Remote Payment) and Click-to-Pay enhance convenience and simplify payments for merchants, particularly those avoiding complex PCI DSS procedures or adapting to regional regulations. Wearable Payments – What’s Next? Wearable payments are rapidly evolving. Smartwatch payments are common, while rings, glasses, and even clothing are gaining interest. The fintech industry will determine how quickly these innovations become mainstream. Soon, paying for coffee with a smart ring or VR glasses could be as easy as using a phone. Tokenization not only simplifies transactions but also shapes the future of finance. The coming years promise even more advancements in this space. Push Provisioning Step by Step Android - Push Provisioning to Google Pay 1. Request Access Before enabling Push Provisioning in the Android application, you'll need to be whitelisted by Google. To initiate this process: Visit the Google Pay Push Provisioning launch page: https://developers.google.com/pay/issuers/apis/push-provisioning/android/launch-process   Click " Request access " and complete the provided form. 2. Provide Application Details (Upon Approval) Once your access request is approved, Google will contact you to gather additional information about your application: Screenshots: Submit screenshots that showcase the placement and functionality of the "Google Pay" button within your app. User Flow Recording: Provide a screen recording demonstrating the user experience for adding a card to Google Pay. Important Note: Google Pay integration does not require any additional paid certifications. 3. SDK Configuration Verestro Application Ownership: If Verestro develops the application, our development team will handle the internal configuration of 3rd party Google Pay SDK. Customer Application Ownership: If the customer owns the application, customer's development team needs to get the Google Pay SDK and follow official documentation. iOS - Push Provisioning to Apple Pay 1. Contact Apple To begin enabling Push Provisioning for Apple Pay , initiate contact with Apple directly. Use the following email addresses: apple-pay-provisioning@apple.com applepayentitlements@apple.com 2. Application Information and Testing Provide Apple with the details of your App Store application. Verestro will conduct integration testing using the same application (including the same ADAM ID) within the TestFlight platform. 3. FIME Certification (Optional) While not mandatory, FIME can provide an optional certification process for Apple Pay Push Provisioning. Contact FIME directly for current pricing and instructions. This cost was approximately €3125 at the time of writing. 4. SDK Configuration Verestro Application Ownership: If Verestro develops the application, our development team will handle the internal configuration of the 3rd party Passkit SDK. Customer Application Ownership: If the customer owns the application, customer's development team needs to get the SDK of their choice (Apple Pay, Passkit, etc.) and follow their documentation. Additional Notes These instructions provide a high-level overview. For detailed technical guidance and code implementation, please refer to the official Google Pay and Apple Pay developer documentation. It will be necessary to implement the 3rd party SDKs and APIs provided by Verestro and used to encrypt card data and support additional processes in xPay's. Push Provisioning & Web Push Provisioning In this article we will focus on the process of pushing card data to X-Pays (like Apple Pay or Google Pay) – a process called Push Provisioning.  In many innovative card issuing use cases it is important to launch tokenization of cards to enable better customer experience and contactless payments with mobile. There are actually a few ways of registering card data at Apple or Google Pay from a user's perspective: 1. Manual provisioning – which means that the user provides card data one by one. After that the user accepts T&C, confirms this action with One Time Password received from the issuer / bank and gets the card tokenized. 2. Scanning card – the above mentioned process can be improved if the user can scan their payment card with their phone, so that the card data and expiry date appear automatically in the wallet. Not a difficult thing to do nowadays. This process is also very useful if a card visual can appear on the website and the user scans the card visual and data directly from their laptop. 3. Push Provisioning – in this case, the process starts with opening a mobile banking application. The user can click the “Add to wallet” or “Register to wallet” button and can be redirected to Apple or Google Pay to finalize registrations. Various SDKs enable quick registration of the user and card data. It is a very user-friendly process.  However, in some cases it is necessary that the process of Push Provisioning starts from the website – not from the mobile app. This is called Web Push Provisioning and it is a very innovative way of starting tokenization. There are available APIs that streamline such a process and it can be used in many cases.  However, to make it happen special approvals of Google or Apple are needed, which is not easy to receive. This use case can be interesting in multiple projects, for example: - Gift cards delivery – the user opens a gift card on the website widget on their phone and can immediately add this gift card to the wallet. -   Expense management cards – the user opens a card generated by their employer on their phone and can immediately tokenize the card in ApplePay. - Emergency cards – the user gets a card from their insurance or bank and can use it immediately on their phone for emergency transactions.   Please contact us if you are interested in testing those use cases. Tokenization in eCommerce Payments Sometimes our customers ask questions connected with tokenization of eCommerce transactions. Let me focus on this topic below.  There are multiple meanings of tokenization in case of eCommerce payments.  Payment Scheme Tokenization  I think that nowadays term tokenization is the most commonly used in the context of VISA or Mastercard card tokenization . Both payment schemes implemented tokenization systems (MDES and VTS) which were first used on mobile phones but today are also used for eCommerce transactions. In such situations, tokenization means that a regular Mastercard or VISA payment card gets connected to a token which is a kind of virtual card number and once this mapping happens, the user is using the token to initiate payment transactions from those cards. An example of such a use case could be Netflix which enables their users to add cards to the service and in many geographies they map cards with tokens and for all transactions a token is used rather than a regular card. In case of a security breach, a thief will steal token numbers and not card numbers. Card on File Tokenization  Very often term tokenization is used in the context of regular Card on File projects. Card on File is a solution that enables merchants or acquirers to enable card payments without asking all the time for card number entry by the user. A card is held "on file" which means that it is saved in the system of merchant, acquirer, processor and can be used any time the user confirms a transaction. In such a context, tokenization can be enabled without VISA or Mastercard and tokens are owned by the processor or acquirer and shared with the merchant. In case of security breach to the merchant, real card numbers are not exposed because they are safely kept by a PCI DSS compliant processor. Apple or Google Pay Tokenization Sometimes tokenization in eCommerce is used in the context of Apple Pay and Google Pay transactions. In those projects the system works very similarly to the standard Payment Scheme Tokenization described above, but iOS and Android devices are used to authenticate the user and the transaction. Apple and Google enable various endpoints that merchants or acquirers can connect to and allow tokenization. Transactions are processed in a similar way to regular Mastercard or VISA transactions. Advantages of Using Tokenization Usually, main advantages or using tokenization are connected with security and minimising PCI DSS requirements that merchant must fulfill. PCI DSS (Payment Card Industry Data Security Standards) require that each entity, which holds and processes card data, performs a set of actions to make sure that cards are securely processed. Very often tokenization brings additional benefits like cost optimisation and user experience improvements. However, once you think about such a project, take seriously all potential long term impacts. If you do a project directly with your acquiring institution you may get seriously impacted in case you want to change provider. The last thing you want as an eCommerce merchant is to have a monopoly of your payment provider. You should choose providers that work with multiple acquirers, can provide tokenization or card on file solutions for users cards and tokens without being limited to a single acquirer. In such cases you can get acquiring offers from multiple acquiring partners and enable competition to lower prices of payment processing.  Please contact us if you consider such projects.  Introduction Token Management Platform enables a quick implementation of multiple tokenization solutions. It will help you launch your Apple Pay or Google Pay program in maximum 2-3 months at an affordable price. Tokenization is available globally and can be delivered by Verestro to any bank, financial institution of fintech. Key features: The platform is integrated with Mastercard MDES and VISA VTS. Full certification of Mastercard, VISA, Apple Pay, Google Pay, Samsung Pay, X-Pays. Enables all mandatory and optional processes required by payment schemes. Simplifies encryption mechanisms required by X-Pays. It can be hosted by Verestro in private cloud in EU or on AWS or Azure at any location in the world. Full coverage of Apple mandatory requirements and certifications. Platform includes Administration Panel for token management. Token Connect, MDES-4-Merchants and Click2Pay can be included into the project scope. Guaranteed implementation time - 3 months. Please check product overview and technical APIs for more details about the product. Intro Slides Token Management Platform The TMP platform is an easy way to implement and manage tokenization process for Issuer. Thanks to this solution, Issuer can manage tokens with various token requestors with minimum development. The TMP platform ensures end to end token management process including configuration, customization and integration. API: pre-digitization process, token lifecycle managment, user notifications and reporting, push provisioning. Readiness: Live. Implementation time: 4 weeks from set up project. Administration Panel for token management: Yes. Fully compliant with Google Pay, Apple Pay, Garmin Pay, Samsung Pay etc. Overview Verestro Token Management Platform is a solution created in order to allow much easier connection to Token Service Providers (TSP) - MDES, VTS. That can be used for card „pre-digitization” from all Token requestors with minimum development on the issuer side . It  consists of the following parts : Predigitization API -  set of processes and requirements that must happen before the payment token becomes ready for use - it will be possible to make payments. Token LifeCycle API - Mastercard or Visa API that TMP connects to in order to manage token life cycle. Admin Panel - Administration Panel for creating/fetching reports and managing token life cycle - can be used by Issuer's Customer Service. PushProvisioning API - allow card issuers the ability to initiate the card provisioning process for Apple/Google Wallet/Click2Pay directly from app. Benefits for issuing bank or fintech partner TMP is created to connect to TSP(MDES/VTS) and enable much easier integration for the Issuer.  TMP integrates with Token Service Providers (Mastercard MDES, Visa VTS) and provides a single interface for the issuers, so issuers don't have to integrate with both TSP. TMP supports various Token Requestors. TMP supports different requirements and implementations recommended by Token Requestors. TMP has audit and reporting capabilities for the Issuer including Apple Pay reports. TMP provides the Token and (optionally) Card Lifecycle Management API. TMP provides Admin Panel. TMP provides customizable Rule Engine, with risk rules kept in line with Token Requestors and Payment Networks recommendations, allowing issuer to make easier and more reliable tokenization authorizations decisions. TMP supports notifications including reminders for the users. TMP supports token requestor based velocity controls. TMP supports automated token lifecycle management. TMP supports In App Push Provisioning and supports In App token activation method. High Level Overview Key components Component Description Bank Customer Service Service that allows direct one-on-one interaction between a consumer using a card and a representative of the bank. Bank SMS/Email Gateway Bank Service to send OTP via SMS or email to users. Used only when Issuer wants to send sms/email by themselves. Verestro SMS/Email Gateway Verestro TMP gateway to send OTP via SMS or email to users. Bifrost Service (Verestro TMP backend) Component responsible for the pre-digitization, token/card lifecycle, reports and push provisioning. Push Provisioning ApplePay/GooglePay Allows a mobile application to push a card to a token requestor. Issuer The bank or institution responsible for issuing the cardholder their card (debit, credit, prepaid). MDES/VTS Token Service Provider which supports digitization (transforming the card into payment token) and is responsible for management, generation and provisioning of transaction credentials to Token Requestor to enable simpler and more secure digital payment experience. MDES Pre-digitization MasterCard  Digital Enablement Service  API with methods to perform pre-digitization process. Verestro TMP Admin Panel Panel that can be used by bank for token LifeCycle management, administration and viewing reports. Token Requestor Is an entity that requests payment tokens for end-users. Some examples of TRs include digital wallet providers, payment enablers, merchants and IoT manufacturers. Features overview Verestro Token Management Platform supports below functionalities: Area Functionalities Interface (Payment network APIs) Mastercard Pre-Digitization API Mastercard Customer Service API Visa Token Service Inbound API Visa Token Service Outbound API Apple Pay Manual provisioning Push provisioning Apple Pay payload encryption Apple Pay card list Google Pay Manual provisioning Push provisioning Google Pay payload encryption Google Pay card list XPays (Samsung Pay, Fitbit Pay, etc.) Manual provisioning Push provisioning Payload encryption Card list Token Management Portal Web UI All tokens available at the same time through the same interface Rules & tokenization decisions overview Identity Verification SMS OTP Email OTP InApp Verification Reports Apple mandatory report Standard report (includes user, device, token, payment history data)  Card Lifecycle Management Automated Card Lifecycle Management Single Token Lifecycle Management Automated removal of inactive tokens Decision Paths & Fraud Prevention Wallet Provider recommendation Wallet Provider reason codes Wallet Provider Device score Account number source Wrong SMS OTP Velocity Wrong CV2 or Exp.Date Velocity Token Limit per Card Token Limit per Device Geolocation Verification Device IP Address Verification Mobile Phone Number Marching Verestro TMP solution Verestro Token Management Platform is solution  which has been developed to facilitate the process of pre-digitizing cards for the Issuer. Solution consists of: Token Management Platform (Server solution) - backend component. TMP Admin Panel - frontend component, dedicated to issuer's customer service teams. Architecture Pre-digitization Pre-digitization is a set of processes that allows to a generation of digital payment tokens to enable simpler and secure digital payment experiences. Simply it turns a payment card into a digital token. In this process, Verestro TMP is taking care of all the requirements from Token Requestors. For this process, the Issuer needs to expose one API method, which will return card verification result or security code verification result. Tokenization process 1. User enters the card into Apple Pay/Google Pay or another Token Requestor wallet. 2. TMP receives Authorize Service request from TSP(MDES/VTS) on Pre-digitization API with Card Number, CVC, Exp Date, Device Score, and other tokenization data provided by Token Requestor. 3. TMP checks device score, number of already active tokens, velocity controls and other risk rules, relevant for the case. 4. TMP sends a request to Issuer Card Verification API with a Card Number and receives the Card Status, Card ID, User Phone Number, CVC validation Result, Product Category. 5. TMP returns the decision to TSP (APPROVED/REQUIRE_ADDITIONAL_AUTHENTICATION/DECLINED). Token activation If the decision is APPROVED - token activated instantly after Authorize Service response. Verestro TMP can also notify the issuer if required. If the decision is REQUIRE_ADDITIONAL_AUTHENTICATION - The message will be displayed to the user with activation options (ex. SMS OTP). After the user selects the activation type, TSP will send a DeliverActivationCode to Verestro TMP. Verestro TMP will send the OTP activation code to the user. After the user enters the OTP, TSP activates the token. The token can also be activated manually via the Administration Panel. If the decision is DECLINE - a token becomes INACTIVE and cannot be activated again. When a token is activated, Verestro TMP will receive a notifyServiceActivated call from TSP. User authentication There are 4 authentication paths for the user : Green Path - Path without user confirmation (authentication) during the token activation process. The payment token is automatically activated. Yellow Path - Path with user confirmation (authentication) during the token activation process. Payment token is activated after correct OTP is provided. Orange Path - Path with user confirmation (authentication) during the token activation process. Payment token is activated by the Bank after the user's request via call. Red Path - Path when the Issuer rejected activation payment token during the token activation process. Pre-digitization API Sequence Diagram @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 } title Green Path actor User 'comment: actor boundary control entity User -> "Token Requestor": 1. Tokenize Card activate "Token Requestor" "Token Requestor" -> "MDES": 2. AuthorizeService request activate "MDES" "MDES" -> "TMP": 3. AuthorizeService request activate "TMP" "MDES" <-- "TMP": 4. AuthorizeService response (APPROVED) "Token Requestor" <-- "MDES": 5. AuthorizeService response (APPROVED) User <-- "Token Requestor": 6. APPROVED "MDES" --> "TMP": 7. NotifyServiceActivated deactivate "TMP" "MDES" --> "Token Requestor": 8. Service Activated deactivate "MDES" "Token Requestor" --> User: 9. Service Activated deactivate "Token Requestor" @enduml @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 } title Yellow Path actor User 'comment: actor boundary control entity User -> "Token Requestor": 1. Tokenize Card activate "Token Requestor" "Token Requestor" -> "MDES": 2. AuthorizeService request activate "MDES" "MDES" -> "TMP": 3. AuthorizeService request activate "TMP" "MDES" <-- "TMP": 4. AuthorizeService response (RAA) "Token Requestor" <-- "MDES": 5. AuthorizeService response (RAA) User <-- "Token Requestor": 6. Activation Methods User -> "Token Requestor": 7. Choose Activation Method "Token Requestor" -> "MDES": 8. Choose Activation Method "MDES" -> "TMP": 9. DeliverActivationCode "TMP" --> User: 10. DeliverActivationCode (SMS, EMAIL) deactivate "TMP" User -> "Token Requestor": 11. Enter activation code "Token Requestor" -> "MDES": 12. Validate activation code "MDES" --> "Token Requestor": 13. Service Activated deactivate "MDES" "Token Requestor" --> User: 14. Service Activated deactivate "Token Requestor" @enduml @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 } title Red Path actor User 'comment: actor boundary control entity User -> "Token Requestor": 1. Tokenize Card activate "Token Requestor" "Token Requestor" -> "MDES": 2. AuthorizeService request activate "MDES" "MDES" -> "TMP": 3. AuthorizeService request activate "TMP" "MDES" <-- "TMP": 4. AuthorizeService response (DECLINE) deactivate "TMP" "Token Requestor" <-- "MDES": 5. AuthorizeService response (DECLINE) deactivate "MDES" User <-- "Token Requestor": 6. Decline deactivate "Token Requestor" @enduml Deliver activation code. This method  is called when authorize service returned decision: REQUIRE_ADDITIONAL_AUTHNETICATION(Yellow Path). Account Holder needs to verify himself with one of the available activation methods (e.g. OTP code or call to call center). OTP code can be generated by Verestro TMP or TSP(preferred option). Verification steps: Verestro TMP  sends OTP code via SMS or email (configurable option) to the Account Holder, but there is also possibility to do that by the Issuer, in that case Verestro TMP will notify  the Issuer and then Issuer sends it to the Account Holder, Account Holder is entering received OTP and TSP or Verestro TMP(configurable) is validating it, When OTP code is correct, notifyServiceActivated method is called which means that token is activated and ready to use. MDES Pre-digitization API technical The process of predigitization presents a set of methods by which Issuer can easily digitize his card.   The process of predigitization presents a set of methods by which Issuer can easily digitize his card. The diagram below shows the flow from the moment the User starts digitizing his card, through its authentication with the activation code ( Deliver Activation Code ) to the activation of the payment token. @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 "Token Requestor" as TR participant "Mastercard Digital Enablement Service" as MDES participant "Token Management Platform" as TMP participant Issuer as Issuer User -> TR: 1. Digitize activate TR TR -> MDES: 2. Digitize activate MDES MDES -> TMP: 3. AuthorizeService activate TMP TMP -> Issuer: 4. CardValidation activate Issuer Issuer --> TMP: 5. Card Validation Response deactivate Issuer TMP --> MDES: 6. Decision and List of Activation Methods deactivate TMP MDES --> TR: 7. List of Activation Methods deactivate MDES TR --> User: 8. List of Activation Methods deactivate TR deactivate User note left: Activation method selected User -> TR: 9. Deliver Activation Code activate TR TR -> MDES: 10. Deliver Activation Code activate MDES MDES -> TMP: 11. Deliver Activation Code activate TMP TMP -> Issuer: 12. Deliver Activation Code activate Issuer Issuer --> User: 13. Send activation code using preferred channel Issuer --> TMP: 14. Activation Code Delivered deactivate Issuer TMP --> MDES: 15. Activation Code Delivered deactivate TMP MDES --> TR: 16. Activation Code Delivered deactivate MDES TR --> User: 17. Activation Code Delivered deactivate TR User -> TR: 18. Enter activation code activate TR TR-> MDES: 19. Activate activate MDES MDES -> MDES: 20. Token MDES -> MDES: 21. Token activated (TUR) MDES -> TMP: 22. NotifyTokenUpdated (TUR, Active) activate TMP MDES -> TMP: 23. NotifyServiceActivated TMP -> Issuer: 24. NotifyServiceActivated deactivate TMP MDES -> TR: 25. NotifyServiceActivated deactivate MDES TR --> User: 26. Token Activated deactivate TR @enduml Lifecycle Token lifecycle support token management which can be use directly by user, issuer or customer service using Admin Panel. This feature provides action on token to change token status. Actions what can happened are: Acivate token → change token status to Active, Suspend token → change token status to Suspended, Unsuspend token → change token status to Active, Delete token → change token status to Deactivated, The diagram below shows the transitions between payment token statuses. Automatic lifecycle management is supported via Verestro TMP API. Issuer can call Verestro TMP API to perform any lifecycle actions on card with will result on lifecycle action on all tokens assigned for the card. Example: User looses his card and calls bank customer services to block the card, bank blocks user's card and automatically calls Verestro TMP to blocks all the tokens for the same card. This solution is compliant with apple automated lifecycle management requirements Payment Token Lifecycle Management These diagrams show what the 4 authentication paths look like for a user: This section describes payment token lifecycle management performed via Issuer or Admin Panel. Token lifecycle options: – Token can be suspended/deleted from the consumer app (Apple Pay/ Google Pay). Verestro TMP will receive a TokenUpdate notification from TSP. – Token can be activated/suspended/unsuspended/deactivated from Administration Panel UI by the Issuer Customer Service Support team. – Token can be activated/suspended/unsuspended/deactivated via Verestro TMP API. – All card tokens can be suspended/unsuspended/deactivated via Verestro TMP API. Card renew and replace is also supported. Thera are a possibility to turn on an automatic notifications depends on any actions on token e. g token was activated or customer didn't finalize token activation. Suspend, Unsuspend, Deactivate the token Payment token can be suspended by the Issuer or the 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 "Token Requestor" as TR participant "Mastercard Digital Enablement Service" as MDES participant "Token Management Platform" as TMP participant "Admin Panel" as AP AP -> TMP: 1. suspend/unsuspend/deactivate token activate AP activate TMP TMP -> TMP: 2. check the permissions alt if permissions are compatible TMP -> MDES: 3. suspend/unsuspend/deactivate token activate MDES else if permissions disagree TMP --> AP: 4. response end MDES -> MDES: 5. suspend/unsuspend/deactivate token MDES --> TMP: 6. response TMP --> AP: 7. response deactivate AP deactivate TMP MDES -> TR: 8. token suspend/unsuspend/deactivate deactivate MDES activate TR TR -> TR: 9. suspend/unsuspend/deactivate token TR --> User: 10. notification deactivate TR @enduml Payment token can be suspended by the Issuer. @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 "Token Requestor" as TR participant "Mastercard Digital Enablement Service" as MDES participant "Token Management Platform" as TMP participant Issuer as Issuer Issuer -> TMP: 1. suspend/unsuspend/deactivate token activate Issuer activate TMP TMP -> TMP: 2. check the permissions TMP -> MDES: 3. suspend/unsuspend/deactivate token activate MDES MDES -> MDES: 4. suspend/unsuspend/deactivate token MDES --> TMP: 5. response TMP --> Issuer: 6. token suspended/unsuspended/deactivated deactivate Issuer deactivate TMP MDES -> TR: 7. token suspend/unsuspend/deactivate deactivate MDES activate TR TR -> TR: 8. suspend token TR --> User: 9. notification deactivate TR @enduml Replace and renew the token Replace/renew payment token is the process with consists of updating payment token data. Every payment token has an expiry date and linked PAN. When the token is expiring, the Issuer can change the token expiration date. When a cardholder has a new card (new PAN) and wants to keep the digital token active, it can be achieved by doing "PAN swap" for a token. The issuer can do it for one or all payment tokens associated with one PAN set to the new data. A new product configuration ID can also be associated with one or all tokens associated with a PAN. The same situation may occur when the cardholder receives a new card (PAN) due to fraud / theft. The issuer changes the payment token data in the same way. @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 "Token Requestor" as TR participant "Mastercard Digital Enablement Service" as MDES participant "Token Management Platform" as TMP participant Issuer as Issuer Issuer -> TMP: 1. replace/renew token activate Issuer activate TMP TMP -> TMP: 2. check the permissions TMP -> MDES: 3. replace/renew token activate MDES MDES -> MDES: 4. replace/renew token MDES --> TMP: 5. response deactivate MDES TMP --> Issuer: 6. token replaced/renewed deactivate Issuer TMP -> TR: 7. replace/renew token deactivate TMP activate TR TR -> TR: 8. replace/renew token TR --> User: 9. notification deactivate TR @enduml Payment Card Lifecycle Management @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 "Issuer" as Issuer participant "Verestro Token Management Platform" as TMP participant "Customer Service API" as CSAPI Issuer -> TMP: 1. Suspend card (CardId) activate Issuer activate TMP TMP -> TMP: 2. Find all tokens for card TMP --> CSAPI: 3. Suspend tokens activate CSAPI TMP --> Issuer: 4. Token Suspended @enduml Push Provisioning Push Provisioning provides the ability to initiate the card provisioning process for Apple/Google Wallet directly from the issuer’s app. Users will find the Push Provisioning feature an extremely convenient method to provision their cards or passes into their devices by avoiding the need to input those details manually. Verestro TMP Push Provisioning module API: Check if card is tokenized. Sign card . Verestro TMP Push Provisioning module allows the following flow: Check if card is tokenized - Return information if a card is tokenized on the device, so the Issuer's mobile application can show "Add to Apple/Google pay" button. Sign card - Prepare encrypted and signed payload which can be used by the Issuer's mobile application. Initiate Push Provisioning with Apple Pay/Google Pay SDK. Authorize Service to  Verestro TMP. Tokenization Decision returned to TSP (APPROVE/DECLINE). Admin Panel Admin Panel for Verestro Token Management Platform is an user interface thanks to we can manage and view tokens and transaction data. Due to admin panel operators can: browse tokens list and see token details, change/manage tokens statuses, browse transactions list and see transaction details (including statuses). generate reports. Can be used by Issuer Customer Service. More information we can find in the Verestro TMP Admin Panel Product Overview documentation.  Additional Features Reports. Verestro TMP can generate various types of reports: ApplePay, Tokens, Transactions, Activity audit. Reports can be downloaded or generated from Admin Panel. Some of the reports can be generated automatically by Verestro TMP. User notifications. Verestro TMP can send custom notifications to Issuer, like: OTP code for additional authentication. Notifications when a token is activated or deleted. Notifications to inactive customers, which didn't perform any transactions after token activation. Notifications on abandoned provisioning, when a user didn't finish the full process of token activation. Jobs. Verestro TMP can generate/notify or do some other custom task automatically, like: Delete inactive tokens after a configured time. Generate reports. Send notifications. Fetch transactions from Customer Service, which can be used for reporting and accessible from administration panel. Monitoring and Alerting: Grafana dashboard with tokenization activity and performance metrics. Statistics. Error and warning alerting. Security: IP whitelist for API communication. Role based access to lifecycle and reporting features. x.509 mTLS authentication. VPN tunnel support. OAuth when connecting to Issuer API. Use Cases This section is dedicated to describe different use cases of Verestro Token Management Platform.  Activating a Token During digitization cardholder have to activate his token by Customer Service. The cardholder calls the Customer Service of their bank to activate the token. Admin Panel for Verestro TMP which can be used by Issuer Customer Service allows tokens activated e.g. when at the end of the pre-digitalization activities cardholder have to call his bank to complete the activation digital card. Updating a Token The cardholder wants to replace his existing card e.g. existing card expiry date is coming to the end.  Admin Panel for Verestro Token Management Platform which can be used by Issuer Customer Service allows tokens provisioned against that device to be update. Deleting a Token A cardholder notifies their bank that a phone with their tokenized account been lost or stolen. To avoid fraud the cardholder wants to delete all digital cards provisioned into the device wallets. Admin Panel for Verestro TMP which can be used by Issuer Customer Service allows tokens provisioned against that device to be deactivated preventing further transactions from being performed and therefore preventing fraud. Token Suspend by Customer Service A cardholder notifies their bank that a phone with their tokenized account been lost or stolen. Admin Panel for Verestro Token Management Platform which can be used by Issuer Customer Service allows tokens provisioned against that device to be suspended preventing further transactions from being performed and therefore strongly reducing the risk of fraud, in case the phone has been stolen. Token Unsuspend by Customer Service Cardholder informs their bank that he finds device (after losing their mobile phone). Cardholder request the bank to resume digital cards related to his mobile phone. Admin Panel for Verestro TMP which can be used by Issuer Customer Service allows tokens to be unsuspended in case the risk of fraud has been eliminated e.g. the phone has been found. Information on status history There is a suspicion of fraud on one digital card. The Issuer was informed and wants to get more information before make any actions. Admin Panel for Verestro Token Management Platform which can be used by Issuer Customer Service allows get information and details about tokens and transaction history.  Searching for information The cardholder has difficulties with card digitalization. The cardholder calls their bank to get information what is wrong.  Admin Panel for Verestro TMP which can be used by Issuer Customer Service allows to identify the token in question and check the status. Thanks to this the cardholder may be informed what was happened and take actions. Quick Integration Guide Introduction In this section you will find a guide on how to successfully integrate Token Management Platform (TMP) into your services to support card tokenization and additional features. Supported Approaches There are two main approaches to Token Management Platform (TMP) integration the issue can follow, depending on the preferred card storage location: Cards stored in Verestro Data Core with the use of Lifecycle API Cards stored outside of Verestro (for example by issuer's processor ) Approach 1. Cards stored IN Verestro (Lifecycle API)  To fully integrate with Token Management Platform (TMP) when storing card data in Verestro, the issuer will have to do the following integrations: 1. Lifecycle API integration (mandatory). 2. TMP API integration (optional). 3. Issuer API integration (optional). Each integration and its purpose is described below: Lifecycle API Lifecycle API is the main way of populating DataCore database with the issuer cards. TMP will use DataCore database as a card source. The main idea, is that the issuer should keep cards in DataCore updated with the actual state. During the tokenization, TMP will check if card number is present, card is not blocked and expiry date matches. All changes to the card state will be also reflected to available tokens. Please refer to Lifecycle API documentation . Features available if Lifecycle API is integrated: MDES/VTS tokenization. MDES/VTS Automated Token Lifecycle Management. TMP API TMP API is exposed by Verestro Token Management Platform. This set of APIs is optional and is used by the Issuer to simplify Push Provisioning process. Available API methods: Sign Card (used for Apple Pay and Google Pay Push Provisioning) Get tokens (used to display or hide "Add to xPay" button in the mobile app) Activate tokens (used when issuer would like to implement InApp activation method) Issuer API Issuer API is a set of APIs exposed by the Issuer. Verestro Token Management Platform will call this API to send Token updates, User notifications or to verify the CVC (required for Apple Pay). Features available if Issuer API is integrated: Receiving of Token Updates, when the token is changed. Receiving of User Notification, when a SMS notification needs to be sent to the user. CVC Verification. Approach 2. Cards stored OUTSIDE of Verestro To fully integrate with Token Management Platform (TMP), when card data is stored outside of Verestro (for example by the issuer's processor), the issuer will have to do the following integrations: 1. TMP API integration (mandatory). 2. Issuer API integration (mandatory). Each integration and its purpose is described below: TMP API TMP API is exposed by Verestro Token Management Platform. This set of APIs is optional and is used by the Issuer to simplify Push Provisioning process and to keep TMP updated on card lifecycle events. Available API methods: Card Events (used to notify TMP about card lifecycle events) Sign Card (used for Apple Pay and Google Pay Push Provisioning) Get tokens (used to display or hide "Add to xPay" button in the mobile app) Activate tokens (used when issuer would like to implement InApp activation method) Issuer API Issuer API is a set of APIs exposed by the Issuer to Verestro TMP. Verestro Token Management Platform will call this API to verify the card data during predigitization; send Token updates and User notifications. Features available if Issuer API is integrated: Verifying card data, which is a mandatory step to complete the tokenization. Receiving of Token Updates, when the token is changed. Receiving of User Notification, when a SMS notification needs to be sent to the user. Issuer API Issuer API Specification @swagger="https://s3.verestro.dev/valinor-public/issuer_api_1.3.6.yaml" TMP API TMP API Specification @swagger="https://s3.verestro.dev/valinor-public/tmp_api_1.2.1.yaml" Additional APIs TMP ADDITIONAL API Specification @swagger="https://s3.verestro.dev/valinor-public/tmp_additional_api_1.0.3.yaml" Rule Engine The Rule Engine is a software component designed for tokenization fraud detection. Its primary purpose is to analyze various aspects of tokenization and determine whether it exhibits any suspicious or fraudulent characteristics. The Rule Engine consists of a collection of predefined rules that are applied to each tokenization, depending on the requirements of Issuers, Token Service Providers, and Token Requestors. Rule Each rule accepts different data points provided by Token Service Providers, Issuers, and Token Requestors and based on its logic returns a result, which can be one of the following values:     • Green - Rule is not violated.     • Yellow - Rule is violated, downgrade to Yellow path.     • Orange - Rule is violated, downgrade to Orange path.     • Red - Rule is violated, downgrade to Red path. Each rule is executed only if applicable in a given tokenization context. The result of each rule is saved for auditing purposes and available in the Admin Panel on the Rules tab. Available Rules Card Verification Rule  This rule makes sure the card information is right:     • The card number is valid.     • The expiration date is valid.     • The security code is valid.     • The card is not blocked by the bank. If any of these checks fail, the tokenization is downgraded to Red . This rule uses Lifecycle API data source or calls Issuer Card Verification API. Account Source Rule This rule checks the account source - entered manually or via mobile app. Tokenizations with manually entered card data are downgraded to Yellow  path. Applicable only for Apple Pay and Google Pay. Available Tokens Rule This rule checks the number of tokens for a card that is being tokenized. If the limit is exceeded - tokenization is downgraded to Red . Applicable only for Apple Pay and Google Pay. The rule is configurable - the default limit is 10 tokens per card. Device Score Rule This rule checks the device score provided by the Token Requestor. If the device score is 1 - tokenization is downgraded to Red . Applicable only for Apple Pay and Google Pay. Wallet Recommendation Rule This rule checks the wallet recommendation provided by the Token Requestor. Wallet recommendation is to require additional authentication - downgrade to Yellow . Wallet recommendation is to decline - downgrade to Red . Wallet recommendation is to approve - Green . Geolocation Rule This rule checks the geolocation data provided by the Token Requestor. If the geolocation is not inside the configured country - the tokenization is downgraded to Orange . Applicable only for Apple Pay and Google Pay. The allowed list of countries is configurable. This rule is not enabled by default. Source IP Rule This rule checks the source IP of the device provided by the Token Requestor. If the source IP is not from the allowed country - the tokenization is downgraded to Orange . Applicable only for Apple Pay and Google Pay. The allowed list of countries is configurable. This rule is not enabled by default. High-Risk Flag Rule This rule checks if the tokenization is not flagged as high risk by the Token Requestor. If it is flagged - the tokenization is downgraded to Orange . Applicable only for Apple Pay and Google Pay. Invalid Attempts Rule This rule limits the number of tokenization attempts for a single card with an invalid expiry date or security code. If the limit is exceeded - the tokenization is downgraded to Red . The limit is configurable and by default is 3 attempts during 24 hours. M4M CVC Rule This rule checks the status of security code verification for M4M tokenizations. Depending on the account source, a missing or invalid security code might result in a different authorization path. Security code is invalid - downgrade to Red . Security code is not present and the account source is "manual" - downgrade to Red . Security code is not present and the account source is "card on file" - downgrade to Yellow . Security code match, account source is one of "manual" or "card of file" or "existing token credentials" - downgrade to Yellow . Applicable only for Mastercard M4M (MDES for Merchants) tokenizations. Phone Number Rule This rule checks if the phone number provided by the Token Requestor matches the phone number in the Issuer system. If the phone number doesn't match - the tokenization is downgraded to Orange . If the phone number is not provided by the Token Requestor - the result of this rule is Green . Applicable only for Apple Pay. This rule is not enabled by default. Decisioning Rule This rule determines the final decision returned to Mastercard or Visa depending on the results of all Rules executed for this tokenization. If all executed rules are Green - the final decision is to approve the tokenization. If at least one rule is Yellow - the final decision is to require additional authentication with the SMS OTP code. If at least one rule is Orange - the final decision is to require additional authentication via the Issuer call center.  If at least one rule is Red - the final decision is to decline the tokenization. Admin Panel On the admin panel, you can check all rules executed for a tokenization. Detailed reason or error is provided. Customization Each optional rule can be disabled, modified, or customized for each Issuer based on preferences or local regulatory requirements. New rules can be added with the following possibilities: Processing data points from Token Requestors included in tokenization requests. Processing data points from Mastercard or Visa included in tokenization requests. Processing data points from the Issuer system, ex. via calling additional APIs or external services during the tokenization. Processing data points from Verestro's own database. The tokenization process is limited by time - 5 seconds. Connectivity & Security 1. Overview This document outlines the connectivity and security mechanisms used by the Token Management Platform (TMP) for secure communication between external Issuer systems and TMP backend services. TMP uses X.509 mutual authentication and JWE (JSON Web Encryption) to ensure data confidentiality and endpoint authenticity. 2. Connectivity Architecture 2.1 Issuer → TMP Protocol: HTTPS (TLS 1.2+) Authentication: Mutual TLS (X.509) Issuer Role: Client TMP Role: Server Certificate Usage: The Issuer presents a client certificate signed by a Verestro CA. TMP validates the Issuer's certificate against its trust store. TMP authenticates the Issuer 2.2 TMP → Issuer Protocol: HTTPS (TLS 1.2+) Authentication: Mutual TLS (X.509) TMP Role: Client Issuer Role: Server Certificate Usage: TMP presents its client certificate. The Issuer validates TMP’s certificate against its trust store. The Issuer authenticates TMP 2.3 Certificate Generation and Use Certificate Type Generated By Signed By Used By Purpose(s) Client Certificate (Issuer) Issuer Verestro Issuer X.509 mTLS authentication (Issuer → Verestro)       Verestro/Issuer JWE. Verestro uses the public key from this certificate to encrypt sensitive fields (e.g., card number) in requests. The Issuer uses the private key from this certificate to decrypt sensitive fields Client Certificate (Verestro) Verestro Issuer Verestro X.509 mTLS authentication (Verestro → Issuer)       Issuer/ Verestro JWE. The Issuer uses the public key from this certificate to encrypt sensitive fields (e.g., card number) in requests. Verestro uses the private key from this certificate to decrypt sensitive fields 🔄 Note: While the same certificate pair may be used for both mTLS and JWE, it's recommended to use separate certificates for TLS and field-level encryption for improved security and certificate lifecycle management. 3. Certificate Requirements Format: X.509 Key Length: RSA 2048-bit or higher Validity: Minimum 1 year validity recommended Certificates are exchanged securely during partner onboarding. The same certificate can be used for both mutual TLS and field-level encryption (JWE). Check the following document on how to create a client certificate: https://developer.verestro.com/books/connecting-to-our-services-and-sandbox/page/connecting-to-server-to-server-apis-fe-sandbox 4. Field-Level Encryption Certain sensitive fields (e.g., cardNumber ) are encrypted using JWE (JSON Web Encryption) to provide end-to-end protection beyond TLS. 4.1 JWE Encryption Details Data is encrypted using JWE per RFC 7516 ( https://tools.ietf.org/html/rfc7516) JWE header Name Description alg RSA-OAEP-256 Cryptographic algorithm used to encrypt CEK enc A256GCM Identifies the content encryption algorithm used to perform authenticated encryption Algorithm: RSA-OAEP-256 Content Encryption: A256GCM Key Material: Derived from or aligned with the public key in the X.509 certificate Envelope Format: Compact JWE serialization 4.2 Encrypted Fields Field Location Requirement encryptedCardNumber  JSON Payload Must be encrypted encryptedCVC JSON Payload Must be encrypted if present The same certificate used for TLS client authentication may be used for encrypting JWE payloads, leveraging the associated public key. 4.3 Example code Check the example code Encryption import org.apache.commons.codec.digest.DigestUtils; import com.nimbusds.jose.*; import com.nimbusds.jose.crypto.RSAEncrypter; public String encryptCardNumberExample() throws Exception { final String cardNumber = "1234123412341234"; //plain text card number final String publicKey = "-----BEGIN PUBLIC KEY-----*****-----END PUBLIC KEY-----"; // Verestro public key final String publicKeyContent = publicKey.replaceAll("\\n", "") .replace("-----BEGIN PUBLIC KEY-----", "") .replace("-----END PUBLIC KEY-----", ""); KeyFactory factory = KeyFactory.getInstance("RSA"); X509EncodedKeySpec encodedKeySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(publicKeyContent)); final RSAPublicKey rsaPublicKey = (RSAPublicKey) factory.generatePublic(encodedKeySpec); JWEHeader.Builder headerBuilder = new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256GCM); JWEHeader header = headerBuilder.type(JOSEObjectType.JOSE) .customParam("iat", Instant.now().getEpochSecond()) // issued at timestamp .keyID(DigestUtils.sha1Hex(rsaPublicKey.getEncoded())) .build(); JWEObject object = new JWEObject(header, new Payload(cardNumber.getBytes())); object.encrypt(new RSAEncrypter(rsaPublicKey)); final String jweEncryptedCardNumber = object.serialize(); // encrypted card number string return jweEncryptedCardNumber; } Decryption import com.nimbusds.jose.JOSEException; import com.nimbusds.jose.JWEObject; import com.nimbusds.jose.crypto.RSADecrypter; import org.springframework.core.io.DefaultResourceLoader; import org.springframework.core.io.Resource; import java.io.IOException; import java.io.InputStream; import java.security.*; import java.security.cert.CertificateException; import java.text.ParseException; import static java.util.Objects.*; public class JweDecryptor { public String decrypt(String encryptedString) { try { JWEObject jweObject = JWEObject.parse(encryptedString); KeyStore keyStore = loadKeystore("/keystore.p12", "password"); PrivateKey privateKey = getPrivateKey(keyStore); jweObject.decrypt(new RSADecrypter(privateKey)); return new String(jweObject.getPayload().toBytes()); } catch (ParseException | JOSEException e) { throw new IllegalStateException("Error on decryption JWE payload"); } } private KeyStore loadKeystore(String storeLocation, String storePassword) { Resource resource = new DefaultResourceLoader().getResource(storeLocation); try (InputStream inputStream = resource.getInputStream()) { requireNonNull(inputStream, "Resource could not be loaded" + storeLocation); KeyStore certificateResource = KeyStore.getInstance(KeyStore.getDefaultType()); certificateResource.load(inputStream, storePassword.toCharArray()); return certificateResource; } catch (CertificateException | KeyStoreException | IOException | NoSuchAlgorithmException e) { throw new IllegalStateException(e); } } private PrivateKey getPrivateKey(KeyStore keyStore) { try { return (PrivateKey) keyStore.getKey("alias", "password".toCharArray()); } catch (KeyStoreException | NoSuchAlgorithmException | UnrecoverableKeyException e) { throw new IllegalStateException(e); } } } Token Management Platform for Card Issuing Token Management Platform (TMP) is an application developed by Verestro that enables the implementation of various tokenization solutions. This chapter focuses specifically on card issuing projects and provides information tailored to this type of implementations.  Overview Token Management Platform (TMP) is an application developed by Verestro that enables the implementation of various tokenization solutions. This chapter focuses specifically on card issuing projects and provides information tailored to this type of implementations. Our customers so fintechs, issuers etc. will be reffered in this documentation as "issuers". Contents This chapter is divided into 4 pages. Introduction -  here you will find high level overview of the solution. User notifications - page dedicated to different user notifications and possible ways to send them Push provisioning  - page with all the details necessary to enhance your cardholders experience with push provisioning InApp authentication  - page dedicated to replace sending SMS OTP codes with InApp authentication Overview Thanks to TMP your cardholders will be able to: Manually add their cards to Apple Pay, Google Pay, Samsung Pay, Garmin Pay and other X-Pays  (manual provisioning) (basic feature) Tokenize the cards in various ecommerce stores with the use of M4M (Mastercard for Merchants) service (basic feature) Add their cards to Apple Pay, Google Pay, Samsung Pay, Garmin Pay and other X-Pays directly from your mobile application  ( push provisioning) (additional feature) Activate pushed token directly from your mobile application, without the need of typing OTP code delivered via SMS (inapp authentication) (additional feature) Features and advantages of the solution from Issuer perspective: Admin panel allows your customer service to review the tokenizations and manually activate or deactivate tokens Thanks to integration with Verestro Life Cycle API all token statuses will be updated automatically, according to card statuses Our backend simplifies encryption mechanisms required by X-Pays in Push Provisioning process Apple mandatory requirements are covered. Pre-digitization Pre-digitization is a set of processes that allows to a generation of digital payment tokens to enable simpler and secure digital payment experiences. Simply it turns a payment card into a digital token. In this process, Verestro TMP is taking care of all the requirements from Token Requestors. Thanks to the use of Verestro Data Core card verification is done internally, between verestro services. No additional development is required from the issuer. Tokenization process 1. User enters the card (either manually or pushes from the app) into Apple Pay/Google Pay or another Token Requestor wallet. 2. TMP receives Authorize Service request from Mastercard Digital Enablement System (MDES) on Pre-digitization API with Card Number, CVC, Exp Date, Device Score, and other tokenization data provided by Token Requestor. 3. TMP checks the device score, number of already active tokens for the card, and velocity controls. 4. TMP sends a request to Verestro Data Core with a Card Number and receives the Card Status, Card ID, User Phone Number, CVC validation Result, Product Category. 5. TMP returns the decision to MDES (APPROVED/REQUIRE_ADDITIONAL_AUTHENTICATION/DECLINED). Token activation If the decision is APPROVED - token activated instantly after Authorize Service response. Verestro TMP can also notify the issuer if required. If the decision is REQUIRE_ADDITIONAL_AUTHENTICATION - The message will be displayed to the user with activation options (ex. SMS OTP). After the user selects the activation type, TSP will send a DeliverActivationCode to Verestro TMP. Verestro TMP will send the OTP activation code either directly to the user or to issuer's server, depending of the project configuration. After the user enters the OTP, MDES activates the token. The token can also be activated manually via the Administration Panel. If the decision is DECLINE - a token becomes INACTIVE and cannot be activated again. When a token is activated, Verestro TMP will receive a notifyServiceActivated call from MDES. User authentication There are 4 authentication paths for the user, TMP chooses one on the basis of different factors and fraud-detection rules which are inline with xPay providers requirements: Green Path - Path without user confirmation (authentication) during the token activation process. The payment token is automatically activated. Yellow Path - Path with user confirmation (authentication) during the token activation process. Payment token is activated after correct OTP is provided. Orange Path - Path with user confirmation (authentication) during the token activation process. Payment token is activated by the issuer through Verestro Admin Panel after the user's request via phone call. Red Path - Path when the Issuer rejected activation payment token during the token activation process. More information about rules engine and path decisions can be found here . Verification steps: Verestro TMP  sends OTP code via SMS or email (configurable option) to the Account Holder, but there is also possibility to do that by the Issuer, in that case Verestro TMP will notify the Issuer and then Issuer sends it to the Account Holder, Account Holder is entering received OTP and Verestro TMP is validating it, When OTP code is correct, notifyServiceActivated method is called which means that token is activated and ready to use. Whole user notification process is described in details here . Lifecycle Token lifecycle support token management which can be use directly by the user or issuer's customer service using Verestro Admin Panel. This feature provides action on token to change token status. Actions what can happen are: Activate token → change token status to Active, Suspend token → change token status to Suspended, Unsuspend token → change token status to Active, Delete token → change token status to Deactivated, The diagram below shows the transitions between payment token statuses. Automatic lifecycle management is supported via Verestro TMP API thanks to integration with Verestron Lifecycle API. User notifications According to xPays requirements, cardholders must be informed about the most important events connected with tokenization. Those events are: ACTIVATION_CODE_DELIVERY -  the most important one. In most cases additional verification is required to succesully activate the token added to the wallet. To achieve that user needs to enter  6 digits OTP code which is being sent alongside this event. This additional verification may happen both in Manual and Push provisioning. TOKEN_ACTIVATED - confirmation, that token activation was successful (the card can now be used from the xPay wallet). CARD_REMOVED_BY_CUSTOMER - this occurs when the user disconnects the card from the wallet. CARD_REMOVED_BY_ISSUER - card removed by the issuer (e.g. when the issuer has cleared the user's balance). In Verestro we offer 3 ways of delivering those notifications: Verestro SMS Gateway - no development on the Issuer side needed. We handle all the SMSes sent to the cardholders. Fintech is charged according to agreed SMS pricing. Custom SMS Gateway integration - Verestro backend may integrate with external SMS provider of Issuer choice. Issuer needs an agreement with selected provider and provide documentation necessary for such integration. As this is custom development it's billed and quoted separately. Server-to-server notifications - Verestro backend may send the notifications to issuer's backend. From there it's issuer responsibility to deliver the notifications to the user - for example through different SMS gateway provider or as push notifications. To achieve that, issuer has to expose endpoint to us, according to below swagger documentation: @swagger="https://s3.verestro.dev/valinor-public/user_notifications_issuer_api_1.4.0.yaml" Push provisioning Push Provisioning provides the ability to initiate the card provisioning process for Apple/Google Wallet directly from the issuer’s app. Users will find the Push Provisioning feature an extremely convenient method to provision their cards or passes into their devices by avoiding the need to input those details manually. Verestro TMP Push Provisioning module API: Check if the card is tokenized. Sign card. Verestro TMP Push Provisioning module allows the following flow: Check if card is tokenized - Return information if a card is tokenized on the device, so the Issuer's mobile application can show or hide the "Add to Apple/Google Pay" button. Sign card - Prepare an encrypted and signed payload that can be used by the Issuer's mobile application. Initiate Push Provisioning with Apple Pay/Google Pay SDK. Authorize Service to  Verestro TMP. Tokenization Decision returned to TSP (APPROVE/DECLINE). @swagger="https://s3.verestro.dev/valinor-public/push_provisioning_tmp_api_1.2.1.yaml" Click to Pay - Integration guide for Issuers In Verestro, we introduced Click to Pay card enrollment as a seperate feature in our Token Management Platform. It's possible to implement it within 2-3 months as a standalone integration or even quicker, if you are already using our TMP for MDES/VTS tokenizations. In this guide, we show how to implement Click to Pay enrollment using Verestro TMP API, to improve the digital banking experience for your cardholders. Just as every document in Token Management Platform book, below chapters are addressed to issuers and focused on issuer's perspective. For more general information on click to pay, please refer to Articles. Business Overview Click to Pay is a universal online checkout standard developed jointly by the four major global payment networks — Visa, Mastercard, American Express, and Discover — under the governance of EMVCo. Since it's launch, it has been adopted by thousands of merchants, issuers, and wallet providers worldwide. At its core, Click to Pay abstracts the consumer's Primary Account Number (PAN) behind a secure network token, enabling merchants to process payments without ever handling raw card data. When a consumer checks out using Click to Pay, their enrolled card credentials are retrieved from the Secure Remote Commerce (SRC) system and delivered to the merchant as a payment token, authorized for that specific transaction. All Click to Pay solutions are indicated by the Click to Pay icon  . Why Click to Pay Enrollment Matters to Issuers For a cardholder to use Click to Pay at checkout, their card must first be enrolled in the relevant SRC System. Without enrollment, the card is invisible to Click to Pay and cannot be presented during checkout — even if the network supports it in principle. Issuers drive enrollment. They are the only party that holds the verified cardholder identity, the authoritative card data, and the customer relationship needed to enroll credentials on behalf of or with consent from the cardholder. The Token Management Platform acts as the issuer's API gateway into the Visa SRC and Mastercard MDES systems. Enrollment possibilities Description Business comment Technical requirements Automated, user initiated via available issuer channel Card credential and personal data are pushed automatically, after accepting T&C’s by the user. Convenient flow, with experience similar to xPay push provisioning. Cardholder intentionally enrolls a card and is thus aware of possibility to use C2P.   Recommended implementation.   Verestro TMP API (including  Synchronous card enrollment endpoint ), Visa SRC / MDES for Digital Commerce integration Automated, issuer initiated Card credential and personal data are pushed automatically, without user additional engagement. C2P T&C’s are usually part of issuer’s T&C and consent is given during card activation. Very convenient flow, with minimal user engagement. Although it’s recommended by TSPs, cardholders may not be aware that their card has been pushed to C2P. This flow can also be used for card migrations and bulk enrollments.     Recommended for migrations.   Verestro TMP API (including  Bulk card enrollment endpoint ),   Visa SRC / MDES for Digital Commerce integration Manually, via Merchant’s Payment Gateway Cardholder needs to manually type card credentials, personal data and accept T&C’s during ecommerce payment. This flow requires significant friction and may result in cart abandonment. Convenient for issuers, as works out of the box, assuming MDES/VTS are integrated. Less popular with cardholders.   Verestro TMP API,   VTS / MDES integration Manually, via TSP website Cardholder needs to register to click to pay via TSP website and manually type card credentials, personal data and accept T&C’s. This flow requires not only a lot of effort from the cardholder, but also knowledge about existence of such websites. Convenient for issuers, as works out of the box, assuming MDES/VTS are integrated. Least popular with cardholders. Verestro TMP API, VTS / MDES integration The Token Management Platform as the Issuer's API Gateway Rather than integrating directly with Visa SRC and Mastercard MDES APIs separately — each with distinct authentication, schemas, and lifecycle models — the issuer connects to a single Token Management Platform. The TMP normalises both networks behind a unified REST API, handles routing to the correct SRCS based on card BIN, manages token lifecycle and provides reporting. Use Cases What Enrollment Creates Enrolling a card into Click to Pay creates two linked artefacts within the TSP's SRC System: • A Consumer Profile (SRC Profile): Tied to the cardholder's verified identity (email address and/or phone number). A single consumer profile can hold multiple enrolled cards across multiple networks. • A Token (Network Token / DPAN): A surrogate value that replaces the PAN for use at Click to Pay checkout. The token is domain-controlled — it is only usable in the SRC context and is bound to the consumer's profile. From an issuer's perspective, enrollment is the act of provisioning the cardholder's PAN and identity into the TMP API, which in turn creates or updates the SRC Profile and requests token issuance from the relevant network SRCS. Available Enrollment Channels An issuer may offer Click to Pay enrollment through any or all of the following channels. The TMP API is the same regardless of channel; the channel determines how the cardholder's identity is verified and consent is captured before the API call is made. Channel Description Typical Consent Mechanism Mobile Banking App (user initiated) Cardholder opts in via the issuer's iOS or Android app. In-app consent screen + biometric or PIN confirmation.   Channel supported by synchronous card enrollment endpoint. Internet web banking (user initiated) Cardholder opts in via the issuer's online banking portal Web consent form + OTP or step-up authentication   Channel supported by synchronous card enrollment endpoint. Card management portal (user initiated) Standalone issuer-hosted portal for card services Portal login + SMS OTP or email OTP   Channel supported by synchronous card enrollment endpoint. No UI, auto enrollment  (issuer initiated) Issuer pushes enrollment without a real-time cardholder session Prior consent captured (T&Cs presented alongside card activation, opt-in campaign, card issuance agreement)     Channel supported by asynchronous bulk enrollment endpoint. Identity Verification and Authentication Requirements The SRC specification requires that a cardholder's identity be verified before their card is enrolled. This is the issuer's responsibility. The TMP carries the verified identity attributes in the enrollment request payload but does not perform identity verification itself. • For user-initiated flows: The issuer's banking application must authenticate the cardholder (e.g., via app PIN, biometric, or step-up OTP) before submitting the enrollment API request. The authentication assurance level must meet the network's minimum requirement. • For issuer-initiated async flows: The issuer must hold a record of prior consent. This is typically captured at card issuance via terms and conditions, an explicit opt-in campaign, or a standing mandate. Regulatory requirements (e.g., GDPR, PSD2) govern the validity of this prior consent. How to Implement User Initiated Enrollment Sequence diagram, happy path   API Documentation API technical documentation can be found on:  TMP API and Issuer API pages. Details may differ, depending on implementation approach, but core APIs are: TMP API: POST /issuer/push-provisioning/c2p   Issuer mobile app backend calls Verestro TMP to enroll a card to Click 2 pay. TMP API:  POST /issuer/push-provisioning/tokens/searches Issuer mobile app backend calls Verestro TMP to check existing token statuses and display or hide "Add to Click to Pay" button in mobile application for better user experience, base on the response. If the card has active Click to Pay token, user shouldn't be able to click "Add to Click to Pay" button.  ISSUER API:  POST /card-verifications Verestro TMP will call Issuer/Processor Card Management System to verify card details and status during predigitization, after enrollment initiation. TMP API: POST /issuer/v2/card-events Card Management System (issuer or processor) calls Verestro TMP to keep us synchronised with token status in MDES/VTS. TMP also performs token lifecycle actions in MDES/VTS, basing on this request.