hamid
56 lines
4.2 KiB
Markdown
56 lines
4.2 KiB
Markdown
# Handoff — after backend phase 10 (Payments core: ledger, transactions, webhooks & card capture)
|
|
|
|
**The money core is live.** A family can now pay the gross price by card: **initiate → PSP webhook confirms →
|
|
the balanced card-capture ledger group posts → the booking converts/confirms**. The PSP acquirer, تسهیم split,
|
|
webhook signature verify, and the distributed lock are **mocked behind seams**; the DB constraints are the
|
|
authoritative money-path backstops.
|
|
|
|
## What f9-b10 can now build
|
|
- **Summary & pay (C6)** — after the nurse accepts, `POST api/v1/bookings/{bookingRequestId}/payments` (as the
|
|
customer, with an `Idempotency-Key` header) → `{ transactionId, redirectUrl, gatewayReferenceCode }`. Show
|
|
the checkout summary (gross + commission/VAT/escrow notice) and send the payer to `redirectUrl`. **Never show
|
|
the internal `account_type`s** — gross + the commission/VAT breakdown only.
|
|
- **Card payment redirect + confirmation** — the (mock) redirect completes; the PSP callback hits
|
|
`POST api/v1/webhooks/payments/{provider}` and confirms. Poll the booking (b9 `bookings/list` /
|
|
`bookings/get`) → it appears **`confirmed`** once the webhook captures. (A booking exists only on capture.)
|
|
- **Nurse payable balance** — `GET api/v1/nurses/{nurseId}/payable_balance` (the nurse themself or admin) →
|
|
`{ nurseId, balanceIrr }` as a digit-string, derived from the ledger.
|
|
|
|
## Live endpoints / contracts
|
|
- Contract: [`dev/contracts/domains/payments.md`](../../contracts/domains/payments.md).
|
|
- Enums: `payment` status (`pending`/`succeeded`/`failed`), `payment_gateways.type` (`standard`/`bnpl`),
|
|
`processing_status` (`received`/`processed`/`failed`/`ignored`), the eight `account_type`s (internal).
|
|
|
|
## Load-bearing rules the client must honour
|
|
- **Money is IRR integer, on the wire as a digit-string.** Never coerce to a JS number for math.
|
|
- **The booking is created & confirmed on capture (the webhook), not on initiate.** After `initiate` you have a
|
|
redirect only; the `bookings` row appears when the PSP callback confirms.
|
|
- **Payment is idempotent end-to-end** — a retried `initiate` (same `Idempotency-Key`) reuses the attempt; a
|
|
replayed webhook is a no-op; a repeat `initiate` after capture is a `409`.
|
|
- **Internal account types are never exposed to the customer** — checkout shows gross + commission/VAT only.
|
|
|
|
## Design note (reconciling b10 with b9's as-built)
|
|
b9 creates the `bookings` row **on capture** (it never persists a standalone `pending_payment` booking). So b10
|
|
initiates payment against the `accepted_awaiting_payment` **request**; `payment_transactions.booking_id` is
|
|
**nullable**, bound only at confirm. Confirm reuses b9's conversion/amount logic through the extracted
|
|
**`BookingFactory`** (no duplication) and posts the ledger + registers the split. The mock
|
|
`IPaymentCaptureSimulator` + the `POST bookings/convert` endpoint **stay** (b9's own tests use them); the real
|
|
capture path uses `BookingFactory` directly, not that seam.
|
|
|
|
## Mocked here → make real later (see reports/mocks-registry.md)
|
|
- **`IPaymentProvider`** (🟡) — deterministic ref + fake redirect; `VerifyAsync` instant-succeeds. Real:
|
|
ZarinPal/Sadad/Vandar/Jibit acquirer-with-تسهیم, merchant id from encrypted `config_json`, server-side verify.
|
|
- **`ISettlementSplitProvider`** (🟡) — records split intent, returns `Settled`. Real: split-by-ratio to
|
|
registered SHEBAs; provider credits IBANs directly.
|
|
- **`IWebhookVerifier`** (🟡) — signature valid unless a marker; parses a test JSON body. Real: per-provider
|
|
HMAC / mandatory server-side verify.
|
|
- **`IDistributedLock`** (🟡) — in-process semaphore. Real: StackExchange.Redis lease, key `booking:{id}:payment`.
|
|
|
|
## Consumed by later backend phases
|
|
- **b11** — refunds/clawbacks/invoices post against the ledger (`refund_payable`/`nurse_clawback_receivable`
|
|
account types are already defined); `IPaymentProvider.RefundAsync` is ready to call.
|
|
- **b12** — BNPL settle routes callbacks through the **same** `payment_webhook_events` idempotency store and
|
|
posts the BNPL-settle group (adds `bnpl_fee_expense`).
|
|
- **b13** — payouts read `GetNursePayableBalance` (the signed `nurse_payable` ledger sum) and post
|
|
DEBIT `nurse_payable` / CREDIT `escrow_held`, gated on b9's `dispute_window_ends_at`.
|