Payment — Fundamentals & Reference

BẮT BUỘC đọc trước payment-flow.md (20 scenarios) và ../architecture/payment-architecture.md (DDD layered architecture).

Doc này tập trung vào concepts (intents, state machine, coupling, payable total) + reference tables (state transition, cross-context event catalog, error codes, admin/customer UI map). Mọi flow chi tiết end-to-end sequence diagram nằm ở payment-flow.md.

Notation chung dùng xuyên suốt:

• C = Customer browser
• FE = Frontend (Next.js)
• API = Backend (NestJS)
• PC = Payment Context
• BC = Booking Context
• LC = Loyalty Context
• OB = Outbox worker
• PR = Provider (Bambora)
• DB = Database

1. Payment Intent

Intent phân loại mục đích của một Payment aggregate. Một booking có thể sinh nhiều Payment qua các intent khác nhau trong đời sống của nó.

DEPOSIT là intent duy nhất chạy MANUAL. Lý do: muốn giữ khả năng VOID trước khi booking thực sự được consume. Sau khi khách ARRIVED → capture → không còn đường void free.

2. Payment State Machine

stateDiagram-v2
    [*] --> INITIATED: initiate()
    INITIATED --> AUTHORIZED: authorize()\n(webhook, MANUAL)
    INITIATED --> CAPTURED: capture()\n(webhook, AUTO)
    INITIATED --> FAILED: markFailed()
    INITIATED --> EXPIRED: markExpired()\n(customer abandoned)
    AUTHORIZED --> CAPTURED: capture()\n(BookingArrived/Completed)
    AUTHORIZED --> VOIDED: void()\n(cancel in window)
    AUTHORIZED --> EXPIRED: markExpired()\n(7-day hold lapsed)
    AUTHORIZED --> FAILED: capture error
    CAPTURED --> PARTIALLY_REFUNDED: refund(partial)
    CAPTURED --> REFUNDED: refund(full)
    PARTIALLY_REFUNDED --> REFUNDED: refund(rest)
    CAPTURED --> [*]
    REFUNDED --> [*]
    PARTIALLY_REFUNDED --> [*]
    VOIDED --> [*]
    FAILED --> [*]
    EXPIRED --> [*]

Terminal states: CAPTURED, PARTIALLY_REFUNDED, REFUNDED, VOIDED, FAILED, EXPIRED. Không có transition nào rời khỏi terminal (trừ partial→full refund).

3. Booking ↔ Payment Coupling

sequenceDiagram
    participant BC as Booking Context
    participant OB as Outbox
    participant PC as Payment Context
    participant LC as Loyalty

    Note over BC: Create (with optional redemption)
    BC->>LC: reserve redemption (L3 tx)
    BC->>BC: discountAmount snapshot
    BC->>OB: BookingCreated<br/>(rawTotal, discountAmount,<br/>captureMode=MANUAL for DEPOSIT)
    OB-->>PC: event
    PC->>PC: initiate(payableTotal × depositPct)

    Note over BC: Lifecycle
    BC->>OB: BookingConfirmed (PENDING→CONFIRMED by PaymentAuthorized listener or admin)
    BC->>OB: BookingArrived (ARRIVED = customer checked in)
    OB-->>PC: capture MANUAL + AUTHORIZED
    BC->>OB: BookingCompleted
    OB-->>PC: capture (fallback if Arrived skipped)
    OB-->>LC: consume redemption

    Note over BC: Or cancel
    BC->>OB: BookingCancelled
    OB-->>PC: decide refund/void/forfeit
    OB-->>LC: cancel redemption (pre-capture only)

Chu trình booking chuẩn: PENDING → CONFIRMED → ARRIVED → IN_PROGRESS → COMPLETED. Payment bám vào 3 trigger: Created, Arrived, Completed. Cancelled / NoShow là terminal alternate.

4. payableTotal vì sao quan trọng

rawTotal       = Σ BookingItem.price
discountAmount = computeLoyaltyDiscount(...)   // 0 nếu không redeem
payableTotal   = rawTotal − discountAmount

DEPOSIT:   Payment.amount = payableTotal × depositPercent / 100
                                 (hoặc fixed, clamped to payableTotal)
REMAINING: Payment.amount = payableTotal − Σ (captured − refunded)

Deposit tính trên payableTotal (không phải rawTotal) → fair cho khách + match Stripe/Booksy. Loyalty discount được snapshot trên Booking.discountAmount tại lúc create, không re-derived khi Payment gọi lại.

5. State Transition Table

6. Cross-Context Event Reference

7. Error Codes (Domain → i18n)

Quy ước chung tại api-design.md §error-codes.

Payment domain

Booking → Payment cross-context

Loyalty discount

Tenant settings combo

8. Admin UI Pages (planned + shipped)

8b. Provider-active guard (FE)

Owner có thể vô hiệu hoá payment provider giữa 2 booking — ví dụ tắt Bambora trong /admin/settings?tab=payment. Flow tiếp theo cần biết booking đó đang dùng provider nào và provider đó còn active không trước khi cho phép thao tác PSP, nếu không owner click "Collect remaining" sẽ trúng API 409 PAYMENT_NO_ACTIVE_CONFIG mà không có hint actionable.

Quy tắc

• Mỗi booking có thể có ≥ 1 Payment row. Provider của booking = latest.provider (Payment có updatedAt lớn nhất, tức là deposit hoặc retry gần nhất).
• FE cross-check latest.provider với danh sách paymentConfigs (qua usePaymentConfigList) — nếu không có config nào provider === latest.provider && isActive === true → block thao tác PSP-bound.
• KHÔNG fallback sang provider khác đang active. Customer expectation là "cùng provider thread", và contract của salon với PSP cũng theo từng provider.

Áp dụng tại BookingPaymentSummary (admin booking drawer)

CollectRemainingModal tự gate option QR theo qrEnabled (booking provider có active không) — nếu PSP inactive, modal vẫn mở với 2 lựa chọn manual (Cash / Terminal); QR slot hiển thị "Online payment is not configured for this salon." Không còn warning bar inline ở booking drawer (gây nhiễu cho cash-only salons).

Tại sao bỏ guard FE

• Owner cần top-up bill từ mọi booking state: thêm dịch vụ trên booking COMPLETED, ghi nhận cancellation fee trên CANCELLED, deposit pre-service trên PENDING. Guard cũ {ARRIVED, IN_PROGRESS, COMPLETED} chặn các use case hợp pháp.
• Booking-state validation thuộc booking context; payment context chỉ ghi nhận tiền. Phân tách trách nhiệm rõ ràng hơn.
• Idempotency-by-intent ở backend vẫn đảm bảo "click nhiều lần không sinh nhiều URL".

9. Customer-Facing UI Flow

1. Booking flow — nếu tenant depositEnabled:
   • Trước submit: show "Depositum: 200 NOK" + link terms (Track C4.3 amber notice)
   • After submit → redirect to Bambora hosted checkout
2. Return page (/b/{slug}/bookings/{id}/payment/return) — client polling 2s interval, 30s timeout, tone cards cho mỗi outcome
3. Cancel page (/b/{slug}/bookings/{id}/payment/cancelled) — static "you cancelled" với CTA Retry
4. Email receipt: sau capture, email với invoice + payment ref (channel deferred — EmailProvider port + LogEmailProvider default impl từ P1-4)
5. Refund / Void notification: SMS template Norwegian từ OnPaymentNotificationListener (P1-10)
6. Retry payment (P1-4): account/BookingsSection show yellow CTA khi depositStatus=RETRY_PENDING && status=PENDING. Click → POST /payment/retry → redirect tới fresh checkoutUrl. Email deep-link ?retry=<id> auto-fire mutation on landing.

10. Liên quan

• payment-flow.md — 20 scenarios end-to-end (deposit, cancel, no-show, refund, retry, reconciliation)
• ../architecture/payment-architecture.md — DDD layered architecture, bounded context, domain model
• booking-flow.md — Booking lifecycle + integration events
• booking-status-flow.md — Booking state machine, transitions, role matrix
• status-matrix/05-payment-driven.md — Reverse direction: Payment events → Booking transitions + depositStatus
• ../architecture/api-design.md — HTTP conventions, response envelope