Token Lifecycle Management

Lifecycle management is a key feature of credential-on-file (COF) network tokenization. This capability allows issuers to keep COF network tokens updated as changes are made to their cardholders' account. TMS notifies you in real-time when updates are made to a card represented by the COF network token in your TMS vault. Issuers push the lifecycle management updates either in real-time or via a batch process to the card brands. Lifecycle updates and timelines will vary by issuer based on their update process. For example, if a credit card is no longer active, TMS notifies you about this status change.

There are two distinct lifecycle management events for tokenized card updates:

COF token status changes. Token statuses are:

ACTIVE:
The account and network token are active and in good standing.

When COF network tokens are in this status, merchants can process transactions according to their COF agreement.

SUSPENDED:
This status is a temporary status for COF network tokens and can change to ACTIVE or DELETED. Merchant’s should not send authorizations on suspended tokens; however, these tokens can be re-activated by the issuer later. Suspended COF network token events are usually triggered per cardholder instruction or flagged by the issuer for suspected fraudulent activity. When the status changes from SUSPENDED to ACTIVE or DELETED a merchant receives an lifecycle management update for the change.

Merchants can proactively contact the cardholder to update the credential or have them contact issuer to reactivate the credential.

DELETED:
This is a final state for the network token. A network token can be deleted when the account is closed or on cardholder instruction.

Merchants must request a new credential from the cardholder.

PAN updates to the COF network token. PAN updates include:

NEW PAYMENT ACCOUNT NUMBER:
A new PAN has been provisioned for the network token.

Merchants can retrieve the new PAN suffix (last 4 digits) and the new expiry date to store in their cardholder records.

NEW PAYMENT ACCOUNT EXPIRY
: A new expiry date has been provided by the issuer related to the PAN.

Merchants can retrieve the new expiry date and store it in their cardholder records.

Example:

When issuers update a card, the information is pushed to the card brands, which in turn update the associated network token. Merchants can get the updated information using the TMS API instrument identifier resource.

Request

GET https://api.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Response


{
  "_links": {    
    "self": {
      "href": "/tms/v1/instrumentidentifiers/7010000000000094444"
    },
    "paymentInstruments": {
      "href": "/tms/v1/instrumentidentifiers/7010000000000094444/paymentinstruments"
    }
  },
  "id": "7010000000000094444",  <-- THE TMS TOKEN ID -->
  "object": "instrumentIdentifier",  
  "state": "ACTIVE",  <-- THE STATE OF THE ACCOUNT SET ONLY BY THE ACCOUNT UPDATER PRODUCT -->
  "tokenizedCard": {    
    "state": "ACTIVE",  <-- THE NETWORK TOKEN STATUS (ACTIVE, SUSPENDED, DELETED) -->
    "expirationMonth": "12",  <-- THE NETWORK TOKEN EXPIRATION MONTH -->
    "expirationYear": "2020", <-- THE NETWORK TOKEN EXPIRATION YEAR -->
    "type": "mastercard",  <-- THE NETWORK TOKEN PROVIDER -->
    "card": {
      "suffix": "5555",  <-- THE LATEST PAN SUFFIX -->     
      "expirationMonth": "12", <-- THE LATEST PAN EXPIRATION MONTH -->
      "expirationYear": "2022" <-- THE LATEST PAN EXPIRATION YEAR -->    
    }
  },
  "card": {    
    "number": "555555XXXXXX4444" <-- THE MASKED PAN USED FOR THE ORIGINAL NETWORK TOKEN -->.  
  },
  "issuer": {
    "paymentAccountReference": "M0000000000005555555555554123" <-- PAR VALUE FOR THE ACCOUNT -->  
  },  
  "metadata": {
    "creator": "mid"  
  }
}