Payment Recovery
How Arcalotl handles failed renewals, payment reminders, and role access during dunning.
When a renewal fails, Arcalotl starts payment recovery, also called dunning. The goal is simple: give the member a clear way to update billing before role access is removed.
How it works
- Renewal fails. Stripe notifies Arcalotl that payment failed.
- Recovery starts. Arcalotl creates a dunning sequence for the subscription.
- Reminder sent. The member receives a DM with the payment recovery copy and a Stripe Billing Portal link when one can be created.
- Fallback used when needed. If DMs are closed or Discord rejects the DM, Arcalotl can create a private
payment-helptext channel. - Stripe keeps processing billing state. Stripe may retry the payment according to the connected account's Stripe settings.
- Access changes after grace. If payment is still unresolved after the grace period, Arcalotl removes the subscription role.
Default timeline
| Day | Action |
|---|---|
| 0 | Renewal fails. First reminder sent with update link. |
| 2 | Second reminder sent if payment is still unresolved. |
| 4 | Third reminder sent if payment is still unresolved. |
| 6 | Fourth reminder sent if payment is still unresolved. |
| 7 | Role access is removed if payment is still unresolved. |
When a member updates their payment method and the charge succeeds, their role is restored automatically. No manual intervention is needed.
What members see
Payment recovery messages are sent as private embeds. They include the affected server, plan, and role when those details are available. When Arcalotl can create a Stripe Billing Portal session, the message also includes a link button labeled Update Payment Method.
If Arcalotl cannot create a Billing Portal link, the footer tells the member to use /manage in the server instead.
Dunning message copy
This is the exact member-facing copy Arcalotl sends during payment recovery.
| Attempt | Title | Body | Footer when the payment link is available |
|---|---|---|---|
| 1 | Payment update needed | Your recent renewal did not go through. Update your payment method to keep your subscription active. | Use the button below to update your payment method. |
| 2 | Subscription still needs attention | The renewal still has not gone through. Your role stays active during the grace period, but access will pause if the payment method is not updated. | Use the button below to update your payment method. |
| 3+ | Access pauses soon | This subscription still needs a payment update. Access will pause after the grace period until the payment is resolved. | Use the button below to update your payment method. |
Fallback footer when no payment link is available:
Use /manage in the server to update your payment method.Button label when a payment link is available:
Update Payment MethodRecovery confirmation:
Payment updated
Your renewal has been processed. Your subscription is active again.Message sent if recovery is exhausted:
Subscription ended
We could not complete the renewal after several attempts, so this subscription has ended. You can subscribe again from the server if you want access back.Private channel fallback
Arcalotl tries to send the recovery message by DM first. If that DM fails, Arcalotl creates a private text channel named payment-help in the server and sends the same recovery message there.
The fallback channel is hidden from @everyone. The target member and the bot can view the channel and send messages. If a Billing Portal link is available, the private channel message keeps the same Update Payment Method button.
Once a fallback channel exists for a recovery sequence, later attempts for that sequence go to the same channel instead of trying a new DM. Arcalotl deletes the temporary channel when the payment is recovered or when the recovery sequence is exhausted.
Recovery fee
Arcalotl charges the retention fee only on revenue recovered through the payment recovery flow. If a failed renewal is not recovered, there is no recovery fee for that failed payment.
Configuration
Payment recovery is enabled by default when setup is complete. The default is 4 attempts, 48-hour spacing, and a 7-day grace period. You can adjust those settings from Retention Settings.