Guides
Log into Sandbox

Token Lifecycle Management

Suggest Edits

This guide describes the procedure for managing token lifecycles using the Get Card Tokens and Manage Card Token endpoints. With these endpoints you can retrieve tokens associated with a card and then suspend, resume, or delete them one at a time, according to the use case.

👍

Availability

The Get Card Tokens and Manage Card Token endpoints will be available in CV before the end of October 2025. The endpoints currently support Mastercard only. Visa support will be deployed at a later date.

Follow this procedure to:

  • Retrieve card-token information such as current token status, token expiry, and the entity that last updated the token.
  • Perform the suspend, resume, or delete operations on a token and specify the reason.

Do not follow this procedure to:

  • Automatically delete all tokens when a card is reported lost, stolen, or closed (canceled); instead, contact Galileo to set the AMTL (Mastercard) or AVTL (Visa) parameters.
  • Provision a card to a mobile wallet; instead, see Setup for Mobile Wallets.
  • Mark a card as lost or stolen in the Galileo system; instead, see Lost, Stolen, or Damaged Cards.
  • Cancel a card in the Galileo system; instead, see Card cancelation in the Setting Up a Card Program guide.
  • Freeze a card in the Galileo system; instead, see Freezing cards in the Card Statuses guide.
  • Reactivate a card in the Galileo system; instead, see Card reactivation in the Setting Up a Card Program guide.

As explained in Mobile wallet support in Choose a Card Strategy, a token is a randomized string that refers to a PAN. The token resides in a mobile wallet instead of the PAN, which prevents malicious actors from accessing sensitive information in the wallet or during transmission.

Token types

Tokens are classified according to where they reside:

  • token_type: C — Server based — The token resides in the cloud rather than on a consumer device. Typically used by merchant mobile wallets such as Amazon Pay and click-to-pay solutions.
  • token_type: F — COF — The token has been saved by the merchant, such as for subscriptions, recurring payments, in-app purchases, and one-click checkout.
  • token_type: S — Device based — The token is saved in a mobile wallet app such as Apple Pay or Samsung Pay on a mobile phone, smart watch, or similar device.

Token lifecycle

A token lifecycle refers to the various statuses that a token may pass through from initial creation to deletion. As the status of a card or its account changes in the Galileo system the status of the token needs to change accordingly.

The token lifecycle consists of these phases:

  • Unmapped — The token has been created but has not yet been assigned to a PAN or activated.
  • Active — The token is associated with a PAN, and it has been validated and approved. It can be used to make card transactions.
  • Suspended — The token has been temporarily deactivated. It cannot be used to make card transactions. From this status, it can be restored to Active status.
  • Deleted — The token has been deactivated or removed from the device. It cannot be restored to Active status.

Token expiry

The token expiry date is assigned by the network tokenization service upon activation, and it usually does not correspond with the expiry date of the PAN that the token represents. The token often has a longer validity period than the PAN to help the transition during card reissue or replacement—the extra time gives the new token the opportunity to be remapped to the reissued PAN without disrupting the customer experience.

Token Management with Program API

Galileo provides two endpoints to help you with token management. To use these endpoints, the MTLCM parameter must be set.

Get Card Tokens

With the Get Card Tokens endpoint you can retrieve information about existing card tokens for the specified card.

Parameters

These are the request parameters that are specific to Get Card Tokens. None of them are required.

ParameterDescription
tokenUniqueReferenceA unique 48-character reference assigned to a token and used to identify the token for the duration of its lifetime. Also called the TUR.

You can retrieve this value from a previous Get Card Tokens response or from the token_id field of the xTCN: mobile_activation TCN event message.

Populate this field when you want to retrieve a specific token.
includeDeviceTokensOnlySpecifies whether to retrieve only the device-based tokens (token_type: S) or to receive all tokens mapped to the PAN.
excludeDeletedIndicatorSpecifies whether to exclude deleted tokens from the response.

  1. The first time you call Get Card Tokens for a card, pass these parameters:

    • accountNo — Pass the PAN, PRN, or CAD. Do not pass the PRN if more than one card has ever been associated with the PRN.
    • tokenUniqueReference — Leave blank.
    • includeDeviceTokensOnly — Pass true to exclude server-based and COF tokens from the response. See Token types for an explanation of these types.
    • excludeDeletedIndicator — Pass true to exclude deleted tokens from the response.

  2. The endpoint returns one or more token entries, sorted from oldest to newest. Each entry represents one token instance that is mapped to the same PAN. For example, if the PAN is mapped to one device-based token, three COF tokens, and four server-based tokens, then the response will return eight entries, provided that includeDeviceTokensOnly: false. This example shows one of each token type:

    "token_details_mc": [
      {
        "current_status_code": "A",
        "current_status_date_time": "2025-07-11T11:35:57-06:00",
        "current_status_description": "Active",
        "expiration_date": "0728",
        "token_requestor_id": "50110030273",
        "token_requestor_name": "APPLE PAY",
        "token_type": "S",
        "token_unique_reference": "DM4MMC1CA0000000a86c710dff0c4e2ea3be39dfa676daba",
        "wallet_id": "327"
      },
      {
        "current_status_code": "A",
        "current_status_date_time": "2025-10-17T23:44:24-06:00",
        "current_status_description": "Active",
        "expiration_date": "0928",
        "token_requestor_id": "50181236725",
        "token_requestor_name": "Mastercard Click to Pay",
        "token_type": "C",
        "token_unique_reference": "DM4MMC1CA0000000327fe78a260b4c388e38bfe3ae91d54b",
        "wallet_id": ""
      },
      {
        "current_status_code": "A",
        "current_status_date_time": "2025-11-21T14:22:59-07:00",
        "current_status_description": "Active",
        "expiration_date": "1128",
        "token_requestor_id": "40010077761",
        "token_requestor_name": "UBER TECHNOLOGIES INC.",
        "token_type": "F",
        "token_unique_reference": "DM4MMC1CA0000000bc6c8f31625049e69d0661f6f6ccd85e",
        "wallet_id": ""
      },
    ]

Get Card Tokens response fields

This table explains the response fields.

FieldDescription
token_unique_referenceUnique ID assigned to a token instance, which identifies the token for the duration of its lifecycle.
expiration_dateExpiration date of the token, which may or may not match the card expiry.
current_status_codeCurrent status of the token. The current_status_description field contains the value descriptions:
  • U — Unmapped
  • A — Active
  • S — Suspended
  • D — Deleted
    • current_status_descriptionDescription for current_status_code.
    current_status_date_timeTime that the current status was applied.
    token_requestor_idNumeric identifier for a token requestor.
    token_requestor_nameThe legal name of the token requestor, according to network records.
    token_typeSee Token types for valid values.
    wallet_idIdentifier of the wallet provider that requested the device token. Populated only when token_type: S. This identifier is assigned by MDES for each wallet or payment-app brand.

    👍

    Tip

    Capture these response values for easy retrieval next time you need to manage a token.

    Manage Card Token

    Now that you have the TUR for the token, you can change its status. Populate the request parameters for Manage Card Token according to your use case.

    Parameters

    These are the request parameters that are specific to Manage Card Token.

    ParameterDescription
    tokenUniqueReferenceRequired. The TUR of the token to manage.

    You can retrieve this value from the Get Card Tokens response or from the token_id field of the xTCN: mobile_activation TCN event message.
    operationRequired. The operation to perform on the token:
  • SUSPEND — Temporarily disable the token so that it cannot make any transactions
  • RESUME — Restore the token to Active status
  • DELETE — Delete the token.
    • reasonCodeThe reason for performing the operation. Go to the Manage Card Token Values page to see which reasonCodes are valid for each operation.
    deleteFromConsumerAppIf operation: DELETE, specify whether to remove the token from the cardholder device or whether to also remove it from the MDES system.

    If you pass true, then the token is deleted from the cardholder device—an Apple Pay wallet on an iPhone, for example—but it remains active on the MDES platform. In this case, the cardholder might re-enable or reinstall the wallet later, and then the token can be added to the wallet without reprovisioning.

    If you pass false, then the token is deleted from the MDES platform as well as the device. In that case, the card must be reprovisioned from scratch.

    Manage Card Token response

    When the endpoint has been successfully called, the endpoint echoes back the TUR of the token that was updated.

    Updated 20 days ago

    © Galileo Financial Technologies, LLC 2025    Privacy Disclosure

    All documentation, including but not limited to text, graphics, images, and any other content, are the exclusive property of Galileo Financial Technologies, LLC and are protected by copyright laws. These materials may not be reproduced, distributed, transmitted, displayed, or otherwise used without the prior written permission of Galileo Financial Technologies, LLC. Any unauthorized use or reproduction of these materials are expressly prohibited.