Hyperswitch network tokenisation

Network tokenisation in Hyperswitch is gated in layers, and a payment only uses a network token when every layer agrees. The first layer is the profile. Network tokenisation must be enabled for the profile that handles the payment, through the is_network_tokenization_enabled setting. The documented default is false, so a profile that was created without changing it will not request network tokens, even if the rest of the stack is ready. Treat this flag as an explicit, reviewed change per profile, and record which profiles have it on so that finance, risk and the platform team can see the same picture.

The second layer is the network tokenisation service. The profile flag alone is not enough. A network tokenisation service must be configured in the deployment, and it must be reachable from the router. If the profile is enabled but no service is configured, the call is rejected with the error NetworkTokenizationServiceNotConfigured. Test this path deliberately in a non-production environment: enable the flag on a test profile without the service and confirm that the rejection surfaces where your integration team expects it. Also confirm how your application handles that error, because a rejection here should not be mistaken for a card decline.

The third layer is the pair of allow lists. The card network list determines which card brands can be tokenised at all. The repository example configuration allows Visa, American Express and Mastercard. The network-token connector list determines which connectors may request and use those tokens. The example lists Adyen, Cybersource, Peach Payments and TrustPay. Operators can change both lists, so the lists in your deployment are the ones that matter, not the example. A card brand missing from the network list, or a connector missing from the connector list, will not receive a token even when every other setting is correct. Review both lists together whenever you add a processor or a card brand.

Because the allow lists narrow the path, some payments will take the non-tokenised route by design. That is why the vault matters. The Hyperswitch docs advise keeping the card in the vault as a fallback, since the saved-card path can still complete a payment when the token cannot be fetched or when the chosen connector is not enabled for network tokens. Decide before go-live whether your business accepts that fallback for each card brand and connector, and confirm how it affects your PCI DSS scope and your customers' expectations about updated card details.

Before relying on this design, confirm the exact configuration keys, their names, their locations and their defaults in the Hyperswitch documentation for the version you run. Setting names and list formats can change between releases, and the example values in the repository are not a substitute for your own configuration. Ask your implementation team to produce a short test matrix that covers an enabled and a disabled profile, a configured and an unconfigured service, each allowed and disallowed card network, and each connector on both lists. Keep the results with the change record.

The Hyperswitch docs say a card should stay in the vault for fallback. The reason is that the saved-card path can still charge the customer's card in two cases: when the network token cannot be fetched, and when the connector is not enabled for network tokens. In both cases the payment has no token to use, so the system depends on the stored card. If the vault record has been deleted or was never kept after tokenization, the fallback has nothing to read and the payment fails, even though the customer's card is valid. Treat the vault record as a dependency of the token flow, and plan your enrollment and storage design around that dependency from the start.

This has direct consequences for data retention. Each card should be kept for as long as either the network token or the fallback might be needed, and your retention schedule must be checked against both uses. Deletion workflows need the same check. Before you build a customer deletion or card expiry cleanup job, confirm whether removing a saved card deletes the network token, the vault record, or both, and whether that deletion breaks the fallback for other payments. The retention periods themselves are a legal and policy decision for your organization, made with counsel, and should not be inferred from the platform defaults.

Re-tokenizing a card needs the same care. When a card is reissued or a customer enrolls the same card again, decide whether the existing vault reference is updated, kept, or joined by a second reference. Duplicate references widen the data you must track, complicate deletion, and can enlarge the set of records your PCI DSS assessment covers. Test both fallback cases in a staging environment: force a token fetch failure, and run a payment through a connector outside the network-token allow list. Confirm that the saved-card path completes in each case, and record the results for your change records.

Your vault model determines who answers these questions. In the self-hosted in-house PCI model, the Hyperswitch docs state that the merchant is fully responsible for PCI DSS certification and data handling, so fallback, retention and deletion all sit inside your own assessed scope. With an external PCI vault provider such as VGS or Tokenex, card data is held by that provider, and your fallback depends on their references and on their retention and deletion terms. With the SaaS Hyperswitch Vault, confirm where the card is held, how deletion reaches the hosted service, and what the fallback needs from it. Ask each provider for its deletion and re-tokenization behavior in writing, and confirm the fallback behavior of your Hyperswitch version against the network tokenisation documentation before go-live.

The vault model you choose decides where card data and network token data live, and who answers for them. Hyperswitch documents three self-hosted models, so settle the model before you enable network tokenisation on a profile. The choice affects your PCI DSS scope, your vendor contracts and the design of the fallback path, and changing it later means moving stored cards and tokens between systems.

Self-hosted with the native Hyperswitch Vault (in-house PCI). In this model the card vault runs in your infrastructure, and the card data sits in your estate. The Hyperswitch docs state that the merchant is fully responsible for PCI DSS certification and data handling in this model. You carry the vault hosting, key management, access control, logging and assessment work. Network token requests, token storage and any card-on-file records also fall inside your scope. Ask your QSA to map every service that touches a network token or a fallback card record before you commit to this model.

Self-hosted orchestration with an external PCI vault. Here you run the Hyperswitch orchestration layer, while a third-party vault provider such as VGS or Tokenex holds the card data. Your scope narrows, but it does not disappear. You still operate the routing and application services, and you still decide which data reaches them. Confirm with the vault provider whether it issues or stores network tokens, how it returns token and fallback data to Hyperswitch, and which of its controls you can evidence in your own assessment. Request the provider's responsibility matrix in writing.

Self-hosted orchestration with the SaaS Hyperswitch Vault. In this model you host the orchestration services, and the card vault runs as a hosted service. The split of responsibilities is different from the external vault model, so the questions change. Confirm where network tokens are created, how long token and card records are retained, and what happens to a stored card when a token request fails. Also confirm how the vault service is audited and how you receive its evidence for your own assessment.

Whichever model you choose, keep the card in the vault as a fallback. The Hyperswitch docs say the saved-card path can use the card when the token cannot be fetched or the connector is not enabled for network tokens. Ask your vault provider and QSA to document this fallback path in a data flow diagram, including which component decides to use the card, which logs record that decision and where the card is decrypted. A fallback that the assessor cannot trace will create findings later.