Hyperswitch with VGS as an external card vault

The ExternalVaultInsert and ExternalVaultRetrieve flows decide which systems ever hold a primary account number, so they set the boundary that your PCI DSS scope analysis starts from. In this model, the VGS connector implements Hyperswitch's ExternalVault interface. On the first payment that saves a card, the card data is sent to VGS through the insert flow. VGS stores it and returns an alias token. Hyperswitch then records that alias against the customer's payment method, so the design intent is that its databases hold the alias and not the card number. Read the connector documentation for your release to confirm which request fields carry card data at each step and whether any of them are written to logs before they reach VGS.

When a later payment or a saved-card operation needs the card, Hyperswitch reads the stored alias from its payment method record and calls the retrieve flow with that alias. Confirm in the connector documentation whether the retrieve response returns card data to the Hyperswitch router or whether the card data is handled inside VGS and only referenced by the router. The answer changes which Hyperswitch hosts, memory paths and logs are in scope, so record it in your data flow diagram before you size the environment. Also confirm how the flow behaves for card-on-file payments, recurring charges and any operation that touches a network token, since each may follow a different path.

The VGS transparent proxy is optional. The Hyperswitch docs suggest VGS when the transparent proxy should forward tokenized requests to processors, so it is most relevant when you want VGS to substitute the stored card data on the outbound request. If you enable it, the processor connection becomes part of the cardholder data path, and your scope analysis must include the proxy configuration, the processors it can reach and the network routes between them. Confirm the supported processors, how substitution is logged, and whether the proxy can be used for every payment method your business accepts. Do not assume the proxy covers every processor in your Hyperswitch routing rules until the connector documentation confirms it.

Before go-live, check where the alias and not the card number is held, and where a card number could still appear. Hyperswitch stores its data in PostgreSQL and uses Redis for caching and the scheduler queue, so test that no card data reaches those stores, the application logs, webhook payloads or Control Center views. Confirm the three VGS credentials (the OAuth2 client ID, client secret and vault ID) and verify that the production vault ID is used, because the docs note that sandbox vault IDs do not work in production. Finally, the PCI DSS assessment itself is performed by a Qualified Security Assessor or through a Self-Assessment Questionnaire under the current version, PCI DSS v4.0.1, and this section does not determine your final scope.

An external vault does not remove your PCI DSS obligations. The standard applies to any entity that stores, processes or transmits cardholder data or sensitive authentication data, and to any entity that could affect the security of the cardholder data environment. Moving card storage to VGS changes where the data sits, but it does not change whether your organization, or the self-hosted Hyperswitch stack you operate, falls in scope. The PCI SSC maintains the standard but does not enforce it. Your payment brands and acquirer decide who must validate compliance and how, so that is the first party to ask.

The scope question shifts from "where is the card vault?" to "where could a full card number appear?" Trace the path through the Hyperswitch Router during the ExternalVaultInsert and ExternalVaultRetrieve calls, then through the Scheduler and its queue, Redis caches, PostgreSQL tables and replicas, application and access logs, error traces, webhook payloads, and the Control Center and support tooling your staff use to look up payments. For each component, record whether card data can appear, even briefly, and whether it persists. Illustrative example: a debug setting that writes request bodies to a log store would bring that log store into scope even though VGS holds the vaulted data.

Document VGS's share of the controls in writing. Request VGS's current Attestation of Compliance and its responsibility matrix, and confirm that the attestation covers the specific services you will use, including the vault and any transparent proxy that forwards tokenized requests to processors. Check the date and scope of that AOC against the services in your contract. Your own assessment should reference VGS's attested responsibilities, not restate them from memory. The Hyperswitch docs state that in the self-hosted, in-house PCI model the merchant carries full responsibility for PCI DSS and data handling, so every control VGS does not cover in writing stays with your team.

Use PCI DSS v4.0.1, the only active version, for any new assessment. Version 4.0 was retired on 31 December 2024. Validation runs through a Report on Compliance completed by a Qualified Security Assessor, or through a Self-Assessment Questionnaire, and each route ends in an Attestation of Compliance. Certificates are not recognized as validation. Which route applies depends on your transaction volume and channels, and your acquirer or a QSA must confirm the scope decision before go-live. If you consider the customized approach for any requirement, it is available only to entities with mature security and risk management, and it requires documented evidence that the stated objective is met in a different way.

The purpose of this test plan is to prove two things before go-live: that card data enters VGS on insert and never persists in Hyperswitch, and that the alias VGS returns can be retrieved for payments and saved-card reuse. Start in a sandbox where the Hyperswitch router, the Control Center and the VGS connector are configured with the three VGS credentials: the OAuth2 client ID, the client secret and the vault ID. Confirm that every value belongs to the sandbox environment end to end, because the VGS docs note that sandbox vault IDs do not work in production. Write each case as a numbered test with preconditions, the input, the expected alias behavior, the expected Hyperswitch record and the evidence to capture.

Begin with the core flows. For a successful insert, submit a test card through the client SDK, confirm that VGS returns an alias through the ExternalVaultInsert flow, and check that the Hyperswitch payment method record holds only that alias. For retrieval, run an authorization that uses the stored alias so the ExternalVaultRetrieve flow supplies card data to the processor, then confirm the payment completes. For a declined or invalid card, submit a processor test number that produces a decline and a malformed number that fails validation. Confirm that the customer sees a clear error, that the processor response is recorded, and that no alias is persisted for the failed attempt. Confirm with VGS and each processor which test numbers apply to your account.

Next, test the failure paths that operations will meet after go-live. Rotate the OAuth2 client secret in the sandbox, then run an insert and a retrieve with the old value. Confirm that the error is explicit and that your runbook names who can issue and deploy the new secret. Repeat with a vault ID from another environment, which should fail rather than succeed silently. For a network interruption, drop connectivity between the Hyperswitch router and VGS during an insert, then during a retrieve. Check whether the client retries, whether a second alias is created for one customer action, and whether a partial payment record remains in PostgreSQL. Finally, charge a card saved in an earlier session. This test depends entirely on retrieval working after a separate insert, so it shows whether the stored reference stays usable.

After every test run, search for card numbers rather than waiting until the end of the plan. Use the test card numbers in each format the client might send, including with spaces and separators. Search the router and scheduler logs, Control Center event data, webhook payloads, error traces, Redis entries and PostgreSQL tables, including replica and backup copies where you have access. Add a distinctive value to the test cardholder name and search for that too, because the name is cardholder data that should also stay out of these stores. Treat any match as a defect, fix it and rerun the affected test. Record the search scope, the queries, the timestamps and the results, and make sure the evidence itself contains no card data.

Store evidence in a form the assessor can review: the test plan with case IDs, the Hyperswitch and Control Center versions under test, configuration snapshots with secrets redacted, the VGS environment and vault identifiers, API responses or screenshots, log search outputs and a defect log showing retests. Map the results to the PCI DSS requirements that your scope depends on, and agree the evidence format with your Qualified Security Assessor before testing starts, since the assessor decides what is sufficient. Sandbox results do not prove production behavior. Production uses different credentials, a different vault ID and live processor connections. Before go-live, repeat the core flows, meaning insert, retrieve, decline, saved-card payment and the card number search, with production credentials in a controlled window. Have the on-call team present and agree the rollback decision in advance.