Skip to content
Wasim Rashid

One error layer across many PSPs

Normalising provider response codes so declines become comparable, and the mapping decisions that matter.

WRBy Wasim Rashid··4 min read

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.

Next article

Loading a million BINs without touching the hot path

Open to consulting engagements

Have a payment problem that needs tracing?

Tell me which providers are involved and what is going wrong, or what needs to go live. I will tell you plainly whether I can help.

Tell me
Which providers and markets are involved
Show me
What is failing, or what needs to go live
You get
A plain answer on whether I can help