Difference between `decline_code` and `code` on a failed charge?

Posted by andre_s — March 19, 2026 — 11 replies

Failed charge object has both code ("card_declined") and decline_code ("insufficient_funds"). Which one should I be branching on in my error handler?

priya.s — Evolve team — March 19, 2026 — accepted answer

Both, depending on what you're doing.

code is Evolve's high-level error category. There are about a dozen — card_declined, authentication_required, processing_error, etc. Stable across networks. Use this for branching to user-facing UI ("your card was declined" vs "please complete authentication").
decline_code is the network's specific reason — there are hundreds. Use this for retry decisions (don't retry on stolen_card, do retry on processing_error) and for analytics.

Don't branch user-facing flow on decline_code — the names aren't fully stable across networks and locales, and there are too many. The message field is also for display purposes only; don't parse it.