Card Tokenization Service Low-Level Design: Token Lifecycle, Network Token Provisioning, and Cryptogram

A card tokenization service manages the lifecycle of network tokens — the scheme-issued surrogate credentials that replace PANs in merchant systems. It handles provisioning tokens from Visa Token Service or Mastercard MDES, refreshing expiring tokens, generating transaction cryptograms, and retiring tokens when cards are canceled.

Requirements

Functional

Provision network tokens from Visa (VTS) and Mastercard (MDES) given a PAN and cryptographic proof.
Generate transaction cryptograms (TAVV/UCAF) for each charge request.
Refresh tokens before expiry and on card replacement events.
Retire tokens on card cancellation or user removal.
Map internal vault tokens to network tokens for the charge path.

Non-Functional

Cryptogram generation under 50 ms (synchronous on charge path).
Token provisioning under 2 seconds (async acceptable).
Zero PAN exposure outside the HSM-backed tokenization boundary.

Data Model

network_tokens(
  id                  BIGSERIAL PRIMARY KEY,
  vault_token_id      BIGINT,            -- FK to payment_methods
  network             ENUM(visa, mastercard, amex),
  network_token_ref   VARCHAR(200),      -- scheme-issued token
  token_status        ENUM(active, suspended, deleted),
  token_expiry        TIMESTAMPTZ,
  provisioned_at      TIMESTAMPTZ,
  last_refreshed_at   TIMESTAMPTZ
)

cryptogram_log(
  id                  BIGSERIAL PRIMARY KEY,
  network_token_id    BIGINT,
  charge_request_id   VARCHAR(200),
  cryptogram          VARCHAR(500),
  generated_at        TIMESTAMPTZ,
  used_at             TIMESTAMPTZ,
  expired             BOOLEAN
)

token_lifecycle_events(
  id                  BIGSERIAL PRIMARY KEY,
  network_token_id    BIGINT,
  event_type          VARCHAR(100),      -- provisioned, refreshed, suspended, deleted
  source              VARCHAR(100),      -- user_action, card_replacement, expiry_refresh
  occurred_at         TIMESTAMPTZ
)

Core Algorithms

Token Provisioning

Provisioning begins with the vault service decrypting the PAN into a secure enclave, then calling the scheme API with the PAN and a provisioning request that includes device binding data if available. The scheme validates the PAN via the issuer and returns a network token reference and expiry. The service stores the reference (never the PAN) and fires a token.provisioned event. The PAN is zeroed from memory immediately after the API call. If provisioning fails, a retry job backs off at 1 minute, 5 minutes, and 30 minutes before marking the vault token as network-token-unavailable and falling back to direct PAN charge.

Cryptogram Generation

Each transaction requires a single-use cryptogram that proves the token holder is authorized. The service fetches the network token reference and calls the scheme cryptogram API with the charge amount, currency, and a nonce. The scheme returns a time-limited cryptogram (TAVV for Visa, UCAF for Mastercard). The cryptogram is logged with its charge request ID and a 5-minute expiry. The charge service passes the cryptogram alongside the network token to the payment processor. Replayed cryptograms are rejected by the scheme, so the log provides tamper evidence.

Token Refresh

A background job queries for network tokens expiring within 7 days. For each, it calls the scheme refresh API, which returns an updated expiry without changing the token reference. If the card was replaced by the issuer, the scheme may return a new network token reference; the service updates the mapping. Card replacement detection is also triggered by push provisioning notifications from the scheme, handled by an inbound webhook endpoint.

API Design

POST /v1/internal/network-tokens/provision — trigger provisioning for a vault token; async.
GET /v1/internal/network-tokens/{vaultTokenId} — returns network token status and expiry.
POST /v1/internal/network-tokens/{id}/cryptogram — generate a single-use cryptogram for a charge.
POST /v1/internal/network-tokens/{id}/refresh — force token refresh.
DELETE /v1/internal/network-tokens/{id} — retire token at scheme.
POST /v1/webhooks/scheme-notification — receive push provisioning and card replacement events from Visa/Mastercard.

Scalability and Fault Tolerance

The cryptogram generation path is synchronous and latency-sensitive. The service maintains a persistent mTLS connection pool to each scheme endpoint to avoid TLS handshake overhead on every request. Connection health is checked with scheme-specific heartbeat calls every 30 seconds. If a scheme endpoint is degraded, the service falls back to PAN-based charge (with the PAN retrieved from the vault) rather than failing the transaction. This graceful degradation is critical because network token provisioning is a best-effort optimization, not a hard requirement for charging.

Interview Tips

Distinguish vault tokens (internal, opaque references to the PAN in your HSM) from network tokens (scheme-issued credentials usable for charging). They serve different purposes and live at different security boundaries.
Mention that cryptograms are single-use and time-limited by design; storing them beyond the transaction is a security anti-pattern.
Discuss the fallback to direct PAN for issuers that do not support network tokenization — not all cards qualify.
Token suspension (by the issuer) is different from token deletion; a suspended token can be reactivated if the cardholder resolves a fraud dispute.

{
“@context”: “https://schema.org”,
“@type”: “FAQPage”,
“mainEntity”: [
{
“@type”: “Question”,
“name”: “How does network token provisioning differ between Visa and Mastercard?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Both schemes expose a Token Service Provider (TSP) API but use different enrollment endpoints and data formats. Visa Token Service (VTS) accepts an enroll call with the PAN, expiry, and a merchant ID and returns a DPAN (device PAN) plus a token reference ID. Mastercard Digital Enablement Service (MDES) follows a similar flow but uses a different cryptographic profile for cryptogram generation (MDES uses TAVV; Visa uses CAVV). Implementations must branch on the card BIN range to call the correct TSP and parse scheme-specific response fields.”
}
},
{
“@type”: “Question”,
“name”: “How are cryptograms generated for tokenized transactions?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “The TSP generates a transaction-specific cryptogram (TAVV for Mastercard, CAVV for Visa) using the network token, a transaction counter, and the transaction amount as inputs to a scheme-defined MAC algorithm. The cryptogram is requested from the TSP's /cryptogram endpoint at the moment a charge is initiated and included in the authorization message alongside the network token. It is single-use: the issuer verifies it server-side with the TSP and rejects replays.”
}
},
{
“@type”: “Question”,
“name”: “What does the token lifecycle (suspend, resume, delete) look like for network tokens?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Each network token has a lifecycle state machine: ACTIVE, SUSPENDED, DELETED. Suspend temporarily blocks authorization without destroying the token — useful when a card is reported lost and then found. Resume re-activates a suspended token. Delete permanently invalidates it at the TSP; this is irreversible and triggers de-provisioning from all associated wallets. State transitions are made via TSP lifecycle API calls and the local vault record is updated transactionally so the two stay in sync.”
}
},
{
“@type”: “Question”,
“name”: “When and how should a tokenization system fall back to PANs?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Fallback to the raw PAN is used when the TSP is unavailable, when a scheme does not support network tokens for a given BIN range, or when a legacy acquirer lacks EMV 3DS support. The vault stores the encrypted PAN alongside the network token precisely for this case. Fallback is triggered by catching TSP timeout or not-supported errors, logging a fallback_reason for compliance review, and routing the charge via the traditional PAN path. Fallback usage should be monitored and minimized because it increases PCI scope.”
}
}
]
}