Payment declines are not all the same. Some result from temporary issuer conditions and may succeed after a carefully timed retry; others require updated customer details, stronger authentication, or an immediate stop. This guide explains payment decline codes, separates soft and hard declines, provides a practical retry and notification workflow, and gives you a monthly approval-rate review template for finding preventable failures without weakening fraud controls.
Overview
A declined online payment means an authorization request was not approved, but the response alone does not always explain what should happen next. The payment processor, gateway, card network, and issuing bank may each use different labels or code formats. A code that appears as “do not honor” in one dashboard may be grouped under a broader issuer-decline category elsewhere.
For that reason, treat a decline code as an operational signal rather than a complete diagnosis. Your team should combine the code with the payment method, transaction type, customer history, authentication result, and gateway response details. Before changing retry rules, confirm how your processor defines each response and whether its documentation distinguishes authorization declines from technical errors.
The most useful first distinction is between a soft decline and a hard decline:
- Soft decline: A temporary or potentially correctable failure. A limited retry, a request for authentication, or updated payment details may resolve it.
- Hard decline: A response that generally should not be retried automatically, such as a closed account, an invalid account, or a clear instruction to stop attempting the transaction.
These categories are practical rather than universal. A processor may classify the same network response differently depending on the transaction context. Your payment operations documentation should therefore record both the original response and the action recommended by your provider.
What to track
Build a decline report that allows someone to move from a summary number to an individual payment attempt. At minimum, capture the following fields:
- Transaction or payment-attempt ID
- Timestamp and time zone
- Payment method, such as card, bank transfer, wallet, or local method
- Authorization outcome and processor response code
- Gateway message and network or issuer category, where available
- Amount, currency, and billing country
- New, saved, recurring, or merchant-initiated transaction type
- Authentication status, including whether 3D Secure was attempted, completed, challenged, or unavailable
- Fraud-screening outcome and any manual review decision
- Retry count, retry timing, and final outcome
- Whether the customer was notified and updated payment details
Use a category structure that your support and engineering teams can understand. The following reference is a starting point; exact code names and retry instructions vary by processor and card network.
| Category | Typical meaning | Usual next step |
|---|---|---|
| Temporary issuer or soft decline | The issuer did not approve the attempt, but the condition may be temporary or context-dependent. | Check the processor guidance, avoid rapid repeated attempts, and consider one controlled retry or customer contact. |
| Insufficient funds or limit | The account may not have enough available funds or credit for the transaction. | Do not loop retries. Ask the customer to use another method or update the payment details. |
| Invalid details | The card number, expiration date, security value, billing address, or account information may be incorrect. | Request corrected details through a secure checkout or account page. |
| Hard issuer decline | The issuer or processor indicates that the transaction should not be approved or retried. | Stop automatic retries and present a neutral payment-method message. |
| Fraud or risk decline | The payment was blocked by issuer, gateway, or merchant fraud controls. | Do not reveal sensitive rules. Review the event, use approved authentication or manual review, and avoid indiscriminate retries. |
| Authentication failure | Required customer authentication was not completed, failed, or could not be verified. | Send the customer through the supported authentication flow or request another payment method. |
| Technical or timeout error | The request may not have completed because of connectivity, gateway, duplicate, or system conditions. | Check the final payment state before retrying. Use idempotency and webhook records to prevent duplicate charges. |
For saved cards and recurring payments, distinguish a failed scheduled charge from a customer-initiated checkout. A recurring payment may need an account-update message and a recovery sequence rather than repeated authorization attempts. Review the subscription billing setup guide for related handling of failed payments and recovery.
Cadence and checkpoints
A monthly review is usually practical for an established payment operation, while a weekly review can be useful after a checkout launch, gateway migration, pricing change, or unusual decline increase. Review a longer period as well when transaction volume is low; a small number of payments can make a short-period rate appear unstable.
Start with a consistent denominator. Decide whether your approval rate means approved authorization attempts divided by all authorization attempts, or whether it excludes technical duplicates, canceled orders, and known test transactions. Keep that definition unchanged from one report to the next.
Use this monthly checkpoint:
- Measure the baseline: Record total authorization attempts, approved attempts, declined attempts, recovered payments, and the resulting approval and recovery rates.
- Break down the decline mix: Group declines by response category, payment method, card type, currency, and recurring or one-time status.
- Locate concentration: Compare geography, issuer or issuer region where available, device type, browser, checkout version, and customer segment.
- Review the retry path: Count retries, time between attempts, recovery outcomes, and any duplicate or customer-service incidents.
- Check authentication: Compare payments that passed, failed, or bypassed the available authentication flow. Review the 3D Secure and strong customer authentication guide when checkout authentication changes.
- Separate control failures from customer failures: Identify declines caused by invalid data, unavailable payment methods, integration errors, or overly broad fraud rules.
- Assign an owner: Give each material issue to payments operations, engineering, fraud, support, or the payment provider, with a review date.
Document gateway changes alongside the results. A new integration setting, token configuration, checkout field, currency option, or webhook behavior can change decline patterns without a change in customer intent. Reliable event handling is especially important when a timeout leaves the final payment state uncertain; use payment gateway webhook guidance as part of the technical review.
How to interpret changes
A lower approval rate is a prompt to investigate, not proof that every decline should be retried. Look for the earliest point where the pattern changed. If declines rise only on one checkout version, device type, or currency, the issue may be integration or configuration related. If they rise across several payment methods for one region, review issuer behavior, local payment coverage, and currency handling. The multi-currency payment gateway guide can help structure that review.
A high share of “do not honor” or general issuer responses is not enough to justify repeated attempts. Compare the rate by issuer group, customer type, transaction amount, and authentication status, then ask your processor whether a more specific underlying category is available.
Watch recovery rate alongside approval rate. A retry strategy can improve recovered revenue while creating unnecessary attempts, customer frustration, duplicate authorizations, or additional fraud exposure. Set a rule for each category: retry automatically, request customer action, route to review, or stop. Keep the rule narrow and test one change at a time.
False declines deserve their own review. Examples may include legitimate customers blocked by an overly sensitive risk rule, a failed address check caused by formatting, an authentication handoff that did not return correctly, or a token that was not updated after card details changed. Investigate these cases using transaction evidence and approved controls rather than weakening fraud protection globally. Tokenization and secure card-on-file practices may also affect how saved payment credentials behave; see the payment tokenization guide.
Customer messages should be clear but discreet. Say that the payment could not be completed, provide a secure way to try another method or update details, and offer support when appropriate. Do not expose internal fraud scores, issuer decisions, or sensitive response logic.
When to revisit
Revisit this article and your internal decline rules at least monthly during active growth, and at least quarterly when payment behavior is stable. Schedule an earlier review after a gateway or processor change, checkout redesign, new market launch, currency expansion, fraud-rule adjustment, recurring billing change, or sudden approval-rate drop.
At each review, confirm that response-code mappings, retry recommendations, authentication behavior, dashboard fields, and webhook states still match your provider’s current documentation. Network and issuer terminology can change, and a dashboard label may not preserve the same meaning after an integration update.
End every review with a short action list:
- One decline category to investigate
- One retry or notification rule to verify
- One customer journey to test from checkout through final payment status
- One metric definition to confirm
- One owner and deadline for the next check
Keep a dated change log so the next approval-rate review can distinguish a real customer trend from a deployment or configuration event. That habit turns payment decline codes from isolated error messages into a repeatable process for improving authorization quality while preserving secure payment processing.