Tokenization Overview
What a payment token is, who is involved, and where UnDosTres sits in the flow.
Tokenization replaces a card's Primary Account Number (PAN) with a different number, called a token, that can be used to pay but is worthless to anyone who steals it. The real PAN never reaches the merchant, the wallet, or the device. It stays in the card network's secure token vault, mapped to the token.
This is what makes Apple Pay and Google Pay possible. When a cardholder adds a card to a phone, the phone does not store the card. It stores a token that only works on that device.
What you need to build
Two things, and they are independent of each other:
- Provisioning — getting a token created and activated on a device or with a merchant. Covered in Provisioning Overview.
- Token lifecycle management — keeping the token's state correct for the life of the card. Covered in Token Lifecycle Management.
Payments themselves need no work from you. A tokenized transaction arrives on the authorization interface you already handle. See How Token Processing Works.
Who does what
%%{init: {"flowchart": {"useMaxWidth": false}}}%%
flowchart TD
CH["Cardholder"] -->|"adds a card"| W["Wallet - Token Requestor"]
W -->|"requests a token"| TSP["Mastercard MDES - Token Service Provider"]
TSP -->|"asks for a decision"| UDT["UnDosTres - Issuer Processor"]
UDT -->|"notifies of every event"| P["You - Programme partner"]
| Role | Who | Responsibility |
|---|---|---|
| Cardholder | Your customer | Owns the card being tokenized |
| Token Requestor | Apple Pay, Google Pay, Samsung Pay, a merchant | Asks for a token and uses it to pay |
| Token Service Provider (TSP) | Mastercard MDES | Creates, stores, suspends, resumes, deletes and re-digitizes tokens. Owns the token vault |
| Issuer Processor | UnDosTres | Authorizes every provisioning request and every token transaction. Holds the integration and certification with MDES |
| Programme partner | You | Owns the cardholder relationship, their contact details, and your own card statuses |
UnDosTres is the BIN sponsor and the Token Issuer of record. You never integrate with Mastercard directly, and you never hold a token vault. You integrate with UnDosTres.
Token states
Every token is in exactly one of these states. They are reported in current_status_description on ListActiveTokens and ListAllTokens.
| State | Meaning |
|---|---|
| Unmapped | Not yet linked to the PAN. Tokenization is still in progress |
| Active | Linked to the PAN and able to start new transactions |
| Suspended | Linked to the PAN but temporarily blocked from transacting |
| Deleted | Logically deleted. Still linked to the PAN so that post-authorization traffic such as refunds can be processed |
Note that Deleted is not the same as gone. A deleted token still resolves for settlement and refunds on transactions that already happened.
Token types
| Code | Type | Used for |
|---|---|---|
C | Cloud-Based Payments (HCE) | Contactless payments. Keys are limited-use and replenished online, so a limited number of offline authorizations is possible |
S | Embedded Secure Element | Contactless payments. Keys live in the device's secure element |
F | Card on File | Card-not-present. Provisioned to a merchant or e-commerce platform rather than a device |
Terminology
Terms used throughout these guides and in the API reference.
| Term | Meaning |
|---|---|
| PAN | Primary Account Number. The real 16-digit card number |
| Token | The surrogate number that replaces the PAN |
| Token Unique Reference (TUR) | The token's unique identifier. Returned as token_unique_reference, and the value you pass as token_reference |
| Token vault | The TSP-owned store that maps every token back to its PAN |
| Digitization | The full process of creating a token and getting it onto a device. Used interchangeably with tokenization and provisioning |
| Push provisioning | The cardholder adds the card to a wallet from inside your app, with one tap |
| Manual provisioning | The cardholder types the card details into the wallet app |
| Activation code / OTP | A short code, usually six digits, that proves the cardholder owns the card. Generated and validated by MDES |
| Wallet ID (WID) | A three-digit number identifying the wallet that requested the token |
| KLV | Key-Length-Value. The string encoding used to carry data in administrative messages. See KLV Lookup |
| Administrative Message | The XML-RPC callback UnDosTres sends you when something happens to a token |
| TAV | Token Authentication Value. An encrypted signature that authenticates a push provisioning request. Calculated by UnDosTres, not by you |
Scope today
These guides cover Mastercard MDES, for Apple Pay and Google Pay.
Visa Token Service and Click to Pay are not in scope and are not currently available on this programme.
Where to go next
- New to this? Read Provisioning Overview next.
- Want the endpoint list? Go to the Tokenization API reference.
- Want to know what to do when something specific happens? Use Cases and Runbook is a lookup table.
Updated about 2 hours ago