Mollie Integration Specification

This document specifies the Mollie Marketplaces integration for operator-to-passenger payment processing within the BusFlow platform.

Related docs: PRODUCT_payments-and-billing.md · schema-commerce.md §payments · ADR-009

WARNING

Review status: This spec was initially drafted during the L2 Checkout & Payment review. Sections marked [TBD — product decision] require explicit sign-off before implementation. Mollie API details (event names, endpoints, OAuth scopes) illustrate the process based on Mollie's public documentation; validate them at implementation time.

---

1. Architecture Overview

BusFlow uses Mollie Marketplaces to route passenger payments to individual operator sub-accounts. The platform acts as the marketplace owner (collecting platform fees), while each Operator tenant has a linked Mollie sub-account which receives payouts.

Passenger → Mollie Checkout → Platform Fee Split → Operator Sub-Account → Payout

Grounded in: PRODUCT_payments-and-billing.md §1 — "Mollie provides a high trust factor in Europe, natively supporting DACH payment methods. Its Marketplace routing allows for delayed payouts (acting as an escrow for bus trips)."

---

2. Sub-Account Provisioning (Operator Onboarding)

Each Operator requires a Mollie sub-account before accepting payments. Mollie-specific configuration resides in the operator_integrations table (not directly on operators), scoped by integration type. See schema-backoffice.md §operator_integrations.

Flow

Step	Actor	Action
1	Operator	Completes Nhost signup → Operator.status = ONBOARDING
2	System	Creates Mollie sub-account via Mollie Connect (OAuth)
3	Mollie	Returns organization identifier + onboarding URL
4	System	Stores Mollie organization identifier + onboarding status in the operator_integrations table (type = MOLLIE)
5	Operator	Completes Mollie KYC onboarding (identity, bank account, UBO — required by EU AML regulations)
6	Mollie	Fires onboarding webhook → System updates integration config → Operator ready to accept payments

NOTE

[TBD — implementation detail] The team must validate the exact Mollie Connect API flow (OAuth scopes, redirect URLs, onboarding webhook events) against Mollie documentation during implementation.

2.1 Integration Config (Mollie)

The system stores Mollie-specific fields in the operator_integrations table under type = 'MOLLIE' with a JSONB config column:

interface MollieIntegrationConfig {
  organization_id: string;           // Mollie sub-account ID
  onboarding_status: 'PENDING' | 'COMPLETED' | 'NEEDS_DATA';
  // Additional Mollie-specific fields as needed at implementation
}

2.2 Operator Payment Config

The following fields remain on the operators table (or in operator-level config), as they are platform concerns — not Mollie-specific:

Field	Type	Description
deposit_config	JSONB	Operator-level deposit rules (see §3)
final_payment_config	JSONB	Operator-level final payment timing (see §4.2)

NOTE

deposit_config and final_payment_config are tenant-level defaults. Operators can override both per TourTemplate.

---

3. Deposit Configuration

The system resolves the deposit percentage via a cascading lookup:

1. tour_templates.deposit_config (if set → use this)
2. operators.deposit_config (tenant default)
3. System default: [TBD — product decision: default deposit percentage, likely governed by § 651a BGB]

JSONB Structure

interface DepositConfig {
  percentage: number;     // e.g., 20 (= 20%)
  type: 'PERCENTAGE' | 'FIXED';
  min_amount: number | null;  // Optional floor
}

IMPORTANT

[TBD — product decision] The system default deposit percentage (fallback when neither template nor operator defines one) must be a conscious product decision. § 651a BGB governs travel package advance payment limits — legal review required.

---

4. Checkout-to-Payment Pipeline

4.1 B2C Payment Flow

Step	Entity	State	Mollie Action
1	CheckoutSession	ACTIVE	—
2	Booking	DRAFT	—
3	Payment (DEPOSIT)	PENDING	Create Mollie payment with deposit amount + marketplace routing
4	Passenger	—	Redirect to Mollie Checkout (hosted payment page)
5	Mollie webhook	payment completed	NestJS receives callback
6	Payment (DEPOSIT)	COMPLETED	provider_transaction_id + payment_method saved
7	Booking	DEPOSIT_PAID	BookingConfirmed event emitted → CostingSheet locks
8	CheckoutSession	CONVERTED	—
9	SeatReservation	CONFIRMED	—
10	Ticket	conditional	If ticket_issuance_trigger = DEPOSIT_PAID (operator default): ticket issued now. If FULLY_PAID: deferred to final payment. See ADR-014.

Grounded in: ADR-009 — DEPOSIT_PAID as BookingConfirmed trigger. Full booking lifecycle in booking-lifecycle-protocol.md.

4.2 Final Payment Flow

The final payment reminder timing is operator-configurable via final_payment_config:

interface FinalPaymentConfig {
  reminder_days_before_start: number;   // e.g., 30 — first reminder at start_date - N days
  escalation_days_before_start: number; // e.g., 14 — second reminder / escalation
  flag_days_before_start: number;       // e.g., 7  — flag for dispatcher review
}

Resolution cascade: tour_templates.final_payment_config → operators.final_payment_config → system default [TBD].

Step	Trigger	Action
1	Hasura Scheduled Trigger final_payment_reminder	Daily scan: for each booking in DEPOSIT_PAID, checks if start_date - reminder_days_before_start ≤ today
2	FinalPaymentDue event	Communications sends Magic Link via configured channels
3	Passenger clicks Magic Link	Opens passenger portal showing outstanding balance
4	Payment (FINAL_PAYMENT)	PENDING → Mollie Checkout
5	Mollie webhook: payment completed	Payment.status = COMPLETED
6	Booking	FULLY_PAID

IMPORTANT

If the system does not receive the final payment by escalation_days_before_start, it sends a second reminder. If it still does not receive the payment by flag_days_before_start, it flags the booking for dispatcher review (manual follow-up or cancellation). We do not implement automatic cancellation in V1.

4.3 B2B Payment Flow

NOTE

[TBD — product decision] B2B agencies may bypass B2C deposit rules and book on agency invoice (see booking-widget/user-journeys.md Journey 3). The B2B payment flow, commission handling, and invoice-based booking mechanism are out of scope for this spec and Management will define them separately.

---

5. Webhook → State Transition Mapping

A dedicated NestJS webhook handler receives all Mollie webhooks.

NOTE

The Mollie event names below illustrate the process based on Mollie's webhook documentation. The team must validate the actual event names, payload structure, and delivery guarantees against the Mollie API at implementation time. The state transitions (which Booking/Payment status follows which payment outcome) constitute the authoritative part of this table.

NOTE

For the complete processPaymentWebhook NestJS handler contract (input, guards, idempotency, cascade sequences), see booking-lifecycle-protocol.md §processPaymentWebhook.

Payment Webhooks

Payment Outcome	Payment Type	Payment Status	Booking Status	Side Effects
Payment succeeded	DEPOSIT	→ COMPLETED	→ DEPOSIT_PAID	Emit BookingConfirmed; lock CostingSheet; confirm SeatReservations; issue Tickets (if ticket_issuance_trigger = DEPOSIT_PAID)
Payment succeeded	FINAL_PAYMENT	→ COMPLETED	→ FULLY_PAID	Update FinancialLedger realized revenue; issue Tickets (if ticket_issuance_trigger = FULLY_PAID)
Payment failed	any	→ FAILED	— (no change)	Emit PaymentFailed → Communications sends retry link
Payment expired	any	→ FAILED	— (no change)	If DEPOSIT: release SeatReservations, expire CheckoutSession. If FINAL_PAYMENT: flag for dispatcher review.
Payment canceled	any	→ FAILED	— (no change)	Same as expired

Refund Webhooks

Refund Outcome	Payment Status	Booking Status	Side Effects
Refund settled	→ REFUNDED	→ REFUNDED (if full) / unchanged (if partial)	Create Payment row with type = REFUND or PARTIAL_REFUND, negative amount. The operator's Mollie sub-account balance funds the refunds. Update FinancialLedger.

Onboarding Webhooks

Onboarding Outcome	Integration Impact
Onboarding completed	Update operator_integrations config: onboarding_status = COMPLETED, enable payment acceptance
Needs additional data	Flag operator for data completion

---

6. Marketplace Routing (Split Payments)

Every payment call includes Mollie Marketplace routing to split funds between the BusFlow platform and the operator sub-account.

IMPORTANT

[TBD — product decision] Platform fee structure: flat percentage per transaction? Tiered by operator volume? Per-operator negotiated rate? This is a core business model decision. The routing mechanism supports any of these — the fee calculation logic is the product decision.

WARNING

[TBD — product decision] Platform fee calculation source: Every payment operation (§8) requires a platform fee value for marketplace routing. No schema or config table currently stores this value. Options: (1) column on operators (per-operator negotiated), (2) global platform config, (3) Lago-driven metered billing sync. We must resolve this before we can implement payment routing.

BusFlow does not manage payout timing directly. Operators configure their payout preferences in their Mollie dashboard (linked from the BusFlow backoffice).

---

7. Error Handling & Idempotency

Concern	Strategy
Idempotency	All webhook handlers are idempotent. provider_transaction_id (unique constraint on payments table) prevents duplicate processing.
Retry delivery	Mollie retries webhook delivery with exponential backoff over ~8 hours (per Mollie documentation). A daily payment_reconciliation_sweep Scheduled Trigger catches any missed webhooks beyond this window (see booking-lifecycle-protocol.md §payment_reconciliation_sweep).
Verification	Handlers verify payment status via Mollie API before applying state transitions — do not trust webhook body alone.
Dead letters	Failed webhook processing follows the error handling pattern in workflow-orchestration.md.

Failure Scenarios

Scenario	Handling
Webhook arrives before checkout completes	[TBD — implementation detail] Queue and process when Booking exists.
Mollie API unavailable at payment creation	Return error to frontend, retry with backoff. [TBD — retry strategy]
Double webhook delivery	Idempotency guard on provider_transaction_id
Partial marketplace routing failure	Log, alert ops, manual reconciliation via Mollie dashboard

---

8. Payment Service Contracts

Service-level operations for payment creation. All operations include Mollie Marketplace routing (§6) and the payment_type discriminator in Mollie metadata for webhook routing. For the webhook handler contract, see booking-lifecycle-protocol.md §processPaymentWebhook.

Booking Payment Operations

Operation	Key Inputs	Output	Notes
Create deposit payment	booking_id, tenant_id, amount (from DepositConfig §3), currency	Mollie checkout URL	Amount calculated from DepositConfig cascade. Includes marketplace routing (§6).
Create final payment link	booking_id, amount_remaining (= total_amount − completed deposits)	Checkout URL (sent via Magic Link §4.2)	Same routing as deposit.
Create partial refund	Payment reference, amount, description	—	Refunds against operator sub-account balance.

8.1 Onboard Payment Link Contracts

The following contracts support the OnboardSale → Commerce Payment Link Bridge flow. The Operations sync handler calls the onboard checkout operation when processing an OnboardSale with payment_method = PAYMENT_LINK. See schema-operations.md §onboard_sales for the full sync handler flow and edge states.

Operation	Key Inputs	Output	Notes
Create onboard checkout session	tenant_id, onboard_sale_id, tour_offering_id, item_description, amount, currency, passenger_contact (phone and/or email)	checkout_session_id, checkout_url, expires_at	Default expiry: 60 min. Operator-configurable via operator_settings.onboard_payment_link_ttl_minutes (default: 60, min: 15, max: 180). Idempotent on onboard_sale_id — returns existing non-expired session if one exists (crash-gap recovery, see schema-operations.md §onboard_sales).

Passenger contact is passed as transient input (not persisted on OnboardSale). Primary: phone (WhatsApp/SMS). Fallback: email.

Cancellation Contract

Operation	Input	Output	Side Effects
Cancel onboard checkout	checkout_session_id, tenant_id, reason	—	Expires session, cancels Mollie payment. If already paid → initiates refund.

Called by the Operations void handler when the driver voids an OnboardSale.

NOTE

Uses the standard Mollie Payments API (/v2/payments) — consistent with the booking checkout pattern. The checkout_url from the response is shareable via WhatsApp/SMS. Alternative: Mollie Payment Links API (/v2/payment-links) generates dedicated shareable URLs with built-in expiry — consider if the standard checkout_url expiry behavior proves insufficient.

NOTE

Passenger contact resolution: Primary path: ticket_id → commerce.tickets → passengers (email/phone) for upsells to existing passengers. Fallback: driver-entered phone number (transient input passed in passenger_contact, not persisted on OnboardSale) for non-ticketed sales.