Skip to main content

Payments & Financials - Version Mapping

Domain: Payments & Financials First Introduced: V1.0 Last Updated: 2025-10-25

Version Introduction Timeline​

VersionStatusScopeDescription
MVP.0OUT OF SCOPENoneAll payment processing deferred
MVP.1OUT OF SCOPENoneAll payment processing deferred
V1.0PLANNEDFull ImplementationComplete payment processing with Stripe integration
V1.1FUTUREAdvanced PaymentsMulti-currency, preauth, automated refunds
V1.2FUTUREReconciliationAutomated reconciliation, accounting integration
V2.0FUTUREEnterprise FinanceSplit disbursements, escrow, invoicing

MVP.0 - OUT OF SCOPE​

Status: Not Implemented Rationale: MVP.0 focuses on foundation. Payment processing deferred until booking engine available (V1.0).

Excluded Entities​

  • All payment entities deferred

Excluded Features​

  • Payment processing
  • Payout management
  • Financial ledger
  • Refund processing
  • Transaction tracking

Workaround​

  • Payments handled outside system
  • Cash or direct transfers
  • Channel-collected payments
  • Manual tracking via spreadsheets
  • No automated payouts

MVP.1 - OUT OF SCOPE​

Status: Not Implemented Rationale: MVP.1 adds read-only booking awareness. Payment processing still requires full booking engine (V1.0).

Excluded​

  • All payment functionality deferred to V1.0

V1.0 - FULL PAYMENT PROCESSING​

Status: Planned Target: Initial production release with booking capabilities

Core Entities (7)​

  1. PaymentAccount - Financial account configuration

    • Stripe Connect integration
    • Provider account linking
    • KYC/AML verification tracking
    • Capability management
    • Status tracking (pending, active, suspended)

  2. Payment - Inbound guest payment

    • Payment intent creation
    • Status tracking (pending, processing, succeeded, failed)
    • Method tracking (card, bank_transfer, cash)
    • Provider transaction linking
    • Idempotency support
    • Refund status tracking

  3. Payout - Outbound disbursement

    • Revenue rule application
    • Recipient account tracking
    • Scheduling support
    • Automatic and manual payouts
    • Stripe Connect transfers
    • Failure handling and retry

  4. Transaction - Immutable ledger entry

    • Double-entry bookkeeping foundation
    • Debit/credit tracking
    • Category classification
    • Source linking (payment, payout, refund)
    • Append-only (never UPDATE/DELETE)

  5. Refund - Payment reversal

    • Full and partial refunds
    • Policy-based calculation
    • Reason tracking
    • Approval workflow (optional)
    • Provider integration
    • Compensating transaction generation

  6. Ledger - Organizational financial book

    • One per organization
    • Balance computation
    • Reconciliation tracking
    • Base currency definition

  7. BalanceSummary - Computed balance view

    • Pending balance (scheduled payouts)
    • Available balance (received but not paid)
    • Paid balance (historical total)
    • Dashboard reporting

Key Features​

Payment Processing:

  • Stripe Connect integration
  • Payment intent workflow
  • Card payment support
  • Idempotency enforcement
  • Webhook handling
  • PCI-DSS compliance (no card data stored)

Payout Management:

  • Revenue rule-based calculation
  • Automatic payout creation (on booking completion)
  • Scheduled batch processing
  • Stripe Connect transfers
  • Failed payout retry logic
  • Manual payout override

Refund Processing:

  • Policy-based refund calculation
  • Manual approval workflow
  • Full and partial refunds
  • Compensating transactions
  • Ledger updates
  • Provider API integration

Financial Ledger:

  • Immutable transaction records
  • Append-only journal
  • Balance computation
  • Audit trail maintenance
  • Double-entry ready (foundation)

Idempotency:

  • Unique provider references
  • Duplicate prevention
  • Safe retry logic
  • Request deduplication

Payment Methods Supported​

V1.0:

  • Credit/debit cards (via Stripe)
  • Manual payment recording (cash, check)
  • Channel-collected payments (tracking only)

Deferred:

  • Bank transfer (ACH/SEPA) - V1.1
  • Digital wallets (Apple Pay, Google Pay) - V1.1
  • Cryptocurrency - V2.0+

Business Rules​

  1. All amounts stored in minor units (cents)
  2. Payment/Payout/Transaction records append-only
  3. Idempotent provider API calls
  4. Stripe Connect required for automated processing
  5. Cannot process payments until PaymentAccount verified
  6. Refunds cannot exceed original payment
  7. Ledger balance must reconcile with transactions
  8. One Ledger per Organization
  9. Payout eligibility requires booking completion

Database Objects​

Tables: 7 (PaymentAccount, Payment, Payout, Transaction, Refund, Ledger, BalanceSummary view) Indexes: 15+ Constraints: 10+ Rules: Transaction immutability (no UPDATE/DELETE)

API Endpoints​

Payment Accounts:

  • POST /payment-accounts - Connect payment provider
  • GET /payment-accounts - List accounts
  • GET /payment-accounts/:id - Get account details
  • PUT /payment-accounts/:id/verify - Complete KYC verification

Payments:

  • POST /payments - Create payment
  • GET /payments - List payments
  • GET /payments/:id - Get payment details
  • POST /payments/:id/capture - Capture authorized payment

Payouts:

  • GET /payouts - List payouts
  • GET /payouts/:id - Get payout details
  • POST /payouts/:id/process - Manually trigger payout
  • POST /payouts/:id/cancel - Cancel pending payout

Refunds:

  • POST /refunds - Create refund
  • GET /refunds - List refunds
  • GET /refunds/:id - Get refund details
  • POST /refunds/:id/approve - Approve pending refund

Reporting:

  • GET /ledger/balance - Get current balance
  • GET /ledger/transactions - List transactions
  • GET /balance-summary - Get balance breakdown

Stripe Integration​

Stripe Connect Setup:

  • Standard Connect accounts for property owners
  • Platform account for fee collection
  • OAuth onboarding flow
  • KYC/AML verification webhook handling
  • Account capability tracking

Payment Intent Flow:

  1. Create PaymentIntent on Stripe
  2. Collect payment method from guest
  3. Confirm payment
  4. Capture funds
  5. Update Payment record
  6. Create Transaction entries

Transfer Flow:

  1. Compute payout from RevenueRules
  2. Create Payout record
  3. Schedule transfer batch
  4. Execute Stripe Transfer API
  5. Update Payout status
  6. Create Transaction entries

Background Jobs​

  1. Payout Batch Processing - Daily or weekly
  2. Failed Payment Retry - Exponential backoff
  3. Webhook Event Processing - Real-time queue
  4. Balance Reconciliation - Nightly
  5. Transaction Cleanup - Archive old records

Performance Requirements​

  • Payment creation: <200ms
  • Payment capture: <300ms (external API dependency)
  • Payout calculation: <100ms
  • Refund processing: <500ms
  • Balance query: <50ms (materialized view)

Security & Compliance​

PCI-DSS:

  • No raw card data stored
  • Stripe.js for client-side tokenization
  • Server never touches card numbers
  • Webhook signature validation

Financial Audit:

  • Immutable transaction records
  • Complete audit trail
  • Creator/approver tracking
  • 7-10 year retention

Access Control:

  • Financial data restricted to admin/finance roles
  • Account-scoped queries
  • Payment approval workflow (optional)

Deferred to V1.1+​

  • Payment authorization holds (preauth + capture)
  • Multi-currency support
  • FX conversion
  • Automated refunds (policy-triggered)
  • Payment plans and deposits
  • Alternative payment methods (ACH, wire)
  • Accounting system integration

V1.1 - ADVANCED PAYMENT FEATURES​

Status: Future Scope: Enhanced payment capabilities

New Features​

Payment Authorization Holds:

  • Preauthorize before checkout date
  • Capture on check-in or completion
  • Automatic release if not captured
  • Reduced fraud risk

Multi-Currency Support:

  • Real-time FX conversion
  • Currency-specific pricing
  • Payout currency selection
  • FX rate tracking

Automated Refunds:

  • Cancellation policy integration
  • Automatic refund calculation
  • No manual approval required
  • Configurable thresholds

Payment Plans:

  • Deposit at booking
  • Balance before arrival
  • Installment schedules
  • Automatic reminders

Alternative Methods:

  • ACH/SEPA bank transfers
  • Wire transfer tracking
  • Check recording
  • Cryptocurrency (exploratory)

Database Changes​

  • Add FX conversion tracking
  • Payment schedule tables
  • Preauth/capture state
  • Currency configuration

Impact​

  • Improved cash flow management
  • International property support
  • Reduced manual processing
  • Enhanced guest flexibility

V1.2 - RECONCILIATION & COMPLIANCE​

Status: Future Scope: Financial automation and compliance

New Features​

Reconciliation Engine:

  • Automated ledger vs provider statement comparison
  • Discrepancy detection
  • Variance reporting
  • Reconciliation dashboard

Accounting Integration:

  • QuickBooks Online API
  • Xero integration
  • NetSuite connector
  • Chart of accounts mapping

Double-Entry Bookkeeping:

  • Full debit/credit implementation
  • Journal entries
  • Account hierarchy
  • Financial reports (P&L, balance sheet)

Tax Engine:

  • Tax calculation integration
  • 1099 generation
  • Tax reporting
  • Jurisdiction tracking

Fraud Detection:

  • Risk scoring
  • Chargeback monitoring
  • Suspicious pattern detection
  • Automated holds

KYC/AML Workflows:

  • Enhanced verification
  • Document collection
  • Risk assessment
  • Compliance reporting

Impact​

  • Reduced accounting errors
  • Automated financial reporting
  • Regulatory compliance
  • Fraud prevention

V2.0 - ENTERPRISE FINANCIAL MANAGEMENT​

Status: Future Scope: Advanced financial operations

New Features​

Split Disbursements:

  • Multi-party payouts in single transaction
  • Complex revenue sharing
  • Automatic distribution

Escrow Management:

  • High-value booking protection
  • Milestone-based releases
  • Dispute resolution support

Invoice Generation:

  • Automated invoice creation
  • PDF generation
  • Custom branding
  • Email delivery

Financial Dashboards:

  • Real-time metrics
  • P&L statements
  • Balance sheets
  • Cash flow projections

Multi-Entity Consolidation:

  • Corporate parent + subsidiaries
  • Consolidated reporting
  • Inter-entity transfers

Payment Gateway Optimization:

  • Multi-gateway support
  • Automatic failover
  • Cost optimization routing
  • Success rate tracking

Impact​

  • Enterprise-scale operations
  • Complex business models
  • Advanced financial management
  • Cost optimization

Feature Availability Matrix​

FeatureMVP.0MVP.1V1.0V1.1V1.2V2.0+
Stripe Connect❌❌✅✅✅✅
Payment Processing (Card)❌❌✅✅✅✅
Manual Payment Recording❌❌✅✅✅✅
Automated Payouts❌❌✅✅✅✅
Manual Refunds❌❌✅✅✅✅
Transaction Ledger❌❌✅✅✅✅
Balance Tracking❌❌✅✅✅✅
Payment Preauth❌❌❌✅✅✅
Multi-Currency❌❌❌✅✅✅
Automated Refunds❌❌❌✅✅✅
Payment Plans❌❌❌✅✅✅
ACH/Bank Transfer❌❌❌✅✅✅
Reconciliation Engine❌❌❌❌✅✅
Accounting Integration❌❌❌❌✅✅
Double-Entry Bookkeeping❌❌❌❌✅✅
Fraud Detection❌❌❌❌✅✅
Split Disbursements❌❌❌❌❌✅
Escrow Management❌❌❌❌❌✅
Invoice Generation❌❌❌❌❌✅

Dependencies​

Upstream Dependencies (Required First)​

  • Identity & Tenancy (MVP.0) - Org/Account structure
  • Bookings (V1.0) - Payment obligations source
  • Pricing & Revenue (V1.0) - Revenue split rules
  • Authorization & Access (MVP.0) - Permission enforcement

Downstream Dependencies (Requires This Domain)​

  • Analytics & Audit (V1.0+) - Financial metrics
  • Channels & Distribution (V1.0+) - Channel payment routing

Migration Path​

From MVP.0/MVP.1 → V1.0​

Prerequisites:

  1. Create Stripe Platform account
  2. Configure Connect application
  3. Obtain API keys
  4. Configure webhooks

Data Migration:

  1. Create Ledger for each existing Organization
  2. Initialize PaymentAccount records for properties
  3. Complete Stripe Connect onboarding for existing accounts
  4. No payment history to migrate (starting fresh)

Integration Setup:

  1. Implement Stripe Connect OAuth flow
  2. Configure webhook endpoints
  3. Set up webhook signature validation
  4. Implement payment intent workflow
  5. Configure transfer automation

Estimated Effort: 4-6 weeks

  • Stripe integration: 2 weeks
  • Schema deployment: 1 day
  • Payment API implementation: 2 weeks
  • Payout automation: 1 week
  • Testing and compliance: 1-2 weeks

V1.0 → V1.1 (Advanced Payments)​

Migration Steps:

  1. Extend schema for multi-currency
  2. Add preauth state tracking
  3. Implement FX rate service
  4. Deploy payment schedule tables
  5. Migrate existing data (minimal changes)

Estimated Effort: 3-4 weeks

V1.1 → V1.2 (Reconciliation)​

Integration Steps:

  1. Select accounting platform (QuickBooks/Xero)
  2. Implement OAuth integration
  3. Map chart of accounts
  4. Build reconciliation engine
  5. Parallel run validation

Estimated Effort: 6-8 weeks

Stripe Connect Configuration​

Account Types​

Platform Account (TVL):

  • Standard platform account
  • Collects application fees
  • Manages transfers
  • Handles disputes

Connected Accounts (Property Owners):

  • Standard Connect accounts
  • Independent Stripe accounts
  • Full dashboard access
  • Direct bank deposit

Fee Structure​

Payment Processing:

  • Stripe fee: 2.9% + $0.30 per transaction
  • Platform fee: Configurable per RevenueRules
  • All fees deducted at payment time

Payouts:

  • Stripe transfer fee: $0.25 per transfer (US)
  • International: Variable by country
  • Instant payouts: 1% (optional upgrade)

Webhook Events​

Required Events:

  • payment_intent.succeeded
  • payment_intent.payment_failed
  • transfer.created
  • transfer.failed
  • account.updated
  • charge.refunded

Testing​

Test Mode:

  • Separate test keys
  • Test card numbers
  • Webhook testing
  • Transfer simulation

Production:

  • Phased rollout
  • Shadow mode (parallel processing)
  • Monitoring and alerting

Document Status: Complete Total Lines: 550+ Coverage: MVP.0 through V2.0