ensemble_stripe 1.2.55

Stripe payment integration for Ensemble framework with support for Stripe Elements and Stripe Payment Intents.

Ensemble Stripe Module

A Stripe payment integration module for the Ensemble framework, providing easy-to-use actions for handling payments with Stripe's Payment Sheet.

Features

• Payment Processing: Initialize Stripe and show payment sheets
• Payment Sheet: Display the native Stripe payment sheet for secure payments
• Error Handling: Comprehensive error handling with onError callbacks
• Modular Design: Easy to extend with new payment features

Installation

Option 1: Using the Starter Script (Recommended)

Run the enable script from your starter project:

npm run hasStripe

This will automatically:

• Add the ensemble_stripe dependency to pubspec.yaml
• Set useStripe = true and register StripeModuleImpl in lib/generated/ensemble_modules.dart
• Add iOS camera permission strings (for Stripe card scanning)
• Add Android ProGuard rules for Stripe (when enabling for Android)

The enable script does not modify ensemble-config.yaml. Stripe YAML actions (initializeStripe, showPaymentSheet) are defined in the Ensemble runtime, but payment processing requires the real module implementation—not the stub.

Option 2: Manual Installation

Stripe is off by default (useStripe = false registers StripeModuleStub). To enable the module, add it to your Ensemble project:

dependencies:
  ensemble_stripe:
    git:
      url: https://github.com/EnsembleUI/ensemble.git
      ref: main
      path: modules/ensemble_stripe

Configuration

Stripe should be initialized using the initializeStripe action. This allows you to:

• Initialize Stripe with different keys for different environments
• Initialize Stripe conditionally based on user preferences
• Initialize Stripe with dynamic configuration from your backend

# Example: Initialize Stripe with dynamic configuration
initializeStripe:
  publishableKey: ${apiResponse.stripeKey}
  onSuccess:
    showToast:
      message: "Stripe ready for payments"

Actions

initializeStripe

Initialize Stripe with custom configuration. This is the primary way to initialize Stripe in your application.

initializeStripe:
  publishableKey: "pk_test_your_publishable_key_here"  # Required
  stripeAccountId: "acct_optional_account_id"  # Optional
  merchantIdentifier: "merchant.com.yourapp"   # Optional, for Apple Pay
  onSuccess:
    showToast:
      message: "Stripe initialized successfully"
  onError:
    showToast:
      message: "Failed to initialize Stripe"

Parameters:

• publishableKey (required): Your Stripe publishable key
• stripeAccountId (optional): Your Stripe account ID for Connect applications
• merchantIdentifier (optional): Your merchant identifier for Apple Pay
• onSuccess (optional): Action to execute when initialization succeeds
• onError (optional): Action to execute when initialization fails

showPaymentSheet

Display the native Stripe payment sheet.

showPaymentSheet:
  clientSecret: "pi_client_secret_here"
  configuration:
    merchantDisplayName: "Your Company"
    primaryButtonLabel: "Pay Now"
    style: "system"  # "light", "dark", or "system"
    billingDetails:
      name: "John Doe"
      email: "[e-mail]"
      phone: "[phone]"
      address:
        line1: "123 Main St"
        city: "New York"
        state: "NY"
        postalCode: "10001"
        country: "US"
  onSuccess:
    showToast:
      message: "Payment completed successfully"
  onError:
    showToast:
      message: "Payment failed"

Complete Example

Here's a complete example of a payment flow:

View:
  body:
    Column:
      children:
        - Text:
            text: "Complete Payment"
            styles:
              fontSize: 24
              fontWeight: bold
              marginBottom: 20
        
        - Button:
            text: "Initialize Stripe"
            styles:
              backgroundColor: "#28a745"
              color: white
              padding: 15
              borderRadius: 8
              marginBottom: 10
            onTap:
              initializeStripe:
                publishableKey: "pk_test_your_publishable_key_here"
                onSuccess:
                  showToast:
                    message: "Stripe initialized successfully"
                onError:
                  showToast:
                    message: "Failed to initialize Stripe"
        
        - Button:
            text: "Pay $20.00"
            styles:
              backgroundColor: "#007AFF"
              color: white
              padding: 15
              borderRadius: 8
            onTap:
              showPaymentSheet:
                clientSecret: "pi_test_client_secret_here"
                configuration:
                  merchantDisplayName: "Your Company"
                  primaryButtonLabel: "Pay Now"
                  style: "system"
                onSuccess:
                  showToast:
                    message: "Payment successful!"
                onError:
                  showToast:
                    message: ${event.error}

Configuration

iOS Configuration

Compatible with apps targeting iOS 13 or above. To upgrade your iOS deployment target to 13.0, you can either do so in Xcode under your Build Settings, or by modifying IPHONEOS_DEPLOYMENT_TARGET in your project.pbxproj directly.

You will also need to update in your Podfile:

platform :ios, '13.0'

For card scanning add the following to your ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Scan your card to add it automatically</string>

Android Configuration

Ensure your Android app uses:

• Android 5.0 (API level 21) and above
• Kotlin version 1.8.0 and above
• Android Gradle plugin 8 and higher
• FlutterFragmentActivity instead of FlutterActivity

Error Handling

All actions support error handling through the onError callback. The error information is available in the event data:

onError:
  showToast:
    message: "Error: {{event.error}}"

Dependencies

• flutter_stripe: ^11.5.0
• ensemble: path: ../ensemble
• get_it: ^8.0.3

License

This module follows the same license as the Ensemble framework.