PRD: Merchant Onboarding (Back Office)

Module	Commerce	PRD ID	PRD-BOP-001
Status	Ready to dev	FEAT	BOP · BANA-1437
Epic	BANA-1337	Plane	BANA-1533
Date	2026-06-30	Version	v1.0
Packages	@nx/commerce · @nx/helpdesk	URD	BOP
Surface	BO · Ops
Owner	Hải Cao · Phát Nguyễn

What Merchant Onboarding (Back Office) is

Signing a client used to mean hopping between tools and asking engineering for help: creating the organizer here, the merchant there, the owner account somewhere else, attaching a plan by hand. There was no single place to take a freshly-signed client and stand them up.

The onboarding flow is a guided Back-Office screen where the operations team signs up a new client end-to-end across four sections in order: Organizer → Owner → Merchant → Plan, plus a live preview card next to the form. It is the front door of the Back Office; ongoing merchant management afterwards lives in Merchant Management.

Pre-fill from an inquiry, atomic completion

Coming in from an inquiry, the screen pre-fills the lead's business and contact details, so the operator doesn't retype anything. The preview card mirrors every change as the operator types, for a final review before completing.

Completing the screen creates the organizer, headquarter merchant, owner account, first merchant, and license all at once - atomically, so a failure anywhere leaves nothing behind. Once done, the screen lands the operator straight on the new merchant, ready to configure and sell.

The easiest thing to get wrong

Re-completing after a network error must not create a second client

Re-submitting the same data after a network error has to be safe: no duplicate client, and an already-uploaded logo is not re-uploaded. The server stores the password as a hash only; the owner's temporary password is visible only during the entry session - it cannot be viewed again after completion.

1. Goals & Non-Goals

Goals

• A guided onboarding screen with four sections in order: Organizer → Owner → Merchant → Plan, plus a live preview card that mirrors the form.
• Pre-fill from an inquiry so an operator doesn't re-type a lead's details.
• Create the organizer, its headquarter merchant, the owner account, the first merchant, and the license as one atomic outcome.
• Land the operator on the new merchant's General tab, ready to configure.

Non-Goals

• Ongoing merchant management after onboarding - profile, lifecycle, payment setup (Merchant Management).
• Configuration of category / sale-channel / onboarding templates and tax groups as standalone screens (CAT, SC, System Config).
• Bulk catalog import, the support center, and the admin dashboard - separate back-office capabilities (the dashboard is Merchant Analytics).
• The owner's own self-service sign-up in the client app.

2. Success Metrics

Metric	Target / signal
Time to onboard	A signed client is stood up in one back-office session, no engineering help
Atomicity	Either the whole client (org + merchant + owner + merchant + license) is created, or nothing is
Lead continuity	A client that came from an inquiry is onboarded without re-typing known details
Hand-off	On completion the operator is taken straight to the new merchant to continue setup

3. Personas & Scenarios

Persona	Goal in this feature
Operations team	Stand up a freshly-signed client end-to-end
Onboarding / sales staff	Convert an inquiry into a live, ready-to-sell merchant

Core scenario: an operator starts onboarding (often from an inquiry, which pre-fills the business and contact details), fills the organizer, the owner account, and the first merchant, picks a subscription plan while the preview card mirrors every change, and completes; the system creates the organizer with its headquarter merchant, the owner, the merchant, and the license together, and opens the new merchant's General tab.

4. User Stories

#	As a	I want	So that
01	operator	a guided screen that walks me from organizer to plan	I don't miss a step standing up a client
02	operator	the flow pre-filled from the inquiry	I don't re-type a lead's details
03	operator	a generated owner password option	I can hand the owner initial credentials
04	operator	a live preview of what will be created	I can review everything before completing
05	operator	everything created together or not at all	I never end up with a half-made client
06	operator	to land on the new merchant when I finish	I can continue configuring it immediately

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Organizer section - 6 fields, each with its own rule. • Required: Organizer name (bilingual VI/EN) · Industry (F&B · Retail · Ticketing - locked, coming soon · Other) · Business type (business-type list, today: Household business). • Optional: Tax code (free text) · Logo (uploaded image). • Responsible sales: read-only, auto-filled with the signed-in user.	✅	URD-BOP-001 · URD-ORG-001
FR-002	Owner section - the client's first owner account, 6 fields, all required. • First name, Last name: two separate fields. • Username: unique system-wide - a duplicate rejects completion with an error naming the username. • Phone numbers, Emails: each a list, multiple entries can be added; each entry must match a valid format. • Password: with a generate temporary password button that fills the field; the operator copies it for hand-off.	✅	URD-BOP-001 · URD-ACC-001
FR-003	Merchant section - exactly 2 fields, both required. • Merchant name (bilingual VI/EN). • Address.	✅	URD-MER-001
FR-004	Plan section - subscription plans shown as cards, exactly one must be picked, required. • Picking one reveals the plan's details block. • Contract code: required only when the picked plan requires a contract; format is letters, digits, and hyphens (-) only, up to 256 characters. • A bad format, or a missing code when required, errors on the field and blocks completion.	✅	URD-BOP-002
FR-005	Pre-fill from an inquiry when the flow starts from one. • The lead's business name seeds both the organizer name and the merchant name. • The lead's first name, last name, phone, and email seed the Owner section. • The lead's business type is adopted only when it matches a valid list value, otherwise the default is used. • Every pre-filled value stays editable before completion.	✅	URD-BOP-001
FR-006	A preview card pinned next to the form, updating instantly with every change. • Shows the organizer name + logo, owner details (full name, username, phone, email), merchant (name, address), and the picked plan's summary. • The operator reviews everything that will be created without leaving the screen.	✅	URD-BOP-001
FR-007	Completion creates the organizer, headquarter merchant, owner, merchant, and license in one atomic operation - a failure anywhere creates nothing. • Retry-safe: re-completing after a network error with the same data does not create a duplicate client, and an already-uploaded logo is not re-uploaded. • When an inquiry is the source, the result is linked back to it. • On success, a notification shows and the screen opens the new headquarter merchant's General tab. • Leaving with unsaved changes triggers a warning.	✅	URD-MER-001 · URD-MER-017

5.1 Acceptance criteria

• Leaving any required field empty (organizer name, industry, business type, first name, last name, username, phone, email, password, merchant name, address, plan) blocks completion and errors that field.
• The "Ticketing" industry is shown but locked (coming soon).
• The "Responsible sales" field shows the signed-in user's name and is not editable.
• Multiple phone numbers / emails can be added for the owner; a malformed phone or email errors on that exact row.
• Clicking the generate button fills the password field with a temporary password.
• Picking a contract-requiring plan with an empty contract code errors; a code with characters outside letters/digits/hyphens or longer than 256 characters errors; a plan without a contract requirement allows the code to stay empty.
• Entering from an inquiry: the lead's business name, first/last name, phone, and email are pre-filled; an unrecognized business type is not adopted and falls back to the default.
• The preview card changes immediately when typing into any field it displays.
• A successful completion creates all 5 entities: organizer, headquarter merchant, owner account, merchant, license - and the new owner account can log in.
• A failed completion (e.g. duplicate username) leaves no entity behind; the error names the duplicated field.
• Re-completing after a network error with the same data does not create a second client; the logo is not uploaded twice.
• On completion the screen navigates straight to the new headquarter merchant's General tab.

6. Non-Functional Requirements

Aspect	Requirement
Atomicity	The whole client is created in one all-or-nothing operation; a failure leaves nothing behind
Retry safety	Re-submitting the same data after a network error creates no duplicate; an uploaded logo is not re-uploaded
Authz	Onboarding is gated to operator roles
Credential safety	The server stores the password as a hash only; the temporary password is visible only during the entry session - it cannot be viewed again after completion
Uniqueness	The owner's username is unique system-wide; the merchant's slug is unique within its organizer
i18n	Labels are bilingual (EN/VI)

7. UX & Flows

How an operator onboards a client:

The sections on the screen:

The screen lives in the Back Office "CRM & Merchant" section, reached from the inquiry list or directly. Four sections stack in order on one screen, with the preview card pinned alongside.

8. Data & Domain

Concept	Role in this flow
Organizer (organizer)	The branding parent created first
Merchant (headquarter)	The legal POS unit created under the organizer, marked as its headquarter
Owner account	The first user, with login identifiers (username, phone, email) and an initial password
Merchant	The first physical merchant captured during onboarding
Subscription plan / license	The plan chosen for the client, issued as a license
Inquiry	The optional lead the flow pre-fills from and links the result back to

Conceptual only - onboarding creates these together as one aggregate; the data model lives in the developer docs.

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	Organizer & merchant (PRD-ORG-001)	onboarding creates the organizer + headquarter merchant.
02	Licensing	the subscription plan / license attached at the plan section (Licensing).
03	Inquiry	the optional lead that pre-fills the flow (CRM inquiry).
04	User accounts	the owner account and its identifiers.
05	Industry category templates & tax groups	the corresponding URD-BOP-002 slice lives in other PRDs: Categories, Sale Channels, and BO Tax Groups.

Assumptions

#	Assumption	What breaks if it is wrong
01	The operator is authenticated with an onboarding-capable role.	Without the role, the onboarding screen is blocked by authorization, and the operator cannot stand up a client.
02	A subscription plan exists to choose from; some plans require a contract code.	The plan section is a required field (FR-004); with no plan to choose, the field cannot be filled, and completion is blocked like any other required field.

10. Release Plan & Criteria

Aspect	Plan
Phase	P1 - the onboarding flow in the Back Office
Rollout	Operator users; no feature flag
Migration	None - it creates new clients
Launch criteria	All §5.1 acceptance criteria pass
Monitoring	Onboarding completion rate; failure/rollback rate

References

• URD: Commerce - BOP (Backoffice Portal) · ORG · MER
• Related: PRD-MER-001 - Merchant management · PRD-ORG-001 - Organizer & merchant
• Module: Commerce - URD · Roadmap: Phase 2 - By Month
• Developer: @nx/commerce

Risks & Open Questions

#	Risk / question	Mitigation / status
01	A half-created client if a section fails	Completion is atomic - all entities are created together or none (FR-007)
02	Double-submit / retry after a network error	Re-submitting the same data creates no duplicate; the logo is not re-uploaded (FR-007)
03	The owner's initial password hand-off	The temporary password is visible only during entry; the server stores a hash only (FR-002)
04	A plan that requires a contract	The contract code is conditionally required + format-checked (letters/digits/hyphens, ≤256 chars) before completion (FR-004)
05	Duplicate username or slug	Uniqueness is enforced; the error names the duplicated field (FR-002)

Frequently asked questions

#	Question	Answer
01	Is this the same as managing a merchant?	No - this stands up a new client. Editing merchants afterwards is Merchant Management.
02	What if the client came from an inquiry?	The flow starts from that inquiry and pre-fills the business and contact details; the onboarding result is linked back to the inquiry.
03	What gets created at the end?	The organizer, its headquarter merchant, the owner account, the first merchant, and the license - together.
04	Does the owner onboard themselves?	This PRD covers the operator-run onboarding in the back office; owner self-service is a separate, client-side flow.