---
id: UJ-051
title: View and pay an invoice in the customer portal
actors: [customer portal user]
surface: tenant portal invoice page and hosted payment page
goal: Review an eligible invoice and complete payment with authoritative status.
trigger: Customer opens portal invoices or a payment link.
preconditions:
  - Invoice is `TAX_ISSUED` and unpaid/partially paid; tenant payment adapter is configured for Pay Now.
success_state: Customer sees updated payment state after gateway webhook; invoice/receipt access follows portal rules.
source_specs:
  - docs/specs/2026-05-31-invoice-payment-ux.md
  - docs/specs/2026-05-30-tenant-portals.md
  - docs/specs/2026-05-31-invoice-payment-link-generation.md
  - docs/specs/2026-05-31-partial-payment-recording.md
---

## Happy path

1. Customer opens portal invoices → sees only own eligible invoices and allowed statuses.
2. Customer opens invoice HTML/PDF → Zync checks portal authentication and customer ownership.
3. Customer chooses Pay Now → hosted provider/tokenization page collects payment details outside Zync.
4. Provider returns session result → portal polls for status while signed gateway webhook remains authoritative.
5. Verified success updates invoice to `PAID` or `PARTIALLY_PAID`; customer refreshes and sees status/receipt where permitted.

## Alternate and failure paths

- Draft/canceled/ineligible invoice → hide Pay Now and payment mutation.
- Payment canceled/failed/expired → show failure and allow safe retry; do not mark invoice paid.
- Customer opens another customer's invoice/token → reject with not-found/forbidden behavior.

## Permissions and boundaries

- Portal never records manual/offline payments; that is staff-only.
- Gateway webhook, not browser return, is the payment source of truth.

## Source specs

- `docs/specs/2026-05-31-invoice-payment-ux.md`
- `docs/specs/2026-05-30-tenant-portals.md`
- `docs/specs/2026-05-31-invoice-payment-link-generation.md`
- `docs/specs/2026-05-31-partial-payment-recording.md`