Recurly decline codes explained: what each one means and what to do
A plain-English guide to the decline reasons Recurly records on failed transactions, which ones are worth retrying, which point to fraud, and how to see which ones you are getting most.
Every failed transaction in Recurly carries a reason. Recurly translates the hundreds of codes that card networks and gateways use into a shorter list of its own, which makes them far more useful, once you know what they mean.
Recurly groups them into soft declines (temporary; the same card may work later), hard declines (the card won't work without new details), and fraud declines. The meanings below follow Recurly's own reference.
Soft declines: worth retrying
| Code | What it means | What to do |
|---|---|---|
insufficient_funds |
The card doesn't have enough available to cover the charge. | Let dunning retry; payday often fixes it. |
try_again |
Declined, with a response suggesting a later attempt may succeed. | Retry later. |
temporary_hold |
The issuing bank has a temporary hold on the card ("do not honor"). | Retry later, or ask for another card. |
call_issuer |
The issuer declined and wants the cardholder to contact them. | Ask the customer to call their bank. |
declined |
The bank declined without giving a specific reason. | Ask the customer to contact their bank or use another card. |
Hard declines: the card won't work as it is
| Code | What it means | What to do |
|---|---|---|
declined_card_number |
The card number is invalid. | Ask for a different card. |
invalid_account_number |
The account number is invalid. | Ask for different details. |
expired_card |
The expiry date has passed or doesn't match. | Ask the customer to update the card. |
restricted_card |
The card can't be used with your merchant account, often a corporate card. | Ask for another card. |
card_blocked |
The cardholder asked for payments to you to be stopped. | Don't retry. Treat it as a cancellation request. |
invalid_transaction |
The card can't do this kind of transaction. | Ask for another card. |
Retrying a hard decline is not just pointless. Repeated attempts on cards that can never succeed raise your decline ratio, which card networks and processors watch.
Fraud declines: look closer
| Code | What it means |
|---|---|
fraud_stolen_card |
The card has been reported lost or stolen. |
fraud_velocity |
Part of a burst of activity from one source. |
fraud_risk_check |
Declined by the fraud settings on your Recurly site. |
fraud_gateway |
Declined by fraud filters at your payment gateway. |
fraud_address |
The billing address didn't match the card's records. |
fraud_security_code |
The security code or expiry date didn't match. |
A few of these on any given day is normal. A cluster of them on new signups, especially
fraud_stolen_card alongside lots of insufficient_funds and declined_card_number, is a classic
sign that someone is testing stolen cards on your signup page. We wrote about spotting card
testing.
Seeing your own mix
The useful question is not what a code means but which ones you are getting, and where. In Claude or ChatGPT with Retrixus:
"What were the top decline reasons on renewals in the last 24 hours, with counts?"
"Compare decline reasons on new signups versus renewals this week."
"Which traffic source had the most fraud declines today?"
If renewals are dominated by soft declines, your dunning schedule is doing its job. If new signups show a spike in fraud and hard declines from one source, look at that source today.
Retrying the right ones
Hard declines on renewals are where dunning wastes money. Once you can see them, you can stop collection on invoices that will never succeed. We cover that in finding failed renewals and stopping dunning on the right plan.
Start free on one Recurly site.
Try it on your own Recurly data
Start free on one Recurly site. Connect Claude or ChatGPT and ask your first question in about 15 minutes.
Start free