Recurring billing is not just “charge the card again next month.” A real billing system has customers, reusable payment methods, subscriptions, invoice periods, retry schedules, dunning outcomes, and dashboard operations.
MasonXPay treats billing as its own product domain while still using the normal payment core for money movement.
Merchant-Owned Billing
MasonXPay owns:
- customer records
- customer payment-method references
- subscriptions and subscription items
- checkout links
- invoice generation
- invoice payment attempts
- retry and dunning state
- merchant dashboard operations
Provider billing products can be useful, but MasonXPay does not make one provider’s subscription model the core source of truth. That keeps the platform portable across providers.
Safe Payment Method References
MasonXPay does not store raw card data. Subscription checkout creates or reuses a provider customer where supported, then stores a safe reusable payment reference through PaymentInstrument.
Examples include:
- Stripe customer and payment method references
- Square customer and card-on-file references
- Braintree vaulted payment method tokens
- Mason Simulator reusable references for local testing
These are opaque references. They are not PAN or CVV.
Invoice Execution
Invoices are charged off-session by InvoicePaymentService. The payment call happens outside the database transaction, and the result is recorded afterward through normal state changes.
This keeps the payment-core discipline intact:
- deterministic provider idempotency keys
- no remote calls inside DB transactions
- idempotent checks for already-paid invoices
- clear invoice status transitions
Retry and Dunning
The InvoiceBillingWorker scans open invoices and attempts payment when they are due. Soft failures can reschedule with bounded delays. Hard declines or exhausted attempts can move the invoice to a terminal dunning outcome.
This is separate from customer-present checkout retry and separate from refund retry. Billing retry applies to invoices generated by active subscription schedules.
Dashboard Operations
The dashboard exposes the operational surfaces merchants expect:
- customer list and edit
- payment method display
- subscriptions and cancellation
- checkout links
- invoice list and details
- manual pay, write-off, and payment-link actions
The result is a billing workflow that lives near payments, routing, and provider operations instead of becoming a disconnected product.
Remaining Product Hardening
The core workflow is in place. The next billing improvements are focused hardening:
- merchant-configurable dunning policy
- customer notification hooks
- Mollie mandate completion
- promotions and coupons
- more failure-mode tests around worker restarts and provider timeouts