A well‑maintained token vault helps Account Updater return more reliable results while keeping processing costs in check. By performing token maintenance (also known as token hygiene) both before and after Account Updater processing, you can reduce unnecessary fees, increase match rates, and preserve long‑term data quality.
Notice
This article describes features that are in pilot and enabled for a limited set of users. Functionality, availability, and documentation might change as we continue to improve this feature.
To discuss enabling this pilot feature for your implementation, contact your Partner Experience Manager.
Important!
The following guidelines are provided for general guidance only and should be adapted based on each partner’s specific operational practices and risk considerations.
We strongly recommend you perform token maintenance before implementation.
The following sections outline the guidelines for token maintenance and the process to update your token information.
Evaluate Token Management Practices
You are expected to regularly self‑evaluate your token management practices to ensure alignment with token maintenance standards and operational best practices. This self‑assessment helps you identify gaps, inefficiencies, or risks before they impact costs, performance, or reporting accuracy.
Consider the following questions before implementing and periodically after implementation:
Are all tokens in the vault actively associated with valid, current customer accounts or use cases?
Are inactive, expired, or non‑billable tokens being identified and removed in a timely manner?
Is there a clear process for validating token eligibility before submission to Account Updater?
Are Account Updater submission volumes aligned with expected business value and billing outcomes?
Are internal controls and reviews in place to prevent accumulation of redundant or low‑quality tokens?
Regular self‑review supports proactive token quality, reduces unnecessary fees, and ensures your token vault remains an accurate, high‑value asset that supports downstream reporting, reconciliation, and performance metrics.
Overview of Token Maintenance
Token maintenance should be performed at regular intervals, informed by token volume, transaction decline codes, and Account Updater responses when applicable.
Strategy for Token Maintenance
The strategy for token maintenance follows these general steps:
Assess the status of token quality to establish a baseline.
Identify invalid or unusable tokens by following the guidelines below.
Select a method for token maintenance: Deactivation or Mark Tokens as Ineligible for Account Updater.
You can also refer to this flow diagram for a visual summary of the workflow:
.png)
Suggested Token Maintenance Intervals
We recommend establishing a consistent token maintenance cadence that follows this structure:
The first iteration of token maintenance should occur before enabling the Account Updater service.
Follow‑up token maintenance should be performed approximately every three to six months to ensure a well-maintained token vault.
Assess Token Status
Before running Account Updater, assess the status of your tokens and identify tokens that could cause issues during account updates. This practice establishes a baseline for metrics and helps measure improvement after maintenance.
To check your current token status, use the portal to review Payment Methods in the Customer Profile. Alternatively, you can use the Token APIs.
We recommend you track the following metrics:
Percentage of active versus inactive tokens
Percentage of tokens with recent declines
Percentage of tokens linked to active customers
Percentage of tokens with upcoming recurring billing
Percentage of accounts that are past due
Number of duplicate tokens
Age distribution of all tokens
Tokens with no activity in over six months
Identify Tokens to Remove
Before submitting tokens to Account Updater, you should validate your token vault and identify tokens for maintenance. The following sections outline the different scenarios where tokens qualify for maintenance.
Note
The following guidelines represent general recommendations and may vary based on your specific needs and environment.
Identify Tokens Based on Card or Transaction History
Examples of tokens to remove based on card or transaction history include:
Cards whose expiration date is more than 12 months ago and have no active transactions.
Tokens that have never been used in a transaction.
Tokens that have not been used in a transaction for the previous 18 months.
Tokens with more than three consecutive failed attempts.
Duplicate tokens or PAN hashes.
Tokens where the associated customer status is Inactive, Canceled, or Deleted.
Tokens where the Account Updater response is Account Closed or Contact Cardholder.
Identify Tokens Based on Customer Profile
Do not update tokens for the following customers:
Customers that are no longer subscribed to Account Updater.
Customers who have canceled their service.
Customers who are in collections or delinquent beyond your threshold.
Customers who have no upcoming invoice or scheduled payment.
Remove Tokens with Hard Declines
Do not submit any cards that return a hard decline because of transaction processing to Account Updater. See Processor Response Codes for a list of response codes that return due to a hard decline.
Token Maintenance Methods
Token maintenance can be performed through the API or through your Technical Account Manager. The sections below outline the processes for maintaining up your token vault.
Important!
You must contact your Technical Account Manager to inform them before attempting any token maintenance process.
You are solely responsible for the accuracy, maintenance, and ongoing review of all tokens in your vault, including any operational or billing impacts resulting from your management practices.
Deactivate Tokens
You can update a token’s status to Inactive, which prevents it from being used for any purpose in the Payrix Pro platform.
Important!
Deactivated tokens are ineligible for transaction processing, and any transactions using deactivated tokens will be declined.
Deactivated tokens are ineligible for subsequent Account Updater updates, and deactivated token records will not be sent for updates.
You should only deactivate tokens if they meet the criteria outlined in the Remove Tokens Based on Card or Transaction History section.
Deactivate Tokens Through Your Technical Account Manager
If you don’t use the API for Account Updater, follow these steps to deactivate tokens:
Submit a partner support ticket to request token deactivation.
The Technical Account Manager reviews complex relationships between you, your customers, payment records, and token records, and then compiles and returns a list of tokens to deactivate.
Review and approve the list of tokens to deactivate with your Technical Account Manager.
The Technical Account Manager deactivates the approved tokens.
The Technical Account Manager updates the support ticket.
Deactivate Tokens Using the API
If you have API access, you can deactivate tokens through your integration. To deactivate tokens:
Inform your Technical Account Manager that you are deactivating tokens.
Retrieve token details using a
GET /tokensrequest.Identify the tokens to deactivate based on the guidelines.
Update the token status using a
PUT /tokens/{id}request withInactive = 1.
Mark Tokens as Ineligible for Account Updater
You can update the token record to indicate it is not eligible for Account Updater without impacting its use for transaction processing.
Important!
This feature is for Account Updater only and does not impact transaction processing.
This process marks the token record as ineligible for Account Updater, which means that the token is not included in the account update request.
This method should be used only when you choose to continue processing transactions with a token that Account Updater repeatedly returns as Account Closed or Contact Cardholder.
Mark Tokens as Ineligible Through Your Technical Account Manager
If you don’t use the API for Account Updater, follow these steps to mark tokens as ineligible for Account Updater:
Submit a partner support ticket to request token to request a token update.
The Technical Account Manager reviews complex relationships between you, your customers, payment records, and token records, and then compiles and returns a list of tokens to mark as ineligible.
Review and approve the list of tokens to mark as ineligible with your Technical Account Manager.
The Technical Account Manager updates the approved tokens.
The Technical Account Manager updates the support ticket.
Mark Tokens as Ineligible Using the API
If you have API access, you can mark tokens as ineligible for Account Updater through your integration. Access the Account Updater developer integration guide on the Worldpay Developer Hub for more information.
Account Updater Response Messages
You should perform token maintenance based on the returned Account Updater response codes. Response codes of Account Closed or Contact Cardholder should be considered for token maintenance. View the following articles for a list of Account Updater response codes: