Decline reason

A decline reason is the cause of a refused payment expressed in one shared dictionary rather than in each provider’s own error code. Mapping provider codes to common reasons shows whether a decline came from the player, the bank, the provider or the merchant’s own integration.

How it works

A decline reason is assigned by mapping each provider’s code and message to one entry in a dictionary. An illustrative mapping:

Provider E  code: E-301 "Insufficient balance"   -> player funds
Provider F  code: currency_not_allowed           -> fixable by merchant
Provider G  code: 9999 "General error"           -> unknown

A code whose meaning is not proven stays unknown. Calling it a player decline would hide a provider problem.

Why it matters

Declines cost deposits, and the cause decides who can fix them. On one anonymised merchant day, 113 provider-specific decline codes reduced to 22 reasons. 8.7% of declined transactions were the provider’s fault, a case for rerouting or an SLA conversation. 42.5% carried a code whose meaning is not proven, and stayed unknown.

How to spot it

List the most frequent decline codes per provider for one week. Group them by what they say, not by their number. Codes that grow after a release point to your integration. Codes that spike for one provider in one hour point to the provider. A large “general error” share means you cannot yet tell.

Related terms

Payment service provider · Canonical status · Normalisation · Callback · Provider intelligence

Try it on one day of your data

One day of your data, reconciled, and the report stays with you whether or not you continue.

Updated