Payments

1In one sentence#

The Payments module is the money-collection engine behind LumosCRM — a provider-agnostic system that takes card payments on invoices (today via Stripe), treats the provider's webhook as the single source of truth, records every payment and refund as an internal, auditable transaction, and keeps the rest of the CRM cleanly decoupled from any one payment provider.

It's mostly invisible to everyday users — they experience it as the "Pay online" button on an invoice — but it's the part that makes sure money actually moves, is reconciled correctly, and is never double-counted.

2Who it's for#

3The core idea: provider-agnostic, webhook-confirmed#

LumosCRM keeps its own internal record of every payment, independent of the provider:

   Client clicks "Pay" ──▶  Provider (Stripe) hosted checkout
                                      │
                       (card processed by provider)
                                      │
                        Provider WEBHOOK  ◀── the source of truth
                                      │
                 ┌────────────────────┴───────────────────┐
                 │  Payment record updated → status: paid   │
                 │  PaymentEvent logged (provider callback)  │
                 │  Invoice notified (event-driven) → paid   │
                 └──────────────────────────────────────────┘

The browser redirect after checkout is treated as a hint only — a payment is marked paid when the signed webhook confirms it, not when the customer's browser comes back. This prevents the classic failure modes (closed tab, flaky network) from ever marking an invoice paid prematurely or missing a real payment.

4Capabilities at a glance#

5How a payment is modeled#

Each payment is an internal record with:

• What it's for — a polymorphic link to the payable (an invoice).
• Type — currently one-off (recurring/subscription is a designed seam, see below).
• Status — pending · processing · paid · partially refunded · refunded · failed · cancelled · expired.
• Amounts — captured and refunded amounts in minor units (cents), plus currency, so figures are always exact.
• Provider pointers — the provider name and its reference, treated as pointers only, never the source of truth.
• Idempotency key — to guarantee a single payment is recorded once, even if a callback arrives twice.

Around it sit refunds (each refund tracked against its payment) and payment events (a log of every provider callback).

6The client payment experience#

From an invoice's public link (see the Invoice module), the client clicks Pay, is taken to the provider's secure hosted checkout, and pays by card. They never need a login, and no card data touches LumosCRM. On return they see a success or cancelled notice — but the invoice only flips to paid once the webhook confirms the money has settled.

Staff can also record payments manually (e.g. a bank transfer) and issue refunds from the invoice itself; both update the same internal ledger.

7Security & reliability#

• Signed, verified webhooks: the webhook endpoint is unauthenticated by necessity (the provider calls it) but CSRF-exempt and signature-verified inside the controller, keyed by provider so adding providers is additive.
• Idempotency at two layers: duplicate callbacks and double submissions can't create duplicate payments.
• Truth lives with settlement: internal status follows the webhook, not the browser.
• Decoupled by events: the Invoice module reacts to payment events rather than calling the provider directly, so billing and payments stay independent.

8Use cases & scenarios#

Use case A — Getting paid online#

A client opens their invoice link, pays €12,000 by card, and closes the tab before the redirect. The webhook still arrives, the payment is recorded, and the invoice flips to paid — nothing is lost.

Use case B — A partial refund#

A client is refunded €2,000 of a €12,000 payment. Finance issues the refund; the payment moves to partially refunded, the refunded amount is tracked, and the remaining balance is clear.

Use case C — No double-charging#

A provider sends the same webhook twice (it happens). The idempotency safeguard recognises it and records the payment only once.

9Platform foundations (built into the data model)#

• Recurring / subscription billing is a deliberate seam — the payment type enum and design leave room for it, ready to activate when (e.g.) Stripe Billing is introduced. It is not live today.
• Additional providers can be added without changing how the rest of the CRM works, thanks to the gateway abstraction and provider-keyed webhook endpoint.

For marketing: describe Payments as "secure online card payments on invoices, with reliable reconciliation." Avoid promising recurring billing or specific non-Stripe providers until they're enabled.

10Glossary#

This document describes the Payments module as currently built: provider-agnostic online card payments on invoices via Stripe, webhook-confirmed. Recurring billing and non-Stripe providers are design seams, not live features.