URD: Tax & Invoice

Module	CORE-10	Version	v0.4
Status	In-progress	Date	2026-05-30

1. Purpose

Define the user-facing requirements for staying tax-compliant when selling. The module records the merchant's tax identity, applies the correct tax rules to products, and turns a completed payment into a legal Vietnamese electronic invoice that can be delivered to the buyer and submitted to the tax authority — with adjustment, cancellation, and buyer self-service claims along the way.

2. Scope

Included	Excluded
Seller tax identity (tax code / MST, name, address)	Authoritative tax-code registry (tax authority owns it)
Tax-group rule templates applied onto products	Tax-rate calculation at sale time (pricing engine)
VN administrative reference data (provinces, wards, units)	PDF rendering of the invoice (provider-side)
Merchant invoice profile + encrypted provider credentials	Payment capture (Payment module)
Invoice issuance lifecycle (queued → issued / failed / cancelled)	Order lifecycle (Orders module)
Provider integration: VNPAY / VNIS via iiapi + T-VAN	Multiple providers beyond the current iiapi/T-VAN set
Tax-authority (CQT) submission and status tracking	Tax declaration / filing automation
Invoice adjustment, replacement, cancellation	Cross-merchant settlement
Invoice request + buyer self-service claim (QR)
Channel routing + profile sharing across branches
Immutable audit trail for every invoice event

3. Definitions

Term	Definition
Tax identity (MST)	The seller's tax registration code, business name, and address printed as the seller on every invoice
Tax group	A reusable rule template that decides which tax applies to which products
Invoice profile	A merchant's invoicing setup linking the tax identity to a provider
Provider	The e-invoice gateway (currently VNPAY / VNIS via iiapi) that issues the legal invoice
Tax authority (CQT)	Vietnam's tax authority, reached through the T-VAN network for submission and validation
Issuance	The act of turning an order into a numbered, legal e-invoice via a provider
Buyer claim	A buyer self-serving their own invoice by scanning a receipt QR before a deadline
Audit trail	The immutable record of every state change an invoice goes through

4. Conceptual Model

Conceptual only — full schema lives in the taxation and invoice developer domain models.

5. Functional Requirements

One table per functional area. <AREA> codes match the test-case IDs. Priority = MoSCoW (Must / Should / Could / Won't).

5.1 Tax Identity (TAX)

ID	P	Requirement
URD-TAX-001	M	Register the seller tax identity (MST, business name, address) used on issued invoices
URD-TAX-002	M	Look up Vietnamese provinces, wards, and administrative units when entering addresses
URD-TAX-003	S	Tax code is validated for correct Vietnamese format before it is accepted

5.2 Tax Groups (GRP)

ID	P	Requirement
URD-GRP-001	M	Define a tax-group rule template that classifies which tax applies to which products
URD-GRP-002	M	Applying a tax group provisions the correct tax onto its matching products
URD-GRP-003	M	Changing or removing a product reconciles its applied tax automatically
URD-GRP-004	S	A tax group is only usable when compatible with the merchant's tax method

5.3 Invoice Configuration (CFG)

ID	P	Requirement
URD-CFG-001	M	Create a merchant invoice profile linked to the seller tax identity
URD-CFG-002	M	Connect a provider (VNPAY / VNIS via iiapi) with credentials stored encrypted
URD-CFG-003	M	Configure per invoice type the serial, category, tax method, and issuance policy
URD-CFG-004	M	Route each sale channel to the provider config that should issue its invoices
URD-CFG-005	M	Configure a retry policy (max retries + delay schedule) for failed issuance
URD-CFG-006	S	Share an invoice profile across branches (private / all-branches / whitelist)
URD-CFG-007	S	Guided onboarding wizard for step-by-step provider setup

5.4 Invoice Lifecycle (INV)

ID	P	Requirement
URD-INV-001	M	Queue an invoice for issuance automatically on a successful payment
URD-INV-002	M	Issue the invoice via the provider and capture its number + tax-authority code
URD-INV-003	M	Track invoice status (pending → processing → success / failed / cancelled)
URD-INV-004	M	Retry a failed issuance per the configured policy
URD-INV-005	M	Submit the issued invoice to the tax authority (CQT via T-VAN) when enabled, and track its status
URD-INV-006	M	Record an immutable audit trail entry for every invoice event
URD-INV-007	M	Adjust an issued invoice (correction linked to the original)
URD-INV-008	M	Replace or cancel an issued invoice with a reason
URD-INV-009	S	Process inbound provider webhooks with signature validation to update status

5.5 Invoice Request & Buyer Claim (REQ)

ID	P	Requirement
URD-REQ-001	M	Capture buyer info (name, tax code, address, email) for an invoice
URD-REQ-002	M	Direct flow: cashier collects buyer info and issues the invoice
URD-REQ-003	S	Buyer self-service: receipt QR with a claim token and deadline
URD-REQ-004	S	Claim lifecycle: pending → claimed / expired
URD-REQ-005	S	Deliver the invoice / claim link by receipt QR, email, or SMS

5.6 Issuance Modes (MOD)

ID	P	Requirement
URD-MOD-001	M	Real-time: issue immediately on payment
URD-MOD-002	S	Manual: cashier-initiated issuance at the counter
URD-MOD-003	S	Scheduled: batch issuance by a scheduled job
URD-MOD-004	S	Buyer self-service: buyer claims and issues via QR

6. Acceptance Criteria

AC-INV-01: Issue on payment

Given	When	Then
A successful payment for an order	The payment-success event is received	An invoice is queued for issuance
The provider accepts	Issuance completes	Invoice number + tax-authority code are recorded; status is success
The provider rejects	Issuance fails	A retry is scheduled per policy
Max retries exceeded	Last retry fails	Status is failed; the failure is recorded in the audit trail

AC-INV-02: Buyer self-service claim

Given	When	Then
A receipt with a valid claim QR	Buyer opens the link before the deadline	Buyer can submit their info
Buyer submits info	Submission succeeds	The invoice is issued with the buyer details
The deadline has passed	Buyer opens the link	The claim is expired and no invoice is issued

AC-INV-03: Tax-authority submission

Given	When	Then
Tax-authority submission is enabled	An invoice is issued	The invoice is submitted to CQT via T-VAN
CQT accepts	The response returns	The invoice status is updated to accepted
CQT rejects	The response returns	The status records the rejection reason

AC-GRP-01: Tax-group provisioning

Given	When	Then
A tax group matching a product	The product is created or updated	The correct tax is applied onto that product
A product is removed	The change is processed	Its applied tax is reconciled / removed

7. Constraints & Non-Goals

Constraints

ID	Constraint
C-01	One active invoice profile per merchant
C-02	One active config mapping per sale channel
C-03	Provider credentials are stored encrypted
C-04	The invoice audit trail is immutable
C-05	A claim token is unique and bound to a single invoice request
C-06	All records use soft-delete; nothing is physically removed

Non-Goals

• Multiple invoice providers beyond the current iiapi / T-VAN set
• PDF rendering of the invoice (produced provider-side)
• Tax-rate calculation at sale time (owned by the pricing engine)
• Tax declaration / filing automation

8. Version History

Date	Author	Description	Ver
2026-02-26	P. Do — Product Owner	Initial user stories	v0.1
2026-02-27	QE	Code-level assessment, requirement adjustments	v0.2
2026-04-16	P. Do — Product Owner	VNPAY IIAPI + T-VAN + buyer-claim model	v0.3
2026-05-30	Migration	Restructured to module-docs convention; AREA codes realigned to taxation + invoice build	v0.4