Prerequisites

Install the required environment before using the SDK.

• Flutter 3.0+
• Dart 2.17+
• Android Studio (for Android builds)
• Xcode (for iOS builds)
• Native ECR SDKs (Android .aar, iOS .framework) are bundled inside the Flutter wrapper — no DLLs required.
• Cashier setup (CRN, printer configuration) must be completed at first launch.
• For App‑to‑App, ensure mada app is installed and configured on the Android device.

For integration steps, refer to Flutter Integration.

Library Import

Add the Flutter wrapper (ecrlib) and import the SDK classes.

dev_dependencies:
  ecrlib:
    path: 'ecrlib'

import 'package:ecrlib/ecrlib.dart';

Core Components

Use the SDK’s provided classes to build and parse transaction data.

• TcpConnect – Establish TCP/IP connection with the terminal.
• BluetoothService – Connect via Bluetooth (Android only).
• AppToAppConnect – Connect via App‑to‑App (Android only, requires mada app).
• ConfigManager – Save and retrieve configuration data.
• EncryptionUtil – Generate signatures, reference numbers, and format request data.
• doTransaction() – Execute transaction with packed request data.
• split() – Parse CSV response fields from terminal output.

Permissions (Manifest Example)

Add the following entries to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
<uses-permission android:name="android.permission.BROADCAST_STICKY"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Integration Example

Dart

// Prepare transaction request
final String uniqueNumber = EncryptionUtil.getSixDigitUniqueNumber();
final String signature = EncryptionUtil.getSha256Hash(uniqueNumber, config!.terminalId!);
final String ecrRef = "${config!.cashRegisterNumber}${EncryptionUtil.getSixDigitUniqueNumber()}";

final String reqData = "${EncryptionUtil.getFormattedDateTime()};${payAmount.text};${_draft.printChoice}!;$ecrRef!;";
final String hexReqData = EncryptionUtil.stringToHex(reqData);

// Send transaction via App-to-App
await _webSocketService.doTransaction(
  reqData: hexReqData,
  txnType: _draft.transactionType,
  signature: signature,
  listener: this,
);

Response Parsing Example

Responses are returned in CSV format. Example:

String response = "00,APPROVED,10000,140524193012,TX12345678,RECEIPT123";
List<String> fields = response.split(",");

String responseCode = fields[0];   // 00 = Approved
String approvalCode = fields[1];   // APPROVED
String amount = fields[2];         // 10000 (minor units)
String timestamp = fields[3];      // ddMMyyHHmmss
String ecrRefNo = fields[4];       // Merchant reference
String receiptData = fields[5];    // Receipt payload

Error Handling

• mada app not installed → Transaction fails silently; prompt user to install mada app.
• Timeouts → Retry or fall back to TCP/IP.
• Invalid CRN → Must be 8‑digit numeric; reject otherwise.
• Missing fields → Validate before processing; abort if null.

Security & Signatures

• Always generate a SHA‑256 signature using CRN and terminal ID before sending requests.
• Validate CRN and transaction reference numbers to prevent replay or tampering.
• Ensure printer configuration is explicitly set (0 or 1).

Configuration Persistence

• Connection parameters (IP, port, CRN) are defined at runtime in the client code.
• No external JSON configuration file is required.
• Configuration is managed through ConfigManager.setConfiguration() and ConfigManager.getConfiguration().

Runtime Behaviors

• The SDK manages communication through TCP/IP, Bluetooth, or App‑to‑App sessions.
• Establish session with the terminal (connectTCP, connectDevice, or connect).
• Send packed request data using doTransaction().
• Receive terminal response as CSV string.
• Parse response fields with split().
• Disconnect after transaction completion.

Transaction Flow

Initialize SDK → Configure POS → Connect Device → Register (txnType 17) → Start Session (txnType 18) → Execute Transaction → Receive Response → Parse Response