feat(refunds): refund a booking from the Desk

[harshtandiya]

Loom: https://www.loom.com/share/a0bfd08d12c648d3b55adb4144179ac6

Lets a System Manager refund a booking from the Event Booking form, and keeps the booking in step with whatever the gateway settles. Depends on frappe/payments#248, which adds refund_payment / fetch_refund and the webhook this subscribes to.

The flow

Refund button on a paid, submitted booking, System Manager only. The dialog lists the tickets still refundable with what each one cost — ticking them fills in the amount, leaving them unticked refunds money without touching a ticket.

Ticket amounts are what the buyer actually paid: attendee amounts are pre-tax and pre-discount, so each ticket's share is scaled to what was charged. The ratio is taken over current attendee amounts rather than net_amount, because a Free Tickets coupon zeroes attendee rows afternet_amount is computed, and using it would count the discount twice.

Tickets picked for a refund are recorded, not cancelled. Cancelling waits until the gateway settles, because a refund can still fail, and a ticket cancelled against a failed refund leaves the customer with neither money nor a seat. A custom amount cancels nothing — it maps to no particular ticket.

handle_refund_notification parses the webhook into a pydantic model (payload.refund.entity, flattened with AliasPath), matches payment_id to an Event Payment and records the outcome. Keyed on the refund id, because the same event arrives more than once. It returns nothing so other subscribers to the hook still run — call_hook_method stops at the first truthy return. A payload carrying no refund raises instead of returning quietly: only refund.processed and refund.failed ever reach us, so such a payload is a defect, and the payments app already logs it and marks the Integration Request failed.

Nothing refunded twice, nothing refunded and used

get_refund_summary is the single answer to "what is still refundable". Dialog and server both read it, so what an operator is offered cannot drift from what the server accepts. A refund still waiting on the gateway holds its money and its tickets, since the gateway will not reject a second refund while the first is unsettled — a booking of 2000 + 3000 cannot give back 3000 twice, Initiated or Processed. A failed refund releases both.

A ticket the front desk has already scanned cannot be refunded. That is checked before the money moves, rather than discovered afterwards when cancelling the ticket raises LinkExistsError. Going the other way, check-in turns away any ticket a refund holds, settled or not: cancelling a ticket can fail, and the savepoint that keeps that failure from dragging the refund down with it leaves the ticket live. A failed refund frees the ticket again.

Schema

Event Booking Refund, named REF-#####: the booking and payment it belongs to, the gateway refund id (unique — this is what makes webhook dedupe safe at the database level), amount, status (Initiated / Processed / Failed), the tickets it covers, and the cancellation request raised for them. Event Booking keeps the summary in refund_status and refunded_amount, both allow_on_submit, since refunds always land after submission.

Tests

29 on the refund path, plus the check-in suite: ticket share maths, the non-Razorpay refusal, the over-refund ceiling settled and unsettled, tickets re-offered after a failure, the checked-in refusals both ways, and the webhook — partial vs full settlement, a repeated event not counting twice, a malformed payload refused, and the job running as Guest. That last one matters: the webhook endpoint is allow_guest, so its job runs as Guest, who cannot write to Event Booking. Caught in a real run, not by the original tests, which all ran as Administrator.

Known limits

• Only Razorpay. Anything else is refused up front with a message saying so.
• Refund state hangs off Event Booking, so sponsorship payments — same Event Payment doctype — cannot reuse it yet.
• No data patch. The doctype changed shape during review and this has never been deployed; the only affected rows were on one developer's site and were moved by hand.
• Cancelling a ticket no longer emails inline, so a mail server having a bad day cannot roll back the cancellation.
• One unrelated crash fixed in passing: Event Payment is named by autoincrement, so name reached PaymentDetails.name as an int and check-in raised for every ticket with a received payment.

[greptile-apps]

Greptile Summary

The PR adds System Manager–initiated Razorpay refunds for event bookings and synchronizes their status through gateway notifications.

• Adds refund records, booking-level refund summaries, and Desk controls.
• Prevents committed or checked-in tickets from being selected again.
• Cancels selected tickets after successful gateway settlement and blocks their check-in while the refund is committed.

Confidence Score: 4/5

The PR is not yet safe to merge because a cancellation submission failure can leave a processed refund’s tickets active indefinitely.

The refund is persisted as Processed before cancellation is attempted, while submission exceptions are caught and logged without an automatic retry, so the previously reported processed-refund-with-active-ticket failure remains outstanding.

Files Needing Attention: buzz/ticketing/doctype/event_booking_refund/event_booking_refund.py

Important Files Changed

Filename	Overview
buzz/ticketing/doctype/event_booking/event_booking.py	Adds refund validation, ticket allocation, gateway dispatch, and booking-level refund accounting; the prior foreign-ticket validation issue is fixed.
buzz/ticketing/doctype/event_booking_refund/event_booking_refund.py	Applies gateway outcomes and submits ticket cancellation requests, but cancellation submission failures still leave processed refunds without eventual ticket cancellation.
buzz/payments.py	Adds validated Razorpay refund webhook handling and idempotent lookup by gateway refund ID.
buzz/api/checkin/services.py	Rejects check-in for tickets claimed by initiated or processed refunds.
buzz/ticketing/doctype/event_booking/event_booking.js	Adds the Desk refund dialog and refund-history rendering for eligible bookings.

_{Reviews (9): Last reviewed commit: "fix(refunds): keep a refunded ticket out..." | Re-trigger Greptile}

[github-actions]

Backport failed for main, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin main
git worktree add -d .worktree/backport-328-to-main origin/main
cd .worktree/backport-328-to-main
git switch --create backport-328-to-main
git cherry-pick -x f4990fee18bbaac9431196d0d081c028a9df1c1f