Finance

# Finance 1.2.13 QA

- Added Square as a first-class provider beneath the existing FinanceService contract.
- Added Square Sandbox/Production configuration using Core SecretVault for access token and webhook signature key.
- Added embedded Square Web Payments SDK card tokenization; raw card data never enters DivisionDesk.
- Added Square Payments API creation/verification, refunds, webhook signature validation, event deduplication and payment status mapping.
- Preserved existing Stripe, PayPal, ledger, source-module identity, completion events, durable integration delivery, refund and convenience-fee contracts.
- No database migration required.

## 1.2.12
- Hardened Finance integration return URL detection and fallbacks.
- Accepts `/root/relative.php`, full same-site `https://host/...`, and `page.php` / `subdir/page.php` relative to the current request folder.
- Normalizes `.` / `..` path segments before storage.
- Rejects protocol-relative URLs, external hosts, CR/LF injection, and unsupported schemes.
- Preserves the already-working Events checkout, existing local-path integrations, Storefront/Membership behavior, and configurable accounting mappings.

## 1.2.11
- FIX: Events online checkout no longer fails when Core supplies its confirmation return URL as an absolute same-site URL.
- Finance now accepts either a local `/path` or an `http(s)` URL on the current DivisionDesk host and normalizes the latter back to a local path.
- Off-site return URLs, protocol-relative URLs, CR/LF injection, and unsupported schemes remain rejected.
- This fixes both the initial `Register & Pay Online` redirect and `Pay Balance Now` on existing pending-payment Event confirmations.
- Retains the configurable Finance accounting mappings introduced in 1.2.10.
- No Core update is required.

## 1.2.10
- Added Finance-owned configurable accounting mappings under Accounts & Funds.
- End organizations can choose the destination Fund and Income Account for National, Division, and Camp dues; National, Division, and Camp late fees; Membership donations; Events registrations/add-ons; Storefront sales defaults; and convenience/processing-fee recovery.
- Existing default accounts are preconfigured automatically, so upgrades remain operational without manual setup.
- Membership checkout now uses the existing Rosters per-level metadata to split National / Division / Camp dues and late fees into their selected mappings without a Rosters update.
- Events checkout no longer hard-codes account 4001; it resolves the organization's Events mapping.
- Generic module checkout resolves a Finance mapping when the caller does not supply explicit fund/account IDs, while preserving explicit user/module selections such as current Storefront settings.
- Refunds continue to reverse the original ledger allocation automatically.
- No Core or other module update is required for this mapping layer.

## 1.2.9
- Publishes the Events checkout contract on a fresh version number.
- `FinanceService::eventRegistrationCheckoutUrl()` creates/reuses on-site Finance checkout for `events / registration / <registration id>`.
- Uses `4001 — Event Registration Revenue` for event registrations and add-ons.
- Preserves Finance 1.2.7 Membership Manager, Storefront, provider, refund, ledger and convenience-fee behavior.

## 1.2.8
- Adds `FinanceService::eventRegistrationCheckoutUrl()` as the stable Events payment handoff.
- Adds `4001 — Event Registration Revenue` as the canonical income account for event registrations and add-ons.
- Event checkouts use stable `events / registration / <registration id>` source identity, so retries reuse the same open/paid Finance request instead of creating duplicate charges.
- Retains the v1.2.7 Membership late-fee/donation allocations and all existing Storefront/refund/provider behavior.

## 1.2.7
- Adds `FinanceService::donationFundOptions()` for designated-donation integrations.
- Membership Manager donations now post to the specific active Finance fund selected for each donation option while using the Designated Donations income account.
- Fixes the historical account-code collision: `0003` remains General Donations and `0005 — Late Fees` is the dedicated late-fee account.
- Retains Storefront checkout/refund contracts, processing-fee handling, duplicate-code friendly errors, statements and existing payment-provider behavior.

# Finance v1.2.6

- Added `FinanceService::refundSourcePayment()` for module-owned refunds through Finance/provider/ledger authority.
- Added `FinanceService::paymentFeePreview()` and shared `PaymentService::processingFeeQuote()` so Storefront can disclose the exact convenience fee before payment without duplicating provider policy.
- Full remaining source refunds include the remaining payer convenience fee.

# Finance 1.2.5

- Added `FinanceService::accountingOptions()` as the stable module-to-module API for active funds and income accounts.
- Account/Fund creation now reports duplicate codes clearly instead of exposing raw SQL constraint errors.
- No Finance checkout validation was weakened; integrating modules must still provide an explicit active fund and income account.

## 1.2.4
- Replaces the misleading generic `checkoutUrl()` membership alias with a true module-neutral checkout contract.
- Requires stable source identity and reuses matching open/paid requests without duplicating orders.
- Rejects reuse when a caller changes the amount under the same source identity.
- Applies Finance-owned processor-fee policy to generic module checkouts.
- Adds validated local post-payment return actions for Storefront and other modules.
- Fixes payment finalization so saved split ledger allocations are posted intact.

## 1.2.3
- Adds configurable processor-fee pass-through using a gross-up calculation so the configured merchant fee can be recovered without reducing the intended dues/donation subtotal.
- Processing fees are provider-specific and calculated after the payer chooses the payment method.
- Adds separate Processing Fee Recovery and Late Fees income accounting.
- Preserves Membership Dues, Late Fees, Designated Donations, and Processing Fee Recovery as separate ledger allocations.
- Adds durable retry delivery for cross-module `finance.payment.completed` events so a successful processor capture is not dependent on the member visiting a reconciliation page.
- Checkout displays the payment subtotal and convenience fee separately and receipts retain the final paid amount.

# 1.2.2

- Completes the Finance-to-Membership Manager payment lifecycle through the Core Integration SDK, adds source-payment reconciliation, membership success actions/receipt links, and clarifies PayPal card checkout UX.

# Changelog

## 1.1.0
- Added Statements & Billing with saved/versioned templates.
- Added prebuilt MRS (Member Renewal Statement).
- Added safe DivisionDesk statement pseudocode with nested conditions, charge/note/total/payment directives.
- Added contextual per-camp dues lookup; unknown is distinct from zero.
- Added single/selected/all-active/camp bulk billing runs with immutable recipient snapshots.
- Added queued bulk email through Communications when available, Core Mailer fallback otherwise.
- Added secure payment link, raw payment URL and QR-code template directives.
- Added multi-allocation payment requests so one combined renewal payment can post to multiple ledger accounts/funds.
- Added edit/delete-or-archive management for funds and ledger accounts.

# DivisionDesk Finance Changelog

## 1.0.0

### Added
- Fund/account ledger with integer-cent monetary storage.
- Separate organizational funds and income/expense ledger accounts.
- Split transactions with server-side balancing validation.
- Manual income, cash/check/Zelle/other payments, and outgoing expenses.
- Secure payment requests with opaque public tokens and expiry support.
- Shared module-facing Finance service for dues, events, applications and future modules.
- Stripe PaymentIntent integration using embedded Stripe Elements.
- PayPal Orders integration using embedded CardFields / PayPal JavaScript SDK.
- Verified Stripe and PayPal webhook handling with idempotent event storage.
- Provider secrets stored through DivisionDesk SecretVault.
- Transaction search/filtering, dashboard summaries, CSV export and audit trail.
- AJAX/fetch-first administration UI with visible loading/error states.

### Security
- Raw card numbers, CVV and sensitive authentication values are never accepted by DivisionDesk PHP endpoints.
- CSRF validation on administrative writes.
- Capability checks on every administration endpoint, independent of UI visibility.
- Idempotency keys on payment creation and webhook event deduplication.

## 1.2.0
- Replaces raw-code-first statement editing with a rich text/email-style editor.
- Adds font formatting, color, size, Insert Block, Insert Field, conditional insertion, Help, Preview, and Send Test.
- Adds safe HTML sanitization and token parsing inside formatted statement HTML.
- Adds automatic syntax/semantic validation while editing.
- Test Send uses a real roster member automatically when the email matches exactly one member, requests a choice for shared addresses, and uses sample data when no member matches.
- Test statements cannot create payments, receivables, statements, or ledger entries; payment links and QR codes resolve to a nonpayable test page.
- Adds camp name/number and camp adjutant contact/address statement variables.
- Preserves generate-review-Bulk Send separation and immutable statement snapshots.

## 1.2.1
- Added `FinanceService::paymentsConfigured()` so other modules can determine whether an enabled processor has usable credentials without reading Finance settings or secrets.
- Added `FinanceService::paymentProviderStatus()` with secret-free provider readiness information.
- Added `FinanceService::membershipDuesCheckoutUrl()` and `checkoutUrl()` as stable checkout handoff APIs for Membership Manager.
- Membership checkout handoffs are idempotent by roster request key and reuse an existing open/paid Finance request instead of duplicating requests.
- Combined dues/donation checkouts split ledger allocations between Membership Dues and Designated Donations while Finance remains authoritative for provider/payment state.