Intercept the invoice.payment_failed webhook and inspect the last payment error code to classify the failure as soft (retry-able) or hard (do not retry).
For soft declines, implement an exponential backoff retry schedule (e.g., retry after 1 day, 3 days, 7 days) using your payment platform's built-in retry settings or a scheduled job.
For hard declines (invalid card, stolen card, do not honor with no retry indicator), immediately suspend the subscription and send a payment update notification to the customer.
Send in-app and email notifications before each retry attempt with a direct link to the customer portal where they can update their payment method.
After the final retry attempt fails, trigger a cancellation flow and provide a grace period during which the customer can reactivate with a new payment method.
Log each retry attempt with the decline code, retry number, and timestamp for support and analytics.
Known gotchas
Retrying a card that has been reported lost or stolen will result in repeated hard declines and may trigger fraud monitoring flags on your merchant account; stop retrying immediately on these codes.
Network rules limit how many times you can retry a declined card in a given period; exceeding these limits can result in fines or merchant account restrictions.
Sending too many dunning emails can cause unsubscribes and spam complaints; limit communication to no more than one message per retry attempt and use a suppression list.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp