Recurring Payments API

What crosses the wire

• Where it sits

  Above the payments API rather than beside it. A plan produces charges, and each charge is an ordinary payment with the same states, the same error codes and the same settlement records as anything else on the account.

• What you send

  A plan: the amount, the interval, any trial or setup fee, the retry policy, and the token to bill. Then a subscriber attached to it. The reference names each field and states which are fixed at creation and which can change later.

• What comes back over time

  Events, not a return value. A renewal succeeding, a renewal failing, a retry succeeding, a plan changing, a subscription ending — each arrives as a webhook, and an integration that only reads the creation response knows nothing after the first cycle.

When to use it

• Revenue that repeats

  Any charge that happens more than once on a schedule belongs here rather than in a job that calls the payments API on a timer and reimplements retries badly.

• Instalment plans

  A fixed number of equal charges after a deposit, common in healthcare and professional services, is a schedule with an end date rather than an open subscription.

• Plans that change

  Upgrades, downgrades and pauses mid-cycle need proration and an audit trail. Both are easier to inherit than to build, and both are where hand-rolled billing quietly diverges from the ledger.

How to implement Recurring Payments API

What fails, and how you find out

• Retrying a hard decline on the schedule

  The retry sequence exists for soft declines. A closed account fails on day 3, day 7 and day 14 identically, against an issuer that has already said no.

• Cancelling on the first failure

  Most failed renewals are an expired or reissued card rather than a customer leaving. Ending the subscription on the first decline turns a recoverable payment into a lost one.

• Plan state living only in your database

  If your record says active and the engine says cancelled, the customer experiences whichever one your product reads. Drive your state from the events rather than from what you wrote when you created the plan.

• No consent record

  A recurring charge a customer disputes is defended with the authorization you captured at signup. Not storing it turns an ordinary dispute into one you cannot answer.

Sandbox versus production

• Cycles you do not have to wait a month for

  Sandbox is where a monthly plan can be observed through several renewals in a sitting, which is the only practical way to test dunning without waiting for real calendar time to pass.

• Failures on demand

  A documented decline card attached to a plan produces a failed renewal and the retry sequence that follows it, so the recovery path can be asserted on rather than hoped for.

• Updater results are simulated

  Sandbox can show a refreshed credential rescuing a renewal. Real recovery depends on network and issuer participation, so treat sandbox as proof your handling works rather than as a rate to plan around.