GlomoPay Flutter SDK v0.0.3

Deprecated - This documentation is for Flutter SDK v0.0.3, which is past end of life and is no longer supported. Versions 1.0.3 and below are deprecated. For the latest version, see Flutter SDK v2.

The GlomoPay Flutter SDK provides a seamless, secure, and customizable payment checkout experience for your Flutter applications. Supports all Glomo payment flows (like 3DS auth or bank redirects), built-in security compliance checks, and error handling.

Before using this SDK, you need:

• API credentials (Public Key) from your GlomoPay dashboard
• Flutter >= 3.7.0
• Dart SDK >= 3.0.0

Add to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  glomopay_sdk: ^0.0.3

Or run:

flutter pub add glomopay_sdk

import 'package:glomopay_sdk/glomopay_sdk.dart';

Add the following to 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>

Add the following to ios/Runner/Info.plist:

<dict>
    <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>

Before starting the checkout flow, create an order and obtain the Order ID (starts with order_).

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',
        ),
        onPaymentSuccess: (GlomoPayPayload payload) {
          print('Payment succeeded! Payment ID: ${payload.paymentId}');
        },
        onPaymentFailure: (GlomoPayPayload payload) {
          print('Payment failed with Order ID: ${payload.orderId}');
        },
        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);
        },
      ),
    );
  }
}

• Glomo Payment Stack Support - Handles standard checkout flows and overlay redirects (3DS, bank pages) seamlessly.
• Security Compliance - Built-in jailbreak and root detection to ensure transactions happen on secure devices.
• Error Monitoring - Built-in error tracking and diagnostics.
• Error Handling - Handles connection drops, DNS issues, HTTP errors, and validation errors.
• Native Support - Full support for Android and iOS native features like the camera and file pickers.
• Mock Mode - Easy testing with test keys (test_..., mock_...).

Returned via onPaymentSuccess and onPaymentFailure:

class GlomoPayPayload {
  final String orderId;      // The order ID (e.g., "order_abc123")
  final String? paymentId;   // The transaction reference, if generated
  final String? signature;   // Validation signature for backend verification
}

class SdkError {
  final SdkErrorType type;   // validationError, deviceForbidden, networkError, or unknown
  final String message;      // Human-readable description of the error
  final String? field;       // Field name that caused the error (e.g., "orderId")
}

Error Types:

• validationError - Input validation failed (invalid publicKey or orderId)
• deviceForbidden - Device does not meet compliance requirements (rooted or jailbroken devices are not permitted)
• networkError - A network-level error occurred
• unknown - An unclassified error

class ConnectionError {
  final ConnectionErrorType type;  // noInternet, timeout, dnsFailure, sslError, etc.
  final String message;            // Error description or HTTP status phrase
  final int? errorCode;            // Internal WebKit/Android error code
  final int? statusCode;           // HTTP status code, if applicable
  final bool isRecoverable;        // Whether it is safe to offer a retry option
}

Connection Error Types:

• noInternet - No internet connectivity
• timeout - Request timed out
• dnsFailure - DNS resolution failed
• sslError - SSL/TLS certificate error
• httpClientError - HTTP 4xx error
• httpServerError - HTTP 5xx error
• webResourceError - WebView resource loading error
• unknown - Unclassified connection error

Passed to onPaymentTerminate to indicate how the user exited:

• userDismiss - User swiped down to dismiss (iOS)
• backButton - User pressed the hardware back button (Android)

The SDK tracks the checkout lifecycle through the following states:

• Checkout appears inside a modal
• Users can dismiss by swiping down, which triggers onPaymentTerminate with TerminationSource.userDismiss

• Checkout appears in full-screen mode
• Pressing the hardware back button triggers onPaymentTerminate with TerminationSource.backButton
• The SDK intercepts back navigation and checks if the overlay WebView (e.g., 3DS bank page) can go back before closing

Mock mode is automatically enabled based on your publicKey:

• If publicKey starts with test_ or mock_ (case-insensitive), mock mode is enabled
• Otherwise, live mode is used

In mock mode:

• Connection heuristics allow mock traffic
• You can simulate transactions without real money movement

/**
 * Mock mode example
 * Use test_ or mock_ prefix for non-production testing
 */
GlomoPayConfig(
  publicKey: 'test_pk_12345',
  orderId: 'order_abc123',
)

Ensure orderId starts with "order_" and meets the minimum length requirement.

Verify config.publicKey is set correctly and starts with the expected prefix (live_ for production or test_ for mock mode).

Run flutter clean and ensure Camera and Storage permissions are granted in AndroidManifest.xml and Info.plist.

Rooted or jailbroken devices trigger onSdkError with a deviceForbidden error. Use an emulator or a non-rooted/jailbroken device for testing.

• Device Compliance - The SDK checks for jailbroken (iOS) or rooted (Android) devices and blocks checkout on non-compliant devices via onSdkError with deviceForbidden.
• Transport Security - All communication uses HTTPS. SSL errors are reported through onConnectionError.
• Signature Verification - The signature field in GlomoPayPayload should be verified server-side to confirm payment authenticity.

The SDK exports the following from package:glomopay_sdk/glomopay_sdk.dart:

• GlomoPayCheckout - The checkout widget
• GlomoPayConfig - Configuration class
• GlomoPayPayload - Payment result payload
• SdkError / SdkErrorType - Error model and enum
• ConnectionError / ConnectionErrorType - Connection error model and enum
• TerminationSource - Enum for how the user exited checkout
• LrsCheckoutStatus - Checkout lifecycle states

• Flutter SDK v2 (Latest)
• Flutter SDK v1 (Archived)
• Changelog
• React Native SDK
• Unified SDK (Web)