Failed Payment Recovery
How CheckoutJoy recovers failed PayFast and Paystack subscription payments: the retry schedule, customer emails, card updates and what happens when retries run out.
A declined renewal does not end a subscription. With managed subscription billing, CheckoutJoy keeps the subscription open, tells your customer what happened, and tries the payment again on a schedule. This process is often called dunning.
Day 0
Renewal
Declined
Day 3
Retry 1
3 days later
Day 7
Retry 2
4 days later
Day 14
Retry 3
7 days later
Day 28
Final retry
14 days later
Still unpaid
Subscription ends
Customer is emailed
What happens when a payment is declined
- The failed payment is recorded on the order, with the reason the gateway gave.
- The subscription becomes Past Due. Your customer keeps their access.
- Your customer receives an email that says the payment was unsuccessful, why, and when the next attempt will be made. It has a button to update their payment details.
- CheckoutJoy tries the payment again on the next date in the retry schedule.
Every declined attempt sends your customer a new email with the date of the next attempt.
The retry schedule
By default CheckoutJoy makes up to five attempts over four weeks.
| Attempt | When | Day |
|---|---|---|
| Renewal | On the billing date | 0 |
| Retry 1 | 3 days after the renewal | 3 |
| Retry 2 | 4 days after retry 1 | 7 |
| Retry 3 | 7 days after retry 2 | 14 |
| Final retry | 14 days after retry 3 | 28 |
The schedule can be changed for your account. See Changing the schedule.
The emails your customers receive
CheckoutJoy sends two emails during recovery. Both carry your business name, and replies go to your business email address.
| When it is sent | What it says | |
|---|---|---|
| Payment unsuccessful | After every declined attempt | The amount, the reason, the date of the next attempt and a button to update payment details. |
| Subscription ended | When the final retry is declined | That the subscription has ended and no further payments will be taken. |
The reason is given in plain words, based on what the bank or gateway reported:
| What happened | What your customer reads |
|---|---|
| Not enough money in the account | insufficient funds |
| The card is past its expiry date | the card has expired |
| The bank declined without a specific reason | the bank did not approve the payment |
| The bank wants the customer to verify the payment | the bank asked for additional authentication |
| The saved card can no longer be charged | the saved payment method can no longer be charged |
| The bank did not answer in time | the bank did not confirm the payment in time |
Updating a card
The button in the payment email takes your customer to your Customer Portal, where they sign in with a link sent to their email address and choose Update Payment Method on the order. Set up your Customer Portal before you turn on managed billing, so that the link has somewhere to go.
How the new card is saved depends on the gateway:
- Paystack. Your customer enters the new card in a Paystack payment window. A small verification charge is made and refunded. The past due payment is then collected within the hour, without waiting for the next date in the schedule.
- PayFast. Your customer is taken to PayFast's secure card update page. The past due payment is collected on the next date in the schedule.
When the bank asks for extra verification on a Paystack payment, the button in the email takes your customer straight to their bank's verification page instead.
When a retry succeeds
The payment is recorded, the subscription returns to Active, and your integrations run as they do for any recurring payment.
The billing date does not shift. The next renewal is counted from the original due date, not from the day the retry went through. A monthly subscription due on the 1st that recovers on the 8th renews again on the 1st of the next month.
When retries run out
If the final retry is declined, the subscription ends and your customer receives the subscription ended email. No further payments are taken.
What happens to your customer's access is a setting on your account:
| Setting | Subscription status | Order | Integrations |
|---|---|---|---|
| Expire (default) | Expired | Left as it is | Run their subscription cancelled actions |
| Cancel | Cancelled | Cancelled | Run their subscription cancelled actions |
In both cases your integrations are told the subscription has ended, so access that an integration granted is removed the way it is for any cancelled subscription.
Changing the schedule
Two things can be set for your account by CheckoutJoy support:
- The retry intervals. The number of retries and the days between them.
- What happens when retries run out. Expire or cancel, as described above.
Contact support with the schedule you want.
Frequently asked questions
Does my customer lose access while a payment is past due?
No. Access stays in place for the whole retry schedule. It is removed only when the final retry is declined.
Is my customer charged twice if they update their card and a retry is also due?
No. Each billing period is collected once. A successful payment closes the period and stops the retries for it.
Why does a subscription show Needs attention?
CheckoutJoy could not finish a billing attempt, for example because the gateway could not be reached for a long time. The attempt is tried again every hour, and billing continues as soon as it goes through. The customer is never charged twice for the same period. CheckoutJoy support is alerted, and there is nothing for you to do.
Do I get told when a payment fails?
Failed payments and retries are shown on the order's timeline and the subscription shows as Past Due. CheckoutJoy does not send you an email for a declined payment.
Managed Subscription Billing
CheckoutJoy collects your PayFast and Paystack subscription and payment plan renewals, retries failed payments and emails customers a link to update their card.
PayFast Subscription Billing
Managed subscription billing for PayFast merchants: renewals collected by CheckoutJoy, free trials, payment plans, automatic retries and card updates in ZAR.