Skip to main content

Dunning and suspension

Suspension on a delinquency rung​

Withdraw a surface from a delinquent owner with 423 Locked once they reach a configured dunning rung:

Route::middleware('billing.suspend:api')->group(/* … */);

The delinquency clock is a stored timestamp, so lockout keeps working during a provider outage — and nobody is locked out unannounced: billing:dunning:advance (scheduled daily) walks the configured ladder, sending each rung's warning once its day arrives and charging that rung's late fee if you set one.

Once the last rung has failed, no attempt is planned any more and the subscription stays past due. Where the package bills the cycles itself and you cancel such a subscription, it ends at the next billing:run after the end the cancellation gave it, and its unpaid period stays unpaid.

A late fee on a rung​

A rung of billing.dunning may carry a fee. The advance charges it once for that rung, and the driver decides how it is collected:

  • Stripe adds it as an invoice item to the owner's next invoice.
  • Mollie, whose cycles the package bills itself, opens the fee as an order of its own and charges it as a separate payment once a cycle of the owner has been paid. Charging it earlier would meet the mandate that has just failed. A fee that is refused stays open for the next paid cycle, and it never starts dunning of its own.

A late fee compensates the delay; it is not the price of anything the customer receives. Its document therefore states no tax, as not subject to VAT, and the DATEV export books it as other income. In Germany this is UStAE 1.3 (6). Across the union, whether a payment is the consideration for a supply is decided under union law (CJEU C-90/20, Apcoa Parking Danmark), and a fee that buys nothing is not. A charge that is the price of something the customer uses, such as an extra service, is not a late fee in this sense: it is consideration for that use and is taxed with it.

Default interest​

Off by default. With billing.dunning_interest.after_days set, a cycle paid late owes interest on what it collected, for each day from the day after that many days have passed since it fell due until the day its payment is recorded, both counted. A cycle falls due when it is first charged, and a direct debit is recorded when it settles. Each day earns at the base rate that held on it plus the surcharge for the owner's kind, and a day is a 365th of its year, or a 366th in a leap year. The sum is rounded to a cent once, half up.

'dunning_interest' => [
'after_days' => 30,
'surcharge' => ['business' => 9, 'consumer' => 5],
'base_rates' => [
'2025-07-01' => 1.27,
'2026-01-01' => 1.27,
],
],

That is § 288 BGB: from the 31st day, 9 points above the base rate between businesses and 5 points for a consumer. The base rate of § 247 BGB moves on 1 January and 1 July, and the application adds a line for each new rate. A day before the first date earns nothing, and the log names it. An application that takes the rate from elsewhere binds Pushery\Billing\Contracts\BaseInterestRates. Whether an owner buys as a business is what IdentifiesBusinessBuyers answers.

On a driver whose cycles the package bills itself, Mollie, the interest is opened as an order of its own once the cycle is paid and charged right after it, as a late fee is. It is compensation for the delay like a late fee, so its document states no tax. Stripe collects its own invoices, and no interest is charged there.

A fallback before the ladder​

An owner can keep a second payment method as the fallback: a card beside a SEPA mandate, or two cards. When the default cannot pay a cycle, because the provider refuses the charge, a direct debit bounces days later, or the default cannot be charged off-session at all, the package charges the fallback once, before any dunning:

  • Nothing is dunned while the fallback is due: no PaymentFailed, no past due, no notice. The next billing:run charges the fallback.
  • The fallback is charged under an idempotency key of its own, because the provider still remembers the key the default was refused under.
  • A fallback drawn by SEPA direct debit is announced like any other debit and drawn on the day its notice allows.
  • When the fallback pays, the cycle is paid, FallbackPaymentMethodCharged is dispatched and the owner receives FallbackPaymentMethodChargedNotification: the default still comes first for the next cycle, and it just failed.
  • When the fallback cannot pay either, the cycle goes to dunning as it would have without one, and the ladder's retries charge the default again. A cycle tries its fallback once.

The owner chooses the fallback on the account hub's payment-methods screen. An application with screens of its own uses KeepsAFallbackMethod, which refuses the default as its own fallback and a method that belongs to somebody else:

use Pushery\Billing\Contracts\KeepsAFallbackMethod;

if (app()->bound(KeepsAFallbackMethod::class)) {
app(KeepsAFallbackMethod::class)->setFallback($user, $methodId);
}

Only a driver whose cycles the package bills itself can keep this promise, so only the Mollie driver binds the contract. Stripe retries a failed invoice on its own schedule, and there the package changes nothing.

A returned direct debit that ends the mandate​

A direct debit the bank returns says why, and some reasons end the mandate: no valid mandate (MD01), missing mandate information (MD02), the payer asked for the money back (MD06), the payer died (MD07), the account is wrong, closed or blocked (AC01, AC04, AC06), the account takes no direct debit (AG01), the payer refused the debit (MS02), or the payer's bank blocks you as a creditor (SL01). On the Mollie driver such a return, as a failed payment or as a chargeback, takes the mandate out of use: it is no longer charged, no longer the default and no longer the fallback, so the dunning that follows draws on no mandate, and the customer is told once that the payment method was removed and asked for another. A return for too little money on the account (AM04) leaves the mandate as it is, and the dunning tries it again.

PaymentFailed::$reason carries the bank's code for a listener of your own, and null where the provider names none.

A payment taken back​

On the Mollie driver, a payment the payer takes back opens again what it paid for. A chargeback of a cycle whose period is still running fails that cycle, as a returned direct debit does, and the ladder collects it again. Where the period is over, or only part of the payment came back, the amount taken back is collected as a charge of its own on the default mandate, announced first where the mandate is a direct debit, and the subscription is past due until that charge is paid. Paying it raises no new invoice, because the invoice of the period still documents the claim. A chargeback of a payment that paid for no cycle, such as an add-on bought on its own, leaves the subscription as it is. ChargebackReceived is dispatched as before, for a listener of your own.

A direct debit whose webhook never arrives​

A direct debit is accepted at once and settles days later, so the cycle it collects waits in processing for the webhook that says whether the money came. Where that webhook never arrives, because your endpoint was unreachable for longer than Mollie retries, billing:cycles:reconcile reads the payment back once the cycle has waited three hours, and every hour after that, at the half hour. It records where the payment stands as the webhook would: a paid payment settles the cycle, a failed one fails it and starts the ladder, and one still open stays open. Nothing is charged again, because the payment exists already and only its standing is read. The run is planned where the package bills the cycles itself, today the Mollie driver; --hours sets the wait.

The hard case — a failed card​

For the harder case — payment has actually failed (a past_due/incomplete subscription) — put billing.dunning on the surfaces that need a working card. A browser request is redirected to the payment-recovery screen (so the customer lands on "update your card", not a dead error); an API/JSON request gets 402 Payment Required (configurable via billing.dunning_status). The recovery screen itself is never blocked, so there is no redirect loop. Like the suspension gate, the decision reads only the local subscription row — no provider call on the hot path.

The card the customer adds there becomes the default for their account and for every subscription that names a card of its own, so the provider's next attempt charges it. That attempt comes on the provider's retry schedule, not the moment the card is added; until it succeeds the subscription stays past due.

The mail that announces the failure says what it means for the customer. Where the failure leaves a subscription past due or incomplete, it tells them that their access is paused until a payment goes through and comes back as soon as one does, and asks them to update their payment details to get it back. A failed payment that paused nothing, such as a one-off charge beside a subscription in good standing, keeps the plain wording. The mail asks the same guard as billing.dunning, when it is built.

The mail of a failed payment as the customer gets it: from Linen & Co, billing@shop.example, with the subject "Your payment could not be processed". It names the amount, €19.00, and the invoice, 2026-1085, each with its label, asks the customer to update the payment details to keep the subscription active, and its button opens the recovery screen of the account hub.

On Stripe the customer does not have to wait for it. Once a method is on file, the recovery screen offers to pay the open invoice at once, and so can a screen of yours through PaysOutstandingInvoices:

use Pushery\Billing\Contracts\PaysOutstandingInvoices;
use Pushery\Billing\Enums\OutstandingPaymentOutcome;

if (app()->bound(PaysOutstandingInvoices::class)) {
$payment = app(PaysOutstandingInvoices::class)->payOutstanding($request->user());

if ($payment->outcome === OutstandingPaymentOutcome::NeedsConfirmation && $payment->confirmationUrl !== null) {
return redirect()->away($payment->confirmationUrl); // Stripe's invoice page, for 3-D Secure
}

$payment->outcome; // Paid, Pending, Declined or NothingOwed
$payment->failureCode; // on a decline, the bank's decline code, else Stripe's
$payment->failureMessage; // and Stripe's words for it
}

It pays the latest invoice of the subscription while it is open, on-session and with the method the subscription charges, which is the card just added. A declined card and a payment the bank wants confirmed come back as outcomes, and Pending is a payment Stripe accepted that has not settled yet. The subscription is active again once Stripe reports the payment, which the recovery screen picks up while it polls. A merchant's subscription or a contract of another type is paid by passing its MerchantScope and type, as the other subscription actions take them. Paying asks CanTransactMoney first and throws EligibilityDenied for an owner who may not move money. The Mollie and Shopify drivers leave it unbound: Mollie's subscriptions are billed by the package's own engine, and Shopify collects its charges itself.

Route::middleware(['auth', 'billing.dunning'])->group(/* … the surfaces that need a paid, current card … */);

A pause is never treated as delinquency: it does not start the delinquency clock or walk the owner up the ladder.

Using the ladder when your arrears live somewhere else​

The ladder is the richest part of this: several rungs instead of one deadline, and a different rung per surface. All of that is configuration — the rungs, the policy and the cure window read no table at all — and the one class that combines them reads a single fact: since when is this owner behind with this merchant.

That fact comes through ArrearsClock, so an application that keeps its own view of who owes what binds its own implementation and gets the ladder unchanged:

use Pushery\Billing\Contracts\ArrearsClock;

$this->app->bind(ArrearsClock::class, YourOwnArrearsClock::class);
final readonly class YourOwnArrearsClock implements ArrearsClock
{
public function delinquentSince(Model $owner, ?MerchantScope $merchant = null): ?DateTimeInterface
{
return /* … your own reading, never a provider call … */;
}
}

Three things worth knowing before you write one:

  • The clock, not the rung. Which rung an owner stands on is derived from the clock and your configured schedule. Returning a stored level instead would be a second answer to a question that already has one, and the two would part company the first time the schedule changed.
  • Per relationship, never across. The merchant is part of the question, so an owner behind with one merchant keeps the surfaces of every other. Answering from an aggregate over all of them is the mistake the seam is shaped to prevent.
  • Never a provider call. The ladder runs on every gated request; a lockout that needed the payment provider to be reachable would open the gates during an outage.

Pushery\Billing\Testing\ArrayArrearsClock is an in-memory implementation for your own suite, so you can exercise the rungs without standing up a billing database. It fakes the storage and nothing else — the rung still comes from your schedule and the withdrawal still comes from your policy.

With nothing bound, the package's own reading applies and an install that uses the shipped schema behaves exactly as before.


← Back to the documentation index