Payment Method Vault Low-Level Design: Tokenization, PCI Scope Reduction, and Default Selection

A payment method vault stores raw card data or network tokens on behalf of users, shielding the rest of the application from PCI DSS scope. The vault is responsible for secure storage, tokenization, default selection logic, and soft deletion so that canceled cards can be recovered without requiring users to re-enter details.

Requirements

Functional

Accept raw card data, tokenize it immediately, and never expose the PAN again.
Store one or more payment methods per user with a designated default.
Support network token provisioning (Visa Token Service, Mastercard MDES) to reduce interchange.
Soft-delete payment methods with a recovery window before permanent purge.
Return masked card details (last 4, expiry, brand) for display without exposing the token.

Non-Functional

PCI DSS Level 1 compliance; raw PAN never touches non-vault systems.
Tokenization round-trip under 100 ms.
Vault availability 99.99% — payment failures have direct revenue impact.

Data Model

payment_methods(
  id               BIGSERIAL PRIMARY KEY,
  user_id          BIGINT,
  vault_token      VARCHAR(200),   -- opaque reference to PAN in HSM
  network_token    VARCHAR(200),   -- scheme network token
  token_expiry     TIMESTAMPTZ,
  card_brand       VARCHAR(20),
  last_four        CHAR(4),
  exp_month        SMALLINT,
  exp_year         SMALLINT,
  billing_name     VARCHAR(200),
  billing_zip      VARCHAR(20),
  is_default       BOOLEAN,
  deleted_at       TIMESTAMPTZ,    -- NULL = active
  purge_after      TIMESTAMPTZ,    -- set on soft delete
  created_at       TIMESTAMPTZ
)

vault_keys(
  key_id           BIGSERIAL PRIMARY KEY,
  encrypted_key    BYTEA,          -- key encryption via HSM
  algorithm        VARCHAR(50),
  active           BOOLEAN,
  created_at       TIMESTAMPTZ,
  retired_at       TIMESTAMPTZ
)

The raw PAN is stored only inside a Hardware Security Module (HSM) or a dedicated secrets store (e.g., HashiCorp Vault). The application table holds only the opaque vault_token reference.

Core Algorithms

Tokenization Flow

The client submits card data over TLS directly to the vault service (or via a JavaScript tokenization widget that posts to the vault endpoint, never touching the merchant server). The vault generates a cryptographically random vault token, encrypts the PAN using AES-256-GCM with a key from the HSM, and stores the ciphertext. The vault token is returned to the caller. All subsequent charge operations pass the vault token; the vault decrypts the PAN only at charge time and passes it directly to the payment processor over a secure channel.

Default Selection

Only one payment method per user can be marked is_default = TRUE. The service enforces this with a partial unique index: CREATE UNIQUE INDEX ON payment_methods(user_id) WHERE is_default = TRUE AND deleted_at IS NULL. When a user adds a new method and requests it as default, the service wraps the old default unset and new default set in a single transaction. If the default is deleted, the service promotes the most recently added active method automatically.

Network Token Provisioning

After storing the vault token, the service asynchronously submits the PAN to the card network tokenization service. The network returns a network token and a token expiry. Network tokens are more stable than PANs across card replacements (the bank updates the network token mapping transparently) and qualify for lower interchange rates. The provisioning call is async so it does not block the user-facing add-card flow; a background job retries failed provisioning with exponential backoff.

API Design

POST /v1/vault/payment-methods — accepts raw card data; returns vault token and masked details.
GET /v1/vault/payment-methods — lists active payment methods for the caller; returns masked fields only.
PUT /v1/vault/payment-methods/{id}/default — set as default.
DELETE /v1/vault/payment-methods/{id} — soft delete; schedules purge after 30 days.
POST /v1/internal/vault/charge-token — internal only; accepts vault token and charge params; returns processor response.

Scalability and Fault Tolerance

The vault service is deployed in an isolated network segment with strict egress rules. It communicates only with the HSM, the card network tokenization endpoints, and the payment processor. No other internal service can reach the vault data store directly. This containment minimizes PCI audit scope dramatically. For high availability, the vault DB is replicated synchronously across two availability zones with automatic failover. Reads are served from the local replica; writes always go to the primary.

Interview Tips

Emphasize network isolation: the most important PCI control is limiting which systems can touch cardholder data.
Discuss key rotation: vault keys should be rotated quarterly; re-encrypting stored PANs is a background job that runs on the old key until all records are migrated.
Mention that JavaScript tokenization widgets (Stripe Elements, Braintree Drop-in) keep the merchant server entirely out of card data scope.
Soft deletion with a purge window balances user experience (easy recovery) with PCI requirement to delete data when no longer needed.

{
“@context”: “https://schema.org”,
“@type”: “FAQPage”,
“mainEntity”: [
{
“@type”: “Question”,
“name”: “What is the card tokenization flow in a payment method vault?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “The client collects raw card data in an isolated iframe or SDK that posts directly to the vault service, bypassing the merchant's application servers. The vault validates the PAN with a Luhn check, stores it encrypted under a vault-managed key (AES-256-GCM), and returns an opaque token (UUID or HMAC-derived string). All subsequent charge requests reference only the token; the merchant system never sees or stores the raw PAN.”
}
},
{
“@type”: “Question”,
“name”: “How do network tokens reduce PCI scope for a payment vault?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Network tokens (also called payment account references) are issued by card schemes (Visa, Mastercard) and replace the PAN in authorization requests. The vault provisions a network token by calling the scheme's Token Service Provider API during card enrollment. Thereafter, transactions use the network token plus a scheme-generated cryptogram instead of the PAN, so even if the authorization message is intercepted the data has no value outside that single transaction, reducing the merchant's PCI DSS scope.”
}
},
{
“@type”: “Question”,
“name”: “How is the default payment method selected and persisted?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “A user's payment methods are stored in a table with columns (user_id, token_id, is_default, created_at). Only one row per user may have is_default = true, enforced by a partial unique index. Setting a new default is a two-statement transaction: clear is_default on the current default, then set it on the chosen token. The API surface exposes PATCH /payment-methods/{token_id}/default to avoid the client needing to know about the previous default.”
}
},
{
“@type”: “Question”,
“name”: “Why use soft deletion for stored payment methods?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Soft deletion (setting deleted_at rather than removing the row) preserves the referential integrity of historical charge records that reference the token. It also supports a grace period during which the user can restore an accidentally removed card, and it enables audit trails required by payment regulations. Hard deletion is performed asynchronously by a purge job after the retention period (typically 7 years for financial records) has elapsed.”
}
}
]
}