Payments and dunning

Collect through an accepted payment mandate

A payment method stores the provider’s protected token and the customer’s accepted mandate. Use hosted collection to avoid storing raw card data in the app. The customer account, provider account and invoice currency must agree before the system prepares an instruction.

The requested amount cannot exceed the current collectible balance available after other pending instructions. A revoked or expired mandate prevents new automatic collection. Replacing a token changes a future authorised instruction; it does not rewrite the provider reference or result of an earlier attempt.

Distinguish attempts from settled money

Prepared, pending, authorised, settled, failed and unknown outcomes have different meanings. An authorisation or accepted API request does not increase the invoice’s collected amount. Apply only a verified settled result, net of confirmed linked refunds, to the payment balance. Preserve disputes and partial settlements as their actual observed states.

A request that times out keeps its original idempotency key and invoice reservation. Reconcile that instruction before deciding whether a retry is safe. A new key must not create another charge merely because the first response was unavailable. Duplicate and out-of-order provider events are checked against their identity and allowed lifecycle.

Use follow-up that matches the current balance

The dunning case records its invoice, owner, next action and stage. A reminder, a payment retry and an internal task are separate activities with their own outcome. Immediately before a notice or retry, recheck the amount due, mandate, customer contact and existing unresolved payment instructions.

A paid or void invoice should skip an old reminder that was queued earlier. A delivery failure stays visible for investigation. Sending a reminder does not mean the customer saw it, and moving a case to a later stage does not record a payment. Keep the communication history tied to the actual invoice.

Pause and escalate deliberately

Support can inspect the permitted customer history and pass an issue to the billing owner. Billing staff may pause follow-up while a dispute or correction is investigated. The pause keeps the unpaid amount visible and records why communication stopped.

Subscription service changes follow their accepted terms and explicit lifecycle. A dunning stage alone cannot silently cancel a contract or deny service. A payment failure can lead to an authorised suspension decision if the configured policy requires it, while an unknown provider outcome must first be reconciled. The collection process retains the distinction for both operators and customers.

Reconcile credits, refunds and fees

Credits reduce billed consideration; refunds return previously collected money; processor fees explain the difference between gross receipts and net settlement deposits. Preserve each source and avoid reducing the customer’s invoice receipt by a merchant processing fee. The accounting connection receives the reconciled identities and amounts. A report should distinguish collectible invoices, unresolved payment attempts and actual settled cash so the team can act on the correct exception.