What Hyperswitch smart retries do and when your team needs them
Many declined payments are not final. A card can be refused by one processor for a reason that a different route may not face, so a second attempt can succeed. Hyperswitch smart retries classify each processor's error codes as retriable or non-retriable, then run one of four retry types: cascading retry to an alternate processor, step-up retry with additional authentication, clear PAN retry when de-tokenization fails, and global network retry on a signature network after a debit network failure. The teams that usually evaluate this feature are payments engineering, which owns connector setup, and finance or revenue operations, which tracks lost authorizations. Risk and fraud teams often join the review because step-up authentication changes what the customer sees at checkout.
Smart retries are not a single on/off switch. Each merchant setup must be enabled for the retry flows it should use, and the merchant must set N, the number of retries permitted. These choices sit alongside the processors connected to that setup, so a flow that works well for one merchant account may do little for another with a different processor mix or different card populations. Before changing any setting, ask your team to list every merchant setup, the processors behind each one, and the retry types that each should use. Record who approves those choices, because they change how often customers are re-charged and through which route.
The error code mapping is where most of the design effort sits. The Hyperswitch docs say processors have between 400 and 1,000 or more error codes, and the retriable or non-retriable label for each code determines whether any retry runs. Export the codes your processors returned over a recent period, check how Hyperswitch labels each one, and log every label your team disagrees with. Confirm with each processor which codes it treats as soft declines and which as hard declines. Retrying a hard decline wastes attempts and may draw scrutiny from the processor, so the mapping needs review whenever you add a processor or change its configuration.
Decide whether you need smart retries before you scope the work. Pull decline data by processor and error code for a recent period and measure how many declines are soft declines or issuer-side failures that a different route might clear. If that share is large, retries are worth evaluating. If most declines are hard declines, such as closed or reported accounts, retries add processing cost and risk without much recovery. Each retry attempt may carry processor fees, so confirm the per-attempt terms in your connector agreements and ask any implementation partner to price the retry configuration and mapping work as a written scope.
How Hyperswitch smart retries map error codes to retry types
Each processor reports failures in its own error code vocabulary, so Hyperswitch smart retries depend on a mapping built for every processor. Each code is classified as retriable or non-retriable, and that classification decides which retry type, if any, runs next.
Processor-specific error codes
Each processor reports declines and technical failures using its own codes. The Hyperswitch smart retries docs say processors have between 400 and 1,000 or more error codes, so a mapping built for one connector cannot be assumed to hold for another. Before design starts, list the processors you will route to and collect each one's full code catalog from its own documentation.
Retriable and non-retriable classification
Hyperswitch classifies each processor error code as retriable or non-retriable. A retriable code opens a path to a retry, while a non-retriable code should end automated retry handling for that attempt. Check each label against the processor's own description of the code, because a wrong label either sends a payment that cannot succeed back through retries or stops one that could have recovered.
Classification selects the retry type
The classification determines which strategy runs: cascading retry to an alternate processor, step-up retry with additional authentication, clear PAN retry when de-tokenisation fails, or global network retry after a debit network failure. Map each code to the strategy you expect, then confirm that the strategy addresses the failure it is paired with. A code mapped to the wrong type produces a retry that cannot fix the underlying problem.
Enabling flows and setting N
Smart retries run only for the retry flows a merchant has enabled, and each merchant must set N, the number of retries permitted. Confirm both settings for every merchant account you configure before go-live. Ask the Hyperswitch docs and your own test results whether N applies across all strategies or to each one separately, since the answer changes how many attempts a failed payment can receive.
Per-processor review before go-live
Because the mapping is set for each processor, review it processor by processor before any live traffic reaches that processor. Use the processor's sandbox to trigger representative failures where it allows, record which code returns and which retry type runs, and sign off each row. Keep the signed table with your configuration so later changes can be compared against the approved version.
Recurring review after changes
Processors can add or change error codes, and Hyperswitch minor releases arrive roughly monthly, so the mapping is a recurring control with a named owner. Track code-level retry outcomes after launch, flag codes that land in the wrong classification, and repeat the review when you upgrade the router or change a processor connector. Without an owner, the table tends to drift from the processor's current behavior.
Which retry strategy and settings fit your payment flows
This table compares the four Hyperswitch smart retry strategies, when each one fits a payment flow, what it depends on and which settings to enable. Read each row against your processor count, authentication mix and card network routing before you choose flows. Each flow must be enabled separately, and each needs N, the number of retries permitted, set deliberately.
| Retry flow | Fits when | Depends on | Settings to configure |
|---|---|---|---|
| Cascading retry to alternate processor | A second processor can accept the same payment after the first declines for a retriable reason | A configured second processor connector and routing that selects it for the retry | Enable the cascading retry flow and set N for retries to the alternate processor |
| Step-up retry with additional authentication | The first attempt fails for a reason that an additional authentication step can resolve | 3DS support on the connector and a 3DS flow in your checkout | Enable the step-up retry flow and set N; confirm your 3DS handling first |
| Clear PAN retry after detokenization fails | A saved card cannot be detokenized and you are permitted to send clear card data to the processor | Card vault configuration and a PCI DSS scope decision made with your compliance lead | Enable the clear PAN retry flow and set N; confirm vault model and scope before enabling |
| Global network retry on signature network | A debit network attempt fails and the same payment can route through a signature network | Card network routing, connector support for the signature network and debit card BIN coverage | Enable the global network retry flow and set N; confirm network routing with each processor |
| Error code mapping (all flows) | Decides whether any failure is retried at all, for every retry flow above | Each processor's error codes classified as retriable or non-retriable and mapped to retry types | Review mappings per processor before enabling flows; confirm against each processor's documentation |
Why clear PAN and global network retries change your compliance scope
Clear PAN retry changes your compliance scope more than any other Hyperswitch smart retry flow, so decide on it before you enable it. On the usual tokenized path, Hyperswitch sends a token to the processor and the primary account number stays inside the card vault. When de-tokenization fails, clear PAN retry lets Hyperswitch retrieve the raw card number and send it to an alternate processor. Cardholder data then leaves the vault boundary and reaches more systems, including the Router app server, the retry logic and the connector path to the new processor. Each of those components, and any logs, queues or caches that could capture the value, may fall into PCI DSS scope.
Map the data path on paper before you change any configuration. List every service that could receive clear PAN during a retry: the Router, the Scheduler if retries are queued, Redis or PostgreSQL if any payload is cached or persisted, connector request logs and your observability stack. In a self-hosted deployment you own all of these, so you also own their network segmentation, access control, log redaction and retention. Confirm which of them the retry path touches in your build. Also confirm which vault model you run. 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.
Global network retry is a routing decision with its own processor and network dependencies, and it should be reviewed as one. After a debit network failure, Hyperswitch can resubmit the payment on a signature network. Whether that works depends on the processor's support, the card's network eligibility and the network rules your acquirer applies. The switch moves the transaction onto a different network path, which can change fees, settlement timing, dispute handling and the records your reconciliation depends on. It also brings additional connectors and network agreements into your review. Confirm with each processor and acquirer which network switches they support, which error codes trigger them and what cost terms apply.
Before you enable either flow, record the decision in your compliance file and get sign-off. Merchants must enable each retry flow they want and set N, the number of retries permitted, so each enabled flow and retry limit is a configuration decision that needs review. Document which flows are on, which N applies, which processors may receive clear PAN and how each processor's error codes map to retriable or non-retriable outcomes. Hyperswitch classifies error codes per processor, and processors can have 400 to 1,000 or more codes, so the mapping review takes real effort. Ask your QSA or internal compliance lead to confirm the scope impact in writing, and repeat the review after any Hyperswitch upgrade or processor change.
Setting up Hyperswitch smart retries in a self-hosted deployment
This sequence takes a self-hosted Hyperswitch stack from working processor connections to tested retry behavior for each failure path, so that retries run only where the business intends them and each retry decision can be traced in logs before production traffic depends on it.
Confirm the deployment and processor connectors work
Before touching retry settings, confirm that the Router, Scheduler, PostgreSQL, Redis and card vault are healthy in your environment, and that each processor connector you plan to use completes a test authorization in the Hyperswitch sandbox or your non-production profile. Your platform engineers own this check, with the payments lead confirming which processors are live. The step is done when every connector returns a clean authorization and a deliberate decline, and the Router logs show both events with the connector name and error code attached. If a connector fails here, fix it before changing any retry setting, because retries will otherwise hide the underlying fault.
Review the error code mapping for each processor
For every processor in use, export the error codes Hyperswitch maps as retriable or non-retriable and compare them with the processor's own documentation. Processors can expose several hundred codes, so focus first on the declines that carry real revenue impact, such as insufficient funds, do not honor, expired card and issuer unavailable. Payments risk and the processor relationship owner should sign off on each classification, and any code you disagree with should be recorded as a documented override. The step is done when a reviewed mapping exists for each connector, with a named owner and a change log entry for every adjustment.
Enable only the retry flows the business needs
Decide which of the four strategies you need: cascading retry to an alternate processor, step-up retry with additional authentication, clear PAN retry after a de-tokenisation failure, and global network retry after a debit network failure. Enable each one deliberately in the merchant configuration, leaving the rest off. Each enabled flow adds processor calls and cost, and some depend on capabilities such as a vault model or a second connector, so confirm those dependencies in your deployment first. The step is done when a written list of enabled flows exists, matched against the configuration export, and the team can explain why each one is on.
Set the retry limit N
Set N, the number of retries permitted, to a value agreed by the payments and risk owners. Hyperswitch requires you to set this value for the flows you enable. A higher N increases recovery potential but also increases repeated attempts against issuers and processors, so document the reasoning and the expected behavior for each decline category. Confirm the value in the configuration export and in a test payment that fails with a retriable code. The step is done when the retry count observed in logs matches N exactly and does not continue past it.
Configure the alternate processor and step-up authentication
For cascading retries, connect the alternate processor and confirm that its routing and currency coverage match the payments that will fall back to it. For step-up retries, confirm which 3DS path you use, whether it is the built-in flow or an external 3DS server, and that the cardholder experience is acceptable. Record which processor receives each fallback and who is accountable for its fees and settlement. The step is done when a test payment that fails on the primary connector reaches the alternate one, and a step-up test shows the additional authentication request in the logs.
Test each failure path in a sandbox
Create a test case for every failure path you enabled: a retriable decline that should cascade, a non-retriable decline that should stop, a step-up trigger, a de-tokenisation failure for clear PAN retry, and a debit network failure for global network retry. Run each case in the sandbox and check the retry logs for the sequence of attempts, the codes returned and the final status. The key check is that non-retriable codes are not retried at all, and that the attempt count never exceeds N. Keep the test results as evidence for your change record. The step is done when every path produces the expected sequence and the evidence is filed.
Promote to production with monitoring in place
Apply the tested configuration to production through your normal change process, and keep the sandbox results and configuration export with the change ticket. Turn on dashboards or alerts for retry volume, recovery rate per processor, and any spike in attempts against a single connector. Review the first production logs with the payments owner, sampling retried transactions to confirm non-retriable codes are not retried in live traffic. The step is done when production retry logs match the sandbox behavior and the monitoring shows the expected attempt counts for each connector.
Security and operational considerations once retries run in production
Smart retries change which payments are attempted again, through which processor, and with which credentials. The controls below cover who can change retry behavior, how retry activity is recorded, and which shared services must stay healthy for retries to run on time.
Restrict who can change retry configuration
Retry settings are changed in the Control Center, and a change to the number of permitted retries or to which retry flows are enabled alters how every future failed payment is handled. Limit write access to the payments team, keep read access broader for finance and support, and record who changed what and when. Before go-live, test that a non-admin user cannot switch on a retry flow or raise the retry count.
Plan Control Center sign-in and role setup
The Control Center supports single sign-on through OpenID Connect only, with no SAML, no just-in-time or SCIM provisioning, and roles managed in Hyperswitch rather than mapped from the identity provider. Each operator must be invited before first sign-in, so onboarding and offboarding are manual steps in your process. Confirm the current SSO setup steps in the Hyperswitch SSO documentation for your version, and assign roles deliberately before retries are enabled.
Log every retry attempt for fraud review
Retries can reveal card testing or stolen card use, since repeated attempts across processors or with step-up authentication look different from a single decline. Record each attempt with its original payment, retry type, processor, error code and outcome, and keep those records in a store your fraud team can query. Agree in advance which patterns trigger a review, such as many attempts on one customer or a sudden rise in step-up retries.
Guard against duplicate charges
A retry that runs after an approval is recorded as pending, or after a timeout, can charge the customer twice. Confirm how Hyperswitch records the state of each attempt before a retry is issued, and reconcile retried payments against processor records as part of your normal finance close. Test timeout and webhook delay scenarios in a sandbox, and document who investigates a suspected duplicate and how a refund is issued.
Monitor the Redis and PostgreSQL dependencies
The Hyperswitch architecture docs describe PostgreSQL with a master and replica setup, and Redis for caching and the scheduler queue. If Redis or the database is slow or unavailable, retries can stall or fail silently, so alert on connection errors, replication lag and queue depth. Size and back up both services as part of your platform plan, and confirm the failover behavior of your chosen deployment before depending on it.
Watch the scheduler behind timed retries
Timed retries depend on the Scheduler service, which the architecture docs split into Producer and Consumer components. A stopped Consumer or a backed-up queue means retries are due but not executed, which can leave customers unpaid without any visible error in the payments path. Run both components with health checks, alert on jobs that remain past their due time, and include scheduler restarts in your upgrade and incident runbooks.
What retries cost in authorization behavior and customer experience
Every smart retry is a new authorization attempt, and each attempt has a cost. A cascading retry sends the payment to an alternate processor, which often means that processor's fees apply to the attempt whether or not it succeeds. A step-up retry sends the cardholder back through a 3DS challenge, adding a prompt at the moment where some customers abandon checkout. A clear PAN retry depends on de-tokenisation working and moves card data through a path that your PCI DSS scope must cover. A global network retry after a debit network failure can recover an approval but changes which network and fee structure applies. Before enabling any flow, write down the expected cost per attempt and who bears it, and check how your processor contracts treat retried transactions.
Customer experience is where retries most often go wrong. A shopper may see a decline from one attempt and then a successful charge from a later one, which can produce a confused support contact or a second hold on the statement if the first authorization is not released. The team needs to decide what the shopper sees while a retry is in progress, which order state applies when a retry succeeds after a visible failure, and how webhooks update the order so the merchant system does not show a failed payment for a completed one. Ask your engineers how Hyperswitch reports each attempt to your order system, and confirm whether duplicate-charge protections apply to every retry path in your integration.
The value of each strategy depends on your processor mix and your decline profile, so the same settings can help one merchant and add little for another. A cascading retry only recovers approvals if you run more than one processor with different acceptance patterns for the declines you actually see. A step-up retry matters most where issuers return authentication-related declines, and it adds the most friction where those declines are rare. Pull your decline data grouped by the error codes Hyperswitch maps as retriable or non-retriable. Processors use 400 and 1,000 or more error codes, so check which of your codes fall into ambiguous groups before assuming a retry will help.
Measure outcomes before and after enabling each flow, one at a time. Record a baseline for authorization rate by processor and card type, the share of declines recovered by each retry type, the step-up challenge rate and abandonment at the challenge, the cost of additional attempts from processor statements, and customer contact volume about duplicate or unexpected charges. Set N to the lowest number of retries that your baseline suggests is useful, and compare results over a period long enough to cover your normal payment cycle. Write down the thresholds that would lead you to disable a flow before you turn it on.
Limits to confirm in your environment before relying on retries
Smart retries depend on settings and dependencies that change by release and by processor, so none of them should be taken from documentation alone. The five checks below cover what your chosen release supports, how completely each processor's error codes are mapped, whether retry paths can reach live processors and networks, and which companion components must be in place before you upgrade.
Retry flows and N in your release
Confirm which of the four smart retry strategies your release supports, and that each one is enabled for your merchant profile. Hyperswitch requires merchants to enable the flows they want and to set N, the number of retries permitted. Ask the vendor or check the release documentation for the N values your version accepts, then record the value you intend to use and who approved it. Test each enabled flow in a non-production environment before live traffic reaches it.
Error code coverage per processor
Hyperswitch classifies each processor's error codes as retriable or non-retriable and maps them to retry types. The docs describe processors with between 400 and 1,000 or more error codes, so coverage varies from one connector to the next. For each processor you plan to route to, confirm that its codes are mapped completely and that unmapped codes fail safely without retrying. Compare the mapping against the processor's own error catalog before you enable retries for it.
Alternate processor and network connections
Cascading retries and global network retries only work if the alternate processor and the card networks are connected in your deployment. Confirm the credentials, connector configuration and network routes for each alternate processor, and confirm that the signature network needed for a global network retry is available after a debit network failure. Test each path with sandbox credentials before enabling it for live payments.
Compatibility matrix for Control Center and web client
Each Hyperswitch release publishes a compatibility matrix for Control Center and web client versions. Confirm which dashboard and web client versions your team will use to configure and test retries, and check that pair against the matrix for your target release. Pin those versions alongside the router release, and repeat the check for every planned upgrade so that retry configuration stays supported.
Superposition dependency before upgrading
The Hyperswitch v1.124.0 release notes state that Superposition became a required configuration dependency, and that a Superposition service must be running before you upgrade to that version. Any deployment that moves across that release needs Superposition deployed, configured and reachable first. Read the release notes for every version between your current release and your target, and add dependency changes to the upgrade plan before retry settings are migrated.
Smart retries questions buyers ask before hiring outside help
What drives the cost of Hyperswitch smart retries work?
Effort rises with the number of processors you route to, the error codes you must review, the vault model you choose, and the compliance review and testing around the change. The Hyperswitch docs state that processors have between 400 and 1,000 or more error codes, and each one needs a retriable or non-retriable classification mapped to a retry type. The vault model adds scope: with the self-hosted, in-house PCI model, the docs state that you are fully responsible for PCI DSS certification and data handling. Compliance review, testing in processor test environments and sign-off from payments and risk owners are separate work items. Ask each provider to price these components separately in a written scope so you can see what each one adds.
How do the number of processors and error codes change the effort?
More processors and more error codes increase the mapping work directly, because every code needs its own retry decision. The Hyperswitch docs describe processors with between 400 and 1,000 or more error codes, so two processors can produce very different review loads. Before you request a quote, count the processors in scope and pull the distinct decline codes each one returns in your own logs. Processors you already use, with a long decline history, are usually easier to map than new ones, but confirm that against your data. Also ask whether the scope includes codes that have never appeared in production, since those still need a documented default decision.
Which smart retries work is one-time and which recurs?
Initial configuration is one-time work: enabling the retry flows you want, setting N (the number of retries permitted), building the error code mapping for each processor, and testing the result. Recurring work is ongoing mapping review and upgrades. Processors can change their error codes over time, and new codes can appear without warning, so mappings need periodic review against decline data. Hyperswitch ships roughly monthly minor releases, and each release lists a compatibility matrix for Control Center and web client versions, so each upgrade needs a retry regression pass. Ask whether a retainer covers mapping reviews, upgrade testing and support, and how often each one is included.
How long does smart retries setup take for our scope?
The duration depends on the written scope, so it cannot be stated from general information. The main inputs are the number of processors, the error codes to review, the vault model, the compliance review and the depth of testing. Ask for a timeline broken into phases: configuration, error code mapping, compliance evidence and testing. Also ask which phases depend on processor access and on your compliance team's availability, since those waits can set the pace more than the configuration itself. Most DeployOpen engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, so the timeline should appear in that document.
What must our team provide before outside help starts?
Your team must provide processor access, decline data and compliance sign-off, and the work stalls without them. For each processor, you need sandbox or read-appropriate access so retry behavior can be tested. You also need decline and retry logs covering a representative period, including error codes and final outcomes. A named owner should approve the retry types and the value of N for each flow. Compliance sign-off is needed for the vault model and the PCI DSS scope decision. Finally, provide access to the Hyperswitch deployment and the Kubernetes environment where it runs, so changes can be built and verified in your infrastructure.
Can an internal team set up smart retries without outside help?
An internal team can do it if it has payments engineering depth, access to every processor in scope, and time to review error codes carefully. The work also needs Kubernetes and Helm deployment skills, PostgreSQL and Redis operations experience, and enough PCI DSS knowledge to scope the vault model correctly. The harder parts are usually the judgment calls in error code mapping and the testing across processors. Many teams split the work: internal staff own day-to-day operation, while an outside partner handles the initial mapping, testing and documentation. Decide which side owns each recurring task before you choose the model, so the mapping does not go stale after go-live.
How does our vault model change smart retries behavior?
The vault model determines where card data is stored, which affects the clear PAN retry path and the compliance work around it. Hyperswitch documents three self-hosted vault models: the native Hyperswitch Vault with in-house PCI, orchestration with an external PCI vault provider, and orchestration with the SaaS Hyperswitch Vault. With the in-house model, you carry PCI DSS certification and data handling responsibilities directly. With an external or SaaS vault, the scope and de-tokenization behavior change. Confirm with the vendor how clear PAN retry works with your chosen vault before you finalize the retry design, and record that answer in your compliance evidence.
How do we verify retry decisions after go-live?
Verify each retry decision by comparing it against the mapped error code and the processor's response in a controlled test set, then monitor live outcomes. Test each strategy: cascading retry to an alternate processor, step-up retry with additional authentication, clear PAN retry when de-tokenization fails, and global network retry after a debit network failure. Confirm that non-retriable declines are never retried and that each payment stops at the configured N. Review logs after every processor error code change and every Hyperswitch upgrade. Keep the test set and results as evidence, so the next review starts from a known baseline.
How DeployOpen works on this
DeployOpen treats Hyperswitch smart retries as a configured payment flow inside infrastructure you control, not a switch to flip. We start from which retry strategies your business needs, how your processors classify their error codes, and how your card data is vaulted, then write that down before any build starts.
How we scope
- Engagements are fixed-scope, with retry strategies, processors and retry limits agreed in writing before work starts.
- We map which of the four retry strategies you intend to enable and which processor pairs they would apply to.
- The written scope names the N retry limit you want to set and the merchant flows that must be enabled for each strategy.
How we build
- We review each connected processor's error code mapping and confirm which codes are classed as retriable or non-retriable.
- We configure cascading, step-up 3DS, clear PAN and global network retries in a non-production environment first.
- We test each retry path with processor sandbox responses and document the expected result for every mapped error category.
How we hand over
- You receive the retry configuration, error code mapping decisions and the reasoning behind each retry limit.
- Runbooks cover how to review retry outcomes, change mappings and roll back a configuration change.
- We document how retry settings interact with your card vault model, so your PCI DSS scope owners can review them.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, covering retry behavior across Hyperswitch releases.
- Retainer work can include re-checking error code mappings when a processor changes its response codes.
- Confirm with the Hyperswitch docs and release notes how each monthly minor release affects retry configuration before upgrading.
