baya-monorepo/archive/docs/flows/checkout-and-payment.md

# Flow — Checkout & payment

> Last verified: 2026-08-02 against commit `c841bde`

**Actor(s):** customer · **Status:** partial
**Client:** partial · **Server:** partial
**Business source:** [product/business/08-payments-and-escrow.md](../../product/business/08-payments-and-escrow.md) ·
[product/payments/escrow-ledger.md](../../product/payments/escrow-ledger.md) ·
[product/business/13-tax-invoicing-and-legal.md](../../product/business/13-tax-invoicing-and-legal.md)
**Integration:** [docs/integration/domains/payment.md](../integration/domains/payment.md) ·
[docs/integration/api-contract.md](../integration/api-contract.md)

## What it does

The customer's nurse accepted, a 30-minute payment window is running, and the family pays the whole service
price on a card. Balinyaar never creates the booking on "the user tapped pay" — the booking, the balanced
escrow ledger group and the commission invoice all come into existence inside the PSP's webhook, after the
server re-verifies the capture with the acquirer. Everything before that is a redirect.

## Screens

| Step | Route | Component / notes |
| --- | --- | --- |
| C6 summary & pay | `/fa/bookings/checkout?request_id=` | [`checkout/page.tsx`](../../client/src/app/%5Blocale%5D/(private-routes)/(customer)/bookings/checkout/page.tsx) — nurse identity card, served `PriceBreakdown`, `CountdownTimer` on the frozen `paymentDeadlineAt`, `EscrowExplainer`, `StickyActionBar`. Non-payable statuses render a `PaymentStateCard` instead of a CTA (`:92-124`) |
| Return from gateway | `/fa/bookings/checkout/return` | `useConfirmGatewayReturn` fires once per mount (`confirmFiredRef`), then the `StatusTimeline` pending-callback state backed by the backoff poll; terminal → `invalidateAfterPaymentSuccess` → confirmation |
| Receipt | `/fa/bookings/checkout/confirmation` | Paid total, copyable LTR کد پیگیری, Shamsi paid-at, method, booking deep-link, «دانلود فاکتور». Shared with the BNPL branch via `?method=bnpl` |
| Money hub | `/fa/wallet` | 4 tabs; «پرداخت‌ها»/«رسیدها» merge card + BNPL rows in `useWalletHistoryRows.ts` |
| Invoice | `/fa/bookings/[id]/invoice` | A4-printable commission invoice, VAT-on-commission line, مودیان status chip |

## API

| Call | Endpoint | Notes |
| --- | --- | --- |
| Checkout summary | `GET booking_requests/checkout_summary/{id}` | **Live — probed `200`.** `clientApi.ts:35-42` |
| Initiate | `POST bookings/{bookingRequestId}/payments` | `clientApi.ts:44-50`; **one of only two endpoints that read `Idempotency-Key`** (`PaymentsController.cs:34`; the other is `CheckoutBnplController.cs:41`) |
| Outcome poll | `GET booking_requests/get/{id}` | No transaction read exists; `clientApi.ts:56-80` maps request status → `succeeded`/`failed`/`pending` |
| Invoice | `GET invoices/{bookingId}` | `clientApi.ts:82-83` |
| PSP callback | `POST webhooks/payments/{provider}` | anonymous, server-only |
| Payment history | `GET bookings/payment_history` | **Phantom — probed `404`** (REQ-047) |

Shapes live in [payment.md](../integration/domains/payment.md); the request DTO in
[booking-requests.md](../integration/domains/booking-requests.md).

## Rules that must hold

| Rule | Value | Where |
| --- | --- | --- |
| Three-amount split | `gross = balinyaar_commission + nurse_payout`, all ≥ 0 | DB CHECK `CK_Bookings_AmountSplit` (`BookingConfig.cs:13-17`) — [business/08](../../product/business/08-payments-and-escrow.md) |
| Commission rate | `0.15` — a **seeded `platform_configs` default**, not a product mandate | key `platform_fee_rate`; read at conversion (`BookingConversion.cs:45`) |
| Rate is snapshotted | frozen onto `Bookings.PlatformFeeRate` at conversion, never re-read | `BookingFactory.Create`; a later rate change is never retroactive |
| VAT | `0.10`, **on Balinyaar's commission line only** — never the gross, never the payout | key `vat_rate`; [business/13](../../product/business/13-tax-invoicing-and-legal.md), [platform-summary GT-2](../../product/overview/platform-summary.md) |
| Payment window | `30` min, server-frozen onto `BookingRequests.PaymentDeadlineAt` | key `booking_payment_deadline_minutes`; [business/05](../../product/business/05-booking-and-scheduling.md) |
| Money on the wire | IRR integer — **digit string outbound, `int64` inbound**. Never `Number()`; parse with the BigInt helpers | `GetCheckoutSummaryQuery.Handler.cs:72` (`Str()`); client rule 18 |
| Ledger balances | `CardCapture` = DEBIT `escrow_held` gross / CREDIT `platform_revenue` commission + `nurse_payable` payout, one group | `LedgerPosting.cs:26-36` **throws** rather than persist an unbalanced group |
| Ledger is append-only | corrections are new balancing groups, never edits | `LedgerEntryConfig.cs`; [escrow-ledger.md](../../product/payments/escrow-ledger.md) |
| Escrow release | only after a **confirmed check-out** and a closed 72 h dispute window — never on `completed` alone | `Bookings/Commands/CheckOutVisit/CheckOutVisitCommand.Handler.cs` (the booking-lifecycle flow file is not written yet — see [flows index](index.md)) |
| The platform holds no cash | «escrow» is a ledger state over funds custodied at the licensed provider (GT-1) | [platform-summary](../../product/overview/platform-summary.md) |
| Webhook idempotency | upsert `payment_webhook_events` on `(provider, external_event_id)` **first**, then re-verify with the acquirer, then confirm | `HandlePaymentWebhookCommand.Handler.cs:31-36, 76-85, 88` |
| One succeeded payment | filtered `UNIQUE(booking_id) WHERE status='succeeded'`; a unique-violation on confirm is idempotent **success** | `ConfirmPaymentAndPostLedgerCommand.Handler.cs:69-75` |
| `409` on initiate is benign | "already paid / not awaiting payment / window lapsed" — converge, never toast | handler `:35-43`; client `checkout/page.tsx:145-149` |

### ⚠ The same commission is taxed two different ways

Probed live on **booking 8 / request 13**, gross `250000`, commission `37500`:

| Surface | VAT | Method |
| --- | --- | --- |
| `checkout_summary/13` | **`3409`** | `commissionNet = round(commission / (1 + vatRate))`, VAT carved **out** (`GetCheckoutSummaryQuery.Handler.cs:44-46`) |
| `invoices/8` | **`3750`** | `vat = round(commission × vatRate)`, VAT **additive** (`IssueInvoiceCommand.Handler.cs:37-38`) |

Both reconcile internally (checkout: `212500 + 34091 + 3409 = 250000`; invoice: `37500 + 3750 = 41250`) but
they disagree by 341 IRR on one booking. No product file resolves it. Never state "VAT is additive/inclusive"
without naming the surface.

## How to test

Log in as **`09120000010`** (سارا محمدی, customer) — see [testing-setup.md](testing-setup.md) for boot, the
OTP and the demo accounts.

> **The pristine seed has nothing to pay for.** Every seeded request has aged past its window: ids 6,7,8,9,12,13
> are `converted`, 2 is `payment_deadline_expired`, 1 is `expired_no_response`, 3 is `rejected_by_nurse`. The
> seed contains **no** `accepted_awaiting_payment` request — you must make one (step 4) to reach a payable C6.
> **The live DB is not pristine:** this session's `booking_requests/list` for `…010` also returned **21**
> (`accepted_awaiting_payment`, live deadline) and **22** (`cancelled_by_customer`), both left by earlier
> walk-throughs. Re-list before assuming an id's state.

**Walk the read-only half (works today):**

1. Open `/fa/bookings/checkout?request_id=13`. **Expect:** the already-paid convergence card («این رزرو
   پرداخت شده است»), not a pay button — the summary returns `requestStatus: "converted"`.
2. Open `/fa/bookings/8/invoice`. **Expect:** `INV-0000000008`, VAT row labelled `۱۰٪`, مودیان chip
   «در انتظار» (`moadianStatus: "pending"` — the mock `IMoadianClient` returns `registered` **only** when
   `Seams:Moadian:ForceRegistered` is on, and it is off by default), no PDF button (`pdfUrl: null`).
3. Open `/fa/wallet` → «پرداخت‌ها». **Expect:** the empty state, *not* an error — `bookings/payment_history`
   404s and the BNPL half is mock-empty (`useWalletHistoryRows.ts`).

**Create something payable (the workaround):**

4. As `09120000010`: search → C4 → submit a booking request. As **`09120000001`** (زهرا عزیزی): accept it from
   the nurse inbox. **Expect:** status `accepted_awaiting_payment` and a 30-minute countdown. (If a leftover
   payable request is still inside its window — id `21` at this stamp — reuse it and skip to step 5.)
5. Return to `/fa/bookings/checkout?request_id=<new>`. **Expect:** the money breakdown, the live countdown,
   and an enabled «پرداخت».
6. **Do not tap «پرداخت» in the browser** — see the first gap. Instead capture from the CLI:
   `POST /api/v1/bookings/convert {"bookingRequestId": <new>}` with the customer's bearer.
   **Expect:** `200` with the booking detail, request → `converted`, and two notifications of *different*
   types (`booking_confirmed` to the customer, `booking_confirmed_nurse` to the nurse).
   **But:** this path posts **no ledger group, no `payment_transactions` row, no invoice and no coordination
   ticket** (`ConvertRequestToBookingCommand.Handler.cs` — it stops at `CommitAsync` + notify), so
   `GET /invoices/{newBookingId}` will `404`. Only the webhook path (`ConfirmPaymentAndPostLedger…:58-98`)
   produces the full money record.

**Live probe results at this stamp** (customer `…010`, every curl `--noproxy '*'`):

- `checkout_summary/13` → `200`; `vatIrr "3409"`, `grossPriceIrr "250000"`, `balinyaarCommissionIrr "37500"`.
- `checkout_summary/21` (a genuinely payable request) → `200`, `requestStatus "accepted_awaiting_payment"`.
- **`POST bookings/21/payments` + `Idempotency-Key` → `200`, `redirectUrl
  "https://mock-psp.local/pay/mock-ref-21-<key>"`.** The dead end below is probed on a payable request, not
  inferred from the 409 path.
- `POST bookings/13/payments` + `Idempotency-Key` → `409 "This booking has already been paid."`
- `bookings/payment_history` → `404` · `booking_requests/get/13` → `200` with `bookingId: 8` ·
  `invoices/8` → `200`; `vatIrr "3750"`, `totalIrr "41250"`, `moadianStatus "pending"`, `pdfUrl null`.

## Known gaps

- **Tapping «پرداخت» dead-ends the browser.** `MockPaymentProvider.cs:20` returns
  `https://mock-psp.local/pay/{ref}` — a non-existent host — and `checkout/page.tsx:137-140` does
  `window.location.assign` on any absolute URL. The customer lands on a DNS error and never returns.
  **Probed:** `POST bookings/21/payments` really does return that URL with a `200`. The local card-gateway
  harness page (`checkout/gateway/page.tsx`) was deleted in `64f6aa4`, so nothing catches the hop.
- **Nothing fires the PSP webhook locally**, so no *new* card payment reaches `ConfirmPaymentAndPostLedger` in
  dev: the `payment_transactions` row stays `pending`, no ledger group is posted, no invoice is issued.
  `bookings/convert` substitutes for the *booking*, not for the money. The succeeded transactions and invoices
  you can read today (booking 8) are **seeded**, not reproducible from the UI — so the flow's core invariant is
  observable only as data, never as behaviour.
- **A verified nurse is shown as unverified on the payment screen.** `CheckoutSummaryDto` (client
  `types.ts:46-47`) declares `nurseAvatarUrl` and `nurseVerified`; the server DTO constructs neither
  (`GetCheckoutSummaryQuery.Handler.cs:48-67`, absent from the probed payload), so `nurseVerified` is
  `undefined` → `<TrustBadge state="unverified">` at `checkout/page.tsx:326`. REQ-046.
- **`sessionCount` is served but nullable, and the client types it as non-null.** The server *does* emit the
  field (`"sessionCount": null` on requests 13 and 21 — `ctx.SessionCount` is `int?`, defaulted to `1` only
  for the internal `gross` maths); the client declares `sessionCount: number` (`types.ts:52`) and feeds it
  straight into the ICU label `row_service_cost_with_count` at `checkout/page.tsx:265`. UNVERIFIED how
  next-intl renders a null `count` — not reproduced in a browser this session.
- **The confirmation screen cannot deep-link to the booking.** `booking_requests/get/{id}` **does** serve
  `bookingId` (probed `8`), but `clientApi.ts:58` types the response as `Omit<…,'bookingId'>` and `:73`
  hardcodes `bookingId: null`. Hardening issue H-10. The receipt also always hides کد پیگیری and paid-at
  (`:76-77`).
- **The client's payment constants and comments are stale and mislead the reader:** `clientApi.ts:36-37` says
  `checkout_summary` "404s until the backend delivers it" (it returns `200`); `constants.ts:5-16` still says
  "Mock is primary this phase" and "the contract serves no checkout summary" while `USE_PAYMENT_MOCK = false`;
  and `constants.ts:53` hardcodes `MOCK_PLATFORM_FEE_RATE = 0.12` against the server's seeded `0.15`. Only the
  last is money-shaped, and it is unreachable while the mock is off.
- **The invoice screen derives a money row.** `invoice/page.tsx:135` computes
  `serviceIrr = gross − commission − vat` = `208750` for booking 8, but the real nurse payout is `212500` —
  wrong by exactly the VAT, because VAT is additive and not part of gross. It also labels `invoice.grossIrr`
  as the invoice total while the served `totalIrr` (`41250`, the commission invoice) is never shown. Violates
  client rule 18 ("the client displays money; it never computes it").
- **The wallet «پرداخت‌ها» tab is permanently empty** for a card-paying customer — `bookings/payment_history`
  is a live `404` on every visit (REQ-047).
- **`InvoiceDto` serves no payment method, transaction reference or seller fiscal identity** (REQ-049), so
  those rows never render on the real path.
- **The escrow ledger has no read surface.** `ledger_entries` is exposed only through
  `GetNursePayableBalance`; a customer, an admin and a tester have no way to see the balanced capture group
  the flow's core invariant depends on.
- **`GET invoices/{bookingId}` is `[Authorize]` only** (`InvoicesController.cs:17`); tenancy is enforced inside
  `GetInvoiceQuery`. Not re-probed cross-tenant this session — UNVERIFIED that a foreign customer gets `404`.