mirror of https://github.com/rjNemo/rentease.git synced 2026-06-06 02:36:49 +00:00

CI / checks (push) Waiting to run

Details

* feat(stripe): add Stripe payment sync and webhook support

Introduce Stripe integration for automatic payment ingestion and refund
tracking. Adds new fields to the payment model for Stripe IDs and
status,
Stripe client driver, sync service, cron job, manual API endpoint, and
public webhook handler for real-time updates. Includes tests and
documentation. Manual cash entry remains supported.

* chore(stripe): upgrade to stripe-go v83

Upgrade Stripe SDK from v79 to v83 across the codebase. Update all
imports to use github.com/stripe/stripe-go/v83 and refactor client usage
to match the new API, including changes to PaymentIntents listing.
Update documentation and plans to reference the new version. Remove
references to the old version from go.mod and go.sum.

* refactor(payment): extract payment logic to new service

Moves all payment-related logic (manual payments, Stripe sync, webhook
handling) from the booking service into a dedicated payment service
(`internal/service/payment`). Updates server, cron, and handler wiring
to
inject and use the new payment service. Adjusts tests, routes, and
documentation to reflect the new separation of concerns.

This improves cohesion, clarifies responsibilities, and prepares for
future payment features. No database schema changes are introduced.

* chore(ci): add Go and templ setup to CI workflow

This update enhances the CI workflow by adding steps to set up Go using
the version specified in go.mod, add the Go bin directory to the PATH,
and install the templ code generation tool. These additions ensure that
Go-based tooling is available for subsequent CI steps.

2025-11-21 15:47:01 +01:00

6.1 KiB

Raw Permalink Blame History

date researcher git_commit branch repository topic tags status last_updated last_updated_by

2025-10-03T20:02:01+0200

Codex

ac94faedb0

main

rentease

Stripe payment ingestion & webhook strategy

research

payments

stripe

complete

2025-10-05

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: https://github.com/rjNemo/rentease/blob/ac94faedb0b491d710c36b04ac27b26890f4d062/internal/server/handle_bookings.go#L130-L179).

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: https://github.com/rjNemo/rentease/blob/ac94faedb0b491d710c36b04ac27b26890f4d062/internal/repository/booking/pg_store.go#L150-L174).
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: https://github.com/rjNemo/rentease/blob/ac94faedb0b491d710c36b04ac27b26890f4d062/internal/server/handle_payments.go#L16-L51)
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: https://github.com/rjNemo/rentease/blob/ac94faedb0b491d710c36b04ac27b26890f4d062/internal/repository/booking/pg_store.go#L65-L174)
internal/server/routes.go:8 – current route layout and auth groups (perm: https://github.com/rjNemo/rentease/blob/ac94faedb0b491d710c36b04ac27b26890f4d062/internal/server/routes.go#L8-L46)
cmd/cron/main.go:13 – cron entrypoint for scheduled jobs (perm: https://github.com/rjNemo/rentease/blob/ac94faedb0b491d710c36b04ac27b26890f4d062/cmd/cron/main.go#L13-L44)

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.

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)?

6.1 KiB Raw Permalink Blame History Unescape Escape