01Every provider has its own dialect
Connect three PSPs and you receive three vocabularies for failure. One returns scheme response codes. Another returns its own numbering. A third returns text. The same issuer decline arrives as three different things, and nobody can answer a simple question such as how many insufficient-funds declines there were yesterday.
On the gateway I built, I normalised error codes from multiple PSPs into one unified layer and rolled it out with no downtime. Merchants and operations then read one set of outcomes, whichever provider handled the payment.
02Map to categories, not to codes
The useful unit is the category, because categories drive decisions. Issuer declines the customer can fix, such as insufficient funds. Issuer declines they cannot. Authentication failures. Risk and fraud rejections. Limits and restrictions. Invalid data. Technical failures and timeouts.
Each category carries a default behaviour: whether a retry makes sense, whether another route is worth trying, and what the customer should be told. That is where a unified layer pays for itself.
03Three rules that keep it honest
Keep the raw provider code and message beside the unified one. The mapping will be wrong somewhere, and the original is the evidence.
Treat unmapped codes as a monitored category. A new code appearing in volume is often the first sign that a provider changed something.
Hold the mapping as data, with a history of changes. When a provider redefines a code, you need to know which reports were produced under the old meaning.