Handle a failed charge

Cards expire, banks reject transfers, and auto-pay sometimes hits a snag. Here's how to spot and clear failed charges.

How to spot them

Failed charges surface in three places:

Screenshot pendingFailed charge visible across Invoices, the Payments report, and the family detail page

12

1. 1Invoices & Finances → Invoices: the Past Due filter lists every invoice whose charge did not land
2. 2The invoice stays in 'Sent' or flips to 'Past due' with the balance still owing

We don't email the parent automatically when a charge fails. That's deliberate — some failure reasons (SCA challenges, temporary network blips) resolve without action. We wait for the parent to retry from the pay-now link, or for the next auto-pay run.

Retry options

You have two paths:

1. Let the parent retry from the email

The original invoice email still has a working Pay now link. Tell the parent, "your last payment didn't go through — click the link in the invoice email and try again, or use a different card." This is the cleanest path.

2. Let auto-pay retry

If the family has auto-pay turned on, NestliCare retries every morning at 6 AM UTC. The retry is idempotent — no double-billing. Most transient failures clear within 24 hours.

Auto-pay retries are capped at 3 consecutive failures

If a single invoice's auto-pay charge fails three days in a row, NestliCare stops retrying and sends an in-app notification:

• The parent gets "Auto-pay attempts stopped" with instructions to update their payment method.
• You and any other admins get "Auto-pay stopped for a family" with the invoice number and the reason of the last failure.

The cap exists so a hard-declined card (closed account, fraud lock, etc.) doesn't get hammered every morning forever. Three days is enough to absorb transient bank-side issues but small enough to surface a real problem before the next billing cycle.

To unstick the invoice after the cap:

• Ask the parent to relink their payment method, then your next billing cycle's invoice will be picked up automatically (the counter resets per-invoice on success).
• Or, if the family settled out-of-band, mark the invoice paid manually from the invoice detail page — the cron's status filter excludes paid invoices automatically.

The stuck invoice itself stays parked until it's paid or voided. The cron does not retry it again on its own once the cap is hit.

If the card is expired or closed

1. On the family's Billing tab, ask them to remove the old payment method.
2. Send them the invoice email again (Invoice detail → Send → Resend email).
3. They pay from the email using a new card. The method gets saved for next time.

If a family goes past due

• Day 1–14: invoice is Sent but unpaid. No automatic nudge — you decide when to follow up.
• Day 15+: invoice flips to Past due (this threshold matches your due_after_days setting from the generate dialog).
• Past due + auto-pay off: message or call the family. Kids can keep attending unless you've set up a financial-hold rule (not built in yet).

When to write it off

If a family leaves and the balance is uncollectable:

1. Open the invoice.
2. Click Void at the top right.
3. Pick Uncollectable as the reason (it's reported separately in financial reports).

Voiding the invoice zeroes out what the family owes. The invoice stays in your records with a red "Void" pill.

Troubleshooting

"Failed" pill with no reason text. Stripe returned an error we didn't parse. Click the payment row to see the raw Stripe error code — it's usually a card-issuer rejection and the parent needs a different card.

Auto-pay didn't retry. Two things to check. First, the family's auto-pay toggle on Family → Billing — auto-pay only retries when the authorization is still active. Second, the invoice's failure count: once an invoice has hit 3 consecutive auto-pay failures the cron stops retrying that specific invoice (see the section above on the 3-failure cap). Future invoices for the same family still go through normally.

Multiple invoices showing past due after we already talked to the family. The new payment only clears the invoice it was linked to. If the family paid $500 but has two $250 invoices, the second one stays owing. Void it manually or generate a new unified invoice.

"Insufficient_funds" keeps happening on the same card. It's not a you-problem — the card issuer keeps declining. Ask the family to switch to ACH (bank transfer) which is cheaper and usually more reliable.