Insights · 5 min read
Recurring billing is where payment gateway integrations break. Here is how to handle retries, proration, dunning, and cancellations the right way.
By GGP Editorial
Most payment gateway guides stop at the first successful charge. That is fine for a one-time purchase, but subscriptions are a different animal. The integration only gets interesting after a customer's card is declined six months in, or they upgrade mid-cycle, or they cancel and you need to stop charging without refunding the wrong amount.
If you are building any kind of recurring product, here is what actually matters, and where most teams get it wrong.
A subscription integration is not one API call. It is a set of moving parts that have to stay in sync:
The webhooks are where projects go wrong. If your system only records a payment when your own checkout page redirects back, you will miss charges that happen days or months later. A customer whose card works for three months and then fails will keep getting your product for free until someone notices. You need the gateway to push events to you, and you need to handle them idempotently, because some gateways send the same event twice and a double record is how you end up double-charging a customer.
Card declines on renewals are normal. Industry data puts the first-attempt failure rate for subscriptions anywhere from 5 to 15 percent, and a good chunk of those cards succeed on a second or third try a few days later.
A smart retry schedule looks like this:
| Attempt | When | Why |
|---|---|---|
| 1 | On the renewal date | Normal charge |
| 2 | 3 days later | Some declines are transient |
| 3 | 7 days later | Give the customer time to update the card |
| Final | 14-21 days | Send a final notice, then cancel |
Between attempts you send the customer a short email: "Your payment didn't go through, here is how to update your card." This is dunning, and it recovers more revenue than almost any other single change. The mistake is being either too aggressive, annoying someone over a $9 charge, or too passive, silently cancelling a customer who would have paid.
The moment a customer can change plans, your billing math gets harder. If someone on a $30 monthly plan upgrades to a $60 plan on day 10, do they owe you $10 more for this month or nothing until next month?
There is no universal answer, but you need to decide one and apply it the same way every time. Prorated upgrades charge the difference for the remaining days. Non-prorated upgrades simply switch at the next cycle. Most consumer products prorate because it feels fair and it lets users upgrade without waiting.
Downgrades and cancellations should almost always take effect at the end of the current period, which means the gateway keeps the subscription active until the period ends, then stops. If you cancel immediately and refund the remainder, you create a refund-heavy support queue and lose the goodwill of a customer who was happy to stay through the month.
Stripe is the obvious choice because its billing engine handles retries, proration, and invoices out of the box. Braintree does recurring billing well too and adds PayPal support, which matters if your customers pay with PayPal. For markets where cards are not the default, you may need local methods like Pix in Brazil, e-wallets in Southeast Asia, or bank transfer in South Africa, and that often means running more than one gateway.
That is the practical reality of selling cross-border: one gateway rarely covers every country's preferred payment method. We have built payment systems for clients in Brazil, South Africa, and Singapore, and almost every one ended up with a primary gateway plus one or two local methods bolted on. The integration work is in making those look like one checkout and one reconciliation report.
One more thing for cross-border sellers: tax. Once you charge customers in multiple countries, you may owe VAT, GST, or sales tax depending on where they are, and the gateway does not calculate that for you by default. Plan for a tax tool or a manual process early, because retrofitting tax handling into a live billing system is painful.
Whatever gateway you pick, keep your subscription state in your own database and treat the gateway as the source of truth for money, not for status. That way you can switch gateways later without rebuilding your product's notion of "active", "past due", and "cancelled".
Tell us what you are building and where you are today. We typically reply within 24 hours.
