refinement phase 6

server/src/API/Baya.Web.Api/Controllers/V1/AdminRefundsController.cs

@@ -1,6 +1,8 @@
 using System.ComponentModel.DataAnnotations;
 using Asp.Versioning;
+using Baya.Application.Features.Refunds.Commands.ConfirmRefundSettlement;
 using Baya.Application.Features.Refunds.Commands.CreateRefund;
+using Baya.Application.Features.Refunds.Commands.MarkRefundSettlementFailed;
 using Baya.Application.Features.Refunds.Queries.ListRefunds;
 using Baya.Application.Models.Common;
 using Baya.Application.Models.Refunds;
@@ -37,4 +39,20 @@ public sealed class AdminRefundsController(ISender sender) : BaseController
     [ProducesOkApiResponseType<PagedResult<RefundListItemDto>>]
     public async Task<IActionResult> List([FromQuery] ListRefundsQuery query, CancellationToken cancellationToken)
         => OperationResult(await sender.Send(query, cancellationToken));
+
+    // Reconciliation confirmed the customer cash-back for a processing BNPL/manual refund — settle it (posts the
+    // deferred refund_payable ↔ escrow_held clearing). Idempotent.
+    [HttpPost("{id}/[action]")]
+    [ProducesOkApiResponseType<RefundSettlementResult>]
+    public async Task<IActionResult> ConfirmSettlement(long id, CancellationToken cancellationToken)
+        => OperationResult(await sender.Send(new ConfirmRefundSettlementCommand(id), cancellationToken));
+
+    // Reconciliation reported the customer cash-back did not land — fail the processing refund (no ledger moves).
+    [HttpPost("{id}/[action]")]
+    [ProducesOkApiResponseType<RefundSettlementResult>]
+    public async Task<IActionResult> MarkFailed(long id, MarkRefundFailedBody body, CancellationToken cancellationToken)
+        => OperationResult(await sender.Send(new MarkRefundSettlementFailedCommand(id, body.Reason), cancellationToken));
 }
+
+/// <summary>The mark-failed body (the id comes from the route).</summary>
+public record MarkRefundFailedBody(string? Reason);