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.
- American Express
- eftPOS
- Mastercard
- Visa
Set of parameter that may be used to initiate the search differs accross card networks and issuer configuration.
American Express
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 | 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 tokens connected to the matching card. |
eftPOS
The search must include only one of the available search parameters; Account PAN and 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.
| Search Parameter | Description |
|---|---|
| Account PAN | 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 tokens connected to the matching card. |
| Token Unique Reference | 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. |
| Exclude Deleted(Checkbox) | A search will per default include deleted tokens in the response. Mark this box if you want to exclude deleted tokens in the response. |
Mastercard
The search must include only one of the available search parameters; Account PAN, Card ID, 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 |
|---|---|
| Card ID | This is non-sensitive reference to the Primary Account Number in the card management or issuer processing system. Returns tokens connected to the matching card. |
| Account PAN | 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 tokens connected to the matching card. |
| Token Unique Reference | 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 | This is the token number 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 number as a search parameter will return this one specific token details. |
| Payment App Instance ID | 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 | 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 | 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 issuer. 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) | A search will per default include deleted tokens in the response. Mark this box if you want to exclude deleted tokens in the response. |
Visa
The search must include one or both of the available search parameters; Account PAN, Card ID 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.
| Search Parameter | Description |
|---|---|
| Card ID | This is non-sensitive reference to the Primary Account Number in the card management or issuer processing system. Returns tokens connected to the matching card. |
| Account PAN | 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 tokens connected to the matching card. |
| Token Unique Reference | 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. |
| Exclude Deleted(Checkbox) | A search will per default include deleted tokens in the response. Mark this box if you want to exclude deleted tokens in the response. |
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.
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 |
|---|---|
| TUR | Token Unique Reference belonging to the token. |
| PAN Suffix | The four last numbers of the card/funding PAN together with the card expiration date. |
| Token Suffix | The four last numbers of the token/digital PAN together with the token expiration date. |
| Status | This is the current status of the token. Refer to token status section for more details. |
| Status Updated | Recent token status update date. |
| Type | Type of device where token provisioned. |
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.
- American Express
- eftPOS
- Mastercard
- Visa
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. Transactions and Status history is only available for Mastercard.
- Lifecycle management as Suspend, Delete, Update, Resume, Update Token Assurance and Reset Mobile PIN. Update Token Assurance and Reset Mobile PIN is only available for Mastercard. 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 and wallet pair. |
| 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 (Conditional) | 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. 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 element | 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) | Category of the merchant |
| Description | 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 element | 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, Reset Mobile PIN buttons, while when viewing a suspended token the buttons Unsuspend, Delete, and Update are visible.
- American Express
- eftPOS
- Mastercard
- Visa
| Token status | Available LCM commands |
|---|---|
| Unmapped | Activate Delete Update |
| Active | Suspend Delete Update Update token assurance (Mastercard only) Reset Mobile PIN (Mastercard only) |
| Suspended | Unsuspend Delete Update Reset Mobile PIN (Mastercard only) |
| Deleted (or deactivated) | No LCM operations available |
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.
Suspend token - TUR prefilled and user can select reason code and provide a comment for the suspension.
Suspend token - the user can select reason code from the dropdown menu.
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.
Delete token - TUR prefilled and user can select reason code and provide a comment for the deletion.
Delete token - the user can select reason code from the dropdown menu.
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.
Update token - the user can decide whether or not the information should be passed on to the wallet provider
Update token - TUR prefilled and user can provide updated information to one or more parameter.
The below table provides an overview and description of the data fields available when updating a token.
| Data element | Description |
|---|---|
| Token Unique Reference | Pre-filled and not possible to edit, the TUR is the unique identifier of the token. |
| New Account PAN | Conditional - 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 product configuration ID to be applied to the updated token. Conditional field, must not be present if any of the following are present - New Account PAN, New Expiration Date, Account PAN Sequence Number. |
| 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 - New Account PAN, New Expiration Date, Account PAN Sequence Number. |
| 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.
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.