Skip to main content

​
1. Prerequisites

  • Flutter SDK >=3.x
  • A Cashful merchant account with:
    • Merchant ID — identifies your merchant account
    • API key — authenticates API requests (created in the merchant dashboard under Settings > API Keys)
  • Familiarity with StatefulWidget, async/await, and basic WebView concepts

​
2. Installation

Add both dependencies to your pubspec.yaml: 
dependencies:
  flutter:
    sdk: flutter
  webview_flutter: ^4.13.1
  flutter_cashful:
    git:
      url: https://github.com/cashful/flutter_cashful.git
      # Pin to a specific version for stability:
      # ref: v0.8.6
If you’re developing against a local clone of the SDK: 
dependencies:
  flutter_cashful:
    path: ../github/cashful/flutter_cashful
Run: 
flutter pub get

​
3. Platform Configuration

​
Android

​
Internet Permission (Required)

The default Flutter project only includes the INTERNET permission in debug/profile build variants. You must add it to the main manifest for release builds to work. Edit android/app/src/main/AndroidManifest.xml: 
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required for WebView to load checkout URLs -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <application
        android:label="your_app"
        ...>
        <!-- existing content -->
    </application>
</manifest>

​
Minimum SDK Version

webview_flutter requires Android API 21+. If your minSdk is delegated to flutter.minSdkVersion (the default), this is already satisfied. To set it explicitly, edit android/app/build.gradle.kts: 
defaultConfig {
    minSdk = 21  // or higher
    // ...
}

​
iOS

No additional configuration is required. webview_flutter uses WKWebView on iOS, which is available on all supported iOS versions. The Cashful checkout is served over HTTPS, so App Transport Security (ATS) does not need to be modified.

​
4. SDK Setup

Configure the API client with your API key: 
import 'package:flutter_cashful/api.dart';

class CashfulConfig {
  // In production, session creation should happen on your backend.
  // See the Security Considerations section.
  static const String _baseUrl = 'https://sandbox.api.cashful.africa';

  static ApiClient createClient(String apiKey) {
    final auth = ApiKeyAuth('header', 'x-api-key');
    auth.apiKey = apiKey;

    return ApiClient(
      basePath: _baseUrl,
      authentication: auth,
    );
  }
}
EnvironmentBase URL
Sandboxhttps://sandbox.api.cashful.africa
Productionhttps://api.cashful.africa