Payment Declined / Failed
A customer's payment is declining. Here's how to diagnose and fix.
What declined means
The customer's bank rejected the charge. It's almost always between Stripe and their bank — HandyBook isn't deciding to decline.
Common reasons
Insufficient funds
The most common reason. Their account doesn't have enough.
Card expired
Their card on file has expired.
Suspected fraud
Their bank flagged the charge as suspicious (large amount, unusual merchant, foreign transaction).
Wrong CVV / zip code
Mistyped during entry.
Card type not supported
You don't accept Discover or AmEx, but they tried one. (Settings → Payments → Accepted Cards)
Merchant restriction
Some banks restrict charges to certain merchant categories. Rare.
Card reported lost / stolen
Card has been frozen by the bank.
What the customer sees
- "Your payment was declined. Please try a different card."
- For some reasons (fraud), they may also get a text from their bank asking to confirm
What you should do
Step 1 — Ask them to retry
Most issues clear with a retry. Maybe they're entering the wrong CVV, or their bank's fraud system needs a confirmation.
Step 2 — Check the decline reason
Open the failed payment in HandyBook → see Stripe's decline reason. Common codes:
insufficient_funds— try a different card or waitexpired_card— they need to use a current cardfraud_detected— Stripe Radar flagged it; their bank may need to authorize manuallycard_declined— generic, often means try again
Step 3 — Suggest alternative
If retries fail, suggest:
- Different card
- ACH bank transfer (lower decline rate)
- Apple Pay / Google Pay (often bypasses card issues)
- Cash / check if you trust them
Step 4 — If you suspect fraud
If the customer is unfamiliar to you and the decline pattern is suspicious (multiple cards declined, asking for partial payment, weird email):
- Don't proceed — this could be a stolen card scenario
- Politely decline business
- Report through Stripe's fraud reporting if appropriate
When to refund a successful but disputed payment
Sometimes a payment goes through but the customer immediately disputes. See the Disputes & Chargebacks article.
ACH-specific issues
ACH (bank transfer) payments fail differently:
insufficient_funds— same as cards, try againaccount_closed— bank account is closed; they need a different accountaccount_frozen— temporary; usually resolves in daysinvalid_account— wrong routing/account number; they re-enter
ACH failures take longer to surface (up to 5 days), so always confirm the customer used a known-good account.
Stripe Radar
Stripe's fraud detection auto-blocks high-risk charges. Configure thresholds in Stripe Dashboard:
- Higher block threshold = fewer false positives, more fraud risk
- Lower threshold = more false positives, less fraud risk
Default is well-tuned for most service businesses.
Recurring billing failures
For recurring plan members whose card fails:
- Stripe Smart Retries kicks in (3-4 retries over 7 days)
- Customer gets emails to update payment
- After all retries fail, plan goes "past due"
- After more time, plan is cancelled (configurable)
FAQ
The decline was last week — can I retry now? Yes — open the invoice → Retry Charge. Tries again immediately.
The customer says their card works elsewhere — why is it declining here? Could be Stripe Radar flag, or merchant-category restriction, or first-time-merchant friction. Usually resolves with a retry or a different card.
Should I just take cash if cards keep failing? Up to you and the trust level. For a known repeat customer, fine. For a new lead, declined cards can be a fraud signal — proceed cautiously.
Can I see what specific code their bank returned? Yes — in HandyBook, open the payment record → Show Stripe details. Some bank decline reasons are very specific ("Do not honor" → call bank), some are generic.
Why does my customer's first ACH always fail? First-time ACH sometimes triggers risk reviews. Stripe usually clears it within minutes; if it persists, customer can verify their bank via Plaid (one-tap, more reliable).