Please enable JavaScript.
Coggle requires JavaScript to display documents.
WONZY AGENCY MODULE — PRD v1.2 - Coggle Diagram
WONZY AGENCY MODULE — PRD v1.2
Agency configuration
FX source and timing
Approval workflows
DISTRIBUTION
Distribution hierarchy — FR-001–005
Agency → Channel → Partner Group → Channel Partner
Channel examples: OTA / Agent / Corporate / Affiliate
Partner belongs to one Group within its Channel at a time
Same business in different Channels = separate partner records
Effective-dated Group transfers
New bookings use booking-date assignment
Historical bookings retain original snapshots
Lifecycle controls
Booking activity / portal access / finance controlled separately
Deactivation preserves history and outstanding obligations
Partner onboarding and portal — FR-006–012
Agency creates partner OR partner self-registers
Required: legal and trading names, business type, contact, email, phone, address
Website optional; tax IDs, documents and bank details optional by default
Validate identity and Agency-scoped duplicates
Single-step or multi-step Agency approval
Pending until approvals and validation complete
Activate before portal access
Multiple users per partner; Agency permission ceiling
Own bookings, commissions, statements, ledger, payments and disputes
Server-side isolation on views, exports and documents
Own-data exports: CSV / XLSX / PDF
Attribution and exceptions — FR-013–017
Sources: referral / integration / logged-in partner / API credentials / manual
Reliable unambiguous evidence → attribute and snapshot
Missing attribution → exception and unassigned booking
Conflicting identifiers → preserve evidence; manual resolution
Booking confirmation is not blocked solely by attribution
Commission deferred until resolved
Agency exception queue: filters, age, identifiers and sources
Staff resolve with reason, actor and timestamp
Use terms valid on original booking creation date
Before settlement: recalculate and preserve original calculation
After settlement: separate adjustment; preserve history
Agency ageing thresholds and email escalation
Original PRD commission — superseded for NEW policies by simplified V2 amendment
Effective-dated terms; no overlapping periods
Booking-time rule and component snapshots
Models
Percentage / fixed per booking / fixed plus percentage
Tiered: marginal rates by tier portion
Commissionable components
Core products / accommodation / extras / fees / taxes / discounts
Agency defaults; Group component overrides
Agency tier policy
Count / value / both; gross or commissionable value
Calendar / rolling / custom periods; Agency timezone
Future-only / period-end / continuous application
Eligible volume retained after later cancellation or refund
Eligibility trigger plus waiting period
Confirmed / payment received / service completed
Refund window expired / manual approval
Eligibility is separate from settlement frequency
Decimal arithmetic; maximum two decimals; consistent rounding
Refund defaults
Full cancellation or full refund: reverse all
Partial refund: proportional adjustment
Separate adjustments; prevent duplicate reversals
FX — FR-026–027
Agency controls external provider / manual rates / timing
Store original and converted currencies, amounts, source and rate
Snapshot policy, timestamp and conversion method
Partner agreed settlement amount protected from later FX changes
Agency bears subsequent FX gains or losses; report separately
Missing or stale rates → explicit exception; no silent substitution
Settlements — FR-028–036
Frequency
Daily / weekly / fortnightly / monthly / quarterly / custom / manual
Grouping
One settlement per partner per period
One settlement per booking
Staff-managed batch — not grouping by staff member
Snapshot grouping; do not restructure existing settlements
Cut-off includes attributed and eligible entries only
Minimum payout threshold
Gross eligible commission OR net payable after deductions and offsets
Below threshold: carry forward by default
Authorised override requires reason
Display tested balance and decision; prevent duplicate inclusion
Statement: opening balance, earned, deductions, refunds, adjustments, payments, closing balance
Statuses: Draft / Pending review / Approved / Paid / Partially paid / On hold / Cancelled
Permission-controlled corrections; no enforced transition graph
Status change alone creates no financial entry or payment
Finalised settlements preserved; corrections use separate entries
Approved but unpaid: next-settlement adjustment OR hold under Agency policy
Manual payment recording only — no automated bank transfer
Amount, currency, date, method, external reference and recording user
Partial payments and outstanding tracking
Negative-balance recovery
Carry forward and offset future eligible commission — default
Manual review and workflow requesting repayment
Separate recovery entries; track remaining debt; prevent double recovery
Disputes — FR-037–040
Partner disputes booking / commission / deduction / settlement
Evidence and status visible to own partner
Agency deadline and reference event; statement issuance default
Snapshot deadline; staff may accept or reject late cases with reason
Hold disputed amount OR entire settlement
Held amounts cannot be paid or reused elsewhere
Agency staff resolve with reason
Uphold / adjust / reject / partially uphold
Financial impact via separate adjustment
Release to correct workflow without duplication
Reports, email and security — FR-041–051
Six Agency report categories
Channel and partner performance
Commission and tier calculations
Settlements and outstanding balances
Exceptions and operational queues
FX gains and losses
Audit and configuration history
CSV / XLSX / PDF; permissions and audited exports
Email enabled by default; configurable events and recipients
Immediate attempt + two retries at five-minute intervals
Fallback recipient after all attempts fail
Per-processing-occurrence emails; retries stay same occurrence
Email failure never rolls back business transaction
Templates: draft, preview, test, publish, version, rollback
Reuse existing authentication, permissions and audit retention
Financial idempotency and immutable history
Customer-facing integrations — Section 17 and FR-052
Agency storefront: confidential application token through server-side BFF
OTA backend: client per integration and environment; bound Agency and partner
Travel-agent user: user login and authorised membership
Affiliate: validated public referral; no partner-user authority
Authentication
Private-key JWT preferred; private key stays on calling server
Short-lived tokens; rotation and live status checks
Application identity is separate from customer identity
Scopes plus record-level permissions; tenant IDs cannot override identity
Partner Group markup in existing markup module
Separate Hotel and Flight rules; fixed or percentage
Selling price = normal Agency price + applicable additional Group markup
Commission separate; never added again as a customer charge
Search → details → revalidation → accepted quote → booking
Changed terms require refreshed acceptance
Quotes bound to Agency, partner/context, product, rate, currency and expiry
Booking snapshots preserved after configuration changes
Safe retries must not duplicate booking
Access and caching
Own customer / authorised partner or integration scope only
Referral alone grants no booking or profile access
Price caches separated by Agency, Group/rule, product and currency
OTA customer registration
Disabled by default; Agency enables per integration
Require live enabled setting AND registration scope
Agency-owned customers; normal verification and consent
No duplicate identity or automatic access to existing customer
Disablement applies even to previously issued tokens
Technical decisions and acceptance
PRD is requirements baseline, not proof of implemented APIs
Verify existing booking events, identity, ledger, refund and FX contracts
Define marginal-tier algorithms and rounding examples
Define threshold interaction with grouping and batch selection
Resolve performance targets, migration and operational monitoring
Test isolation, idempotency, refunds, holds, partial payments and recovery
CURRENT IMPLEMENTATION — attachment sections 15–16
Evidence boundary
Local implementation description; not production acceptance
Source references supplied; repositories not inspected in this update
Test matrix is an execution plan — no connected end-to-end test run
Attachment starts at section 15; sections 1–14 and referenced amendment not supplied
Updates absent from earlier diagram
Simplified V2 commission architecture
Supersedes older commission controls for new policies
Current runtime, calculation and cycle services take precedence
Exact policy rules require the referenced simplified amendment
Partner onboarding stages are separate
Business approval → invitation acceptance → membership activation → portal access
Accepted invitation does not itself activate membership
Explicit membership selection and live permission checks
Application scopes, Agency permissions and Partner capabilities are separate
Trusted Partner booking mode
Book travel explicitly establishes Partner commerce context
Save authoritative ownership before payment
Ordinary Customer mode stays separate even with a Partner cookie
Revocation, disabled membership and foreign IDs denied at API and BFF
Saved booking receipts
Hotel and flight-package booking IDs bound to saved records
Success hard-refresh loads saved details, not draft fallback
Pending / failed / confirmed / incomplete outcomes handled distinctly
Polling, stale-data suppression and authorised detail links
Synthetic receipt check exists; does not prove supplier booking
Financial attribution reconciliation
Current reconciliation and commission worker supersede older no-worker notes
Compensating entries preserve history
Commercial credit correction does not silently change booking ownership or price
Hosted storefront registration
Automatic hosted registration exists
Universal generate-everything integration button is NOT implemented
Server-side keys, trusted host resolution and OAuth token handling
Settlement execution
Group policy fields are separate from effective executable schedules
Preview and preparation require cut-off, threshold and concurrency checks
Approvals, issuance, holds and partial external-payment recording
Disputes and operations
Protected evidence and late-submission gates
Immutable resolution and separate hold release
Durable notifications; provider acceptance is not inbox delivery
Documented limitations — verify or remediate
Scheduler historical catch-up
120-period loop restarts from anchor; sufficiently old schedules may stall
Scheduler month-end cadence
Monthly and quarterly advancement uses previously clamped boundary
Verify month-end and historical catch-up before relying on automation
PDF international text
No complex-script shaping or RTL layout
Unsupported glyphs shown as explicit Unicode escapes
Historical null-owner bookings
Receipt or navigation fixes do not establish historical Partner ownership
Acceptance still to demonstrate
Provision required policy/grants, schema and indexes
Verify payment, supplier, OAuth and notification environment integrations
Execute setup, application review, invitation, activation and negative-access tests
Execute Partner hotel/package and ordinary-Customer separation tests
Exercise saved receipts and pending/failure outcomes
Validate commission and tier transitions using simplified amendment
Full/partial refunds before and after settlement; retry idempotency
Attribution financial corrections without price or ownership rewrite
Settlement concurrency, carry-forward, holds, overpayment and partial-payment tests
Disputes, scoped exports and actual notification delivery
Hosted and external-client scopes, origins and disabled-client tests
Not established as missing by this attachment
Unmentioned PRD features require full implementation document and source verification
Do not treat a planned test or linked service as proof of passing behaviour
START HERE — implementation comparison
COLOR LEGEND
BLUE — PRD requirement
GREEN — functionality described in supplied implementation notes
RED — documented limitation or defect
YELLOW — acceptance test or verification still required
PURPLE — superseded requirement; follow current amendment
ORANGE — insufficient evidence or configuration dependency
01 ONBOARDING — compare Applications / Invitations / Partner Users
REQUIRED: review business application and control portal access
DOCUMENTED: approval → invitation acceptance → membership activation → selected membership
CHECK: no access before activation; revocation and permission ceiling enforced
02 BOOKING — compare Customer Book travel / Bookings / Success
REQUIRED: trusted context, secure booking access and immutable booked price
DOCUMENTED: explicit Partner mode, saved ownership, receipt IDs and stale-data suppression
LIMIT: historical null-owner bookings are not repaired by receipt fixes
CHECK: hotel and package bookings; hard-refresh; ordinary-Customer separation
03 COMMISSION — compare Group Terms / Commission runtime and cycles
CHANGE: simplified V2 amendment supersedes older PRD controls for new policies
DOCUMENTED: runtime, calculation and cycle services referenced
CHECK: obtain amendment; validate exact rates, qualification, cycles and retries
04 ATTRIBUTION — compare Attribution Exceptions / Reconciliation
REQUIRED: manual missing/conflicting attribution resolution with audit
DOCUMENTED: financial reconciliation and worker; compensating entries
CHECK: correction preserves ownership, customer price and finalised history
05 SETTLEMENTS — compare Group Schedules / Finance Settlements
REQUIRED: eligible cut-off, grouping, threshold, approval and manual payments
DOCUMENTED: separate executable schedules, preview/preparation, holds and partial payments
LIMIT: 120-period catch-up loop and clamped month-end cadence need verification
CHECK: retry/concurrency safety, duplicate allocation, overpayment and held amounts
06 INTEGRATIONS — compare Integrations / Hosted runtime / OAuth
REQUIRED: trusted Agency/partner context, scopes and disabled-client enforcement
DOCUMENTED: automatic hosted registration and controlled external-client configuration
NOT IMPLEMENTED: proposed universal generate-everything button
CHECK: keys server-side, correct return origins, tenant boundaries and scopes
07 DISPUTES — compare Disputes / Evidence / Finance Holds
REQUIRED: deadlines, evidence, authorised resolution and separate adjustments
DOCUMENTED: late gate, protected evidence, immutable resolution and separate hold release
CHECK: before/after deadline, partial hold, release and no double payment
08 REPORTS AND EMAIL — compare Reports / Notifications
REQUIRED: scoped exports, delivery retries and audit
DOCUMENTED: report and durable notification services referenced
LIMIT: PDF has no complex-script shaping or RTL layout
CHECK: totals and permissions; actual email delivery beyond provider acceptance
EVIDENCE REMINDER
Attachment contains sections 15–16 only; no connected end-to-end run recorded
Unmentioned features are unverified, not automatically missing