# GlomoPay Flutter SDK v0.0.3

> **Archived** - This documentation is for Flutter SDK **v0.0.3**. v0.0.3 is no longer the latest version.
For the latest version, see [Flutter SDK v1.0.4](/product-guide/sdk/flutter-sdk/v1).


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

Before using this SDK, you need:

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


## System Requirements

| Platform | Minimum Version |
|  --- | --- |
| Flutter | >= 3.7.0 |
| Dart SDK | >= 3.0.0 |
| Android | API 21+ |
| iOS | 13.0+ |


## Installation

### 1. Add Dependency

Add to your `pubspec.yaml`:

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

Or run:

```bash
flutter pub add glomopay_sdk
```

### 2. Import

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

## Platform Setup

### Android Permissions

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

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

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

## Quick Start

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

```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.
- **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_...`).


## API Reference

### GlomoPayCheckout Widget

#### Props

| Prop | Type | Required | Description |
|  --- | --- | --- | --- |
| `config` | `GlomoPayConfig` | Yes | Configuration details for the checkout session |
| `onPaymentSuccess` | `Function(GlomoPayPayload)` | Yes | Called when payment completes successfully |
| `onPaymentFailure` | `Function(GlomoPayPayload)` | Yes | Called when the transaction declines or fails |
| `onSdkError` | `Function(List<SdkError>)` | Yes | Called on SDK-level validation or configuration errors |
| `onConnectionError` | `Function(ConnectionError)` | Yes | Called on internet drops, DNS failures, or HTTP errors |
| `onPaymentTerminate` | `Function(TerminationSource)?` | No | Called when the user dismisses the modal or presses back |
| `autoCloseOnConnectionError` | `bool` | No | Auto-close widget on connection error (default: `true`) |


### GlomoPayConfig

| Property | Type | Default | Description |
|  --- | --- | --- | --- |
| `publicKey` | `String` | - | Your GlomoPay public key. Starts with `live_` (production) or `test_`/`mock_` (mock mode) |
| `orderId` | `String` | - | The order ID for this transaction. Must start with `order_` |


### GlomoPayPayload

Returned via `onPaymentSuccess` and `onPaymentFailure`:

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

### SdkError

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


### ConnectionError

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


### TerminationSource

Passed to `onPaymentTerminate` to indicate how the user exited:

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


### Checkout Status

The SDK tracks the checkout lifecycle through the following states:

| Status | Description |
|  --- | --- |
| `validating` | Input keys and device compliance are being checked |
| `ready` | Validation passed; loading the checkout UI |
| `paymentInProgress` | User is actively completing the payment |
| `paymentSuccessful` | Payment completed successfully |
| `paymentFailed` | Payment was declined or failed |
| `paymentCancelled` | User dismissed or cancelled the checkout |


## Platform-Specific Behavior

### iOS

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


### Android

- 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

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


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

## Troubleshooting

### Invalid Order ID format

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

### SDK errors on launch

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

### File upload buttons not working

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

### Device Forbidden error

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

## Security

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


## Exports

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


## Related

- [Flutter SDK v1.0.4 (Latest)](/product-guide/sdk/flutter-sdk/v1)
- [Changelog](/product-guide/sdk/flutter-sdk/changelog)
- [React Native SDK](/product-guide/sdk/react-native-sdk)
- [Unified SDK (Web)](/product-guide/sdk/unified-sdk)