RevGuard PayPal subscription payment failed: what PayPal does, when it suspends, and how to recover the customer
PayPal handles failed subscription payments differently from Stripe. This guide covers the PayPal sequence and the recovery steps.
What PayPal does on its own
When a billing attempt fails, PayPal sends BILLING.SUBSCRIPTION.PAYMENT.FAILED and, depending on the plan's payment-failure settings, retries the charge itself. After the configured number of failures it suspends the subscription and sends BILLING.SUBSCRIPTION.SUSPENDED. A suspended subscription does not bill again until it is reactivated. It does not cancel by itself either, so a customer can sit suspended for months, paying nothing, still counted as a subscriber in your own database if you never handled the webhook.
The two webhooks that matter
BILLING.SUBSCRIPTION.PAYMENT.FAILED: the moment to record the case and start your own sequence. PayPal's retry is still running, so do not double-charge; email instead.BILLING.SUBSCRIPTION.SUSPENDED: PayPal has stopped. From here, the only way back is the customer updating their funding source and the subscription being reactivated through the API or by the customer.
Verify every webhook through PayPal's own verify endpoint before acting on it. PayPal webhooks are easy to forge and the payload alone is not proof.
The recovery sequence
- On the first failure, one plain email: the payment failed, PayPal will retry, here is how to update the funding source in their PayPal account. Include the subscription id so support can find it if they reply.
- On suspension, a second email that says the subscription is paused, not cancelled, and gives a link to reactivate. Reactivation requires the customer's approval on PayPal's side, so the link should go to the PayPal subscription page. The full steps are in how to reactivate a suspended PayPal subscription.
- Days 3 and 7 after suspension, two more short emails. After that, stop. A customer who has ignored four emails has decided.
- Re-check before every email. Fetch the subscription status first. If it is active again, do nothing and record the recovery.
Two PayPal-specific traps
- Access tokens expire in hours; your sequence runs for days. Mint a fresh token inside the loop, every time, never at the start.
- Suspended is not cancelled. If your product grants access on "not cancelled", suspended customers keep using it for free. Treat suspended as unpaid.
Doing it without another monthly tool
Most dunning services are Stripe-only. RevGuard's PayPal recovery workflow handles the two webhooks, the verification, the token refresh, the four-email sequence and the re-check, and posts each case to the same dashboard as the Stripe side so you see both providers in one place. It is $59 on its own, or part of the $179 Complete Kit, and runs on your own machine.