A decline is a one line answer to a question the customer bank was asked. The useful part is not that the payment failed, but which of the roughly forty possible reasons applied, because about a third of them are recoverable at checkout and the rest are not.
Who actually declined it
Three parties can stop a payment, and they produce different codes.
- The issuing bank. Most declines. Nothing on your side caused it, and nobody at your processor can overturn it.
- The processor or gateway. Formatting problems, invalid credentials, unsupported currency, duplicate transaction, velocity rules.
- Your own rules. Fraud filters, AVS mismatch rejection, country blocks.
The declines you can recover
| Reason | What to show the customer |
|---|---|
| Insufficient funds | Ask them to try another card. Retrying the same card later works surprisingly often, which is why dunning exists. |
| Incorrect number, expiry or CVV | Ask them to check the field named. Do not say declined, say check the security code. |
| Do not honour | Generic issuer refusal. Ask for another card, or ask them to call the number on the back. |
| Card not supported for this transaction type | Common with prepaid and some debit cards on recurring billing. Offer a different method. |
| Suspected fraud | The bank blocked it. Only the cardholder can clear it, usually by approving a push notification. |
The declines that are yours to fix
- Invalid merchant credentials. Wrong API key, wrong environment, or a key rotated in the gateway and not in the store.
- Transaction not permitted. The MID is not enabled for that transaction type, for example ACH, recurring, or a currency you have not been approved for.
- Duplicate transaction. The same amount, same card, within a short window. Usually a double submit on your checkout, not a customer error.
- Invalid amount. Zero, negative, or too many decimal places. Nearly always a currency formatting bug.
- Velocity exceeded. Your own fraud rule fired. Check the threshold before assuming a card problem.
Soft and hard declines, and why the difference matters
A soft decline is temporary: insufficient funds, issuer unavailable, a limit hit for today. Retrying later can work, and the card networks permit a limited number of retries.
A hard decline is permanent: stolen card, closed account, pick up card. Retrying a hard decline is not just useless, it can attract network fines under the excessive retry rules. Any dunning routine you build must read the code and stop on a hard decline.
What to write in your checkout messages
Never show the raw gateway text to a shopper. It is written for a terminal in 1994. Map it instead:
- Wrong CVV becomes: The security code did not match. Check the three digits on the back and try again.
- Insufficient funds becomes: Your bank declined the payment. Try another card, or contact your bank.
- Do not honour becomes: Your bank declined the payment and did not say why. Trying a different card usually works.
- Fraud suspicion becomes the same message as above. Never tell a shopper that fraud was suspected. If they are a genuine customer it is insulting, and if they are not you are teaching them your rules.
Measuring the right thing
Track the decline rate as a share of attempts, split by reason, weekly. A healthy card not present store sits somewhere between five and twelve percent. A sudden jump in one reason code is the signal worth chasing. Three patterns are common:
- A spike in invalid card number attempts across many small amounts is card testing. Add velocity limits and a CAPTCHA on the checkout.
- A spike in do not honour on one BIN range usually means an issuer changed its risk model. Nothing to fix, it settles.
- A spike in transaction not permitted after a deploy means credentials or a gateway setting changed.
Where to look inside WooCommerce
Order notes carry the gateway response for each attempt, including the code and the AVS and CVV results. When the response is missing entirely, the request never reached the gateway, which points at the checkout, a plugin conflict, or an outbound connection problem rather than at the card. The troubleshooting guide covers reading those notes step by step.
One habit is worth building: when a customer emails about a failed payment, find the order note before replying. Ninety percent of the time it names the cause in one line, and you can answer with something specific rather than asking them to try again.