Domain and data model
Status: Logical design, not a final Prisma schema. Business ownership is merchant-scoped; consumer identity and payment-method vault references are shared where consent permits.
| Domain | Core entities | Important rules |
|---|---|---|
| Identity | User, Consumer, Merchant, MerchantUser, MerchantCustomer | Merchant customer reference is unique within merchant; consumer matching must be verified |
| Onboarding | MerchantVerification, PayoutDestination, MerchantAgreement | Keep verification evidence, approvals and effective dates |
| Payments | PaymentMethod, PaymentMandate, ConsentEvidence, PaymentPreference | Only tokenised methods; merchant-specific permissions and revocation |
| Billing | Bill, BillVersion, Payment, PaymentAttempt | Bill versions immutable; attempt references unique by provider |
| Funds | Collection, SettlementRecord, Payout, PayoutAllocation | Separate collection, settlement and payout; no double allocation |
| Accounting | LedgerAccount, LedgerTransaction, LedgerEntry | Balanced double-entry, append-only, integer minor units |
| Exceptions | Refund, Dispute, Reversal, ReconciliationRecord | Trace back to original payment and ledger postings |
| Commercial | MerchantPricing, PricingAgreement, FeeAssessment, MerchantInvoice, InvoiceLine | Versioned pricing; fee invoices separate from bill proceeds |
| Operations | ProviderWebhook, Notification, AuditEvent, IdempotencyKey, Job | Webhook deduplication, traceability, retries and access control |
Key relationships
Implementation principles
- Use UUID/ULID primary keys and explicit unique constraints on provider IDs and merchant-scoped external IDs.
- Store money as integer minor units with ISO currency, never floating-point.
- Store event times in UTC; preserve the relevant Australian business timezone and cut-off calendar for scheduling.
- Separate internal IDs from external provider and merchant identifiers.
- Use soft disable/status changes for operational records; do not delete financial or consent evidence.
- Encrypt personal information at rest, minimise retained data and set evidence retention rules after legal review.
- Use outbox/inbox patterns for reliable events and webhooks.
- Define row-level/tenant authorization for every merchant API and admin query.
To design next
Formal Prisma schema, unique indexes, state-transition guards, retention policy, migrations, test fixtures and reconciliation queries.