Amwal Pay SDK Flutter

A Flutter SDK for integrating Amwal Pay payment solutions into your mobile apps, providing secure, seamless, and customizable payment experiences.

Features

• Multi-Platform Support: Android, iOS, Web, macOS, Windows, Linux
• WASM Compatibility: Full support for WebAssembly compilation (Flutter 3.32.0+)
• Payment Methods: Card payments, wallet payments, QR payments
• Security: Built-in security features and encryption
• Customizable UI: Flexible and customizable payment interfaces with bottom sheet design and color theming

WASM Compatibility

This SDK is fully compatible with Flutter's WebAssembly (WASM) compilation for web platforms. WASM provides:

• Better Performance: Near-native execution speed in web browsers
• Smaller Bundle Size: Optimized compilation for web deployment
• Modern Web Standards: Leverages the latest web technologies

WASM Requirements

• Flutter 3.32.0 or higher
• Dart 3.8.0 or higher
• Modern web browsers with WASM support

Building for WASM

# Build with WASM support
flutter build web --wasm

# Build with JavaScript fallback
flutter build web

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  amwal_pay_sdk: ^1.1.26

Usage

import 'package:amwal_pay_sdk/amwal_pay_sdk.dart';

// Initialize the SDK
await AmwalPaySdk.instance.initSdk(
  settings: AmwalSdkSettings(
    merchantId: 'your_merchant_id',
    terminalId: 'your_terminal_id',
    amount: '100.00',
    currency: 'OMR',
    transactionId: 'unique_transaction_id',
    sessionToken: 'your_session_token',
    environment: Environment.PROD,
    merchantReference: 'optional_merchant_reference', // Optional: Merchant reference for transaction tracking
  ),
);

Optional Parameters

• merchantReference: An optional merchant reference string that can be used to associate the payment with a specific order or reference number in your system. This field is passed through to the Execute endpoints when provided.

Optimizing App Size (Important)

When integrating the Amwal Pay Native SDKs into your app, you must apply the following configurations to avoid drastically inflating your production app size by 100-200MB.

Android

By default, Flutter builds native libraries (.so files) for multiple architectures, including x86_64 (emulator-only). If you build a universal APK without filtering, your app size will increase unnecessarily.

The amwalsdk library module already restricts its own native code to production architectures (arm64-v8a and armeabi-v7a) via abiFilters in its build.gradle.kts. This prevents the SDK itself from contributing emulator-only slices to your app.

Additionally, in your app's app/build.gradle (Kotlin DSL: app/build.gradle.kts), you should also apply abiFilters to ensure the final APK only includes supported architectures:

// Kotlin DSL (build.gradle.kts)
android {
    defaultConfig {
        ndk {
            // Exclude x86/x86_64 (emulator-only) from production releases
            abiFilters += listOf("arm64-v8a", "armeabi-v7a")
        }
    }
}

// Groovy DSL (build.gradle)
android {
    defaultConfig {
        ndk {
            // Exclude x86/x86_64 (emulator-only) from production releases
            abiFilters 'arm64-v8a', 'armeabi-v7a'
        }
    }
}

Note: For Play Store distribution, prefer Android App Bundles (AAB) — Google Play will automatically deliver only the architectures required by each device, eliminating the need for manual abiFilters.

iOS

The SDK podspec defaults to the Release subspec to ensure production apps remain small. However, the Release subspec does not support the iOS Simulator.

To test on the Simulator during development, you must map the Debug subspec to your project's Debug configuration in your Podfile:

target 'YourAppTarget' do
  # Link Debug subspec for Debug builds (Supports Simulator)
  pod 'amwalsdk/Debug', :configurations => ['Debug']
  # Link Release subspec for Release builds (Optimized, physical device only)
  pod 'amwalsdk/Release', :configurations => ['Release']
end

Platform Support

Platform	Status	Notes
Android	✅ Full Support	Native Android implementation
iOS	✅ Full Support	Native iOS implementation
Web (JavaScript)	✅ Full Support	Traditional web compilation
Web (WASM)	✅ Full Support	WebAssembly compilation
macOS	✅ Full Support	Native macOS implementation
Windows	✅ Full Support	Native Windows implementation
Linux	✅ Full Support	Native Linux implementation

Web Platform

The web platform supports both JavaScript and WASM compilation modes:

• JavaScript Mode: Traditional compilation for broader browser compatibility
• WASM Mode: Modern compilation for better performance and smaller bundles

Web-Specific Features

• Responsive design for all screen sizes
• Touch and mouse input support
• Progressive Web App (PWA) capabilities
• Cross-browser compatibility

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• GitHub Issues: Create an issue
• Documentation: SDK Documentation
• Email: support@amwal.com

Additional Configuration

The SDK supports additionValues parameter for passing custom key-value pairs that can be used for various SDK functionalities including UI customization and payment flow control.

Default Addition Values

The SDK automatically provides default values:

• merchantIdentifier: "merchant.applepay.amwalpay" (used for Apple Pay configuration)

Available Configuration Options

You can customize the SDK behavior using the following additionValues keys:

UI Customization

• useBottomSheetDesign: 'true' | 'false' (default: 'false')

  • Controls the payment screen design
  • 'true': Uses the newer bottom sheet design (v2) - slides up from bottom covering 90% of screen
  • 'false': Uses the original full-screen design

• primaryColor: Hex color string (e.g., '#FF5733')

  • Sets the primary theme color for the SDK UI
  • Default: #7F22FF (purple)

• secondaryColor: Hex color string (e.g., '#33FF57')

  • Sets the secondary theme color for the SDK UI
  • Default: #37658c (blue)

Payment Flow

• ignoreReceipt: 'true' | 'false' (default: 'false')

  • Controls whether to show the receipt screen after transaction
  • 'true': Skips the receipt display
  • 'false': Shows the receipt screen

• merchantIdentifier: String (default: 'merchant.applepay.amwalpay')

  • Apple Pay merchant identifier for iOS

Usage Examples

import 'package:amwal_pay_sdk/amwal_pay_sdk.dart';

// Using default additionValues (automatically applied)
final settings = AmwalSdkSettings(
  environment: Environment.UAT,
  sessionToken: sessionToken,
  currency: 'OMR',
  amount: '100.0',
  merchantId: 'your_merchant_id',
  terminalId: 'your_terminal_id',
  transactionType: TransactionType.cardWallet,
  // additionValues will automatically include merchantIdentifier
);

// Using custom additionValues with bottom sheet design and colors
final customSettings = AmwalSdkSettings(
  environment: Environment.UAT,
  sessionToken: sessionToken,
  currency: 'OMR',
  amount: '100.0',
  merchantId: 'your_merchant_id',
  terminalId: 'your_terminal_id',
  transactionType: TransactionType.cardWallet,
  additionValues: {
    'useBottomSheetDesign': 'true',
    'primaryColor': '#FF5733',
    'secondaryColor': '#33FF57',
    'ignoreReceipt': 'false',
    'merchantIdentifier': 'merchant.custom.identifier'
  },
);

// Minimal configuration with just bottom sheet design
final minimalSettings = AmwalSdkSettings(
  environment: Environment.UAT,
  sessionToken: sessionToken,
  currency: 'OMR',
  amount: '100.0',
  merchantId: 'your_merchant_id',
  terminalId: 'your_terminal_id',
  transactionType: TransactionType.cardWallet,
  additionValues: {
    'useBottomSheetDesign': 'true'
  },
);

// Initialize and start payment
await AmwalPaySdk.instance.initSdk(settings: customSettings);

Note: All boolean values should be passed as strings ('true' or 'false'). Custom additionValues will be merged with defaults, with custom values taking precedence.

Bottom Sheet Design

When useBottomSheetDesign is set to 'true', the payment screen will:

• Slide up from the bottom of the screen
• Cover approximately 90% of the screen height
• Automatically expand when keyboard is open
• Provide a modern, modal-style user experience
• Include rounded corners at the top (24px radius)
• Allow dismissal by dragging down (if enabled)

This design is particularly useful for maintaining context with the parent application while providing a focused payment experience.