Billing reconciliation

Billing Verification & Reconciliation

Because external payment gateways, invoicing APIs and the application database do not share a distributed transaction, webhooks will occasionally be delayed, dropped or fail mid-processing. A production-grade billing system detects drift automatically and provides safe, idempotent reconciliation.

1. Sources of Cross-System Drift

Always design for partial failures across the four boundaries:

• Payment succeeded at PSP, webhook delayed or missed: customer was charged, but local Subscription/Entitlement is still pending.
• Payment succeeded and entitlement granted, but invoicing API failed: customer has access, but the legal invoice (Billingo / Számlázz.hu) was never issued or timed out.
• Refund or dispute occurred in PSP dashboard: money was returned, but local entitlements or credit balances were not adjusted.
• Ambiguous outbound timeout: server requested a charge or refund, timed out waiting for HTTP response, and local state is unknown.

2. Active Reconciliation & Self-Healing Mechanisms

1. On-Demand Return-Path / Status Polling:
   • When a user returns from checkout before the webhook arrives, show "Confirming your payment..." and query the PSP's authoritative status endpoint (PaymentIntent / CheckoutSession / Barion GetPaymentState / SimplePay query) by ID, triggering the same idempotent fulfillment handler used by webhooks.
2. Scheduled Reconciliation Job:
   • Periodically scan local records stuck in transitional states (pending, processing, invoice_pending) older than a threshold (5–15 minutes) and query the provider API to resolve their terminal state.
   • Pull recent provider events/transactions over a rolling lookback window and compare against local processed_webhook_events and payments tables to catch missed webhooks.
3. Decoupled Invoice Retry Queue:
   • Track invoicing state (invoice_status: 'not_needed' | 'pending' | 'issued' | 'failed') separately from payment state.
   • If the invoicing provider returns 5xx or times out after a successful payment, retry invoice issuance with a deterministic external_id / order reference so the customer is never charged again and duplicate invoices are never created.

3. Mandatory Verification Matrix

Before marking any billing change complete, test these scenarios explicitly:

• Happy path + Return URL before webhook: user lands on success page before webhook fires; verify no race condition or duplicate fulfillment when webhook arrives 1 second later.
• Duplicate & out-of-order webhooks: replay the same webhook payload twice concurrently and in reverse order (updated before created); verify single charge, single invoice and single credit grant.
• Interrupted & abandoned checkout: user closes browser at 3DS challenge or declines payment; verify no entitlement is granted and user can retry cleanly.
• Failed renewal & dunning: simulate card decline on renewal (invoice.payment_failed); verify transition to past_due, grace-period access and recovery upon payment method update.
• Proration & plan switch: verify exact minor-unit math, period dates and quota adjustment on upgrade and scheduled end-of-period downgrade.
• Partial & full refunds: verify ledger entries, credit note / storno invoice creation and whether entitlements remain or revoke per business rule.