# GlomoPay Flutter SDK v0.0.13

> **Deprecated** - This documentation is for Flutter SDK **v0.0.13**, 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](/platform/sdk/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.

## Prerequisites

- A GlomoPay account with API keys (public key starting with `live_` or `test_`)
- An order ID generated from your server via the GlomoPay API


## System Requirements

- Flutter 3.0 or higher
- Dart 2.17 or higher
- Android: minSdkVersion 21 or higher
- iOS: iOS 13.0 or higher


## Installation

Add the `glomopay_sdk` to your `pubspec.yaml` dependencies:

```yaml
dependencies:
  flutter:
    sdk: flutter
  glomopay_sdk: ^0.0.13
```

Then run:

```bash
flutter pub get
```

Import it in your Dart code:

```dart
import 'package:glomopay_sdk/glomopay_sdk.dart';
```

## Platform Setup

### Android

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

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

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

```xml
<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:

```dart
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);
        },
      ),
    );
  }
}
```

## Features

- **Glomo Payment Stack Support** - 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.
- **Error Monitoring** - Built-in error tracking and diagnostics.
- **Comprehensive Error Handling** - Handles 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_...`).


## API Reference

### GlomoPayCheckout Widget

/**

* The main checkout widget. Embed it in your widget tree
* to present the GlomoPay payment UI.
*/


| 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 is an internet drop, DNS failure, or severe HTTP error. |
| `onPaymentTerminate` | `Function(TerminationSource)?` | No | Called if the user dismisses the modal or hits back. |
| `autoCloseOnConnectionError` | `bool` | No | Whether the widget should automatically call `onPaymentTerminate` upon encountering a critical connection error. Defaults to `true`. |


### GlomoPayConfig

/**

* Configuration object passed to GlomoPayCheckout.
* Contains keys, order info, and environment settings.
*/


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


### GlomoPayPayload

/**

* Returned via onPaymentSuccess and onPaymentFailure callbacks.
* Contains the order reference and optional verification data.
*/


| Property | Type | Description |
|  --- | --- | --- |
| `orderId` | `String` | The system ID of the order. |
| `paymentId` | `String?` | The transaction reference, if generated. |
| `signature` | `String?` | The validation signature hash for backend verification. |


### SdkError

/**

* Represents an SDK-level error such as validation failure
* or a forbidden device condition.
*/


| Property | Type | Description |
|  --- | --- | --- |
| `type` | `SdkErrorType` | One of: `validationError`, `deviceForbidden`, `networkError`, `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

/**

* Represents a network or connectivity error encountered
* during the checkout flow.
*/


| Property | Type | Description |
|  --- | --- | --- |
| `type` | `ConnectionErrorType` | One of: `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. |


### TerminationSource

/**

* Indicates how the user exited the checkout flow
* before completing payment.
*/


| Value | Description |
|  --- | --- |
| `userDismiss` | The user swiped down or tapped a close button to dismiss the checkout. |
| `backButton` | The user pressed the Android back button to exit the checkout. |


### Checkout Status

/**

* Internal lifecycle states of the checkout session.
* Observable via the checkout lifecycle.
*/


| Status | Description |
|  --- | --- |
| `validating` | Input keys and devices are securely checked. |
| `ready` | Verified; loading the UI. |
| `paymentInProgress` | The user is currently entering card details or authorizing. |
| `paymentSuccessful` | Payment cleared. |
| `paymentFailed` | Processing declined. |
| `paymentCancelled` | The user exited before completing. |


## Platform-Specific Behavior

- **iOS Swiping** - The SDK intercepts iOS downward swipe gestures to dismiss the payment sheet and 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

Using a public key that starts with `test_` or `mock_` shifts the SDK into mock mode.

In this mode:

- 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)** - A root/jailbroken device will immediately trigger `onSdkError`. Test within your emulator.


## Security

- The SDK performs jailbreak/root detection at startup. Compromised devices trigger `onSdkError` with `SdkErrorType.deviceForbidden`.
- All checkout traffic is served over HTTPS. SSL errors are surfaced via `onConnectionError`.
- Public keys are validated before any network request is made.
- Payment credentials never pass through your application code - they are handled entirely within the secure WebView.


## Exports

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

- `GlomoPayCheckout` - The main checkout widget.
- `GlomoPayConfig` - Configuration model.
- `GlomoPayPayload` - Payment result payload.
- `SdkError` / `SdkErrorType` - SDK error model and type enum.
- `ConnectionError` / `ConnectionErrorType` - Connection error model and type enum.
- `TerminationSource` - Enum for checkout exit source.


## Related

- [Flutter SDK v2 (Latest)](/platform/sdk/flutter-sdk/v2)
- [Flutter SDK v1 (Archived)](/platform/sdk/flutter-sdk/v1)
- [Changelog](/platform/sdk/flutter-sdk/changelog)
- [React Native SDK](/platform/sdk/react-native-sdk)
- [Unified SDK (Web)](/platform/sdk/unified-sdk)