Payment Reason Code Directory
When a payment fails, the bank or scheme returns a reason code explaining why. Each payment stream has its own code set: debit order unpaids use one set of return reasons, DebiCheck mandates another, and card payments use scheme response codes. The numeric or alphanumeric codes differ between streams and can differ between specifications, but the underlying reasons are consistent and predictable.
This directory describes the common reason categories for each stream and what to do about them. It deliberately avoids listing exact numeric codes, because those depend on the specification version your provider or bank uses. Always consult your provider or bank's current specification for the precise code values. For statuses rather than reasons, see the status directory, or return to the Reference hub.
How reason codes work
A reason code accompanies a failed or returned payment and tells you which party caused the failure and whether a retry is worthwhile. Broadly, reasons fall into three groups:
- Funds-related — the account is valid but could not pay right now. A retry on a better date often succeeds.
- Account-related — something is wrong with the account itself (closed, frozen, invalid). Retrying without fixing the details will fail again.
- Authority-related — the payer or their bank has withdrawn or refused authority (payment stopped, mandate cancelled, disputed). Do not simply retry; resolve the mandate or agreement with the customer first.
Debit order unpaid reasons
Common reasons a debit order collection is returned unpaid:
| Reason | What it means | What to do |
|---|---|---|
| Insufficient funds | The account did not have enough money on the action date. | Resubmit on a better date or use tracking; contact the customer if it repeats. |
| Account closed | The payer's account has been closed. | Get new bank details and a new or updated mandate. |
| Payment stopped | The payer instructed their bank to stop this debit order. | Contact the customer; do not resubmit until the underlying issue is resolved. |
| Account frozen / blocked | The account exists but is blocked, for example by a legal hold. | Contact the customer for an alternative payment method. |
| Account holder deceased | The bank has flagged the account holder as deceased. | Stop collections and follow your estate/collections process. |
| No such account / invalid account | The account number does not exist at that branch. | Verify the details, correct them and recollect. See account validation and CDV. |
| Authorisation cancelled | The payer cancelled the underlying authority or mandate at their bank. | Treat the mandate as ended; obtain a new mandate before collecting again. |
For resubmission rules and strategy, see unpaids, returns and resubmissions.
DebiCheck mandate decline reasons
Common reasons a DebiCheck mandate request fails:
| Reason | What it means | What to do |
|---|---|---|
| Rejected by customer | The payer actively declined the mandate at their bank. | Contact the customer to understand why before sending a new request. |
| Authentication expired / no response | The payer did not respond before the request lapsed. | Warn the customer to expect the bank prompt, then resend. |
| Account type not allowed | The account cannot carry DebiCheck mandates, for example some savings or credit accounts. | Ask the customer for a different account. |
| Mandate details mismatch | The details in the request do not match the bank's records, for example the ID number or account holder. | Correct the customer details and resubmit. |
| Invalid or closed account | The target account is invalid or closed. | Verify the bank details before retrying. |
For the DebiCheck-specific view, see DebiCheck statuses and reason codes.
Card decline reasons
Common categories of card response codes:
| Reason | What it means | What to do |
|---|---|---|
| Do not honour | The issuer declined without a specific reason; the most common generic decline. | Ask the cardholder to retry, contact their bank or use another card. |
| Insufficient funds | The card's available balance or limit is too low. | Ask the cardholder to retry later or use another method. |
| Expired card | The card's expiry date has passed. | Request updated card details. |
| Suspected fraud / security decline | The issuer's risk systems blocked the transaction. | The cardholder must contact their bank; do not repeatedly retry. |
| 3-D Secure failure | The cardholder did not complete or failed authentication. | Ask the cardholder to retry and complete the bank's verification step. See 3-D Secure. |
| Invalid card details | The card number, CVV or expiry was entered incorrectly. | Ask the cardholder to re-enter their details. |
For a deeper treatment, see card declines and response codes.
Bank transfer return reasons
Credit payments and payouts are returned for a narrower set of reasons: invalid or closed destination account, account unable to accept credits, or beneficiary details that do not match. Verify beneficiary details before paying, and see failed and returned transfers for handling returns.
Where to find exact codes
The authoritative source for exact code values is always the specification of the provider, bank or stream you integrate with. Code lists are versioned and occasionally change, so check that you are reading the version that matches your integration. If you receive a code you do not recognise, ask your provider rather than guessing, because acting on the wrong reason (for example retrying a stopped payment) can create disputes.
Status Directory
A directory of payment statuses across cards, debit orders, DebiCheck, registered mandates and bank transfers, with what each status means and what to do.
Industry Roles
The roles that make payments work, including issuers, acquirers, sponsors, system operators, TPPPs, PSPs, switches and clearing houses.