Network tokenization & card updaters

When a customer saves a card for future use, two things can silently invalidate it: the card expires or is reissued. Network tokenization and card updaters are the two mechanisms that keep stored cards working without the customer doing anything.

VINR handles both automatically — no configuration is required. This page explains what is happening under the hood, how to observe the lifecycle, and what to do when an update occurs.

Network tokenizationAskCopy

What it is

Network tokenization (also called scheme tokenization) is a service run by the card schemes themselves — Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES). When you store a card with VINR, VINR acts as a token requestor and asks the card scheme to issue a network token: a 16-digit surrogate PAN scoped to VINR's merchant ID that travels the authorization rail instead of the real card number.

The scheme maps the network token to the underlying PAN in its own vault. When the cardholder gets a new card number — because their card was lost, stolen, or simply reissued at expiry — the scheme silently updates the mapping. The network token stays the same; your stored pm_ ID continues to work.

Why it improves authorization rates

Issuers see network-tokenized credentials as lower risk for three reasons:

1. Merchant binding — the network token is cryptographically scoped to VINR's merchant ID. It cannot be used by another merchant even if it is compromised.
2. Transaction cryptogram — each authorization includes a one-time cryptogram generated from the token, similar to EMV chip. Replay attacks are impossible.
3. Issuer awareness — the issuer knows this credential came through a scheme-managed tokenization programme and applies less friction, resulting in fewer soft declines on off-session recurring charges.

Typical authorization rate improvements range from 1–4 percentage points on off-session charges, concentrated on the card brands and issuers that have rolled out full VTS/MDES support.

How VINR implements it

When a card is saved to a VINR customer via setupMethod or savePaymentMethod: true, VINR:

1. Vaults the raw card data in its PCI DSS Level 1 vault and creates a pm_ identifier.
2. Immediately requests a network token from the card scheme (Visa or Mastercard).
3. Once the scheme responds, stores the network token internally and uses it on all future charges against that pm_ ID.

This is automatic and transparent. Your code doesn't change — you still pass paymentMethod: 'pm_...' on charges.

American Express and Discover do not participate in third-party scheme tokenization. Cards from these networks are charged against the raw PAN (still vaulted securely by VINR) and are kept current via the card updater service instead.

Checking network token status

const pm = await vinr.paymentMethods.retrieve('pm_7Xk4...');

console.log(pm.networkToken.status);       // 'active' | 'inactive' | 'suspended' | 'not_supported'
console.log(pm.networkToken.scheme);       // 'visa_vts' | 'mastercard_mdes' | null
console.log(pm.networkToken.lastUpdated);  // ISO 8601 timestamp of last scheme sync

Network token lifecycle events

Subscribe to payment_method.network_token.* events to monitor token health:

if (event.type === 'payment_method.network_token.updated') {
  const pm = event.data.object;
  // The stored card is now backed by updated credentials.
  // No action required — VINR uses the refreshed token automatically.
  // Log for reconciliation if needed:
  console.log('Network token refreshed for', pm.customer, 'method', pm.id);
}

if (event.type === 'payment_method.network_token.suspended') {
  const pm = event.data.object;
  // The card has been reported lost or stolen.
  // Consider pausing subscriptions that reference this method.
  await suspendSubscriptionsForMethod(pm.id);
}

Card updater (Account Updater)AskCopy

What it is

Card updater (also called Account Updater or Automatic Card Update) is a batch service run by the card networks. Issuers submit updates — new expiry dates, replacement card numbers, account closures — to a network file once per day. VINR ingests these files nightly and applies any matching updates to stored payment methods.

Card updater is the fallback mechanism for cards that are not covered by network tokenization:

• American Express and Discover cards
• Cards from issuers that haven't enabled VTS/MDES
• Cards where the network token request was declined by the issuer

What gets updated

Timeline

Card updater runs as a nightly batch after market close. Updates appear on stored methods within 24–48 hours of the issuer submitting them to the network file. This is slower than network tokenization (which is real-time) but covers card brands and issuers that don't participate in VTS/MDES.

Coverage

Coverage within each network depends on issuer participation. Major banks in the US, EU, UK, Canada, and Australia have strong participation rates. Smaller regional banks and credit unions may not submit updates.

Handling card updater events

Card updater fires the same payment_method.updated webhook as network tokenization refreshes. Your handler can treat both sources identically:

if (event.type === 'payment_method.updated') {
  const pm = event.data.object;
  const updateSource = pm.lastUpdateSource; // 'network_token' | 'card_updater'
  const updateType = pm.lastUpdateType;     // 'expiry' | 'pan' | 'closed' | 'contact_issuer'

  if (updateType === 'closed') {
    // The card account is closed — remove it from the customer's wallet
    await db.paymentMethods.markClosed(pm.id);
    await notifyCustomerToUpdatePaymentMethod(pm.customer);
  }

  if (updateType === 'pan') {
    // PAN replaced — log for your records; no action needed, VINR handles it
    console.log('Card number replaced for method', pm.id, 'customer', pm.customer);
  }
}

Network tokenization vs card updater — comparisonAskCopy

TestingAskCopy

In the sandbox, use the following test card numbers to simulate updater scenarios:

Trigger a simulated update via the API:

// Sandbox only — simulate a card updater event on a stored method
await vinr.testHelpers.paymentMethods.simulateUpdate('pm_7Xk4...', {
  updateType: 'expiry',
});

Next stepsAskCopy