Token Management Platform

• Article
• Tokenization and Contactless Payments - Verestro's competitive advantages
• Tokenize it!
• Push Provisioning Step by Step
• Push Provisioning & Web Push Provisioning
• Tokenization in eCommerce Payments
• Introduction
• Intro Slides
• Overview
• Use Cases
• Quick Integration Guide
• Issuer API
• TMP API
• Additional APIs
• Rule Engine
• Connectivity & Security
• Token Management Platform for Card Issuing
• Overview
• User notifications
• Push provisioning
• Click to Pay - Integration guide for Issuers
• Business Overview
• Use Cases

Article

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

Features overview

Verestro Token Management Platform supports below functionalities:

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:

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:

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:

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:

1. Check if card is tokenized.
2. Sign card .

Verestro TMP Push Provisioning module allows the following flow:

1. 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.
2. Sign card - Prepare encrypted and signed payload which can be used by the Issuer's mobile application.
3. Initiate Push Provisioning with Apple Pay/Google Pay SDK.
4. Authorize Service to  Verestro TMP.
5. 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:

Jobs.

Verestro TMP can generate/notify or do some other custom task automatically, like:

Monitoring and 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:

1. Cards stored in Verestro Data Core with the use of Lifecycle API
2. 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

🔄 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)

• 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

The same certificate used for TLS client authentication may be used for encrypting JWE payloads, leveraging the associated public key.

4.3 Example code

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;
}

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

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.

1. Introduction - here you will find high level overview of the solution.
2. User notifications - page dedicated to different user notifications and possible ways to send them
   
3. Push provisioning - page with all the details necessary to enhance your cardholders experience with push provisioning
   
4. InApp authentication - page dedicated to replace sending SMS OTP codes with InApp authentication
   

Overview

Thanks to TMP your cardholders will be able to:

1. Manually add their cards to Apple Pay, Google Pay, Samsung Pay, Garmin Pay and other X-Pays (manual provisioning) (basic feature)
2. Tokenize the cards in various ecommerce stores with the use of M4M (Mastercard for Merchants) service (basic feature)
3. 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)
4. 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:

1. Admin panel allows your customer service to review the tokenizations and manually activate or deactivate tokens
2. Thanks to integration with Verestro Life Cycle API all token statuses will be updated automatically, according to card statuses
3. Our backend simplifies encryption mechanisms required by X-Pays in Push Provisioning process
4. 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:

More information about rules engine and path decisions can be found here.

Verification steps:

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:

1. 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.
2. 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.
3. 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:

1. Check if the card is tokenized.
2. Sign card.

Verestro TMP Push Provisioning module allows the following flow:

1. 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.
2. Sign card - Prepare an encrypted and signed payload that can be used by the Issuer's mobile application.
3. Initiate Push Provisioning with Apple Pay/Google Pay SDK.
4. Authorize Service to  Verestro TMP.
5. 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

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.

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.

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:

1. TMP API: POST /issuer/push-provisioning/c2p  Issuer mobile app backend calls Verestro TMP to enroll a card to Click 2 pay.
2. 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. 
   
3. 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.
4. 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.