# BoomPay secured repair financing: shared specification and project contracts

## Summary

Create one authoritative, versioned business specification in `boompay-ca`, with linked implementation contracts in Garage, Boost, Partners, Collateral, Argus, and Sign. Each project must identify which requirements are implemented, tested, deployed, or still missing.

The workflow is: **garage estimate → customer invitation → identity and vehicle evidence → paid eligibility check → exact approval and signing → completed final invoice → receivable purchase → repayment → security release**.

This work defines the specifications and conformance checklist. It does not enable lending, charge customers, change existing agreements, or claim that source code proves production readiness.

## Business rules

### R1. Garage onboarding and estimate approval

- Permit provisional garages to upload estimates and invite customers. Require completed business, signing-authority, payout, and onboarding checks before purchase.
- Start the **30-day completion window** when the customer first approves the exact estimate and security terms. Revised estimates must not restart that clock.
- Partners shows incomplete garages immediately, including invitations without customer approval, approved work awaiting onboarding, age, blockers, and follow-up history. Describe amounts as potential business, not guaranteed money owed.
- Store original estimates privately with document hashes, revisions, itemized work, taxes, totals, and uploader history.
- Dynamic QR codes carry expiring, opaque, single-use invitation tokens. Scanning does not authorize work, borrowing, a debit, or lien registration.
- Customers can decline or approve the exact displayed revision. New or substituted work requires fresh approval; previous decisions remain retained.

### R2. Customer evidence and paid checks

- Preserve Boost’s email-and-SMS verification. Add Stripe Identity as the launch identity-verification provider; verification does not itself approve credit, ownership, insurance, or security.
- Require ownership/registration evidence, valid matching insurance, requested vehicle photographs, mileage, and an explicit customer declaration of known vehicle damage. Require confirmation when no damage is reported.
- Argus proposes extracted document and vehicle facts. Customers confirm them; Collateral supplies monetary valuation and registry evidence.
- Collect **one $50 fee before performing the check**. No financed-fee option in this launch workflow.
- Explain before payment that a completed check does not guarantee financing and the fee remains earned if the loan is declined. Retain payment, disclosure, check-result, and consent evidence.
- Refund duplicate charges and checks not delivered. Reusing the same completed check must not silently create another charge; any new paid check requires explicit consent.
- Existing or uncertain liens require Partners review of current balances, priority, and BoomPay’s permitted security position. Missing evidence blocks approval.

### R3. Lending limit and purchase

Use integer cents and retain every input and policy version:

```text
V = accepted vehicle security value after condition/damage adjustments
L = verified existing secured claims
H = other active BoomPay exposure or reservations, without double counting
R = $1,500 recovery reserve
Q = approved repair estimate, including its disclosed taxes
M = Q + floor(Q × 10%)

Available financing room = V − L − H − R

Approve only when available financing room ≥ M
```

- Insufficient room means **decline** for launch. Do not introduce split funding, customer contributions, or automatic smaller offers.
- Reserve capacity for the full approved allowance. The final certified repair invoice may range from **$0 to M**, limited to the approved work.
- A $0 invoice closes without a receivable purchase or repair debt. The separately earned check fee remains distinct.
- Purchase only the positive, completed final invoice. Actual purchased principal equals that invoice, never the estimate ceiling or reserve.
- Purchase requires current customer approval, retained signed agreements, completed garage onboarding, accepted vehicle/security evidence, required registration confirmation, and valid banking authorization.
- Signing consent, registry submission, confirmed registration, purchase, and garage payout are separate states with separate evidence.
- The reserve is neither principal nor an automatic fee. The specification must distinguish collateral capacity from the legal registration amount and treatment of interest and recoverable costs.

### R4. Repayment and the 33-day decision

- Anchor debt dates to the actual receivable purchase, using `America/Toronto`. Preserve the original day of month and clamp anniversaries to month-end without cumulative drift.
- Customers have through day 33 to repay in full interest-free or actively accept the disclosed monthly arrangement. No automatic conversion.
- A full Stripe payoff initiated by the deadline enters **payment pending**, holding conversion and duplicate collection. Only verified settlement pays the debt. Failure goes to review without automatic retroactive interest or a replacement debit.
- Monthly financing starts interest on day 34 and finishes by the twelfth purchase anniversary.
- Use equal principal portions over the remaining monthly anniversaries. For example, conversion on day 33 normally leaves **11 installments**, starting at month two.
- Add simple interval interest calculated on the **original purchased principal**, using the signed annual flat rate and actual elapsed days divided by 365. Do not capitalize unpaid interest or compound it.
- Explain that this differs from declining-balance pricing. Display principal, rate, applicable APR/cost of borrowing, each payment, total interest, and total repayment before acceptance.
- Use deterministic cent rounding and adjust the final principal installment to clear rounding residue.
- Early payoff stops future interest accrual. Missed payments, returns, disputes, and reversals retain history and trigger review; they must not invent fees, extend maturity, or create duplicate debits.
- No active monthly product until its reviewed rate and disclosure version are configured. Do not adopt the existing illustrative 27% rate by default.

## R5. Project contracts and installation

- **Shared specification:** publish stable requirement IDs, terminology, state transitions, calculation examples, evidence requirements, and precedence over conflicting new-business documentation. Maintain a conflict register for the existing $1,000 reserve, financed fee, and 33-day-only implementation.
- **Garage:** own provisional onboarding, original estimates, immutable revisions, invitations, final-invoice certification, and garage status.
- **Boost:** own customer identity, damage declarations, insurance/ownership confirmation, fee consent/payment, exact financing acceptance, loan schedules, customer balances, and agreement history.
- **Collateral and registry integration:** own valuation provenance, registry evidence, freshness, capacity reservations, and confirmed registration/release evidence. No automatic existing-lien approval.
- **Partners:** own manual secured-credit review, garage follow-up queues, exception decisions, purchase/payout oversight, and reconciliation. Review decisions cannot fabricate provider or registry evidence.
- **Sign:** own signed document evidence binding the exact customer, garage, vehicle, estimate revision, purchase limits, reserve treatment, rate, repayment rules, and document versions.
- **Stripe:** launch with hosted identity and banking flows. Canadian bank repayments use **PAD/ACSS**, with verified accounts and appropriate debit mandates. Store provider references rather than raw bank credentials. Keep identity verification separate from bank authorization.
- Define a provider-independent settlement interface for later internal banking support; implement no internal debit rail in this release.
- Every cross-service transition binds immutable entity/revision IDs, evidence references, policy version, actor scope, and an idempotency key. Unknown write outcomes require status reconciliation before retry.
- Link the canonical specification from each project’s existing guidance. Add a conformance matrix with implementation evidence, meaningful tests, deployment evidence, and explicit gaps.

## R6. Verification and rollout

- Test provisional garage intake, customer rejection, expired/replayed QR codes, changed estimates, and overdue onboarding.
- Test missing/expired insurance, ownership mismatch, damage declarations, identity failures, and manually reviewed existing liens.
- Test fee settlement, declined loans after completed checks, duplicate payment, failed checks, and reuse without duplicate charging.
- Test exact lending boundaries, one-cent shortfalls, concurrent reservations, zero invoices, lower invoices, exactly 110%, excess invoices, and scope substitutions.
- Test day-33 cutoff, pending payoff settlement/failure, explicit monthly election, month-end/leap-year dates, flat-interest examples, rounding, early payoff, returns, and mandate cancellation.
- Run one persisted journey across the real application interfaces with designated test actors and supported provider test environments. Simulation-only success is insufficient.
- Install versioned specifications first, then implement projects in dependency order: evidence and policy → approvals and purchase gates → schedules and mandates → collection and release.
- Preserve historical contracts unchanged. Use reviewed migrations for new policy versions.
- Native hooks own Git delivery. Jenkins must verify the exact released revisions, explicit targets, and live acceptance; deployment and provider enablement remain distinct.

## R7. Assumptions and activation gates

- Initial scope is Canadian CAD vehicle-secured repair financing.
- The $50 fee, $1,500 reserve, 10% allowance, 30-day garage window, and repayment choices above are the agreed product policy.
- Ontario legal review must confirm the receivable-assignment/security structure, fee treatment, flat-interest disclosures, cost of borrowing, and registration/release requirements.
- Confirm Stripe supports the intended lending collections and Identity use on the actual account. A working integration or bank mandate alone does not establish that support.
- Missing legal, provider, valuation, registry, or settlement evidence keeps the affected financial transition disabled.

## Dispatch provenance and precedence

Dispatch ID: BP-MVP-20261017-v1. Recovered from the coordinator conversation’s 2026-10-17 accepted policy answers and complete financing specification. The original specification is attached separately, unchanged. Stable IDs R1–R7 label its sections. The coordinator distributes this agreement; receiving project agents own repository documentation, assessments, and implementation. The latest coordinator plan changes delivery ownership, not these financing rules.

No actual launch interest rate, valuation freshness policy, legal registration amount, or Stripe account approval is established by this handoff. Record evidence gaps explicitly. Preserve historical agreements, other existing work, and existing payout commitments unless a new authorized policy explicitly changes them. The $50 customer check fee is distinct from any Garage subscription and from BoomPay’s actual costs.