help wanted: Stripe dispute/chargeback → folio & A/R workflow for hotels

[telivity-otaip]

Why hotels care

Chargebacks are a desk + accounting event, not a Stripe Dashboard hobby. When a guest disputes a stay deposit or folio settlement, the hotel needs:

1. The folio / payment marked disputed in the PMS
2. Night audit / cash reports that don’t pretend the money is still final
3. A path to evidence (folio PDF, reg card, auth log) without leaving HAIP

Today Stripe webhooks handle payment_intent.succeeded|payment_failed|canceled. There is no dispute lifecycle wired into payments/folios.

Current state (code anchors)

• apps/api/src/modules/payment/stripe-webhook.controller.ts — PI events only
• PaymentService — authorize / capture / refund with atomic claims (Bug 1)
• Folio + A/R + cashier modules exist; disputes are not a first-class payment status today
• PCI rule unchanged: never store raw card data

What we need

1. Handle Stripe dispute events (charge.dispute.created|updated|closed — confirm against current Stripe API docs, don’t invent)
2. Map dispute → HAIP payment (+ folio note / status flag) with idempotency on Stripe dispute id
3. Staff notification (critical) to property finance/front-office roles
4. Operator runbook: what evidence to pull from HAIP for representment
5. Tests with signed webhook fixtures; dashboard surfacing (list/badge) can be a follow-up slice

Open questions (GMs / controllers — comment)

• Should a disputed payment block night-audit “clean close", or only warn?
• Auto-move balance to city ledger / A/R on needs_response, or wait for lost dispute?
• Multi-currency / partial-capture stays — any property-specific pain?

Do not invent accounting law. If the KB/docs don’t lock the GL treatment, implement the payment flag + notification first and leave GL posting behind a clearly labeled follow-up.

Acceptance criteria

• Dispute webhooks update HAIP payment records idempotently
• Folio/payment UI or API shows disputed state
• Staff notification on create + lost/won close
• No raw PAN/CVc storage; secrets stay in Stripe
• Vitest + webhook signature tests
• Short docs/integrations/ runbook for hotel finance

How to contribute

Perfect for someone who has integrated Stripe Connect/disputes or run hotel finance through chargeback season. Use the Stripe skill/docs; sandbox disputes are fine.

Search keywords: chargeback, Stripe dispute, folio, hotel payments, representment, payment_intent, A/R, night audit