Charge a card-on-file no-show fee (admin)

What the "Charge fee" action on /payments, a booking's own detail dialog, and the reservations/bookings lists all call. The one MANUAL step in the whole card-on-file mechanism (migration 0129): every route upstream of this one only ever SAVES a card at zero charge (createSetupIntent, the guest checkout routes), and nothing is ever charged until a human clicks the button that POSTs here, on a no-show or a late cancellation staff decided is chargeable. There is no cron, no trigger, nothing on a timer.

A direct charge on the connected account, off-session against the card saved at booking. The fee amount snapshotted into deposit_amount_cents at booking time (the same column a real deposit uses) is the CEILING; a later policy change never moves it.

amountCents (migration 0137) is optional and, when sent, is clamped server-side against that same deposit_amount_cents before it is trusted for anything: strictly greater than 0 and no larger than the deposit. Omitted or null keeps the pre-0137 behaviour exactly: the full frozen deposit, charged unconditionally. This is what lets the dialog charge less than the disclosed ceiling for a booking whose own cancellation notice earned a lighter tier (see GET above), while a suggested figure or any custom amount a staff member types is never trusted on the client's word alone.

An Idempotency-Key header is REQUIRED, identical in shape to /api/payments/refunds: withIdempotency runs the route at most once per key and replays the first response, the same key goes to Stripe as its own idempotency option, and the ledger row carries the charged PaymentIntent id in stripe_event_id (this charge's own webhook delivery is a deliberate no-op, so there is no separate evt_... to dedupe against). A fourth layer this route needs that refunds does not: a compare-and-set claim (card_on_file_status → 'charging') before Stripe is ever called. A refund is safe from two racing keys because Stripe itself is the ceiling (a second refund attempt fails outright); a charge has no such ceiling: two off-session PaymentIntents against the same saved card, carrying two different keys, would both succeed at Stripe and charge the guest twice. The claim closes that window; a losing request never reaches Stripe at all.

Admin-only, and that gate is the whole authorization: the button is hidden from a staff login, but hiding a button is cosmetic (see src/lib/auth/require-member.ts). Not engine-gated: card_on_file_enabled lives on book_companies for either vertical, and both booking tables carry the 0129 columns this route reads and writes.

Response BodyCopy Anchor Link

curl -X POST "https://example.com/api/payments/no-show-fee" \  -H "Content-Type: application/json" \  -d '{    "bookingTable": "book_appointments",    "bookingId": "string"  }'

{  "ok": true,  "paymentIntentId": "string",  "amountCents": 0,  "suggestedTierCents": 0}