Decline Messages at Checkout
When a customer's card declines, the message they see decides whether they fix the problem or give up. "Your card was declined" on its own leaves them guessing. A message that says the card has insufficient funds or that the billing ZIP code does not match tells them what to do next.
UltraCart handles this for you. When a card declines, UltraCart analyzes the payment gateway's raw response and writes a short, plain-language explanation of that specific decline for the customer. There is nothing to configure.
What the customer sees
The customer stays in checkout with the decline message shown, so they can correct their billing details or try a different card. The message has two parts:
Your credit card has been declined. Explanation of this specific decline.
For an insufficient-funds, expired-card, or address verification (AVS) mismatch decline, the second sentence explains that problem and what the customer can do about it.
When the standard message appears instead
In some cases the customer sees the standard message:
Your credit card has been declined. Make sure the billing address matches the location that the credit card statement is mailed. Please verify the information and try again.
This happens when:
- The decline looks like fraud prevention. Responses such as a pickup-card or stolen-card decline are deliberately not explained to the person holding the card.
- The analysis is not available for that attempt. The analysis has a short time limit so that it can never hold up checkout. If it does not finish in time, the standard message is shown.
If the payment gateway returns its own customer-facing text, the customer sees that text after "Your credit card has been declined." instead of the generated explanation.
Declines that come from your own Fraud Prevention rules work differently. They show the custom decline message you set on the rule, or the standard message above if the rule has none.
What your team sees
The analysis is also saved on the transaction, so whoever works the order in Accounts Receivable can see why it declined without decoding gateway response codes. Open the order and view its transaction history. The analysis appears alongside the gateway's own response fields:
| Field | What it tells you |
|---|---|
uc_ai_category | The kind of decline: temporary_decline, permanent_decline, authentication_issue, technical_error, or fraud_prevention. |
uc_ai_retry | true if retrying the same card has a reasonable chance of succeeding, false if it is unlikely to. |
uc_ai_reason | A one-sentence explanation of the decline. |
uc_ai_corrective_action_before_retry | What to do before retrying, for example contacting the cardholder to verify funds. Empty when no action is likely to help. |
uc_ai_customer_message | The explanation that was shown to the customer. |
The analysis never changes the outcome of a transaction. A declined card is still declined; the analysis only explains it.
When no message is shown
Some declines never reach the customer, because UltraCart saves the order to Accounts Receivable instead:
- The customer has reached your failed-attempt limit. The After Failed Attempts setting in your credit card payment settings controls how many declines a customer gets before the order goes to Accounts Receivable for your team to follow up.
- The customer left during post-checkout upsells. UltraCart makes a final charge attempt after the customer leaves. If that declines, the order goes to Accounts Receivable with the UPSELL-NFO-01 merchant note. See When are Credit Cards Charged for the timing.
Can I change the decline message?
The decline-specific explanation is written for each decline, not drawn from a template, so there is no text to edit. The standard message is the same on every storefront.
The decline text you control is on your Fraud Prevention rules. Each rule set to decline can carry its own customer message, and each rule can be limited to specific items, payment gateways, or screen branding themes, so the message can differ from one storefront to another.