This blog deep-dives into the challenges with PSP codes and how Hyperswitch resolves these errors by deep-diving into the open source code base.

Payments fail all the time. A perfectly happy customer, ready to renew their subscription or buy your product, can churn in seconds. It’s often for a reason that’s completely avoidable.

One culprit? PSP error codes.

Every Payment Service Provider (PSP) has its own way of saying “no.” At one point or another (may be during college), we, as customers, may have overdrawn the account or had “Insufficient funds”. Each PSP can has their own unique way of representing this in terms of codes:

PSP A: Code 05 - Do not honor

PSP B: Decline 51 - Insufficient funds

PSP C: Error 1234 - Your transaction could not be processed

And it doesn’t always stop there. Errors don’t just originate at the PSP level. They can come from the issuing bank, get bucketed and standardized by the card network (Visa, Mastercard, etc.), and then be reinterpreted again by the PSP before finally reaching the merchant. By the time it reaches the merchant, the error may have been represented in several different ways, making the original cause less clear.

To the customer, it’s just a declined payment. But to the merchant, it’s a confusing puzzle: should they retry the transaction, switch to another provider, or ask the customer for a new card?

At Hyperswitch, we built Error Normalization and Smart Retries to eliminate that guesswork. Our system takes inconsistent error signals from across the payments value chain, like the issuer, network, PSP, and turns them into clear, automated decisions that merchants can rely on at scale.

Before we dive into how Hyperswitch solves the problem, let’s unpack the challenges hidden inside these error codes.

Inconsistent Error Languages Across the Payments Chain

There is no canonical template or schema that issuers, networks, and PSPs all reference to propagate errors. As a result, every layer in the payments chain can reinterpret the same failure in a slightly different way, and by the time it reaches the merchant, the original meaning is often distorted.

• Issuer Level (Banks): The issuing bank is the first to decide whether to approve or decline a transaction. Networks like Visa and Mastercard provide standardized “buckets” (e.g., insufficient funds), but issuers don’t always classify errors consistently. Issuers sometimes map errors differently, for example, a valid account could be flagged under to a different category. This can create confusion downstream.
• Network Level (Card Networks): Card networks propagate issuer errors using their own standardized sets, but subtle mismatches still creep in. An error that begins as insufficient funds at the bank may surface as do not honor once processed by the card issuing bank, depending on how it’s categorized.
• PSP Level (Payment Service Providers): PSPs aggregate across many card networks and acquirers. Each PSP then applies its own error taxonomy. Some return only codes, others include free-text messages, and some expose both their own error mapping and the underlying network error. This inconsistency makes automation and decision-making nearly impossible for merchants.

Examples of the Noise

Different codes for the same issueThe same failure, let’s say, insufficient funds may show up as:

PSP A: 05 – Do not honorPSP B: 51 – Insufficient fundsPSP C: ERR-1234 – Transaction could not be processed

To the merchant, these look unrelated, but they all mean the exact same thing.

Even when the error message is clear from the PSP, there’s rarely any signal on what the merchant should do next. Should they

• Retry immediately?
• Retry with more information?
• Switch to a different PSP?
• Stop retrying altogether?

Without standard guidance, merchants risk over or under retrying.

The Risk of Over- and Under-Retrying Failed Payments

Without clear retry rules, merchants walk a fine line. Over-retrying can quickly backfire: issuer fraud systems may flag repeated attempts and lower authorization rates on future transactions, card networks may penalize high decline ratios, and customers may become frustrated or confused when they see multiple failed charges on their bank statements. Each unnecessary retry also consumes processing resources and clutters logs, adding noise for support and reconciliation teams.

On the other hand, under-retrying leaves money on the table. Payments that could have been recovered with a simple retry are abandoned, customers churn for no reason other than a “false failure,” and support teams are left with the costly burden of manual intervention. Merchants are stuck choosing between losing revenue or risking penalties, and it’s this exact gap that Hyperswitch addresses with Error Normalization and Smart Retries.

How Hyperswitch Solves It

Hyperswitch addresses the retry challenge in three layers:

1. Error NormalizationRaw errors from issuers, networks, and PSPs are messy and inconsistent. Hyperswitch’s Gateway Status Mapping (GSM), translates them into unified codes and categories, giving merchants a single, consistent error language.
2. Smart RetriesOnce normalized, Hyperswitch decides if and when to retry. It stops immediately on hard declines, waits on soft declines like insufficient funds, and requests more data on authentication failures. This prevents both over- and under-retrying.
3. Two Specialized Approaches to Recovery
   • Intelligent Routing (PSP-level): If the failure stems from a PSP issue (like an outage or misconfiguration), Hyperswitch routes the retry to another PSP that’s performing better.
   • Revenue Recovery (Issuer/Network-level): If the error originates deeper in the chain and may have been misclassified (e.g., an issuer incorrectly flags a card as “account closed”), Hyperswitch uses ML-driven pattern detection to determine whether the payment is still recoverable. It does this by retrying later at the right time based on historical data.

As a result, merchants recover more revenue automatically while avoiding the risks of over-retrying, under-retrying, or sending retries through the wrong provider.

In the next part, we’ll cover how intelligent routing plays a role in these challenges.