How Do Payment Error and Reason Codes Work?

Every payment outcome comes with a code: a structured value that explains why a transaction succeeded, failed, was rejected or was returned. Banks and providers return these codes in API responses, webhook payloads, response files and unpaid files, and each rail has its own code set defined in the relevant specification.

Raw codes are precise but not actionable on their own. The real work is mapping them into categories your systems and teams can respond to consistently: retry, fix the data, contact the customer, or stop.

Where do reason codes come from?

• API responses return validation and processing errors immediately, usually with a code, a field reference and a human-readable message.
• Webhooks and callbacks carry the reason for each status change, for example why a DebiCheck authentication was declined or a collection was unpaid. See webhooks and callbacks.
• Response and unpaid files in host-to-host integrations report a status and reason code per record, defined in the bank's file specification.

The same underlying event can surface with different codes in different channels, which is why a mapping layer matters.

What are the main categories of codes?

Rather than memorising individual codes, think in categories:

Validation errors

The instruction was rejected before processing: malformed fields, invalid branch codes, failed check-digit validation on the account number, missing mandatory data or a reference that breaches format rules. These fail the same way every time, so fix the data rather than retrying. Account validation is covered in account validation and CDV.

Account errors

The instruction reached the paying bank but the account cannot be debited: account closed, account not found, account frozen, or account type not supported for the stream.

Authorisation and mandate failures

The customer or their bank declined authority: a DebiCheck authentication rejected or expired, a mandate suspended or cancelled, or a collection that does not match the mandate terms.

Unpaid reasons

The collection processed but was returned: insufficient funds, payment stopped by the account holder, or the debit disputed. These are business outcomes with rules about what you may do next; see unpaids, returns and resubmissions.

System and technical errors

Timeouts, unavailable services and internal bank errors. These are usually retryable with backoff, as described in retries and stuck payments.

How should you map codes into your system?

• Store the raw code and the source (which bank, channel and spec version) with every transaction. Never overwrite it with your internal interpretation only.
• Map to internal categories that drive behaviour: retryable, data fix required, customer action required, final failure, disputed.
• Keep the mapping in configuration, not scattered through code, so a new code from a spec update is a data change rather than a release.
• Handle unknown codes safely: route unmapped codes to a review queue with a sensible default (usually non-retryable) instead of failing or guessing.

DebiCheck has its own well-defined status and reason model, covered in DebiCheck statuses and reason codes.

How do reason codes drive operations?

• Dashboards: unpaid and failure rates broken down by reason category show whether a spike is a data-quality problem, a customer-affordability trend or a bank incident.
• Automation: category-driven rules decide which failures re-queue automatically and which create work items.
• Customer communication: map codes to plain-language messages; never show a raw bank code to a customer as the explanation.
• Disputes and audits: the original code, with its source and timestamp, is part of the evidence trail described in logging, masking and audit trails.

Exact code values differ per bank and specification version, so always work from the current specification for your integration rather than a copied list.

Back to the Payment Operations hub.