--- date: 2025-10-03T20:02:01+0200 researcher: Codex git_commit: ac94faedb0b491d710c36b04ac27b26890f4d062 branch: main repository: rentease topic: "Stripe payment ingestion & webhook strategy" tags: [research, payments, stripe] status: complete last_updated: 2025-10-05 last_updated_by: Codex --- # Research: Stripe payment ingestion & webhook strategy ## Research Question What changes are needed to fetch Stripe payment data for a given period and replace manual double-entry with webhook-driven updates? ## Summary Rentease captures payments through a manual UI that posts to `/payments/:id`, with records now persisted by a dedicated payment service in `internal/service/payment`. Reporting features still depend on these rows—especially for card totals—so Stripe imports share the same storage path. Stripe connectivity is also centralised in that payment service, while configuration continues to supply the API/ webhook secrets and `main.go` wires the Stripe client. ## Detailed Findings ### Manual Payment Entry Flow - Booking detail page exposes a modal that posts amount and method to the server (`internal/view/booking_by_id.templ:52`, `internal/view/booking_by_id.templ:130`). - `/payments/:id` handler binds the form payload, delegates to the payment service for creation, and re-renders the payment list (`internal/server/handle_payments.go`). - Booking page view model preloads payments to display them alongside line items (`internal/server/handle_bookings.go:130`, permalink: ). ### Payment Persistence & Reporting - `payment.Service.CreatePayment` wraps repository inserts without additional de-duplication (`internal/service/payment/service.go`). - `PgStore.CreatePayment` writes plain `amount` and `payment_method`; schema lacks external references for Stripe IDs (`internal/repository/booking/pg_store.go:150`, permalink: ). - Reports compute card totals by summing `payments` joined to bookings, so Stripe-imported transactions must populate this table to keep analytics accurate (`internal/repository/booking/pg_store.go:65`, `internal/service/booking/report.go:76`). ### Integration Hooks for Stripe API Fetch - Configuration currently has no Stripe credentials, so `internal/config/config.go` must gain `StripeSecretKey`, `StripeWebhookSecret`, etc., and `main.go` should wire a Stripe client (`internal/config/config.go:11`, `main.go:52`). - Extraction logic can mirror existing external service patterns (e.g., the OpenAI parser driver) by adding a `internal/driver/stripe` client and a `booking` service method to request Stripe payments and upsert records (`internal/service/booking/sync.go:7`). - The cron binary is designed to host scheduled jobs and can trigger periodic Stripe backfills once a job runner function exists (`pkg/cron/cron.go:9`, `cmd/cron/main.go:13`). ### Webhook Considerations - Routes under `private` require authentication, so Stripe webhooks need a new public endpoint (e.g., `/webhooks/stripe`) mounted before auth middleware in `internal/server/routes.go:8`. - Handlers should verify Stripe signatures, deserialize events, and, for `payment_intent.succeeded` or `charge.refunded`, call into a service layer that ensures idempotent upserts (likely by storing Stripe IDs in the `payments` table). - Payment view models already display method strings from config; mapping Stripe payment methods (card, bank redirect) to existing enums may require normalisation in the webhook handler before storing (`internal/view/item_list.templ:19`, `internal/config/host.go:41`). ### External Integration Patterns - The OpenAI booking parser demonstrates how the app encapsulates third-party clients behind drivers and service methods, including error handling and data persistence hooks (`internal/driver/parser/client.go:17`, `internal/service/booking/sync.go:7`). This pattern can guide the Stripe integration for consistency. ## Code References - `internal/server/handle_payments.go:16` – manual payment creation flow (perm: ) - `internal/service/payment/service.go` – service layer inserts payments and delegates to the repository. - `internal/repository/booking/pg_store.go:65` – card totals depend on stored payments (perm: ) - `internal/server/routes.go:8` – current route layout and auth groups (perm: ) - `cmd/cron/main.go:13` – cron entrypoint for scheduled jobs (perm: ) ## Architecture Insights Rentease now splits business logic across `booking.Service` and `payment.Service`, with storage handled through a repository abstraction and UI forms using htmx requests. External integrations live in `internal/driver` and are injected via `main.go`. Payment records are simple and lack idempotency safeguards, so any Stripe sync must extend the schema and service methods to avoid duplicates, enforce foreign keys, and reconcile amounts with existing booking items. ## Historical Context (from ./thoughts/) - No prior research documents found in `./thoughts` related to payments or Stripe. ## Related Research - None available. ## Open Questions - How will Stripe payments be matched to internal bookings (metadata, external IDs, or manual association)? - Should the `payments` table store Stripe identifiers and status fields to enable idempotent upserts and refunds? - What is the preferred flow for backfilling historical payments—ad hoc command, scheduled cron job, or admin-triggered API? - Which Stripe event types should the webhook handle beyond successful payments (refunds, disputes, payouts)?