paypal REFERENCE_TRANSACTION declined: billing agreement cancelled by buyer

Fixing "paypal REFERENCE_TRANSACTION declined: billing agreement cancelled by buyer"

TL;DR

The buyer cancelled the billing agreement on PayPal's side, so the reference transaction has nothing to charge against. Stop retrying the dead agreement: mark it cancelled, tell the customer their PayPal preapproval was revoked, and guide them through creating a new billing agreement before the next charge.

paypal REFERENCE_TRANSACTION declined: billing agreement cancelled by buyer

Steps

1. On this decline, mark the billing agreement as cancelled in your system and stop all retries against it. Expected: No further charges attempt the dead agreement.

2. Check the agreement status via the PayPal API to confirm it shows cancelled and capture the cancellation timestamp. Expected: Your record matches PayPal's state.

3. Email the customer explaining that their PayPal preapproval was cancelled and include a link to set up billing again. Expected: The customer knows exactly what to do.

4. When the new agreement is approved, link it to the subscription and resume charges; back-bill any missed period per your policy. Expected: Billing resumes on a live agreement.

Prevention

Poll or webhook-watch billing agreement status so cancellations are known the day they happen, not at the next failed charge. Send the customer a re-approval link immediately on cancellation instead of waiting for the decline.

Detection

Alert on reference transaction declines with the cancelled-agreement reason. Reconcile agreement statuses weekly: any agreement PayPal shows as cancelled that you show as active is a future failed charge. Watch for retry loops hammering a dead agreement.

Recovery

There is no way to revive a buyer-cancelled agreement; a new one must be created by the buyer. For missed billing periods, decide whether to back-bill, prorate, or forgive, then communicate the decision clearly when the customer re-approves.

When this applies

• PayPal recurring charges fail with a reference transaction decline tied to a cancelled agreement
• The buyer revoked preapproval in their PayPal account
• Retries keep failing against the same agreement id

When it doesn't

• The decline is for insufficient funds or risk (the agreement is still live)
• This is a first-time PayPal checkout, not a reference transaction
• The agreement shows active in PayPal (then the decline has another cause)

Compatibility

PayPal REST API v2 (billing agreements, reference transactions), PayPal webhooks for billing agreement status changes.

paypal billing agreement was cancelled and renewals fail

reference transaction has no live agreement to charge

buyer revoked paypal preapproval and subscription keeps failing

Why it happens

A PayPal billing agreement is consent the buyer can revoke at any time from their own account. Your system keeps the subscription active because nothing told it otherwise, so the next renewal charges a dead agreement and declines. The gap between PayPal-side cancellation and your-side awareness is the whole problem.

Edge cases

• The buyer cancels and immediately re-approves: make sure the new agreement id replaces the old one everywhere
• Partial period owed at cancellation: decide your back-billing policy before the customer asks
• Webhook delays: confirm status via the API before telling the customer the agreement is dead

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eJ7Wn9troyu5-TZnA5Lgaw