baya-monorepo/dev/phases/backend/backend-phase-11.md

# Backend Phase 11 — Refunds, invoices & nurse clawbacks

> **Mission:** make money flow *backwards* correctly. Build the admin-only refund engine that reverses a
> captured booking payment across **both fee legs** (platform commission vs nurse payout), posts the
> balanced reversal into the append-only ledger, and forks hard on one question — *has the nurse already
> been paid?* Pre-payout it is a clean `nurse_payable` reversal; post-payout it opens a first-class
> **`nurse_clawbacks`** receivable, because an Iranian IBAN transfer is effectively irreversible. Same
> phase adds the minimal **`invoices`** record (VAT on the commission line, sequential number, optional
> مودیان submission behind a seam). Refunds are admin-initiated, ticket-linked, channel-aware (card vs
> BNPL revert), and never customer self-service. After this phase, a cancellation can actually return
> money and the books stay balanced.
>
> **Track:** backend · **Depends on:** [b10](./backend-phase-10.md) (ledger / transactions / webhook idempotency / capture), [b9](./backend-phase-9.md) (cancellation policies / bookings / dispute window), [b1](./backend-phase-1.md) (VAT config / typed config accessor) · **Unlocks:** payout clawback netting ([b13](./backend-phase-13.md)); frontend **f10-b11**
> **Before you start, read [`../_shared/agent-operating-rules.md`](../_shared/agent-operating-rules.md).** It is not optional.

---

## 1. Context — where this sits

This is **backend phase b11**, the reversal leg of the payments arc (b10 ledger/capture → **b11
refunds·invoices·clawbacks** → b12 BNPL → b13 payouts). The platform never custodies cash: "escrow" is an
internal **double-entry ledger state** ([`product/payments/escrow-ledger.md`](../../../product/payments/escrow-ledger.md)),
and a booking's money already sits posted as `escrow_held` / `platform_revenue` / `nurse_payable` from
b10's capture. A refund un-does some or all of that. The hard problem is **timing**: if the nurse has not
yet been paid (the common case, because b13 gates payout on `dispute_window_ends_at`), the refund simply
reverses the `nurse_payable` accrual — nothing leaves Balinyaar. If the nurse *has* been paid, the money
is already gone to an irreversible bank transfer, so the refund becomes platform-funded and opens a
**clawback receivable** the next payout batch nets out. This phase also issues the minimal commission
**invoice** with config-driven VAT, because Iranian commission marketplaces owe VAT on *their commission*
(the Snapp/Tapsi precedent), not on the nurse's earnings.

**What this phase does *not* do:** it does **not** build the cancellation policy resolver or the
`CancelBooking` flow (that is b9 — this phase *consumes* the resolved policy snapshot); it does **not**
build the card/BNPL provider adapters (b10/b12 — this phase *calls* their refund/revert methods through
seams); it does **not** net or recover clawbacks into a payout (that is b13 — this phase only *opens* the
receivable + posts its ledger leg).

**What already exists (do not rebuild) — built by prior phases:**
- **The ledger, transactions & webhook idempotency** — [b10](./backend-phase-10.md) built
  `ledger_entries` (append-only, balanced, `transaction_group_id`, the account types incl.
  `escrow_held`, `platform_revenue`, `nurse_payable`, `refund_payable`, `nurse_clawback_receivable`),
  `payment_transactions` (the `succeeded` capturing row, filtered `UNIQUE(booking_id) WHERE
  status='succeeded'`, `UNIQUE(gateway_reference_code)`), `payment_webhook_events`
  (`UNIQUE(provider_code, external_event_id)`), the **card-capture posting** (`DEBIT escrow_held` gross /
  `CREDIT platform_revenue` commission + `nurse_payable` payout), the **ledger posting helper**, the
  `IPaymentProvider` seam (incl. `RefundAsync`), the `IWebhookVerifier` seam, and the `IDistributedLock`
  Redis-lock pattern on the money path. **Reuse the ledger posting helper, the webhook idempotency path,
  the `IPaymentProvider` seam, and the lock — do not re-implement them.**
- **Bookings, cancellation policies & the dispute window** — [b9](./backend-phase-9.md) built `bookings`
  (the three-amount split `gross_price_irr = balinyaar_commission_irr + nurse_payout_amount`,
  `platform_fee_rate` snapshot, `dispute_window_ends_at`), `booking_sessions` (`visit_payout_amount`,
  `payout_eligible_at`, `cancellation_event_id`), `cancellation_policies` (config-driven tiers by lead
  time × actor, `code`, `is_active`), and the `CancelBooking` / `CancelSession` commands that **resolve
  the applicable policy and snapshot `cancellation_policy_code` + the resolved refund percentage** onto
  the cancellation event. **This phase reads that resolved policy snapshot to populate the refund's
  `cancellation_policy_code` / `refund_percentage_applied`; it does not re-resolve policy from live
  config.**
- **VAT config & the typed config accessor** — [b1](./backend-phase-1.md)'s `platform_configs` table with
  a typed, cached accessor (behind `ICacheService`). The `vat_rate` key (default `0.10`) and any
  refund-ETA config are read **through that accessor**, never hardcoded. b1 also built `notifications` +
  the `INotificationDispatcher` real in-app write, and `support_alerts`.
- **The b0 foundation:** the REST surface, `BaseController`, `OperationResult<T>`, CQRS via
  **`martinothamar/Mediator`** (`ISender`/`ICommand`/`IQuery`, `internal sealed` handlers),
  `IFieldEncryptor`, `ICurrentUser` + audit interceptor, rate limiting, `IDateTimeProvider`,
  `IObjectStorage` (for the invoice PDF key, optional), and the mock-report discipline.

**What this phase introduces:** the three tables (`refunds`, `nurse_clawbacks`, `invoices`), the
refund/clawback/invoice capabilities, and **one new seam — `IMoadianClient`** (the mocked سامانه مودیان
e-invoicing rail). The BNPL revert path *targets* the `IBnplProvider.RevertAsync` seam introduced in
**b12**; until b12 lands, the `bnpl_revert` channel is exercised through the same ledger legs with the
BNPL provider call behind its seam (see §3.6 + §4).

> **Forward dependency (tickets):** refunds **must** link a `ticket_id`, but the `tickets` table arrives
> in [b15](./backend-phase-15.md). Make `refunds.ticket_id` a **nullable FK now** with the column +
> index in place, enforce "ticket required" as a **validator/handler rule that is config-gated off until
> b15** (so admin refunds are testable today), and note the forward-dep in the report. b15 wires the
> real FK target and flips the rule on. **Do not invent a `tickets` table in this phase.**

## 2. Required reading (do this first)

- [`../_shared/agent-operating-rules.md`](../_shared/agent-operating-rules.md) and
  [`../_shared/backend-conventions-checklist.md`](../_shared/backend-conventions-checklist.md) —
  especially the *Performance, caching, money, idempotency* block (IRR `BIGINT`, append-only balanced
  ledger, idempotent money writes, Redis lock on the money path, config read through the typed accessor).
- [`product/business/07-cancellation-and-refunds.md`](../../../product/business/07-cancellation-and-refunds.md) —
  **the business rules**: tiered/snapshotted policy, **admin-only + ticket-linked** refunds, fee-leg
  decomposition, per-session (un-started only), pre- vs post-payout fork, BNPL-via-provider-revert-only,
  MVP vs DEFERRED (automated nurse-no-show penalty is a manual admin action; self-service partial-refund
  UI and holiday overrides are DEFERRED).
- [`product/payments/cancellation-and-payout.md`](../../../product/payments/cancellation-and-payout.md) —
  **Q1 the BNPL refund unwind**: money *always* flows `customer ↔ provider ↔ Balinyaar`, never direct;
  `revert` (full) vs `update` (partial, strictly-lower amount); the async **7–10 business-day** customer
  window surfaced as `expected_customer_refund_eta`; `refund_status = processing` until reconciled; the
  **nullable** `provider_commission_reversed_amount` (do not hardcode whether the provider returns its
  commission); the same fee-leg decomposition applies.
- [`product/data-model/06-payments-ledger-and-refunds.md`](../../../product/data-model/06-payments-ledger-and-refunds.md) —
  **the canonical schema** for `refunds` (the new 1:N cardinality, `platform_fee_refunded_irr` /
  `nurse_payout_refunded_irr`, `refund_channel`, `external_revert_reference`,
  `expected_customer_refund_eta`, `cancellation_policy_code` / `refund_percentage_applied`),
  `nurse_clawbacks` (`status`, `original_payout_id`, `recovered_in_payout_id`), `invoices`
  (`invoice_number` UNIQUE, `platform_commission_irr` the VAT-relevant line, `vat_rate`/`vat_irr`,
  `moadian_reference_number`/`moadian_status`), and the **canonical postings** table. Mirror these field
  names exactly.
- [`product/payments/escrow-ledger.md`](../../../product/payments/escrow-ledger.md) — the **refund and
  clawback postings** in depth (pre-payout reversal; the `refund_payable` ↔ `escrow_held` confirm step;
  the clawback receivable leg).
- **Code to mirror:** b10's ledger posting helper + `IDistributedLock` usage + `payment_webhook_events`
  idempotency + the `IPaymentProvider`/`IWebhookVerifier` seams + the `Features/Payments/**` command
  structure; b9's `bookings`/`cancellation_policies` configs and the policy-snapshot fields; b1's typed
  config accessor and `INotificationDispatcher`; b0's `IFieldEncryptor`/`IObjectStorage` + seam
  registration via `ServiceConfiguration/` extensions.
- **Contract conventions:** [`../../contracts/conventions/api-conventions.md`](../../contracts/conventions/api-conventions.md)
  and [`money-and-types.md`](../../contracts/conventions/money-and-types.md) (IRR `BIGINT`, money as a
  digit-string on the wire, the `refund_channel` enum, masking, the envelope).
- **Prior handoffs:** `dev/shared-working-context/backend/handoff/after-backend-phase-10.md`, `…-9.md`,
  `…-1.md`, and `reports/mocks-registry.md` (seam rows you reuse / the one you add).

## 3. Scope — build this

All money is IRR `long` / `BIGINT` — no floats anywhere. Features live under
`Baya.Application/Features/Refunds/{Commands|Queries}/<Name>/` (refunds + clawbacks) and
`Baya.Application/Features/Invoices/{Commands|Queries}/<Name>/`; entities in
`Baya.Domain/Entities/Refunds/` and `…/Invoices/`; one `IEntityTypeConfiguration<T>` per entity in
`Persistence/Configuration/RefundsConfig/` and `…/InvoicesConfig/`; one EF migration for the three tables.

### 3.1 Entities + migration

**`refunds`** [CORE] — admin-initiated, ticket-linked, **1:N per `payment_transaction`**, fee-leg
decomposed, channel-aware.
- Fields (baseline + new, mirror [data-model 06](../../../product/data-model/06-payments-ledger-and-refunds.md)):
  `id`, `payment_transaction_id` (FK `payment_transactions`), `booking_id` (FK `bookings`),
  `requested_by_customer_id` (FK `customer_profiles` — the customer the refund is *for*, not the actor),
  `ticket_id` (**FK NULLABLE — forward-dep on `tickets` in b15**, see §1 callout), `amount` (BIGINT, the
  total refunded = fee leg + payout leg), `refund_percentage` (resolved %), `reason_category`,
  `reason_notes`, `status`, approval/rejection fields (`approved_by_admin_id`, `rejected_reason`),
  `gateway_refund_reference` (the PSP card-refund ref), `processed_at` (nullable), `admin_notes`, audit
  fields; **plus the new decomposition/channel fields:**
  - `platform_fee_refunded_irr` (BIGINT) — the portion of `balinyaar_commission_irr` being reversed.
  - `nurse_payout_refunded_irr` (BIGINT) — the portion of `nurse_payout_amount` being reversed (drives a
    clawback if the nurse was already paid).
  - `refund_channel` (enum) — `psp_card` | `bnpl_revert` | `manual` (the data-model also writes
    `manual_bank`; **use `manual` as the canonical wire code** per
    [`money-and-types.md`](../../contracts/conventions/money-and-types.md), and document the mapping).
  - `external_revert_reference` (NVARCHAR(200) NULL) — the BNPL provider revert id.
  - `expected_customer_refund_eta` (DATE NULL) — the ~7–10 business-day BNPL window, surfaced in
    UI/reconciliation; null for instant card refunds.
  - `cancellation_policy_code` (NVARCHAR NULL) + `refund_percentage_applied` (DECIMAL NULL) — **snapshot**
    of the policy that produced this refund (read from b9's cancellation event; never re-resolved live).
- **`refund_status`** enum (`status`): `requested` | `approved` | `processing` | `succeeded` | `failed` |
  `rejected`. (`processing` is the state a BNPL revert sits in until the reconciliation job confirms the
  customer cash-back.)
- **Cardinality / invariant:** **1:N** per `payment_transaction`. The app invariant
  **`Σ refunded ≤ captured`** is enforced **in the handler** (sum of prior succeeded/processing refund
  `amount` for the transaction + this one ≤ the captured `payment_transactions.amount`) — it is *not* a
  single-row DB CHECK. Likewise `amount = platform_fee_refunded_irr + nurse_payout_refunded_irr` (handler
  invariant + a CHECK where SQL Server allows).
- Relations: N:1 → `payment_transactions`, `bookings`, `customer_profiles`, `tickets` (nullable); 1:1 →
  `nurse_clawbacks` (only when refunding a booking whose nurse was already paid).

**`nurse_clawbacks`** [CORE] — first-class receivable when a booking is refunded/disputed **after** the
nurse was already paid.
- Fields (mirror [data-model 06](../../../product/data-model/06-payments-ledger-and-refunds.md)): `id`,
  `nurse_id` (FK `nurse_profiles`), `booking_id` (FK `bookings`), `refund_id` (FK `refunds`),
  `original_payout_id` (FK `nurse_payouts` **NULL** — `nurse_payouts` arrives in b13, so this FK is
  nullable now and the column/index are in place; the *value* is set once b13 exists),
  `amount_irr` (BIGINT — equals the `nurse_payout_refunded_irr` leg), `status`, `recovered_in_payout_id`
  (FK `nurse_payouts` **NULL** — set by **b13** when a batch nets it; this phase only ever leaves it
  null/`pending`), `created_at`, `resolved_at` (nullable), audit fields.
- **`clawback_status`** enum (`status`): `pending` | `recovered` | `written_off`. **This phase only ever
  creates rows in `pending`** (and supports an admin `write_off`); **`recovered` is set by b13's payout
  netting — do not implement recovery here.**
- Relations: N:1 → `nurse_profiles`, `bookings`; 1:1 → `refunds`; → `nurse_payouts` (original +
  recovering, both nullable until b13).

**`invoices`** [MVP] — minimal official receipt per booking; **VAT on the commission line only**.
- Fields (mirror [data-model 06](../../../product/data-model/06-payments-ledger-and-refunds.md)): `id`,
  `booking_id` (FK `bookings`), `invoice_number` (NVARCHAR(40) **UNIQUE** — official, **sequential**),
  `issuing_entity_type` (`platform` | `partner_center`), `gross_irr` (BIGINT),
  `platform_commission_irr` (BIGINT — **the VAT-relevant line**), `bnpl_commission_irr` (BIGINT NULL),
  `vat_rate` (DECIMAL(5,4) — read from config, default `0.10`), `vat_irr` (BIGINT — computed
  `round(platform_commission_irr * vat_rate)`, integer-only), `moadian_reference_number` (NVARCHAR(40)
  NULL — the 22-digit سامانه مودیان ref when issued), `moadian_status` (NVARCHAR(20) NULL —
  `pending` | `submitted` | `registered` | `failed`), `pdf_storage_key` (NVARCHAR(512) NULL — an
  `IObjectStorage` key), `issued_at` (DATETIME2), audit fields.
- **`invoice_number` is UNIQUE and sequential** — generate it from a gap-free, concurrency-safe sequence
  (a dedicated DB sequence / a locked counter row), **never** a random or timestamp-derived value. Relate
  1:1 → `bookings`; N:1 → `partner_centers` (when the issuer is a partner center).

### 3.2 Commands & queries (CQRS, `OperationResult`, never throw for expected failures)

| Capability | Type | Route (admin/customer) | What it does |
| --- | --- | --- | --- |
| **`CreateRefundCommand`** | Command | `POST api/v1/admin_refunds` | Admin-only. Validates the booking has a captured (`succeeded`) `payment_transaction`; **requires a `ticket_id`** (config-gated off until b15, see §1); reads the **resolved cancellation policy snapshot** from b9's cancellation event for the booking to populate `cancellation_policy_code` / `refund_percentage_applied`; **decomposes** the refund into `platform_fee_refunded_irr` + `nurse_payout_refunded_irr` (pro-rata of the booking's `balinyaar_commission_irr` / `nurse_payout_amount` at the resolved %, or admin-supplied legs that must still sum to `amount`); enforces **`Σ refunded ≤ captured`**; picks `refund_channel` from the original payment type (`psp_card` for card, `bnpl_revert` for BNPL, `manual` for an out-of-band bank refund); creates the `refunds` row in `requested`/`approved`. Under `lock(booking:{id}:refund)`. Then dispatches the channel execution + ledger posting (below). |
| **`ExecuteRefundChannelCommand`** | Command (internal step) | — | Calls the channel: **card** → `IPaymentProvider.RefundAsync(gatewayReferenceCode, amountIrr, idempotencyKey, ct)` (channel `psp_card`), storing `gateway_refund_reference`, status → `succeeded` (card refunds are effectively immediate, `expected_customer_refund_eta = null`); **BNPL** → `IBnplProvider.RevertAsync(...)` (b12 seam; **full** = `revert`, **partial/shortened** = `update` with a strictly-lower amount), storing `external_revert_reference`, setting `expected_customer_refund_eta = now + config(bnpl_refund_eta_business_days, 10)` (business-day shifted), status stays **`processing`** until the reconciliation job/webhook confirms cash-back; **manual** → records the admin-entered bank ref, status `processing`/`succeeded` per admin. **Carries an `idempotencyKey`** so a retried call never double-refunds. |
| **`PostRefundLedgerCommand`** | Command (internal step) | — | **Pre-payout path** (nurse not yet paid): posts the balanced reversal in one `transaction_group_id` — `DEBIT platform_revenue platform_fee_refunded_irr` + `DEBIT nurse_payable nurse_payout_refunded_irr`, `CREDIT refund_payable (sum)`. When the provider confirms the customer cash-back (card immediately; BNPL via reconciliation), a **second** balanced posting **clears `refund_payable` ↔ `escrow_held`** (`DEBIT refund_payable` / `CREDIT escrow_held`). Uses b10's posting helper; append-only; Σdebit = Σcredit. |
| **`CreateClawbackCommand`** | Command (internal step) | — | **Post-payout path** (nurse already paid — detected via b13's `nurse_payout_booking_links` for the booking, or, until b13 exists, a config/flag indicating the booking was paid): instead of debiting `nurse_payable`, posts `DEBIT nurse_clawback_receivable nurse_payout_refunded_irr` (+ the `DEBIT platform_revenue` fee leg) / `CREDIT refund_payable`, and **creates a `nurse_clawbacks` row in `pending`** (`nurse_id`, `booking_id`, `refund_id`, `amount_irr = nurse_payout_refunded_irr`, `original_payout_id` when available). Raises a `support_alert` (b1) on every clawback. **Does not net or recover it — that is b13.** |
| **`WriteOffClawbackCommand`** | Command | `POST api/v1/admin_clawbacks/{id}/write_off` | Admin marks a `pending` clawback `written_off` (uncollectable) with a reason; posts the balancing ledger correction (`DEBIT bad_debt` / `CREDIT nurse_clawback_receivable`) and sets `resolved_at`. (Recovery via payout netting is b13.) |
| **`IssueInvoiceCommand`** | Command | `POST api/v1/admin_invoices` (and reused on confirmation) | Creates an `invoices` row for a booking: **sequential `invoice_number`** from the safe sequence; copies `gross_irr` / `platform_commission_irr` / `bnpl_commission_irr` from the booking; reads **`vat_rate` from config** (default `0.10`); computes `vat_irr = round(platform_commission_irr * vat_rate)` (integer-only, VAT **on the commission only**, never the nurse's earnings — set `vat_irr = 0` when a medical-service exemption sets `vat_rate = 0`); attempts **`IMoadianClient.SubmitAsync`** which (mock) returns no ref → `moadian_reference_number = null`, `moadian_status = pending`. Idempotent per booking (one issued invoice per booking; re-issue returns the existing). |
| **`ListRefundsQuery`** | Query | `GET api/v1/admin_refunds?booking_id=&status=&page=&page_size=` | Admin refund worklist: projected (AsNoTracking + `.Select`) + paginated; surfaces channel, decomposed legs, status, `expected_customer_refund_eta`, the policy snapshot. |
| **`GetRefundStatusQuery`** | Query | `GET api/v1/refunds/{id}/status` (customer-visible, tenancy-scoped) | The customer-facing status of *their* refund: `status`, `refund_channel`, `amount`, and **`expected_customer_refund_eta`** (the BNPL 7–10-business-day window) — so f10 can show "on its way, ~N days". Tenancy-scoped to the booking's customer via `ICurrentUser`. |
| **`GetInvoiceQuery`** | Query | `GET api/v1/invoices/{booking_id}` (customer/admin) | The booking's invoice: `invoice_number`, `gross_irr`, `platform_commission_irr`, `vat_rate`, `vat_irr`, `moadian_status`, and a `pdf_storage_key`-derived download URL when present. Tenancy-scoped. |

- **Cancellation integration (b9 → refund):** b9's `CancelBooking` / `CancelSession` resolves the policy
  and computes the refundable amount per un-started session. **This phase exposes `CreateRefundCommand` as
  the money-side of that flow** — b9 (or admin) calls it with the booking/session, the resolved %, and the
  ticket. Do **not** duplicate the policy resolver; consume its snapshot.
- **Controllers:** `AdminRefundsController` (admin policy; refund endpoints **rate-limited** —
  refund-sensitive per `CONVENTIONS.md` §11), `AdminClawbacksController` (admin policy),
  `AdminInvoicesController` (admin policy), and a customer-facing `RefundsController` / `InvoicesController`
  (authenticated, tenancy-scoped) for `GetRefundStatusQuery` / `GetInvoiceQuery`. All `sealed :
  BaseController`, inject `ISender`, return `base.OperationResult(...)`, snake_case `[controller]` /
  `[action]` routes, `CancellationToken` threaded.
- **Validators:** FluentValidation on `CreateRefundCommand` (positive `amount`; legs sum to `amount`;
  `amount > 0`; `ticket_id` required when the gate is on; channel matches the transaction type) and the
  id-bearing commands.

### 3.3 DEFERRED (build the seam/flag, not the feature)
- **Clawback *recovery / netting* into a payout** — DEFERRED to [b13](./backend-phase-13.md). This phase
  only opens the `pending` receivable + supports `write_off`. Leave `recovered_in_payout_id` /
  `original_payout_id` as the (nullable) join points b13 fills.
- **Automated nurse no-show penalty / forfeiture** — a **manual admin action** at launch per
  [`product/business/07-cancellation-and-refunds.md`](../../../product/business/07-cancellation-and-refunds.md) §(c);
  do not automate. The admin uses `CreateRefundCommand` (full customer refund) and records the nurse
  penalty manually.
- **Self-service partial-refund UI** and **holiday-specific cancellation overrides** — DEFERRED (no
  customer refund-initiation path; the policy override model is out of scope).
- **Real مودیان automation** — DEFERRED; the seam returns a null/pending ref now (see §4). The
  reconciliation job that flips `moadian_status` to `registered` and the BNPL-revert reconciliation job
  that clears `refund_payable ↔ escrow_held` are **thin/manual-trigger** now; note the cron in the report.

## 4. Mocks & seams in this phase

| Seam | Owner | Mock behaviour | Registry |
| --- | --- | --- | --- |
| **`IMoadianClient`** | **introduced here** | `SubmitAsync(InvoiceSubmission, ct)` → leaves `moadian_reference_number = null`, returns `moadian_status = pending` (no external call). A config switch can force a deterministic `registered` (with a fake 22-digit ref) so the reconciliation/`registered` path is testable. The real سامانه مودیان adapter is a drop-in. | **add a new row** (🟡) |
| `IPaymentProvider` | reuse from **b10** | `RefundAsync(gatewayReferenceCode, amountIrr, idempotencyKey, ct)` → deterministic `gateway_refund_reference`, instant `Succeeded`, echoes amount; channel `psp_card`. | reuse row |
| `IBnplProvider` | reuse from **b12** | `RevertAsync` / `UpdateAsync` → echoes the reverted/new amount, returns an `external_revert_reference` + nullable `provider_commission_reversed_amount`, `settledAt`-style lag; channel `bnpl_revert`. **Until b12 lands**, register a thin local mock behind this interface so the `bnpl_revert` path is exercised; b12 owns the real seam definition. | reuse row (note pre-b12) |
| `IWebhookVerifier` | reuse from **b10** | verifies the async BNPL cash-back/reconciliation callback that flips a `processing` refund to `succeeded` and posts the `refund_payable ↔ escrow_held` clearing leg. | reuse row |
| `IDistributedLock` | reuse from **b10** | in-memory mock lock; `lock(booking:{id}:refund)` around the whole refund money-path so a cancellation-driven and a webhook-driven refund can't both fire (keeps `Σ refunded ≤ captured`). | reuse row |
| `IFieldEncryptor` | reuse from **b0** | local symmetric key; never logs plaintext. | reuse row |
| `INotificationDispatcher` | reuse from **b1** | in-app write; notifies the customer on refund issued/completed; raises a `support_alert` on every clawback. | reuse row |
| `ICacheService` | reuse from **b0/b1** | in-memory; behind the typed config accessor (`vat_rate`, ETA config). | reuse row |
| `IObjectStorage` | reuse from **b0** | local-disk/in-memory; stores the optional invoice `pdf_storage_key`. | reuse row |

The mock lives behind a **DI-registered interface** in Infrastructure (real impl is a drop-in later);
provider/مودیان selection is **config-driven, never** an `if (mock)` branch in a handler. Append the
`IMoadianClient` row to
[`../../shared-working-context/reports/mocks-registry.md`](../../shared-working-context/reports/mocks-registry.md)
(seam, file, what's faked, config keys, **step-by-step how to make it real** — سامانه مودیان enrollment,
the معاملات/invoice submission API, the 22-digit reference shape, the `pending → submitted → registered`
reconciliation callback). Confirm the BNPL `IBnplProvider` row notes the pre-b12 local stub if you add one.

## 5. Critical rules you must not get wrong

**Money correctness is sacred — the following must hold verbatim:**

- **Money is IRR `BIGINT`, no floats, ever.** Every amount (`amount`, `platform_fee_refunded_irr`,
  `nurse_payout_refunded_irr`, `amount_irr`, `gross_irr`, `platform_commission_irr`, `vat_irr`) is
  `long`/`BIGINT`. VAT is `round(platform_commission_irr * vat_rate)` computed integer-only; **no float
  path**. Toman conversion happens only inside a provider adapter at its boundary.
- **Gross = commission + payout.** A refund **decomposes across both fee legs** —
  `amount = platform_fee_refunded_irr + nurse_payout_refunded_irr`, derived pro-rata from the booking's
  `balinyaar_commission_irr` / `nurse_payout_amount` at the resolved %. The two legs are never conflated
  and must always sum to the refunded `amount`.
- **`Σ refunded ≤ captured` (handler invariant).** Refunds are **1:N** per `payment_transaction`; the sum
  of all succeeded/processing refunds for a transaction may never exceed the captured amount. Enforce in
  the handler under `lock(booking:{id}:refund)`; the lock is the fast first line, the summed check is the
  authoritative backstop.
- **Append-only, balanced ledger.** Every refund/clawback posts balanced legs (Σdebit = Σcredit) under one
  `transaction_group_id`, via b10's helper. **Never UPDATE/DELETE a ledger row;** corrections (e.g. a
  write-off) are *new* balancing postings. Balances are derived by filtering `ledger_entries`, never a
  stored column.
- **Refund-before-payout is a clean reversal; refund-after-payout drives a `nurse_clawbacks` receivable.**
  Pre-payout: `DEBIT platform_revenue` + `DEBIT nurse_payable` / `CREDIT refund_payable`. Post-payout:
  `DEBIT nurse_clawback_receivable` (+ `DEBIT platform_revenue`) / `CREDIT refund_payable` **and** a
  `pending` `nurse_clawbacks` row — **because an Iranian IBAN transfer is irreversible**, so the money is
  already gone and must be recorded as owed-back, never silently absorbed. **Gate payout on
  `dispute_window_ends_at`** (b9/b13) so the pre-payout path is the common one; the clawback is the
  fallback, not the plan.
- **Refunds are admin-only (no customer self-service) and must link a `ticket_id`.** There is no
  customer refund-initiation path — only `GetRefundStatusQuery` is customer-visible. The `ticket_id`
  requirement is enforced (config-gated until b15 ships `tickets`); the FK is nullable now only for that
  forward-dep.
- **VAT applies to the platform COMMISSION only — never the nurse's earnings.** `vat_irr` is computed on
  `platform_commission_irr` with a **config-driven rate (default `0.10`)**; the nurse is the taxable
  seller of the care service (Snapp/Tapsi precedent). A `vat_rate = 0` exemption sets `vat_irr = 0`.
  Never apply VAT to `nurse_payout_amount`.
- **`invoice_number` is unique + sequential.** Generate gap-free from a concurrency-safe sequence/locked
  counter — never random or timestamp-derived. One issued invoice per booking (idempotent).
- **Card refund and `bnpl_revert` post the SAME ledger legs.** The only differences are `refund_channel`,
  the external reference (`gateway_refund_reference` vs `external_revert_reference`), and the ETA
  (`expected_customer_refund_eta` null for card vs ~7–10 business days for BNPL, with `status =
  processing` until reconciled). Do not branch the *ledger* on channel — only the execution + metadata.
- **BNPL refunds go through the provider revert API only.** Money *always* flows
  `customer ↔ provider ↔ Balinyaar` — **never** nurse→customer or Balinyaar→customer direct. Full =
  `revert`, partial/shortened = `update` (strictly-lower amount). The provider's own commission reversal
  is `provider_commission_reversed_amount` — **nullable, reconciled from the response, never hardcoded.**
- **Idempotency on the money path.** Channel calls carry an `idempotencyKey`; the async cash-back
  confirmation flows through `payment_webhook_events` (`UNIQUE(provider_code, external_event_id)`) so a
  replayed "refunded"/"reverted" callback can't double-clear `refund_payable` or double-post. The refund
  `status` state machine (`requested → approved → processing → succeeded|failed`) is forward-only.
- **Tenancy & scope.** `GetRefundStatusQuery` / `GetInvoiceQuery` are scoped to the booking's customer via
  `ICurrentUser`; a customer can never read another customer's refund/invoice. All create/write endpoints
  sit behind the **admin** policy and are rate-limited.

## 6. Definition of Done

The shared [definition-of-done.md](../_shared/definition-of-done.md), plus:
- [ ] The three tables (`refunds`, `nurse_clawbacks`, `invoices`) exist via one migration, each with its
      `IEntityTypeConfiguration<T>`: `refunds` with the **nullable `ticket_id` FK**, the decomposition
      columns, `refund_channel`, the `amount = fee_leg + payout_leg` CHECK where possible; `nurse_clawbacks`
      with nullable `original_payout_id` / `recovered_in_payout_id`; `invoices` with **`invoice_number`
      UNIQUE** + the sequential generator and `vat_irr` on the commission line; soft-delete/audit wiring.
- [ ] All §3.2 commands/queries implemented (CQRS, `OperationResult`, projected + paginated reads,
      validators), with the admin + customer controllers.
- [ ] **`IMoadianClient`** introduced (Application interface, Infrastructure mock, DI registration via a
      `ServiceConfiguration/` extension, config-selected). No `if (mock)` in handlers. `IBnplProvider`
      reused (with a noted pre-b12 local stub if b12 isn't merged), `IPaymentProvider`/`IWebhookVerifier`/
      `IDistributedLock`/`INotificationDispatcher` reused.
- [ ] Refund decomposition + `Σ refunded ≤ captured` correct; the **pre-payout reversal** and the
      **post-payout clawback** both post balanced ledger groups; the `refund_payable ↔ escrow_held`
      clearing posts on confirm; the invoice computes `vat_irr` from config on the commission with a
      sequential number.
- [ ] Handler unit tests (NSubstitute) for: pre-payout balanced reversal; partial-refund leg decomposition
      + `Σ refunded ≤ captured` rejection; post-payout clawback creation + receivable leg; invoice VAT
      computed from config + sequential numbering; channel parity (card vs bnpl_revert same legs). ≥1
      `WebApplicationFactory` integration test per controller (happy path, 401, validation 400, 409 on
      over-refund). `dotnet build Baya.sln` zero new warnings; `dotnet test Baya.sln` green.
- [ ] The `Baya.Application/Features/Refunds/**` + `…/Invoices/**` areas are reflected in the **Project
      map** in `server/CLAUDE.md`; the `IMoadianClient` seam noted where seams are documented; the
      `tickets` forward-dep and the `manual`/`manual_bank` channel-code decision recorded.
- [ ] The contract `dev/contracts/domains/refunds-invoices.md` written and the `swagger.json` snapshot
      republished.

## 7. How to test (what a human can verify after this phase)

Seed (or reuse from prior phases) a booking with a **captured card payment** (b10) and a resolved
cancellation policy snapshot (b9), plus one booking flagged as **already-paid-to-nurse** and one **BNPL**
booking.

1. **Pre-payout full refund (clean reversal)** — `POST api/v1/admin_refunds` for the captured card
   booking with the resolved % and a ticket → a `refunds` row with `refund_channel = psp_card`, decomposed
   `platform_fee_refunded_irr` + `nurse_payout_refunded_irr` summing to `amount`; the **ledger** shows a
   balanced `DEBIT platform_revenue` + `DEBIT nurse_payable` / `CREDIT refund_payable`, and on confirm a
   `DEBIT refund_payable` / `CREDIT escrow_held` clearing leg (Σdebit = Σcredit); status → `succeeded`.
2. **Partial refund + over-refund guard** — issue a **partial** refund (e.g. 50%): legs decompose
   correctly and sum to the partial `amount`; `Σ refunded` for the transaction stays ≤ captured. Then
   attempt a second refund that would push the total **over** the captured amount → rejected with `409`
   (or validation `400`); no ledger posting occurs.
3. **Issue an invoice** — `POST api/v1/admin_invoices` for the booking → an `invoices` row with a
   **sequential `invoice_number`**, `vat_irr = round(platform_commission_irr * 0.10)` (verify it is
   computed from config on the **commission**, not the nurse payout, and `vat_irr = 0` when `vat_rate` is
   set to 0); `moadian_reference_number = null`, `moadian_status = pending`. Issue a second invoice for a
   second booking → the number is the **next** in sequence (gap-free, unique).
4. **Refund on an already-paid booking (clawback)** — `POST api/v1/admin_refunds` for the
   already-paid-to-nurse booking → instead of debiting `nurse_payable`, the ledger posts `DEBIT
   nurse_clawback_receivable` (+ `DEBIT platform_revenue`) / `CREDIT refund_payable`, **a `nurse_clawbacks`
   row is created in `pending`** (`amount_irr = nurse_payout_refunded_irr`), and a `support_alert` is
   raised. Confirm it is **not** auto-recovered (recovery is b13).
5. **BNPL revert (channel parity + ETA)** — `POST api/v1/admin_refunds` for the BNPL booking →
   `refund_channel = bnpl_revert`, `IBnplProvider.RevertAsync` called, `external_revert_reference` stored,
   `expected_customer_refund_eta` ≈ now + 10 business days, status `processing`; the **ledger legs are
   identical** to the card case. `GET api/v1/refunds/{id}/status` as the customer shows the ETA window.
6. **Write-off** — `POST api/v1/admin_clawbacks/{id}/write_off` → the `pending` clawback → `written_off`
   with a balancing `DEBIT bad_debt` / `CREDIT nurse_clawback_receivable` and `resolved_at` set.
7. **Admin worklist + tenancy** — `GET api/v1/admin_refunds?status=processing` lists channel/legs/ETA;
   `GET api/v1/refunds/{id}/status` as a **different** customer is **not** visible (403/404).

## 8. Hand off & document (close the phase)

- **Docs to update:** the **Project map** in [`server/CLAUDE.md`](../../../server/CLAUDE.md) (add the
  `Features/Refunds/**` + `Features/Invoices/**` areas + the `IMoadianClient` seam). If you discover/confirm
  a rule the product docs don't capture — e.g. the canonical `manual` vs `manual_bank` channel code, the
  `bnpl_refund_eta_business_days` default, the `vat_rate = 0` exemption behaviour, or the
  `ticket_id`-config-gate until b15 — record it in
  [`product/business/07-cancellation-and-refunds.md`](../../../product/business/07-cancellation-and-refunds.md)
  / [`product/data-model/06-payments-ledger-and-refunds.md`](../../../product/data-model/06-payments-ledger-and-refunds.md)
  (and regenerate the HTML view per `product/CLAUDE.md`). **Don't invent rules.**
- **Contract to write:** **`dev/contracts/domains/refunds-invoices.md`** (per
  [`../../contracts/domains/_TEMPLATE.md`](../../contracts/domains/_TEMPLATE.md)) — the admin refund/
  clawback/invoice endpoints (create refund, write-off clawback, issue invoice, list refunds) and the
  customer-facing `refunds/{id}/status` + `invoices/{booking_id}`; the `refund_status` /
  `refund_channel` / `clawback_status` / `moadian_status` enums; the refund/invoice DTO shapes (IRR
  `BIGINT` as digit-strings, the decomposed legs, **masked** references, `expected_customer_refund_eta`);
  auth/rate-limit/idempotency notes; the admin-only + ticket-link + dispute-window/clawback side-effects.
  Republish the `swagger.json` snapshot per
  [`../../contracts/openapi/README.md`](../../contracts/openapi/README.md). This is what **f10-b11**
  consumes.
- **Handoff & report:** write `dev/shared-working-context/backend/handoff/after-backend-phase-11.md` (the
  refund/clawback/invoice engine is live, what f10 can now build — admin refund console + the
  customer-facing cancellation/refund-status + invoice views — which endpoints/contracts are live, that
  مودیان is mocked behind `IMoadianClient`, that clawback *recovery* waits on b13 and `tickets` on b15),
  append to `backend/STATUS.md`, write
  `dev/shared-working-context/reports/backend-phase-11-report.md` (what was built, **what is now testable
  and exactly how** per §7, what is mocked + how to make it real, contracts produced, follow-ups: the
  مودیان reconciliation cron, the BNPL-revert reconciliation cron clearing `refund_payable ↔ escrow_held`,
  clawback netting in b13, the `tickets` FK wire-up in b15), and update
  `dev/shared-working-context/reports/mocks-registry.md` (the `IMoadianClient` row → 🟡; reconfirm the
  reused seam rows).
- **Memory:** save a `project` memory note for the non-obvious decisions this phase fixes — the
  fee-leg/payout-leg decomposition, the **pre-payout reversal vs post-payout clawback fork** (and *why*
  Iranian transfers are irreversible), the `refund_payable ↔ escrow_held` two-step clearing, channel
  parity (card vs bnpl_revert post the same legs), VAT-on-commission-only with a config rate, the
  sequential `invoice_number` generator, and the `tickets`/`nurse_payouts` forward-dep nullable FKs — with
  a one-line pointer in `MEMORY.md`.