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

Platform	Status
Android	Supported (startTransaction + client token)
iOS	Supported (makePayment; client-token parity in progress)

---

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

Method	Platform	Description
startTransaction(amount, { environment, clientToken, idempotencyKey, theme })	Android	Opens native reader UI and charges with client-token
makePayment(amount, { environment, apiKey, secretKey })	iOS	Starts native MagTek payment UI
getPlatformVersion()	Both	Debug helper

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.