Skip to main content
Welcome to the preview portal — This is an early release of the new Doc Hub experience, with more content coming soon.

Lifecycle Management

Life-cycle management is a key feature of credentials-on-file (COF) network tokenization. Issuers can keep COF network tokens updated as changes are made to their cardholders' accounts.

notifies you in real time when updates are made to a card represented by the COF network token in your vault. Issuers push the life-cycle management updates either in real time or via a batch process to the card brands. Life-cycle updates and timelines will vary by issuer based on their update process. For example, notifies you when a card becomes inactive.

and webhooks enable you to stay informed about the status of COF network tokens in different ways:

  • Subscribe to real-time notifications for lifecycle management events using Webhooks.
  • Generate reports that contain life-cycle management events for network tokens. You can generate reports that contain Life-Cycle Management events for Network Tokens. These reports include network token-related fields that are updated as a result of the Life-Cycle Management events sent to the .
  • Simulate life-cycle management for Visa cards using the simulator.

For example webhook notifications, see Webhook Notification Examples.

When a network token is provisioned, these life-cycle management reasons can be applied:

ReasonDescription
PROVISIONEDA network token has been provisioned.
CARD_UPDATEDThe card expiration date or last four digits have been updated.
TOKEN_EXPIRY_UPDATEDThe token expiration date has been updated.
TOKEN_UPDATEDThe token expiration date and token status have been updated.
METADATA_UPDATEDThe card metadata such as card art or issuer data has been updated.
REDIGITIZATIONA new network token has been created due to redigitization. This status is available only for Mastercard.
TOKEN_STATUS_UPDATEDThe status of the network token has been updated.

When you receive the TOKEN_STATUS_UPDATED life-cycle management update reason, one of these network token statuses is applied:

StatusDescription
ACTIVEThe account and network token are active and in good standing. When COF network tokens are active, merchants can process transactions according to their COF agreement.
SUSPENDEDThis status is temporary for COF network tokens and can change to ACTIVE or DELETED. Merchants should not send authorizations on suspended tokens. These tokens can be re-activated by the issuer later.
DELETEDThis is the final state for a network token. A network token can be deleted when the account is closed or on cardholder instruction.

Webhook Notification Examples

These examples show different notifications for life-cycle management events:

{   "eventType":"tms.networktoken.provisioned",   "webhookId":"3xxxxffb-xxxx-fae4-e063-a058xxxx266f",   "productId":"tokenManagement",   "organizationId":"OrganizationId",   "eventDate":"2025-07-03T09:58:09",   "transactionTraceId":"f25xxxx-38eb-4a2c-a065-732fxxxx6a7f-0",   "retryNumber":0,   "payload":{      "data":{         "reason":"PROVISIONED",         "id":"3904693A51027574XXXXAF598E0AA195",         "type":"tokenizedCardEnrollments",         "version":"1.0",         "_links":{            "tokenized-cards":[               {                  "href":"/tms/v2/tokenized-cards/38F377C4044F251XXXX3AF598E0A8B67",                  "id":"38F377C4044F251AE06XXXX98E0A8B67",                  "state":"ACTIVE"               }            ],            "instrumentIdentifiers":[               {                  "href":"/tms/v1/instrumentidentifiers/7030010xxxx56432345",                  "id":"7030010xxxx56432345"               }            ]         }      },      "organizationId":"OrganizationId"   },   "requestType":"NEW"}
{ "eventType": "tms.networktoken.updated", "webhookId": "261d2616-xxxx-9ba8-q3456-8b588d0a5f2a", "productId": "tokenManagement", "organizationId": "mid", "eventDate": "2025-02-24T16:46:27", "transactionTraceId": "234234234234234c14e374c2b5a31e26c4316f0dc-0", "retryNumber": 0, "payload": {   "data": {     "reason": "TOKEN_STATUS_UPDATED",     "id": "2EE7067B2F015632E0631E588E0A1987",     "type": "tokenizedCardUpdates",     "version": "1.0",     "_links": {       "tokenized-cards": [         {           "href": "/tms/v2/tokenized-cards/2E8B371F931C4B9BE0631D588D0AF123",           "id": "2E8B371F931C4B9BE0631D588D0AF123",           "state": "DELETED"         }       ],       "instrumentIdentifiers": [         {           "href": "/tms/v1/instrumentidentifiers/7045450003485829870",           "id": "7045450003485829870"         }       ]     }   },   "organizationId": "mid" }, "requestType": "NEW"}
{ "eventType": "tms.networktoken.updated", "webhookId": "261d2616-xxxx-9ba8-q3456-8b588d0a5f2a", "productId": "tokenManagement", "organizationId": "mid", "eventDate": "2025-02-24T16:46:27", "transactionTraceId": "234234234234234c14e374c2b5a31e26c4316f0dc-0", "retryNumber": 0, "payload": {   "data": {     "reason": "TOKEN_STATUS_UPDATED",     "id": "2EE7067B2F015632E0631E588E0A1987",     "type": "tokenizedCardUpdates",     "version": "1.0",     "_links": {       "tokenized-cards": [         {           "href": "/tms/v2/tokenized-cards/2E8B371F931C4B9BE0631D588D0AF123",           "id": "2E8B371F931C4B9BE0631D588D0AF123",           "state": "DELETED"         }       ],       "instrumentIdentifiers": [         {           "href": "/tms/v1/instrumentidentifiers/7045450003485829870",           "id": "7045450003485829870"         }       ]     }   },   "organizationId": "mid" }, "requestType": "NEW"}
{   "eventType":"tms.networktoken.updated",   "webhookId":"3903effb-xxxx-fae4-e063-a0xxxx0a266f",   "productId":"tokenManagement",   "organizationId":"OrganizationId",   "eventDate":"2025-07-03T10:29:12",   "transactionTraceId":"01bcdb1655702343e1b4e48ad2089873daafff2e4ff12da4abb1e9ecc522d769-0",   "retryNumber":0,   "payload":{      "data":{         "reason":"TOKEN_STATUS_UPDATED",         "id":"3904B9E29F574360xxxxAF598E0AB766",         "type":"tokenizedCardUpdates",         "version":"1.0",         "_links":{            "tokenized-cards":[               {                  "href":"/tms/v2/tokenized-cards/38F377C4044F25XXXX63AF598E0A8B67",                  "id":"38F377C4044F25XXXX63AF598E0A8B67",                  "state":"SUSPENDED"               }            ],            "instrumentIdentifiers":[               {                  "href":"/tms/v1/instrumentidentifiers/7030010XXXX56432345",                  "id":"703001XXXX056432345"               }            ]         }      },      "organizationId":"OrganizationId"   },   "requestType":"NEW"}
{   "eventType":"tms.networktoken.updated",   "webhookId":"3903effb-xxxx-fae4-e063-a058xxxx266f",   "productId":"tokenManagement",   "organizationId":"OrganizationId",   "eventDate":"2025-07-03T10:30:12",   "transactionTraceId":"9fa8d1a66d588b2c3e98ccxxxxe25128901ce6305ac4cfd756f0089836f618f2-0",   "retryNumber":0,   "payload":{      "data":{         "reason":"TOKEN_STATUS_UPDATED",         "id":"3904CA019A3A55F9E063AFXXXX0A8356",         "type":"tokenizedCardUpdates",         "version":"1.0",         "_links":{            "tokenized-cards":[               {                  "href":"/tms/v2/tokenized-cards/38F377C4044F251AXXXXAF598E0A8B67",                  "id":"38F377C4044F251AE063XXXX8E0A8B67",                  "state":"DELETED"               }            ],            "instrumentIdentifiers":[               {                  "href":"/tms/v1/instrumentidentifiers/703001XXXX056432345",                  "id":"70300XXXX0056432345"               }            ]         }      },      "organizationId":"OrganizationId"   },   "requestType":"NEW"}
{   "eventType":"tms.networktoken.updated",   "webhookId":"3903effb-xxxx-fae4-e063-a0xxxx0a266f",   "productId":"tokenManagement",   "organizationId":"OrganizationId",   "eventDate":"2025-07-03T10:32:15",   "transactionTraceId":"3b4afde1bf4d69477a7e7109cc8e65882412820770a2044ad4c9fed75d31f4e8-0",   "retryNumber":0,   "payload":{      "data":{         "reason":"TOKEN_STATUS_UPDATED",         "id":"3904DXXXXC6D597AE06XXXX98E0A6B8C",         "type":"tokenizedCardUpdates",         "version":"1.0",         "_links":{            "tokenized-cards":[               {                  "href":"/tms/v2/tokenized-cards/3904CA019F0355XXXX63AF598E0A8356",                  "id":"3904CA019F035XXXX063AF598E0A8356",                  "state":"ACTIVE"               }            ],            "instrumentIdentifiers":[               {                  "href":"/tms/v1/instrumentidentifiers/703008XXXX051962341",                  "id":"703XXXX000051962341"               }            ]         }      },      "organizationId":"OrganizationId"   },   "requestType":"NEW"}
{  "eventType": "tms.networktoken.updated",  "webhookId": "27bc79a2-xxxx-8532-xxxx-a0588e0ade3b",  "productId": "tokenManagement",  "organizationId": "OrganizationId",  "eventDate": "2025-02-28T20:40:39",  "transactionTraceId": "e9d7949bf85521625053f23270af389660fafa4328ddd63518e5deb8577c7564-0",  "retryNumber": 0,  "payload": {    "data": {      "reason": "CARD_UPDATED",      "id": "2F3AC2D2450BB025E06XXXX98E0AF0CA",      "type": "tokenizedCardUpdates",      "version": "1.0",      "_links": {        "tokenized-cards": [          {            "href": "/tms/v2/tokenized-cards/2F1F09A14C7E3B7AXXXXAF598E0A5151",            "id": "2F1F09A14C7E3XXXX063AF598E0A5151"          }        ],        "instrumentIdentifiers": [          {            "href": "/tms/v1/instrumentidentifiers/70304500XXXX3860034",            "id": "70304XXXX0093860034"          }        ]      }    },    "organizationId": "OrganizationId"  },  "requestType": "NEW"}
{   "eventType":"tms.networktoken.updated",   "webhookId":"3903effb-f536-fae4-e063-a0588e0a266f",   "productId":"tokenManagement",   "organizationId":"OrganizationId",   "eventDate":"2025-07-03T10:30:12",   "transactionTraceId":"9fa8d1a66d588b2c3e98cc108de25128901ce6305ac4cfd756f0089836f618f2-0",   "retryNumber":0,   "payload":{      "data":{         "reason":"TOKEN_UPDATED",         "id":"3904CA019A3A55F9E063AF598E0A8356",         "type":"tokenizedCardUpdates",         "version":"1.0",         "_links":{            "tokenized-cards":[               {                  "href":"/tms/v2/tokenized-cards/38F377C4044F251AE063AF598E0A8B67",                  "id":"38F377C4044F251AE063AF598E0A8B67",                  "state":"ACTIVE"               }            ],            "instrumentIdentifiers":[               {                  "href":"/tms/v1/instrumentidentifiers/7030010000056432345",                  "id":"7030010000056432345"               }            ]         }      },      "organizationId":"OrganizationID"   },   "requestType":"NEW"}
{  "eventType": "tms.networktoken.updated",  "webhookId": "3903effb-f536-fae4-e063-a0588e0a266f",  "productId": "tokenManagement",  "organizationId": "organizationId",  "eventDate": "2026-02-23T14:40:45",  "transactionTraceId": "ddd36b68-b0cd-4bea-a1c9-d9d5f39ede88-0",  "retryNumber": 0,  "payload": {    "data": {      "version": "1.0",      "id": "4B7FB81DA338515FE063AF598E0AD417",      "reason": "TOKEN_EXPIRY_UPDATED",      "type": "tokenizedCardUpdates",      "_links": {        "instrumentIdentifiers": [          {            "href": "/tms/v1/instrumentidentifiers/7030050000048066475",            "id": "7030050000048066475"          }        ],        "tokenized-cards": [          {            "href": "/tms/v2/tokenized-cards/4B7FB756657A1B9FE063AF598E0AE530",            "id": "4B7FB756657A1B9FE063AF598E0AE530"          }        ]      }    },    "organizationId": "organizationId"  },  "requestType": "NEW"}
{  "eventType": "tms.networktoken.updated",  "webhookId": "3903effb-f536-fae4-e063-a0588e0a266f",  "productId": "tokenManagement",  "organizationId": "OrganizationID",  "eventDate": "2026-02-23T14:40:45",  "transactionTraceId": "ddd36b68-b0cd-4bea-a1c9-d9d5f39ede88-0",  "retryNumber": 0,  "payload": {    "data": {      "version": "1.0",      "id": "4B7FB81DA338515FE063AF598E0AD417",      "reason": "TOKEN_EXPIRY_UPDATED",      "type": "tokenizedCardUpdates",      "_links": {        "instrumentIdentifiers": [          {            "href": "/tms/v1/instrumentidentifiers/7030050000048066475",            "id": "7030050000048066475"          }        ],        "tokenized-cards": [          {            "href": "/tms/v2/tokenized-cards/4B7FB756657A1B9FE063AF598E0AE530",            "id": "4B7FB756657A1B9FE063AF598E0AE530"          }        ]      }    },    "organizationId": "OrganizationId"  },  "requestType": "NEW"}
{  "eventType": "tms.networktoken.updated",  "webhookId": "3903effb-f536-fae4-e063-a0588e0a266f",  "productId": "tokenManagement",  "organizationId": "OrganizationId",  "eventDate": "2026-02-26T12:41:05",  "transactionTraceId": "ed950d64-3e32-467e-9983-329e51f5adc5-0",  "retryNumber": 0,  "payload": {    "data": {      "version": "1.0",      "id": "4BBA5FF1292594B4E063AF598E0AAA66",      "reason": "REDIGITIZATION",      "type": "tokenizedCardUpdates",      "_links": {        "instrumentIdentifiers": [          {            "href": "/tms/v1/instrumentidentifiers/7032130000022946478",            "id": "7032130000022946478"          }        ],        "tokenized-cards": [          {            "href": "/tms/v2/tokenized-cards/4BBA5FF1272C94B4E063AF598E0AAA66",            "id": "4BBA5FF1272C94B4E063AF598E0AAA66"          }        ]      }    },    "organizationId": "OrganizationId"  },  "requestType": "NEW"}

Simulate Lifecycle Status

You can use the Visa Token Service (VTS) simulator to simulate life-cycle management events for network tokens.

Prerequisites

Before you can simulate life-cycle management events, you must meet these requirements:

  • You must be configured for . See Get Started with TMS.
  • Network tokens must be enabled. For more information, see Network Token Enablement.
  • You must be enabled for the VTS simulator. To enable the VTS simulator, contact your account administrator.

Endpoint

Test:

POST /tms/v2/tokenized-cards/{tokenizedCardId}/issuer-life-cycle-event-simulations
Required Fields for Simulate Lifecycle Status
state string

Required when you request a network token status update.

card.last4 string

Required when you request an update to the last four digits of the underlying PAN associated with the tokenized card.

card.expirationYear string

Required when you request a tokenized card update.

card.expirationMonth string

Required when you request a tokenized card update.

metadata.cardArt.combinedAsset.update string

Required when you request an update to the card art associated with the network token.

{    "state": "SUSPENDED"}
{    "card": {        "last4": "1234",        "expirationMonth": "05",        "expirationYear": "2032"    }}
{    "metadata": {        "cardArt": {            "combinedAsset": {                "update": "true"            }        }    }}
{    "expirationMonth": "05",    "expirationYear": "2032",    "state": "SUSPENDED",    "card": {        "last4": "1234",        "expirationMonth": "05",        "expirationYear": "2032"    },    "metadata": {        "cardArt": {            "combinedAsset": {                "update": "true"            }        }    }}

A successful request returns an empty HTTP 204 No Content status.

Last published: October 28, 2026

Not available for your audience

This page isn't available for your current audience selection.