mobibox_pay

Flutter SDK for Mobibox Payment Orchestrator

mobibox_pay is a Flutter plugin that lets you integrate Mobibox Payment Orchestrator into any Flutter app. Through a single unified interface you get access to hundreds of payment connectors — making payment integration faster and more reliable.

---

Features

• One-line payment flow via MobiPay.startPayment()
• Hosted Payment Fields (HPF) — PCI-compliant card collection via WebView
• Automatic 3D Secure (3DS) handling with redirect + status polling
• Recurring payments, card tokenization, and returning-customer tokens
• Dark-themed BottomSheet UI
• Callback-driven architecture — onTransactionComplete, onTransactionFailed, etc.
• Supports both Android and iOS

---

Requirements

Requirement	Minimum
Dart SDK	^3.9.2
Flutter	>=3.3.0

---

Installation

Add this to your pubspec.yaml:

dependencies:
  mobibox_pay: ^1.1.1

Then run:

flutter pub get

---

Quick Start

1. Initialize

import 'package:mobibox_pay/mobi_pay.dart';

class _MyAppState extends State<MyApp> {
  final MobiPay _mobiPay = MobiPay();

  @override
  void initState() {
    super.initState();
    _mobiPay.initialize(
      checkoutHost: 'https://pay.example.com',
      merchantKey: 'your-merchant-key',
      password: 'your-merchant-password',
    );
  }
}

2. Start a Payment

_mobiPay.startPayment(
  context: context,
  orderNumber: 'order-${DateTime.now().millisecondsSinceEpoch}',
  orderAmount: '10.00',
  orderCurrency: 'USD',
  orderDescription: 'Premium subscription',
  cardholderName: 'JOHN DOE',       // optional — pre-fills the name field
  email: 'john@example.com',        // optional
  onTransactionComplete: (result) {
    debugPrint('Success! Payment ID: ${result.paymentId}');
  },
  onTransactionFailed: (result) {
    debugPrint('Failed: ${result.declineMessage}');
  },
  onError: (e) {
    debugPrint('Error: ${e.toString()}');
  },
  onPaywallClosed: () {
    debugPrint('User closed the payment sheet');
  },
);

That's it. The SDK handles session-token creation, card collection, 3DS redirects, status polling, and success/error screens automatically.

---

API Reference

MobiPay

Method	Description
initialize(checkoutHost, merchantKey, password)	Configure credentials. Must be called once before any payment.
startPayment(context, ..., callbacks)	Opens a BottomSheet and runs the full payment flow.
getSessionToken(...)	Returns a session token (advanced — for custom UI).
createHPFWidget(...)	Creates an HPF widget (advanced — for custom UI).

startPayment Parameters

Parameter	Type	Required	Description
context	BuildContext	Yes	Build context for showing the bottom sheet.
orderNumber	String	Yes	Unique order identifier.
orderAmount	String	Yes	Amount (e.g. '10.00').
orderCurrency	String	Yes	ISO 4217 code (e.g. 'USD').
orderDescription	String	Yes	Human-readable description.
cardholderName	String?	No	Pre-fill cardholder name field.
email	String?	No	Customer email.
billingAddress	Map<String, dynamic>?	No	Billing address fields.
browserInfo	Map<String, dynamic>?	No	Browser information.
birthDay	String?	No	YYYY-MM-DD format.
selectedLanguage	String?	No	Language code.
recurringInit	bool?	No	Initialize a recurring payment.
scheduleId	String?	No	Schedule ID for recurring.
reqToken	bool?	No	Request a card token.
cardToken	List<String>?	No	Tokens for returning customers.

Callbacks

Callback	Type	Description
onSubmitResult	void Function(Map<String, dynamic>)	Card form submitted (HPF data collected).
onTransactionInitiated	void Function(MobiPayTransactionResult)	Transaction initiated — fires for ALL results.
onTransactionComplete	void Function(MobiPayTransactionResult)	Transaction successful (settled).
onTransactionFailed	void Function(MobiPayTransactionResult)	Transaction failed (decline, void, etc.).
onSuccessRedirect	void Function(String)	Redirect to success URL.
onErrorRedirect	void Function(String)	Redirect to error URL.
onError	void Function(Exception)	Any exception during the flow.
onPaywallClosed	void Function()	The payment BottomSheet was dismissed.

MobiPayTransactionResult

Property	Type	Description
status	String	Transaction status.
publicId	String?	Unique payment identifier.
paymentId	String?	Payment ID for status checks.
transactionId	String?	Transaction ID.
orderId	String?	Order ID.
hash	String?	Verification hash.
declineMessage	String?	Decline / error message.
redirectUrl	String?	Redirect URL (if applicable).
redirectParams	Map<String, dynamic>?	Redirect params (POST redirect).
rawData	Map<String, dynamic>?	Complete raw API response.
isSuccess	bool	true if success or redirect.
isDeclined	bool	true if declined.
requiresAction	bool	true if redirect/waiting.

---

Payment Flow

┌──────────────────────────────────────────────────┐
│  1. mobiPay.startPayment(...)                    │
│     ↓                                            │
│  2. SDK fetches session token                    │
│     POST /api/v1/session/token                   │
│     ↓                                            │
│  3. BottomSheet opens with card form (HPF)       │
│     ↓                                            │
│  4. User fills card details → taps Pay           │
│     ↓                                            │
│  5. SDK processes payment                        │
│     POST /api/v1/processing/purchase/card        │
│     ↓                                            │
│  6a. success → onTransactionComplete → thank you │
│  6b. decline → onTransactionFailed → error       │
│  6c. redirect → 3DS WebView → status polling     │
│       POST /api/v1/payment/status (every 5s)     │
│       → settled  → onTransactionComplete         │
│       → decline  → onTransactionFailed           │
│  6d. waiting → status polling (same as above)    │
└──────────────────────────────────────────────────┘

---

Transaction Statuses

From Purchase API

Status	Description
success	Transaction completed successfully.
decline	Transaction declined.
redirect	3DS or other redirect required.
waiting	Transaction is being processed.
undefined	Uncertain status.

From GET_TRANS_STATUS

Status	Description
prepare	Payment being prepared.
settled	Payment completed.
pending	Payment pending.
3ds	3DS authentication in progress.
redirect	Redirect required.
decline	Payment declined.
refund	Payment refunded.
reversal	Payment reversed.
void	Payment voided.
chargeback	Chargeback received.

---

Recurring Payments

_mobiPay.startPayment(
  context: context,
  orderNumber: 'sub-001',
  orderAmount: '9.99',
  orderCurrency: 'USD',
  orderDescription: 'Monthly subscription',
  recurringInit: true,
  scheduleId: 'sched-abc-123',
  reqToken: true,
  onTransactionComplete: (result) {
    // Store result.paymentId for future recurring charges
  },
);

For returning customers with saved tokens:

_mobiPay.startPayment(
  // ...
  cardToken: ['saved_token_abc', 'saved_token_def'],
  // ...
);

---

Advanced: Custom UI with Session Tokens

If you want full control over the UI, use getSessionToken() and createHPFWidget() directly:

// 1. Get a session token
final token = await _mobiPay.getSessionToken(
  orderNumber: 'order-123',
  orderAmount: '25.00',
  orderCurrency: 'USD',
  orderDescription: 'Custom checkout',
);

// 2. Create an HPF widget with the token
final hpfWidget = _mobiPay.createHPFWidget(
  sessionToken: token,
  cardholderName: 'JOHN DOE',
  onTransactionComplete: (result) {
    debugPrint('Success: ${result.paymentId}');
  },
  onTransactionFailed: (result) {
    debugPrint('Failed: ${result.declineMessage}');
  },
  onError: (e) {
    debugPrint('Error: $e');
  },
);

// 3. Place it in your widget tree
Scaffold(
  body: SizedBox(
    height: 400,
    child: hpfWidget,
  ),
);

---

Full Example

import 'package:mobibox_pay/mobi_pay.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: MyApp()));
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final MobiPay _mobiPay = MobiPay();

  @override
  void initState() {
    super.initState();
    _mobiPay.initialize(
      checkoutHost: 'https://pay.example.com',
      merchantKey: 'your-merchant-key',
      password: 'your-merchant-password',
    );
  }

  void _startPayment() {
    _mobiPay.startPayment(
      context: context,
      orderNumber: 'order-${DateTime.now().millisecondsSinceEpoch}',
      orderAmount: '1.00',
      orderCurrency: 'USD',
      orderDescription: 'Test Purchase',
      cardholderName: 'JOHN DOE',
      email: 'test@example.com',
      onSubmitResult: (data) {
        debugPrint('Payment submitted: $data');
      },
      onTransactionInitiated: (result) {
        debugPrint('Transaction initiated: ${result.status}');
        debugPrint('  Payment ID: ${result.paymentId}');
      },
      onTransactionComplete: (result) {
        debugPrint('Transaction completed: ${result.status}');
        debugPrint('  Payment ID: ${result.paymentId}');
        debugPrint('  Is Success: ${result.isSuccess}');
      },
      onTransactionFailed: (result) {
        debugPrint('Transaction failed: ${result.status}');
        debugPrint('  Decline Message: ${result.declineMessage}');
      },
      onSuccessRedirect: (url) {
        debugPrint('Success redirect: $url');
      },
      onErrorRedirect: (url) {
        debugPrint('Error redirect: $url');
      },
      onError: (e) {
        debugPrint('Exception: ${e.toString()}');
      },
      onPaywallClosed: () {
        debugPrint('Paywall closed by user');
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Mobibox Pay SDK')),
      body: Center(
        child: ElevatedButton(
          onPressed: _startPayment,
          child: const Text('Start Payment'),
        ),
      ),
    );
  }
}

---

Project Structure

mobi_pay/
├── lib/
│   ├── mobi_pay.dart                    # Main entry point
│   ├── mobi_pay_checkout_widget.dart    # Checkout BottomSheet flow
│   ├── mobi_pay_hpf_widget.dart         # WebView + HPF + 3DS
│   ├── mobi_pay_payment_processor.dart  # Purchase + status APIs
│   ├── mobi_pay_session_token.dart      # Session token API
│   ├── mobi_pay_hash.dart               # SHA1(MD5(...)) signing
│   ├── mobi_pay_transaction_result.dart # Result model
│   ├── mobi_pay_platform_interface.dart # Platform interface
│   └── mobi_pay_method_channel.dart     # Method channel
├── example/                             # Example app
│   └── lib/main.dart
├── pubspec.yaml
└── README.md                            # This file

---

Dependencies

Package	Version	Purpose
webview_flutter	^4.4.2	Hosted Payment Fields WebView
http	^1.1.0	HTTP networking
crypto	^3.0.3	MD5/SHA1 hash generation
plugin_platform_interface	^2.0.2	Flutter plugin platform

---

License

Proprietary — Mobibox Technologies. All rights reserved.