Hyperswitch card vault deployment and PCI DSS scope

Under each Hyperswitch vault model, PCI DSS scope follows where card data is captured, stored, transmitted and accessed, so the first task is to decide which model you run and then map the data path it creates. Under the self-hosted, in-house PCI model, the Hyperswitch docs state that the merchant is fully responsible for PCI DSS certification and data handling. In practice the card vault (locker), its encryption service, the cluster hosting both, administrator access paths, application and infrastructure logs, backups and any analytics copies of card data are typically all in scope. Treat each of those as a system to inventory, not as an implementation detail of the vault.

Under a self-hosted orchestration model with an external PCI vault such as VGS or Tokenex, the provider's own compliance evidence generally covers the vault itself. That does not remove your review obligations. The Hyperswitch router, the scheduler, the databases and caches that sit in front of the vault, the client SDK integration, any browser redirects that carry card fields, and every stored token still need to be examined. Ask the provider for its current attestation and a written responsibility matrix, then confirm with your assessor which of your components touch raw card data in transit and which only hold tokens.

Under the SaaS Hyperswitch Vault, your team must confirm in writing exactly what the hosted vault covers, including how card data is received, where it is held and who can access it on the provider side. The self-hosted orchestration you keep running usually remains your responsibility. Check whether any card data passes through your own routers, logs or Control Center sessions before it reaches the hosted vault, and whether your database holds only tokens. Mixed boundaries are where gaps tend to appear, so document the handoff point explicitly.

Scope follows data flows, and the assessor, not the vendor, decides where the boundary sits. Vendor documentation and a vendor's own compliance evidence describe what the vendor controls, but they do not settle what your environment must prove. Before committing to a model, draw the data flow for your chosen vault, from the payment page through the SDK, router, vault, database, logs and backups, and review it with your assessor. Revisit the diagram after each Hyperswitch upgrade or connector change, because new components and new log destinations can move the boundary without anyone intending it.

Once the card vault is live, the work that keeps PCI DSS scope stable is operational discipline: monitoring the vault without leaking card data into telemetry, backing up vault data and key material on separate paths, rotating keys on a schedule your policy defines, tracking upstream releases, and keeping scope documentation current. Each of these is a recurring task with a named owner, and each affects what an assessor will ask to see. Monitoring is where scope often gets broken without anyone noticing. The vault service, its database and the encryption service should emit availability, latency and error-rate metrics, but logs, traces and alert payloads must not carry primary account numbers, CVVs or decrypted values. Review the logging configuration of every service that touches the vault, including the Router, the Scheduler and any reverse proxy or service mesh sidecar. Confirm with Hyperswitch which request and response fields are logged at each level, and test the redaction with a synthetic card number before go-live and after every upgrade. Any monitoring tool that stores card values moves into scope. Backups need two separate control paths. Vault database backups hold encrypted card data, so they follow the same access, encryption and retention rules as the live store. Key material belongs on a separate path with separate custodians, so that restoring data never requires the same people or systems that hold the working keys. Rehearse a restore into an isolated environment on a schedule your team sets, and record the result. Key rotation is handled the same way: agree the rotation interval and procedure with your security policy owner, rehearse re-encryption, and log each rotation as evidence. Hyperswitch ships roughly monthly minor releases, and each GitHub release includes a compatibility matrix for the Control Center and web client versions. Assign one person to review each release notes entry for vault, encryption and dependency changes, and for any new required service such as Superposition, which the v1.124.0 release notes describe as a required configuration dependency. Every connector addition or routing change should trigger a documented scope review: does the new processor receive raw card data, does it change the data flow, and does it need its own attestation? Keep three artifacts current: the data flow diagram, the written scope statement and a change log that links each release, connector change or configuration change to its scope review. Assessors expect this evidence to be collected continuously, not assembled before an assessment. Store screenshots, configuration exports, access reviews, restore test records and rotation logs as they happen. Ask your QSA or assessor early which evidence formats they accept.

The verification plan has to prove two things: the card vault stores and returns card data correctly, and card data never appears anywhere else in the platform. Run these tests in a non-production environment that matches the production topology, including the Router, the card vault, the encryption service, PostgreSQL and Redis. Start with end-to-end tokenization and payment flows using the test card numbers that your processors and Hyperswitch publish for sandbox use. Confirm that each payment returns a token, that the token can be used for a follow-up payment, and that the Control Center shows only the masked form of the card. Do this for every vault model you plan to run, because the self-hosted in-house model and the external vault models put different systems in the flow.

Next, test the boundaries. Attempt to reach the card vault directly from a pod, host or network segment outside the Router, and confirm that the connection is refused. Then search every place where card data could land: application logs, PostgreSQL tables and replicas, Redis keys and caches, scheduler queue payloads, Control Center exports, support bundles and backups. Use a pattern search for primary account number formats combined with a Luhn check to cut false positives. Expect some matches on test data and on order references, so record how each hit was classified. Ask your assessor early which search method and evidence they will accept, because a search that is documented and repeatable is worth more than a one-time manual grep.

Then simulate failure. Stop the card vault, stop the encryption service and cut network paths between the Router and each one. For each case, confirm that the payment fails with a clear error, that no retry or fallback path writes the card number to a log, a queue, a database row or a cache, and that the merchant-facing response contains no card data. Check the scheduler's retry behavior specifically, since a queued retry that holds raw card data would move the problem into a new system. Record which components were down, how long the failure lasted in your test window and what state the database was left in after recovery. These results show whether the platform fails closed.

Test key rotation and the data flow next. Rotate the encryption keys in the test environment and confirm that tokens stored before rotation still return the correct card data, and that new tokens are written under the new key. Keep old key material available until re-encryption is verified. Then walk your assessor through the current data flow diagram, following a card from the checkout SDK through the Router, the vault and the processor, and pointing out every system that is in scope. Keep the diagram and the test results in one evidence folder. For each test, record the date, environment, Hyperswitch version, tester, expected result, actual result and the location of logs or screenshots. Evidence recorded this way supports the assessment and makes the tests repeatable after each upgrade.