easymerchant_reader_sdk #

Flutter plugin for EasyMerchant MagTek Mobile Reader payments.

Use MagTek BLE card readers (e.g. DynaFlex II Go) from a Flutter app: create a client_token on your backend, start a reader transaction, and complete the charge with encrypted ARQC data. Native SDK screens handle reader connect, tap-to-pay, cancel confirmation, and success / failure UI (light or dark theme).

Install #

dependencies:
  easymerchant_reader_sdk: ^0.1.2

flutter pub get

Payment flow (recommended) #

Merchant app / backend
  └─ POST /paymentintent  (X-Api-Key + X-Api-Secret)
       └─ client_token
            └─ Magteksdk.startTransaction(amount, clientToken: …)
                 └─ Native UI: connect → tap → charge (client-token header)

Never put API key / secret inside the SDK or the mobile app for production. Generate client_token on your server and pass it into Flutter.

Pass environment as one of: sandbox, staging, or production (values provided by EasyMerchant for your account).

Quick start (Android) #

import 'package:easymerchant_reader_sdk/magteksdk.dart';

final sdk = Magteksdk();

// clientToken comes from your backend: POST /paymentintent
final result = await sdk.startTransaction(
  '100.00',
  environment: 'sandbox', // sandbox | staging | production
  clientToken: clientToken,
  theme: MagtekSdkTheme.dark, // or MagtekSdkTheme.light
  // idempotencyKey: 'order-123', // optional; UUID generated if omitted
);

print(result);

Themes #

MagtekSdkTheme.light  // light native screens
MagtekSdkTheme.dark   // dark native screens

Native screens include: preparing terminal, tap to pay, cancel dialog, payment successful, payment failed.

Android host setup #

1. MagTek mtusdk.aar #

Place MagTek’s mtusdk.aar in your app’s android/ folder (next to settings.gradle), or under android/libs/.

In android/app/build.gradle:

dependencies {
    implementation files('../mtusdk.aar')
    // or: implementation files('libs/mtusdk.aar')
}

configurations {
    all {
        exclude group: 'net.sf.kxml', module: 'kxml2'
    }
}

Native reader UI and payment code ship inside this Flutter plugin (android/vendor/…). You do not need GitHub Packages, Maven credentials, or a separate em-MobileReaderSDK-Android dependency.

2. Permissions #

BLE / location permissions are declared by the plugin and requested at runtime. Ensure your app targets a supported minSdk (plugin uses 21+).

3. Optional: MainActivity wiring #

If the plugin does not auto-register on your Flutter embedding, wire MagteksdkPlugin in MainActivity as shown in the example app.

iOS host setup #

1. Set platform in ios/Podfile:

platform :ios, '15.0'

2. Add Bluetooth usage to Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app requires Bluetooth to connect to payment readers.</string>

3. Run:

cd ios && pod install

4. Call payment (iOS API):

await Magteksdk().makePayment(
  100.00,
  environment: 'sandbox',
  // Prefer client-token flow on Android; iOS keying may differ by version.
);

MagTek MTUSDK / MTSCRA frameworks ship with the plugin for iOS.

API overview #

Magteksdk #

Charge headers (Android) #

The native layer sends:

• client-token — from clientToken
• Idempotency-Key — your key, or a generated UUID per payment
• Body includes arqc, amount, description, payment_mode, etc.

Example app #

cd example
cp env.json.example env.json   # fill EM_API_KEY / EM_API_SECRET (sandbox)
flutter run --dart-define-from-file=env.json

QA APK:

./scripts/build-qa-apk.sh

Support #

• Issues: GitHub Issues
• Related checkout plugin: easymerchantsdk

License #

Proprietary — EasyMerchant. See LICENSE. Distribution and use require EasyMerchant authorization. MagTek SDKs remain subject to MagTek’s license terms.