Hyperswitch v1.124 upgrade and the Superposition dependency

Before you change the Hyperswitch router to v1.124.0, a working Superposition service must already be running and reachable in that environment. The v1.124.0 release notes make Superposition a required configuration dependency, and deployments must have an active Superposition service before upgrading. Treat it as a prerequisite change with its own deployment, verification and rollback steps, not as a detail inside the router rollout. Dev, staging and production each need it in place ahead of the router change, and staging should follow the same ordering you will use in production so the sequence you test is the sequence you run.

Several ordering questions must be answered before the first deployment. Decide where Superposition runs: in the same cluster and namespace as the router, or in a separate environment owned by the platform team. Establish how the router reaches it, including the service name, DNS entry, port, and any network policies, load balancer rules or firewall paths that must allow that traffic. List the secrets it needs, who creates them, and where they are stored. Confirm which database it uses, whether that database is separate from the PostgreSQL instance behind the router, and who provisions, backs up and restores it. Check each of these against the v1.124.0 release notes and the Hyperswitch self-hosting documentation rather than assuming they match your earlier deployment.

Use health checks to hold the router rollout until Superposition is ready. In a Kubernetes rollout or a pipeline, add a gate that calls the Superposition health endpoint and confirms that it can read its database before the router deployment starts. The gate should fail closed, so an unhealthy Superposition stops the pipeline instead of letting the router roll forward. Confirm the health endpoint path, the expected response and any readiness conditions in the release notes or the Hyperswitch docs. Then decide how the router's own readiness probe behaves if it cannot reach Superposition, and test that behavior in staging so you know whether a failure shows up as a blocked rollout or as a router that starts and then misbehaves.

Plan for failure after the change as well as during it. If Superposition becomes unavailable once the router is running, configuration handling may be affected, so assign a named owner for the Superposition service with its own alerts, capacity plan and on-call path. Write the rollback order into the runbook before the production window. In most cases, you will need to decide whether the router is rolled back first and whether any Superposition changes can be reversed safely, and that decision depends on what the migration package has already written. Ask the Hyperswitch maintainers or the release documentation which Superposition versions are tested with v1.124.0, and record the answer with the environment inventory.

The superposition_migration.zip package that ships with Hyperswitch v1.124.0 contains three parts: a script that seeds the dimensions Superposition needs, a script that migrates supported database configurations into Superposition as overrides, and the SQL query that identifies those configurations. Treat the SQL query as the first step, not the last. Its output tells your team which configurations exist in your database, which ones the package is designed to move, and which ones it will leave behind. Before running either script, extract the zip, read both scripts end to end, and confirm from the v1.124.0 release notes what each one writes and in what order it must run. Record the file names, runtime requirements and any prerequisites in your upgrade runbook so the staging and production runs follow the same sequence.

Run the SQL query against a read-only copy of your production database and export the full result set. Each row is a configuration your platform currently reads from its database. The file config/superposition_seed.toml in the Hyperswitch repository lists the configurations the migration covers, so compare your export against that list key by key. Sort every row into one of two groups: configurations inside the supported set, which the migration script should move, and configurations outside it, which it will not move. Confirm the exact matching rule with the release notes, since a key that appears in the seed file under a slightly different name or scope may still fall outside what the script handles. Keep the export and the comparison in your change record as the inventory the team signs off on.

Your team must decide how to handle every configuration outside the supported set. The release notes supplied for this topic do not describe what happens to an unmigrated database configuration after the upgrade, so confirm this with Hyperswitch maintainers or in the release documentation before you plan. Possible handling includes leaving the value in the database if the v1.124.0 code still reads it there, recreating it manually as a Superposition override, or retiring it after confirming nothing depends on it. Assign an owner to each item, and give priority to any configuration that affects payment behavior, such as routing or connector settings. A configuration that stops applying without an error is the most likely source of a production incident after this upgrade, so each decision should name the test that proves the behavior is unchanged.

Verify the scripts against the v1.124.0 release notes and a staging copy before anything runs in production. Restore a recent production database snapshot into staging, start the Superposition service the release requires, and run the seed script followed by the migration script exactly as your runbook states. For each migrated key, compare the value in Superposition with the value in the original database. Then run a set of test payments that exercise the routing and connector settings you identified in the inventory, and confirm the Control Center displays the expected configuration. Check whether the scripts can run more than once without duplicating or overwriting overrides, and test a rerun on the staging copy. Keep the original database values unchanged until production sign-off is complete, so a rollback has a known source.

Staging is the only place where the v1.124.0 migration can show its effect on payments before customers see it. Build the staging environment from a copy of production configuration: the same router and Scheduler settings, the same PostgreSQL and Redis versions and topology, the same secrets handling, and a Superposition service running as it will in production. Connector credentials should point to sandbox or test accounts. Then run the migration dry run against a restored copy of the production database, using the superposition_migration.zip package. Save the output of the seeding script, the migration script and the SQL query that finds supported configurations as evidence, and attach it to the change record. Confirm which Hyperswitch image tag you are testing, since v1.124.0 and v1.124.0-standalone differ in AWS SES support.

Reconciliation shows whether the migration moved what you expected. Use config/superposition_seed.toml to list the configurations that should now exist as overrides, then compare each migrated value with its source value from the pre-upgrade database. Record every mismatch, every missing item and every configuration that the migration skipped, and decide for each one whether it is acceptable. Next, run end-to-end test payments through sandbox or test connectors. Cover the routing rules and fallback routing your business depends on, refunds, webhook delivery, and any saved-card or vault flow in use. Compare the routing outcomes with the outcomes you recorded before the upgrade. Ask each connector vendor which test cases their sandbox supports, because gaps there will not show up in your results.

Failure tests check how the platform behaves when the new dependency is not healthy. Stop the Superposition service and start the router, then record whether the router refuses to start, which is what the v1.124.0 release notes require before upgrading. Test a Superposition outage during live test traffic and note which payment operations fail, which are retried and which degrade silently. Run the migration script a second time to confirm it does not duplicate overrides. Restore the database backup into a clean environment and time the restore, so that you know how long recovery takes if the production migration corrupts data. Write down each failure, the expected result and the observed result, and assign an owner to every gap before the production window.

Rollback has two levels, and the team must know which one applies before starting. Redeploying the previous router image reverts application code and the way the router reads configuration. That is enough only if the previous version still runs correctly against the database and Superposition state left behind by the migration, which your staging rollback test must prove. Changes written to PostgreSQL, including migrated configuration rows and any payment or scheduler records created under v1.124.0, require a database restore or a documented reverse procedure. Set a decision point in the runbook. Before that point, rollback is an image redeploy. After it, where new payments have been processed and recorded, rollback becomes a data recovery exercise that must reconcile transactions. Agree the go or no-go criteria, the rollback triggers and the sign-off roles with the business owners before the production window, and record them in writing.