Display Refund reason

[SarahSync]

User story

As a user viewing a refunded transaction, I want to see the reason for the refund directly on my receipt, so that I don't have to contact support to find out what went wrong with my order.

Acceptance criteria

1. GIVEN an aggregator initiates a refund
   WHEN the refund process is completed
   THEN the aggregator must send a webhook containing the specific refund reason to the sender/backend for storage.

2. GIVEN a transaction has the status "refunded"
   WHEN the user opens the transaction details/receipt
   THEN a new row labeled "Refund Reason" must be visible and it must display the reason fetched from the database.

3. GIVEN a transaction has a status of "pending," "settled," or "failed" (not refunded)
   WHEN the user opens the transaction receipt
   THEN the "Refund Reason" row must NOT be visible in the UI.

Technical details

• Webhook Update: Update the Aggregator's refund webhook listener to parse and store the refund_reason field in the transactions table.
• API Enhancement: Modify the transaction details endpoint to include the refund_reason field in the response payload when the status is "refunded."
• Frontend Logic: Implement conditional rendering in the receipt component to show the "Refund Reason" row only if status === 'refunded' and the reason string is not empty.

Notes/Assumptions

• Data Availability: It is assumed the Aggregator has access to the specific failure or refund trigger reason to send in the webhook.

[onahprosper]

Summary

The aggregator will send a refund reason in the payment_order.refunded webhook and include it in the transaction details (and list) API when status is refunded. The reason is derived from existing data: cancellation_reasons (and optionally cancellation_count) on the PaymentOrder table. No new schema or migration. Dashboard/UI changes are excluded and will be handled in another issue.

Data flow

sequenceDiagram
  participant Initiator as RefundInitiator
  participant DB as PaymentOrder DB
  participant Indexer as Blockchain Indexer
  participant Webhook as Sender Webhook
  participant API as Sender API
  Initiator->>DB: Set cancellation_reasons if needed
  Initiator->>Indexer: RefundOrder (on-chain)
  Note over Indexer: OrderRefunded event detected
  Indexer->>DB: UpdateOrderStatusRefunded (status=refunded)
  DB->>Webhook: SendPaymentOrderWebhook (refundReason from cancellation_reasons)
  API->>DB: Get order by ID or list
  API->>API: Derive refundReason from cancellation_reasons when status=refunded

Loading

Source of refund reason: For refunded orders, refundReason is derived from paymentOrder.CancellationReasons (e.g. strings.Join(..., "; ")). Optionally include cancellation_count. HandleCancellation and provider CancelOrder already set cancellation_reasons; for stale-ops refunds, if the order has no reasons yet, set a default (e.g. SetCancellationReasons([]string{"Order timed out"})) before calling RefundOrder.

---

1. Ensure refunded orders have a reason (stale-ops only)

• File: aggregator/tasks/stale_ops.go — In the refund loop, before calling service.RefundOrder: if the order has no cancellation reasons (len(order.CancellationReasons) == 0), update it with a default (e.g. SetCancellationReasons([]string{"Order timed out"})).
• Orders cancelled by providers or via HandleCancellation already have cancellation_reasons set. No changes to order.go or provider.go.

---

2. Webhook payload (aggregator)

• Types: aggregator/types/types.go — In PaymentOrderWebhookData, add RefundReason string with json:"refundReason,omitempty".
• Send logic: aggregator/utils/utils.go — In SendPaymentOrderWebhook, when building payloadStruct.Data, set RefundReason only when paymentOrder.Status == paymentorder.StatusRefunded: derive from paymentOrder.CancellationReasons (e.g. strings.Join(paymentOrder.CancellationReasons, "; ")). If the slice is empty, leave RefundReason empty.

Senders will receive refundReason in the payment_order.refunded webhook for storage/display.

---

3. Transaction details and list API (aggregator)

• Types: aggregator/types/types.go — In SenderOrderResponse, add RefundReason string with json:"refundReason,omitempty".
• Controllers: aggregator/controllers/sender/sender.go — GetPaymentOrderByID and GetPaymentOrders (list): set RefundReason in the response when status is refunded to the joined paymentOrder.CancellationReasons; otherwise leave empty.

Per acceptance criteria, the API includes refund reason when status is refunded; omitempty keeps the field out when not refunded or when reason is empty.

---

4. Testing and edge cases

• Backward compatibility: No schema change; existing refunded orders may have empty or populated cancellation_reasons; API and webhook will send whatever is stored.
• Optional: Add or extend tests for (1) webhook payload containing refundReason when status is refunded and cancellation_reasons are set, (2) GetPaymentOrderByID / list including refundReason derived from cancellation_reasons.

---

File checklist

Area	File	Change
Stale-ops	aggregator/tasks/stale_ops.go	If order has no cancellation_reasons before refund, set default (e.g. "Order timed out")
Webhook	aggregator/types/types.go	Add RefundReason to PaymentOrderWebhookData
Webhook	aggregator/utils/utils.go	Set RefundReason from joined CancellationReasons when status is refunded
API types	aggregator/types/types.go	Add RefundReason to SenderOrderResponse
API	aggregator/controllers/sender/sender.go	Set RefundReason in GetPaymentOrderByID and list from cancellation_reasons when refunded

Out of scope for this issue: Schema/migration, dashboard, and any UI (handled elsewhere).