Skip to main content

💸 Payment and Payout Management

Welcome, Inner Journey financial wizards! This document details how Inner Journey manages customer payments and coach payouts, ensuring a seamless, scalable, and secure financial flow. We leverage Stripe for payments, Stripe Connect for payouts, and Fortnox for accounting, all automated within our Google Cloud infrastructure for maximum efficiency. Let's ensure the financial engine runs smoothly! 🌟

🛠️ Payment and Payout Strategy​

Our strategy focuses on automation and clear separation of concerns using specialized services.

Customer Payments​

  • Service: Stripe for processing all incoming payments (both one-time and recurring subscriptions).
  • Flow:
    • Frontend: Users initiate payments through a Stripe Elements form integrated into the application (e.g., for premium features or specific coaching programs).
    • Backend: Our /process-payment API endpoint interacts with Stripe to create a payment session, charge the user securely, and record the transaction details in Firestore upon success.
  • Pricing Models:
    • Monthly Subscription: Access to premium features (e.g., 99 SEK/month).
    • One-Time Payments: Enrollment in specific coaching programs (e.g., 499 SEK for a 4-week program).
  • Automation: Stripe automatically handles recurring subscription billing. Stripe Webhooks notify our backend about payment events (success, failure, etc.), which trigger updates in our Firestore database.

Coach Payouts​

  • Service: Stripe Connect for managing and distributing funds securely to our coaches.
  • Flow:
    • Onboarding: Coaches complete a Stripe Connect onboarding process directly within the Inner Journey app. This includes providing necessary bank details and identity verification to meet KYC (Know Your Customer) requirements.
    • Distribution Logic: When a customer payment is received (e.g., 499 SEK for a coaching program), Inner Journey retains a platform fee (e.g., 20%, which is 99 SEK). The remaining amount (400 SEK) is automatically allocated to the respective coach's connected Stripe account balance.
    • Scheduled Payouts: The /schedule-payouts backend endpoint initiates payouts from coaches' Stripe Connect balances to their linked bank accounts on a regular schedule (e.g., weekly).
  • Automation: A Google Cloud Scheduler job triggers the /schedule-payouts endpoint reliably every week (e.g., Monday at 08:00 CET).

Accounting Integration​

  • Service: Fortnox for streamlined and automated bookkeeping.
  • Flow:
    • Data Syncing: The /sync-accounting backend endpoint retrieves payment and payout data from Firestore and pushes it to Fortnox.
    • Automated Bookkeeping:
      • Customer payments are recorded as revenue (e.g., using Fortnox account 3001).
      • Platform fees are also recognized as revenue.
      • Payouts to coaches are booked as expenses (e.g., using Fortnox account 5090).
  • Automation: A Google Cloud Scheduler job triggers the /sync-accounting endpoint daily (e.g., at 02:00 CET) to keep financial records up-to-date.

📈 Scalability and Integration​

Our chosen tools and architecture are designed for growth.

Scalability​

  • Stripe & Stripe Connect: Natively designed to handle high transaction volumes and global payouts, scaling automatically with demand.
  • Firestore: Google's NoSQL database scales seamlessly to accommodate a growing number of transaction records (payments, payouts).
  • Google Cloud: Services like Cloud Run and Cloud Functions provide auto-scaling capabilities for our backend APIs (/process-payment, /schedule-payouts, /sync-accounting) and webhook handlers.

Integration with Existing System​

  • Frontend: Integrate Stripe Elements into relevant payment forms (e.g., within a dedicated PaymentForm.tsx component or similar).
  • Backend: Develop the new API endpoints (/process-payment, /schedule-payouts, /sync-accounting) within our existing FastAPI framework, utilizing shared services like firebase_service.py for database interactions.
  • Automation: Configure Google Cloud Scheduler jobs and Cloud Functions to manage scheduled tasks (payouts, accounting sync) and process incoming Stripe webhooks.
  • Security: Securely store sensitive API keys (Stripe, Fortnox) using Google Cloud Secret Manager. Protect payment-related endpoints using Firebase Authentication and appropriate authorization checks.

🗄️ Database Support​

To effectively manage financial data, we require two new Firestore collections:

Required Collections​

  • payments: Stores records of all customer transactions.

    • userId: String – Reference to the paying user in the users collection.
    • amount: Number – The total amount paid by the customer (e.g., 499).
    • currency: String – Currency code (e.g., "SEK").
    • date: Timestamp – Firestore timestamp indicating when the payment was processed.
    • status: String – Payment status (e.g., "succeeded", "failed", "pending").
    • subscriptionId: String (Optional) – Stripe subscription ID, if the payment relates to a subscription.
    • stripePaymentId: String – Unique Stripe Payment Intent ID for reconciliation.
    • description: String (Optional) – Description of the purchase (e.g., "Premium Subscription", "4-Week Coaching Program").

  • payouts: Stores records of funds paid out to coaches.

    • coachId: String – Reference to the receiving coach in the users collection (coach's UID).
    • amount: Number – The amount paid out to the coach (e.g., 400).
    • currency: String – Currency code (e.g., "SEK").
    • date: Timestamp – Firestore timestamp indicating when the payout was initiated or completed.
    • status: String – Payout status (e.g., "pending", "completed", "failed").
    • stripePayoutId: String – Unique Stripe Payout ID for tracking.
    • fortnoxReference: String (Optional) – Reference ID from Fortnox once the payout is successfully booked in accounting.
    • relatedPaymentIds: Array<String> (Optional) – List of payments document IDs related to this payout for traceability.

Database Update Note​

These new payments and payouts collections need to be formally added to our primary database structure documentation (e.g., database-structure.mdx).

📊 Monitoring and Error Handling​

Robust monitoring and error handling are crucial for financial operations.

  • Google Cloud Monitoring: Configure alerts to track key metrics like payment success rates, payout volumes, and API endpoint latency/errors. Notify the team of anomalies (e.g., spikes in failed payments, payout delays).
  • Google Cloud Logging: Ensure comprehensive logging for all payment, payout, and accounting sync operations, including detailed error messages for failed transactions or sync issues.
  • Stripe Webhooks: Implement reliable webhook handlers to process critical events from Stripe in near real-time (e.g., payment_intent.succeeded, payout.paid, payout.failed), ensuring Firestore data consistency.
  • Retry Mechanisms: Implement basic retry logic for transient failures in payout scheduling or Fortnox synchronization. Persistent errors should be logged clearly for manual investigation.

For detailed implementation specifics, refer to the relevant backend code: GitHub: backend/routes/