Putting together the bytes

Token Management

The Token Management application allows the user to search for tokens to view their details, and to perform lifecycle management related updates to the token. MSP is implemented to reduce differences between the payment networks to the extent possible, but some limitations exists resulting in slight variations in data available to use for searching, visible to see, or to update. While this guide tries to identify such differences, please contact us if you see any discrepancies that should be mentioned here.

Search

The first step in managing the tokens is to search for the token(s). The search feature provides the functionality to lookup tokens, based on a number of parameters. The following subsections will cover the basic usage of this feature.

How to search

As you enter the Token Management page, you will see the search field. Before searching for a token, you need to select the relevant card network to which the card/token belongs to.  

Token search options for MDES
The search must include only one of the available search parameters; Account PAN, Token Unique Reference, Token, Payment App Instance Id and Alternate Account Identifier. The Search button is by default disabled and will be enabled first when entering a value of valid format in one of the fields.
Search parameter Description
Account PAN Definition This is the Primary Account Number. The PAN will be minimum 9 digits and maximum 19 digits. This field has a built in Luhn check to validate that the card number is entered correctly. Returns Using the Account PAN as a search parameter will return tokens connected to the Account matching this number.
Token Unique Reference (TUR) Definition This is a unique reference which is created and assigned following the allocation of a token. It is used to identify the token for the duration of its lifetime. The TUR field will be a char string with max length 64. Returns Using TUR as a search parameter will return the one single matching token.
Token Definition This is the token that is generated upon digitization at the Token Service Provider, mapped to the Account PAN and issued onto the mobile device. The Token will be minimum 9 digits and maximum 19 digits. Returns Using the Token as a search parameter will return this one specific token.
Payment App Instance ID Definition This is the identifier of the Payment App instance within a device that will be provisioned with a token. Returns The Payment App Instance Id will return all the tokens associated with the specific Payment App Instance on the device.
Comment Id Definition Comment Id is generated when any comment are submitted to a specific token. Returns When using this as a search parameter, it will return the specific token that is associated with this comment.
Alternate Account Identifier Definition An Alternate Account Identifier is a cardholder-friendly reference to a bank account, for example an IBAN (International Bank Account Number). Note! This might not be implemented by the bank. Returns Using Alternate Account Identifier as a search parameter will return all tokens associated with this identifier. This is similar to the Account PAN.
Exclude Deleted (checkbox) Definition A search will per default include deleted tokens in the response. Mark this box ff you want to exclude deleted tokens in the response.
Token search options for VTS

The search must include one or both of the available search parameters; Account PAN and/or Token Unique Reference. The Search button is by default disabled and will be enabled first when entering a value of valid format in one of the fields.

Exclude Deleted (checkbox)

Definition
A search will per default include deleted tokens in the response. Mark this box ff you want to exclude deleted tokens in the response.

Search parameter Description
Account PAN

Definition
This is the Primary Account Number. The PAN will be minimum 9 digits and maximum 19 digits. This field has a built in Luhn check to validate that the card number is entered correctly.

Returns
Using the Account PAN as a search parameter will return tokens connected to the Account matching this number.

Token Unique Reference (TUR)

Definition This is a unique reference which is created and assigned following the allocation of a token. It is used to identify the token for the duration of its lifetime.

The TUR field will be a char string with max length 64.

Returns
Using TUR as a search parameter will return the one single matching token.

Token search options for Amex TS

Searching for Amex tokens only support searching by Account PAN. The Search button is by default disabled and will be enabled first when entering a value of valid format in the Account PAN field.

Search parameter Description
Account PAN

Definition
This is the Primary Account Number. The PAN will be minimum 9 digits and maximum 19 digits. This field has a built in Luhn check to validate that the card number is entered correctly.

Returns
Using the Account PAN as a search parameter will return tokens connected to the Account matching this number.

Token search options for eftpos TSP

The search must include only one of the available search parameters; Account PAN or Token Unique Reference. The Search button is by default disabled and will be enabled first when entering a value of valid format in one of the fields.

Exclude Deleted (checkbox)

Definition
A search will per default include deleted tokens in the response. Mark this box ff you want to exclude deleted tokens in the response.

Search parameter Description
Account PAN

Definition
This is the Primary Account Number. The PAN will be minimum 9 digits and maximum 19 digits. This field has a built in Luhn check to validate that the card number is entered correctly.

Returns
Using the Account PAN as a search parameter will return tokens connected to the Account matching this number.

Token Unique Reference (TUR)

Definition This is a unique reference which is created and assigned following the allocation of a token. It is used to identify the token for the duration of its lifetime.

The TUR field will be a char string with max length 64.

Returns
Using TUR as a search parameter will return the one single matching token.

Search result

The search page contains a table where each row represents a unique token, as shown in the below picture. The user can enter the token details page by clicking anywhere in the row for the relevant token.

An example of a search result, resulting in a number of tokens

Filter result

The search page allows the user to easily filter the search result, to easier find the relevant token. The user can filter the result in one out of three ways:

  • Filter by any field – allowing the user to enter any data and only display tokens that holds this data. This can be status, PAN or token suffix, device or device type
  • Filter by status – allowing the user to see only active or only deactivated (deleted) tokens.
  • Filter by device type – allowing the user to see only tokens stored on a specific device type

Understanding the list of tokens

Each row contains the columns PAN Suffix, Token Suffix, Status, Device Name and Device Type. These will be populated with results provided by the token service provider after a successful search. Depending on the network, the information may or may not be available. The information found in the columns are explained in the table below.

Column title Description
PAN Suffix
The four last numbers of the funding PAN together with the card expiry date and scheme.
Token Suffix
The four last numbers of the token PAN together with the token expiry date
Status

This is the current status of the token. Please refer to token status section for more details.

Device
This is the name of the phone/device on which the the token is stored. The name is presented as provided by the token requestor (i.e. the "wallet") and may be more or less informative.
Type
Shows the type of the device on which the token is stored (e.g., phone, watch, tablet, eCommerce).

Token page

The purpose of the token page is to provide a detailed overview of the token, its parameters, transaction and status history (when available) in a categorized and structured way. It also allows for lifecycle management for the specific token.

Different sections of the token details page

The token details page is divided into several sections, and you can use the tabs and buttons to navigate to the specific section or action you want to: 

  • Token details, Transactions, and Status history (marked in dotted green rectangle)
  • Lifecycle management (marked in dotted orange rectangle)

Each section is described in more details below.

Different sections of the Visa token details page

The token details page is divided into several sections, and you can use the tabs and buttons to navigate to the specific section or action you want to: 

  • Token details (marked in dotted green rectangle)

Each section is described in more details below.

Different sections of the eftpos token details page

The token details page is divided into several sections, and you can use the tabs and buttons to navigate to the specific section or action you want to: 

  • Token details (marked in dotted green rectangle)
  • Lifecycle management (marked in dotted orange rectangle)

Each section is described in more details below.

Different sections of the eftpos token details page

The token details page is divided into several sections, and you can use the tabs and buttons to navigate to the specific section or action you want to: 

  • Token details (marked in dotted green rectangle)
  • Lifecycle management (marked in dotted orange rectangle)

Each section is described in more details below.

Token details

You enter the token details tab by default, or by clicking the “Token Details” tab when on the Token Management page. This tab displays detailed information on the selected token. The following table is meant to give a brief explanation of the displayed data.
Note: Conditional values will only be present if successfully assigned and provided in the response, and may depend on the payment network whether it exists or not.

Data element Description
Token Unique Reference (TUR) (Conditional)
A unique reference which is created and assigned following the allocation of a token. It is used to identify the token for the duration of its lifetime.
Token Suffix (Conditional)
Last 4 digits of a token. Present once the token has been designated for the digitization.
Account PAN
Last 4 digits of the PAN to which the token is connected.
PAN Reference (Conditional)
Unique reference to the Account PAN which was originally digitized.
Account PAN Seq Nr (Conditional)
The Account PAN Sequence Number is associated with a specific token. This is provided to by the issuer during pre-digitization. It may be used to distinguish between multiple cardholders for a single Account PAN, to represent an issuance number of a specific card, or to distinguish between different card products, such as debit or credit, that share the same Account PAN. It is a conditional field, and thus present when successfully assigned.
Token Expiration Date (Conditional)
Expiration date of token on the format "mmyy".
Wallet ID (Conditional)
Identifier of the Wallet Provider who requested the digitization or tokenization. Present when supplied by the Payment App Provider.
Token Type
Type of token. Valid values: "S" - Embedded Secure Element token "C" - Mastercard Cloud-Based Payments token "F" - CoF token
Activation Code Expiration (Conditional)
Date and time when an Activation Code will expire. This is a conditional field which is only present when an Activation Code has been generated and activation has not yet occurred. The date and time may be in the future or past. Date format: mm/dd/yyyy hh:mm UTC+2
Requestor ID
The Token Requestor ID (also known as TRID) is the unique ID identifying the Token Requestor.
Requestor Name
The legal name of the token requestor. Note that there can be more than one Token Requestor ID per Token Requester Name (legal name). Thus it is important to use both parameters to uniquely identify a token requestor. String, up to 100 characters.
Current Status
This is the current status of the Token. Valid values:
  • "U" - Unmapped. The token has not yet been linked to the Account PAN. The process of tokenization is ‘In Progress.'
  • "A" - Active. The token is linked to the Account PAN and may be used for transactions.
  • "S" - Suspended. The token is linked to the Account PAN but can not perform transactions.
  • "D" - Deleted. The token is logically deleted but is still linked to the Account PAN for the purposes of post-authorization transaction processing.
Current Status Time
Date and time the status was updated. Date format: mm/dd/yyyy hh:mm UTC+2
Payment App Instance ID
Identifier of the Payment App instance within a device that will be provisioned with a token. NOTE - This may contain the identifier of the Secure Element or a mobile device for some programs.
Activated Date (Conditional)
Date and time that the token was activated. Present when the Token has been activated. Date format: mm/dd/yyyy hh:mm UTC+2
Activation Code Expiration (Conditional)
If an activation code has been generated, this field shows the date and time for when the activation code expires. If not used before expiration, the user must either request a new activation code, or activate the token otherwise. Date format: mm/dd/yyyy hh:mm UTC+2
Storage technology
The architecture or technology used for token storage. Valid values:
  • "D" - Device memory
  • "P" - Device memory protected by Trusted Platform Module (TPM)
  • "H" - Server
  • "E" - Trusted Execution Environment (TEE)
  • "S" - Secure Element (SE)
  • "V" - Virtual Execution Environment (VEE)
Digitization Request Time (Conditional)
Date and time of the initial request for digitization of the Account PAN for this token. Date format: mm/dd/yyyy hh:mm UTC+2
Provisioning Status (Conditional)
Current provisioning status of the token. Valid values:
  • "P" - Token being prepared
  • "T" - Awaiting cardholder acceptance of Terms and Conditions
  • "D" - Token being delivered to Wallet Provider or Device
  • "A" - Awaiting Activation
  • "S" - Provisioning successful
  • "F" - Provisioning failed.
Tokenization Decision (Conditional)
Final decision related to the digitization of the Account PAN for this token. Valid values:
  • "D" - Digitization was declined
  • "A" - Digitization was approved
  • "R" - Digitization was approved but required authentication prior to activation.
Assurance Level (Conditional)
Indicates the level of Identification and Verification performed to validate the Cardholder and the Cardholder's account at the time the Token was issued (or at any subsequent time post-issuance). Only present when a token has a Token Assurance Level assigned. Supported values are 0 (Not Authenticated) and non-zero (Authenticated).
Correlation ID (Conditional)
Value linking pre-digitization messages generated during provisioning.
Last Comment ID
Identifier of the last comment associated with the token.

Transactions

The Transactions tab contains a simple overview of the latest transactions performed with the token within the last 30 days. Please note that transactions are only available for Mastercard tokens, and the tab is not displayed when viewing tokens issued by other payment networks.

The following table displays the available information and related description.

Note: Conditional values will only be present if successfully assigned and provided in the response.

Data Description
Date
Date and time the comment was updated. Date format: mm/dd/yyyy hh:mm UTC+2
Code
Type of transaction. Valid values:
  • "PURCH" = Purchase
  • "PURCB" = Purchase with Cashback
  • "REFND" = Refund
  • "AFD" = Purchase Pre-Auth AFD
  • "CLRRF" = Clearing Refund
  • "NAFD" = Purchase Pre-Auth Non-AFD.
Currency
This is the currency code as per ISO-4217.
Amount
This is the amount of the transaction. Format includes decimals.
Status
Transaction status. Valid values:
  • "AUTH" = Authorized
  • "COMP" = Completed
  • "DCLN" = Declined
  • "PAUTH" = Pre-Authorized
  • "PAUTC" = Pre-Authorization Completed
  • "PAUTD" = Pre-Authorization Declined
  • "REFND" = Refunded
POS Entry Mode (Conditional)
This indicates the mode by which transaction data was collected at the merchant. Valid values:
  • "07" - Contactless M/Chip transaction
  • "09" - Digital Secure Remote Payment containing EMV data
  • "81" - Digital Secure Remote Payment containing UCAF data or CoF
  • "82" - CoF - PAN auto entry via server
  • "90" - Dynamic Magnetic Stripe Data
  • "91" - Contactless magnetic stripe
Merchant (Conditional)
Name of the merchant
Category (Conditional)
Merchant category of the merchant
Decription
Description of the merchant category. (E.g. GROCERY STORES, SUPERMARKETS)

Status history

The Status History tab – currently only available for Mastercard tokens – presents a view of the historical statuses and lifecycle events for a token. These are events such as when it was initially activated, suspended, resumed or deleted. The following table shows the information presented by this tab, in addition to related descriptions.

Data Description
Status Code
This is the status of the Token. Valid values:
  • "U" - Unmapped. The token has not yet been linked to the Account PAN. The process of tokenization is ‘In Progress’.
  • "A" - Active. The token is linked to the Account PAN and may initiate new transactions to be authorized.
  • "S" - Suspended. The token is linked to the Account PAN but may not perform transactions at the request of one or more suspenders.
  • "D" - Deleted. Sometimes referred to as deactivated. The token is logically deleted but is still linked to the Account PAN for the purposes of post-authorization transaction processing.
Initiator
The initiator of the status update. Valid values:
  • "I" - Issuer
  • "W" - Token Requestor (including Wallet Provider)
  • "C" - Cardholder
  • "P" - Mobile PIN Validation service
  • "M" - Mobile PIN Change Validation service
Reason Code
Reason for the status update. Valid values:
  • "A" – Cardholder successfully authenticated using a mobile App prior to activation
  • "C" – Cardholder successfully authenticated with a customer service agent prior to activation. (For 'Token Activate')
  • "C" – Account closed. (For 'Token Delete')
  • "F" – Cardholder reported token device found or not stolen
  • "L" – Cardholder reported/confirmed token device lost
  • "S" – Cardholder reported/confirmed token device stolen
  • "T" – Issuer or cardholder reported fraudulent/then confirmed no fraudulent token transactions
  • "Z" – Other
Date
Date and time the status was updated. Date format: mm/dd/yyyy hh:mm UTC+2
Comment (Conditional)
Comment provided by initiator when updating token status.

Lifecycle management

All token lifecycle management functionalities are located in a horizontal menu in the top right corner of the token page. Which buttons/actions that are available is depending on the payment network, as well as on the token status. For example: when viewing an active token may show Suspend, Delete, Update, and Update assurance buttons, while when viewing a suspended token the buttons Unsuspend, Delete, and Update are visible.

Token status Available LCM commands
Unmapped
  • Activate
  • Delete
  • Update

Active

  • Suspend
  • Delete
  • Update
  • Update token assurance
  • Reset mobile PIN
Suspended
  • Unsuspend
  • Delete
  • Update
  • Reset mobile PIN

Deleted (or deactivated)

No LCM operations available
Token status Available LCM commands
Unmapped
  • Activate
  • Delete
  • Update

Active

  • Suspend
  • Delete
  • Update
Suspended
  • Unsuspend
  • Delete
  • Update

Deleted (or deactivated)

No LCM operations available
Token status Available LCM commands
Unmapped
  • Activate
  • Delete
  • Update

Active

  • Suspend
  • Delete
  • Update
Suspended
  • Unsuspend
  • Delete
  • Update

Deleted (or deactivated)

No LCM operations available
Token status Available LCM commands
Unmapped
  • Activate
  • Delete
  • Update

Active

  • Suspend
  • Delete
  • Update
Suspended
  • Unsuspend
  • Delete
  • Update

Deleted (or deactivated)

No LCM operations available

The following sections will go through the different features and their use cases.

Audit logging

The APIs from the network TSPs (e.g. MDES, VTS) are set up to require audit information (such as user id, username, and organization) for every lifecycle management request. The Mea Service Portal provides this information based on the logged in user meaning that all changes performed on a token are logged and shared with the network TSP.

Activate token

This is used to activate a token (that has been approved and provisioned onto the mobile device) that requires additional cardholder authentication prior to activation.

Use case
In the process of digitization, the cardholder wants to activate the token to complete the process. The cardholder may then contact the Issuer’s customer service desk who will authenticate the cardholder and use this functionality in order to manually activate the token.

Suspend Token

This is used to suspend an active token so that it may not initiate any new transactions. When clicking on Suspend, a dialog box is presented with the Token Unique Reference pre-populated as shown in the image below. It is required to provide one of the following reason code: Device Lost, Device Stolen, Suspected Fraud, Other. The user may also leave a comment to the suspension.

Note: All payment transactions for a SUSPENDED token will be declined by the network TSP.

Use case
When the customer service desk finds it necessary to suspend a token, e.g. the customer calls in to report a lost phone or to block their payment card. The customer service employee may then use this function to suspend the token with a reason code.

Unsuspend token

This is used to unsuspend (also known as resume) a suspended token and return it to the active state where it may be used for new transactions. A suspended token will only be unsuspended when all suspenders have unsuspended the token

Unsuspending suspended tokens

Tokens may be suspended by multiple parties (suspenders) concurrently. The token status is updated from ACTIVE to SUSPENDED when the first suspender triggers a suspend action. Additional suspenders can add their suspend action to the list of suspenders. Suspenders can unsuspend only their own suspend action. All suspenders need to perform an unsuspend action to move a token from SUSPENDED to ACTIVE. The token status will only change when the last suspender has unsuspended the token. The Status History tab shows the history of suspending and unsuspending.

Delete token

This is used to delete an active token so that it may not initiate any new transactions. When clicking on Delete, a dialog box is presented with the token unique reference pre-populated. It is required to provide one of the following reason code: Device Lost, Device Stolen, Suspected Fraud, Other. The user may also leave a comment to the deletion.  All payment transactions for a deleted token will be declined. A deleted token may not be returned to an active state.

Update token

This is used to update Account PAN Mapping Information or Issuer Product Configuration ID associated to a provisioned token. Updates will only be applied to tokens in active or suspended state, not those in in progress or deleted state.

When clicking on the Update-button, a dialog box is presented with the token unique reference pre-populated as shown in the images below. 

The below table provides an overview and description of the data fields available when updating a token.

Data field Description
Token Unique Reference
Pre-filled and not possible to edit, the TUR is the unique identifier of the token.
New Account PAN

Optional - New Account PAN to be applied to the updated token if there is in fact a new Account PAN. Optional if updating Expiration Date or PAN Sequence Number.

New Expiration Date

Conditional - New expiration date to be applied to the updated token. Conditional field, must not be present when IssuerProductConfigurationId is present. Optional if updating PAN mapping or PAN Sequence Number.

New PAN Sequence Number

Conditional - New PAN sequence number to be applied to the updated token. Conditional field, must not be present when IssuerProductConfigurationId is present. Optional if updating PAN mapping or Expiration Date.

Issuer Product Configuration ID

Conditional - New product configuration ID to be applied to the updated token. Conditional field, must not be present if any of the following are present - NewAccountPan, ExpirationDate, AccountPanSequenceNumber.

Wallet Provider Indicator
Indicates whether the updated token information should be provided to the Wallet Provider.

Update token assurance

Used after an issuer has performed additional cardholder authentication to indicate an increased level of token assurance. It will only be applied to tokens that actually have a Token Assurance Level, and those that are in active or suspended state.

Resend activation code

(NB: Only relevant to banks that have implemented support for yellow path)

This is used to trigger the process of generating and sending a new Activation Code (for a specific token) to the cardholder via the requested Activation Method. When successful, a new Activation Code Expiration Date Time period will begin, and a new Activation Code will be sent to the issuer using the relevant pre-digitization network message.

It can only be used to do this for Activation Methods that involve the external distribution of an Activation Code to the cardholder. For example, via email or SMS. It cannot be used to send a new activation code via the “Mobile Application” activation method, for instance. A new Activation Code can be sent even if the previous code has not expired. A new Activation Code can also be sent even after the previous code has expired; however, it can only be done up to 30 days after the token was created (the number of days is subject to change at the discretion of the network TSP).

Reset mobile PIN

Relevant only for MCBP wallets, this allows the user to request a reset for a token-level or wallet-level Mobile PIN.

On this page