baya-monorepo/archive/docs/integration/domains/nurse.md

nurse — nurse bank accounts

Client seam client/src/services/nurse/ · USE_NURSE_BANK_MOCK = false (real) · 4 server ops Last verified: 2026-07-30 against commit d3ec723 and swagger.v1.json (2026-07-29).

The nurse's payout destination. Narrow domain, high stakes: a payout cannot be paid to an unverified IBAN.

The domain is named nurse, not nurse-bank-accounts, because that is the client folder name. The nurse's profile lives in profiles.md; coverage in service-areas.md; verification in verification.md.

Endpoints

Method	Path	Rate limit	Verdict
GET	/api/v1/nurse_bank_accounts/list	—	wired
POST	/api/v1/nurse_bank_accounts/add	sensitive 20/min	wired
POST	/api/v1/nurse_bank_accounts/set_primary/{id}	—	wired
POST	/api/v1/nurse_bank_accounts/verify_ownership/{id}	sensitive 20/min	wired

All [Authorize]. No phantoms. The domain maps 1:1.

Shape rules the JSON does not express

• iban_hash is UNIQUE across the platform. The same IBAN cannot be registered by two nurses; the second add returns a 409. The uniqueness is enforced on a deterministic hash, not the encrypted column.
• The IBAN is encrypted at rest and returned masked — maskedIban on every read model, including the admin-side PayoutDto and the nurse's own NursePayoutHistoryDto. The full IBAN is never returned after the write that created it. Write-then-masked is the pattern.
• verify_ownership is استعلام شبا — a Shahkar-class inquiry that confirms the account holder's national id matches the nurse's. It is a seam: Seams:BankOwnership:Provider = mock (default) or finnotech. The mock returns a match for every IBAN except Seams:BankOwnership:MismatchIban (IR000000000000000000000000), which exists so the payout-gating path is testable.
• Ownership verification gates payouts, and the gate lives in the payout engine, not here. EligibleNurseEarningsDto.hasVerifiedPrimaryIban is the flag the admin console reads before generating a batch — see payouts.md. A nurse with earnings and no verified primary IBAN accrues a balance and is simply not paid.
• Client-side IBAN handling (iban.ts) does checksum validation and formatting only. It is a UX affordance; the server re-validates.

Enums

Vocabulary	Values
BankAccountStatus	pending verified mismatch

mismatch is a terminal, actionable state — the holder's national id did not match — and is distinct from pending, which only means the inquiry has not run.

Open REQs

None.