GlomoPay Flutter SDK

pub package license

The GlomoPay Flutter SDK provides a seamless, secure, and customizable payment checkout experience for your Flutter applications. It features a robust dual-webView architecture for handling complex payment flows (like 3DS auth or bank redirects), built-in security compliance checks, and comprehensive analytics tracking.

Features

  • Dual-WebView Architecture: Handles standard checkout flows and overlay redirects (3DS, bank pages) seamlessly.
  • Robust Security: Built-in jailbreak and root detection to ensure transactions happen on secure devices.
  • Deep Analytics: Automatic Segment analytics and Sentry error tracking for monitoring checkout performance.
  • Comprehensive Error Handling: Built to handle connection drops, DNS issues, HTTP errors, and validation mistakes gracefully.
  • Native Support: Full support for Android and iOS native features like the camera and file pickers required by certain payment methods.
  • Mock Mode: Easy testing with test keys (test_..., mock_...).

Installation

1. Depend on it

Add the glomopay_sdk to your pubspec.yaml dependencies:

dependencies:
  flutter:
    sdk: flutter
  glomopay_sdk: ^0.0.3

Alternatively, run this command in your terminal:

flutter pub add glomopay_sdk

This will automatically add the latest version of the SDK to your project and run an implicit flutter pub get.

2. Import it

Now in your Dart code, you can use:

import 'package:glomopay_sdk/glomopay_sdk.dart';

Platform Setup

Android Permissions & Setup

Add the required permissions in your android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required for the checkout flow -->
    <uses-permission android:name="android.permission.INTERNET"/>
    
    <!-- Required if you need users to upload images/documents during checkout -->
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" />
</manifest>

iOS Permissions & Setup

Add the keys to your ios/Runner/Info.plist:

<dict>
    <!-- Required for camera/file uploads during the checkout process -->
    <key>NSCameraUsageDescription</key>
    <string>This app requires access to the camera to upload documents required for payment verification.</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>This app requires access to the photo library to select documents for payment verification.</string>
</dict>

Quick Start

Import the library and display the GlomoPayCheckout widget.

import 'package:flutter/material.dart';
import 'package:glomopay_sdk/glomopay_sdk.dart';

class PaymentScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Complete Payment')),
      body: GlomoPayCheckout(
        config: const GlomoPayConfig(
          publicKey: 'test_pk_12345',
          orderId: 'order_abc123',
          devMode: true, // Set to false in production
        ),
        onPaymentSuccess: (GlomoPayPayload payload) {
          print('Payment succeeded! Payment ID: ${payload.paymentId}');
          // Navigate to success screen
        },
        onPaymentFailure: (GlomoPayPayload payload) {
          print('Payment failed with Order ID: ${payload.orderId}');
          // Show error message
        },
        onSdkError: (List<SdkError> errors) {
          print('SDK Error: ${errors.first.message}');
        },
        onConnectionError: (ConnectionError error) {
          print('Connection error: ${error.message}');
        },
        onPaymentTerminate: (TerminationSource source) {
          print('User cancelled checkout via $source');
          Navigator.pop(context);
        },
      ),
    );
  }
}

API Reference

GlomoPayCheckout Props

Prop Type Required Description
config GlomoPayConfig Yes The configuration details for the checkout session.
onPaymentSuccess Function(GlomoPayPayload) Yes Called when the payment is completed successfully.
onPaymentFailure Function(GlomoPayPayload) Yes Called when the transaction gets declined or fails.
onSdkError Function(List<SdkError>) Yes Called when an SDK-level error occurs (e.g., validation, or forbidden device).
onConnectionError Function(ConnectionError) Yes Called if there's an internet drop, DNS failure, or severe HTTP error.
onPaymentTerminate Function(TerminationSource)? No Called if the user dismisses the modal or hits back.
onEvent Function(String, Map)? No A generic listener for handling deep telemetry events.
autoCloseOnConnectionError bool No Whether the widget should automatically call onPaymentTerminate upon encountering a critical connection error. Defaults to true.

GlomoPayConfig

Property Type Default Description
publicKey String - Your GlomoPay public key (e.g., live_..., test_...).
orderId String - The unique tracking ID generated for this transaction on your server.
server String? null A custom LRS checkout URL (leave blank to use the official env URL).
devMode bool false Enables full debugging logs, console traces, and bypasses strict compliance checks.

Payload Types

GlomoPayPayload

Returned via onPaymentSuccess and onPaymentFailure:

  • orderId (String): The system ID of the order.
  • paymentId (String?): The transaction reference, if generated.
  • signature (String?): The validation signature hash for backend verification.

Error Models

SdkError

  • type (SdkErrorType): validationError, deviceForbidden, networkError, or unknown.
  • message (String): A human-readable description of the constraint that failed.
  • field (String?): The field name (e.g., "orderId") that caused the validationError.

ConnectionError

  • type (ConnectionErrorType): noInternet, timeout, dnsFailure, sslError, httpClientError, httpServerError, webResourceError, unknown.
  • message (String): Extracted error description or HTTP status phrase.
  • errorCode (int?): The internal WebKit/Android error code.
  • statusCode (int?): HTTP status code, if applicable.
  • isRecoverable (bool): Suggests if it is safe to offer a 'Retry' button.

Checkout Lifecycle States (LrsCheckoutStatus)

You can listen for changes via the onEvent generic listener or observe telemetry. Internal states are:

  1. validating: Input keys and devices are securely checked.
  2. ready: Verified; loading the UI.
  3. paymentInProgress: The user is currently typing card details or authorizing.
  4. paymentSuccessful: Payment clear.
  5. paymentFailed: Processing declined.
  6. paymentCancelled: The user bounced.

Platform-Specific Behavior

  • iOS Swiping: The SDK successfully intercepts iOS downward swipe gestures to dismiss the payment sheet and accurately triggers onPaymentTerminate with TerminationSource.userDismiss.
  • Android Back Button: Automatically overrides standard pop. First checks if the Flow WebView overlay (e.g. 3DS bank page) can go back. Does so accordingly until the modal is closed, returning TerminationSource.backButton.

Mock Mode Testing

Using a public key that starts with test_ or mock_ shifts the SDK into "mock mode." In this mode:

  • Analytics events attach a mock flag.
  • Connection heuristics allow mock traffic.
  • You can simulate fake transactions without real money movement.

Troubleshooting

  • Invalid Order ID format: Ensure orderId starts with "order_" and has appropriate length.
  • SDK crashes immediately on open: Ensure config.publicKey is correctly set and starts with the expected prefix (test_ or live_).
  • File upload buttons do nothing: Run flutter clean and ensure Camera/Storage permissions were explicitly granted in the native AndroidManifest and Info.plist layers.
  • Device Forbidden (Error): Your root/jailbroken device will immediately trigger onSdkError unless you test strictly within your emulator or with a custom devMode workaround logic enabled in your fork.

Libraries

glomopay_sdk