Failed Payments

Failed payments occur when a customer’s renewal or invoice charge cannot be processed. Handling them properly reduces churn and ensures a smooth customer experience.

Common Causes of Failed Payments

• Expired credit or debit card

• Insufficient funds

• Incorrect billing details

• Bank declines due to fraud checks

• Network or gateway errors

Most failed payments are caused by expired or blocked cards. Automated retries can recover a large percentage.

Payment Retry Logic

By default, the system automatically retries failed payments. You can configure the retry schedule in the dashboard.

Default Retry Schedule

{
  "retry_policy": {
    "max_attempts": 4,
    "intervals": ["immediate", "24h", "3d", "7d"]
  }
}

Customer Notifications

Customers are notified by email when a payment fails. Notifications include:

• Reason for failure (e.g., expired card)

• Link to update billing details

• Next retry attempt date

Custom email templates can help reduce involuntary churn by making the update process easier.

Grace Periods

You can set a grace period during which the customer can still access the service while updating payment details.

Example API setup:

curl -X POST https://api.saasapp.com/v1/settings/grace_period \
  -H "Authorization: Bearer <API_KEY>" \
  -d days=7

Dunning Process

If all retries fail:

1. The subscription moves to Past Due state

2. Notifications are sent at each retry step

3. After retries + grace period, the subscription is canceled or paused (based on your settings)

Flow summary:

• Failed → Retry → Notify → Grace Period → Cancel/Pause

Best Practices

• Enable automatic retries and notifications

• Offer multiple payment methods (card, PayPal, bank debit)

• Use dunning emails with clear CTAs

• Add in-app reminders for billing updates

• Keep a short but fair grace period (3–7 days)

Summary

• Failed payments are common but recoverable

• Automated retries + clear notifications reduce churn

• Grace periods and dunning flows ensure fairness while protecting revenue

• Always test failed payment handling in Sandbox before going live