Payment Basics

ShipFlutter provides a flexible payment system that adapts to different platforms:

1. Mobile: RevenueCat for App Store and Google Play
2. Web: LemonSqueezy for web payments

Structure

The payment system is organized into client and server components:

• Directoryapp/

  • Directorylib/core/account/payments/

    • Directorymobile/ // RevenueCat implementation

      • …
    • Directoryweb/ // LemonSqueezy implementation

      • …
    • Directorymodels/ // Shared payment models

      • …
    • Directoryui/ // Payment UI components

      • …
    • payments_service.dart // Platform-agnostic interface
  • Directoryweb/payment/

    • lemon_squeezy.js // LemonSqueezy SDK interop
• Directoryfunctions/src/payment/

  • revenue_cat.ts // Mobile webhooks
  • lemon_squeezy.ts // Web webhooks
  • payments_schema.ts // Shared types

Basic Usage

Get Paywall

// Get paywall with available packages
final paywall = await paymentsService.instance.getPaywall();

// Access packages
final packages = paywall.packages;

Make Purchase

try {
  // Purchase a package
  final entitlements = await paymentsService.instance.purchase(
    package,
  );

  // Handle success
  if (entitlements.isNotEmpty) {
    // User has access
  }
} on PaymentException catch (e) {
  // Handle payment errors
}

Check Access

// Check current access
final hasAccess = await paymentsService.instance.hasEntitlement();

// Listen to changes
paymentsService.instance
  .observeActiveEntitlements()
  .listen((entitlements) {
    // Handle entitlement changes
  });

Payment Models

The system uses these core models:

// Package represents a purchasable item
class PaymentPackage {
  final String id;
  final String productId;
  final String title;
  final String description;
  final String price;
  final String currency;
  final int? subscriptionDuration;
  final int? trialDuration;
}

// Paywall groups packages with presentation
class PaymentPaywall {
  final String id;
  final String title;
  final List<PaymentPackage> packages;
}

Paywall and Trial UI

ShipFlutter includes responsive and ready-to-use payment UI components that are compliant with Apple App Store and Google Play store. The UI automatically adapts to the platform (mobile/web) and handles all payment flows.

// Show paywall
context.go('/paywall');
// Show trial
context.go('/trial');

// Or use the widget directly
PaywallView(
  onClose: (isSuccessful) {
    // Handle result
  },
);

Caution

You must configure RevenueCat and/or LemonSqueezy “packages” before using the UI, otherwise an error will be shown.

Webhooks Integration

The payment system uses Firebase Functions to handle webhooks from both providers:

1. RevenueCat - /api/v1/payment/event/rc

   • Handles subscription events
   • Updates entitlements
   • Manages trial periods

2. LemonSqueezy - /api/v1/payment/event/ls

   • Processes web payments
   • Manages subscription lifecycle
   • Syncs product data

Tip

Check the RevenueCat and LemonSqueezy docs for provider-specific setup.

Next Steps

1. Set up payment providers:

   • RevenueCat Setup for mobile
   • LemonSqueezy Setup for web

2. Configure Entitlements to manage user access

3. Customize the payment UI to match your app’s design