Token Maintenance Process

New
  • Updated on Feb 19, 2026
  • 3 minute(s) read
Prev Next

A well‑maintained token vault helps Account Updater return more reliable results while keeping processing costs in check. By performing token cleanup both before and after Account Updater processing, you can reduce unnecessary fees, increase match rates, and preserve long‑term data hygiene.

The following sections outline the best practices for token maintenance and the process to update your token information.

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. The token maintenance process follows these general steps:

  1. Get token health details to establish a baseline.

  2. Identify invalid or unusable tokens.

  3. Deactivate the invalid or unusable tokens.

You can also refer to this flow diagram for a visual summary of the workflow:

Flowchart illustrating token management process including health details and deactivation steps.

Token Health Report

Before running Account Updater, partners should generate a health report to understand token quality and identify data to clean up. This process establishes a baseline for metrics and helps measure improvement after cleanup.

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, partners should validate their token vault and remove tokens that can’t or shouldn’t be updated.

Remove Tokens Based on Card or Transaction History

If not removed, invalid or unusable tokens can generate unnecessary fees, fail to return meaningful updates, and ultimately reduce the overall value of Account Updater results.

Examples of tokens to remove based on card or transaction history include:

  • Cards whose expiration date is more than 12 months ago.

  • 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.

Remove Tokens Based on Customer Profile

To avoid paying fees for accounts that will not transact again, tokens should not be updated 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

Any cards that have been hard declined should not be submitted to Account Updater. Examples of cards that would cause a hard decline include the following:

  • Stolen cards

  • Lost cards

  • Closed accounts

  • Cards flagged for suspected fraud

Token Maintenance Process

Token maintenance can be performed through the API or through your Technical Account Manager. The sections below outline the process for cleaning up your token vault.

Important!

Partners must contact their Technical Account Manager to inform them before attempting any token cleanup process.

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.

  • Tokens should be deactivated only if they meet the criteria outlined in the Remove Tokens Based on Card or Transaction History section.

Deactivate Tokens Using the API

Partners with API access can deactivate tokens through their integration. To deactivate tokens:

  1. Inform your Technical Account Manager that you are deactivating tokens.

  2. Retrieve token details using a GET /tokens request.

  3. Identify the tokens to deactivate based on the guidelines.

  4. Update the token status using a PUT /tokens request with Inactive = 1.

Deactivate Tokens Through Your Technical Account Manager

Partners who don’t use the API for Account Updater should follow these steps to deactivate tokens:

  1. Contact your Technical Account Manager through email to request token deactivation.

  2. The Technical Account Manager reviews complex relationships between the partner, customers, payment records, and token records, and then compiles and returns a list of tokens to deactivate.

  3. Review and approve the list of tokens to deactivate with your Technical Account Manager.

  4. The Technical Account Manager deactivates the approved tokens.

Account Updater Response Messages

Partners should clean up tokens based on the returned Account Updater response codes. Response codes of Account Closed or Contact Cardholder should be considered for token cleanup. Access the following articles for a list of Account Updater response codes:

Related articles