carmanagement/MANUAL_SUBSCRIPTION_PAYMENTS.md

Manual subscription payments

This project implements bank-transfer and check collection as first-class subscription billing paths. Evidence submission is explicitly not settlement: only a fresh-2FA finance confirmation of cleared funds creates a successful offline payment attempt, pays the canonical billing invoice, and activates or renews the subscription.

Safe rollout

1. Apply the 20260809190000_manual_subscription_payments migration and deploy with all new flags disabled.
2. Configure a private persistent, encrypted-at-rest FILE_STORAGE_ROOT; set both private-storage confirmation flags only after verifying the mounted storage; configure a fail-closed scanner executable, bank/check payer instructions, billing contacts, valid IANA timezones, and finance collections owners.
3. Enable MANUAL_PAYMENT_EVIDENCE_UPLOAD_ENABLED, then MANUAL_SUBSCRIPTION_PAYMENTS_ENABLED and the desired manual method flags.
4. Enable SUBSCRIPTION_COLLECTIONS_NOTIFICATIONS_ENABLED; verify the AR/EN/FR snapshots, outbox delivery, 48-hour call task, and escalation queue.
5. Enable SUBSCRIPTION_AUTOMATIC_SUSPENSION_ENABLED only after observing a full reminder/grace cycle. Suspension starts after 30 calendar grace days and rechecks payment, overrides, and configuration atomically.

Manual methods remain hidden unless their instructions and evidence-scanning pipeline are ready. The non-production PAYMENT_EVIDENCE_SCANNER_MODE=stub-clean option exists only for local tests; production requires PAYMENT_EVIDENCE_SCANNER_PATH.

Operational invariants

• Subscription billing has one canonical BillingInvoice; legacy SubscriptionInvoice rows are compatibility links only.
• A scheduled renewal is reused by Stripe checkout rather than duplicated.
• Manual confirmation requires the full current MAD balance, matching collection method, clean same-invoice evidence, a unique normalized external reference, a unique idempotency key, a clearance timestamp, and a funds-verified attestation.
• Initial purchases activate from confirmation time. Renewals extend from the original expiration, including late confirmations after suspension.
• Evidence is stored privately with no public URL, quarantined before scanning, served only through authorized routes, and immutable after submission.
• Collections reminders are recipient-specific and localized using contact preference, linked employee preference, then company default. Only Arabic, English, and French can be enabled.
• Payment resolution cancels open call tasks and suppresses queued collections reminders.