aba_pos_sdk_flutter 0.0.7

Enable Flutter app to connect to ABA POS terminal.

ABA POS SDK - Flutter

Enable your Flutter app to connect to ABA POS terminal.

Getting Started

• Setup the SDK by adding the latest dependency into your project:

dependencies:
  flutter:
    sdk: flutter
    
  aba_pos_sdk_flutter: ^0.0.x

Using USB Serial Port:

• For Android (USB OTG):

To use USB connectivity with the POS terminal, the ECR or billing system must support USB OTG (USB On the Go). Most Android systems now support this feature. It's not recommended to replace the USB cable that comes with the POS terminal. Please report any issues with the cable to ABA Bank.

import 'package:aba_pos_sdk_flutter/callbacks.dart';
import 'package:aba_pos_sdk_flutter/pos_usb_otg_connector.dart';

class _AppState extends State<App> implements PosUsbConnectionCallback {
    
  PosUsbOTGConnector? _usbOTGConnector;

  @override
  void initState() {
    super.initState();
    // A new key will be provided by ABA Bank to use with the production POS terminal. 
    final key = '001116A775D266AE67DF1F6CA9C7F071';
    _usbOTGConnector = _usbOTGConnector ?? PosUsbOTGConnector(key);
    _usbOTGConnector?.initialize(this);
  }
  
  @override
  void dispose() {
    _usbOTGConnector?.release();
    _usbOTGConnector = null;
    super.dispose();
  }
  
  @override
  void onWaitingResponseFromPosTerminal() {
    // Data was sent to the POS terminal, and it's waiting for a response back.
  }
  
  @override
  void onReceivedResponseFromPosTerminal(String data) {
    // The POS terminal sent the response back.
  }
  
  @override
  void onOperationError(Exception error) {
    // This can be a connection error. You can also get the message and error code from 
    // this class PosConnectorException.
  }
  
  @override
  void onOperationTimeOut() {
    // The POS terminal doesn't respond back on time.
  }

  @override
  void onUsbAttachedOrDetached(UsbDev? usbDevice, bool isAttached) {
    // Notify when a USB cable is plugged in or unplugged.
  }

Using Wi-Fi (IP Address):

To use Wi-Fi (IP Address) connectivity, the ECR or billing system and the POS terminal must be connected to the same Wi-Fi router/hotspot.

• For macOS, you must add these lines into your_flutter_project/macos/Runner/Release.entitlements and DebugProfile.entitlements:

<dict>
  <key>com.apple.security.network.client</key>
  <true>
  <key>com.apple.security.network.server</key>
  <true>
</dict>

import 'package:aba_pos_sdk_flutter/callbacks.dart';
import 'package:aba_pos_sdk_flutter/pos_ip_address_connector.dart';

class _AppState extends State<App> implements PosIpAddressConnectionCallback {
    
  PosIpAddressConnector? _ipAddressConnector;

  @override
  void initState() {
    super.initState();
    // A new key will be provided by ABA Bank to use with the production POS terminal. 
    final key = '001116A775D266AE67DF1F6CA9C7F071';
    _ipAddressConnector = _ipAddressConnector ?? PosIpAddressConnector(key);
    
    final ip = '192.168.0.102'; // POS terminal IP address.
    _ipAddressConnector?.initialize(ip, this);
    // To update IP address, you can also use _ipAddressConnector?.updateIpAddress(newIpAddress)
  }
  
  @override
  void dispose() {
    _ipAddressConnector?.release();
    _ipAddressConnector = null;
    super.dispose();
  }
  
  @override
  void onWaitingResponseFromPosTerminal() {
    // Data was sent to the POS terminal, and it's waiting for a response back.
  }
  
  @override
  void onReceivedResponseFromPosTerminal(String data) {
    // The POS terminal sent the response back.
  }
  
  @override
  void onOperationError(Exception error) {
    // This can be a connection error. You can also get the message and error code from 
    // this class PosConnectorException.
  }
  
  @override
  void onOperationTimeOut() {
    // The POS terminal doesn't respond back on time.
  }

Send a transaction to the POS terminal:

The example below works the same for any connectivity.

  final saleRequest = '{"CMD":"SALE","TYPE":"EDC","QRTYPE":"ALL","AMT":"0.01","CURRCODE":"USD","TIMESTAMP":"2021-05-06 16:00:35","ECRREF":"INV000001"}';
  
  final timeout = 60000 // 60 seconds. You can also extend this timeout if it's too fast.
  _usbOTGConnector?.sendTransaction(saleRequest, timeout);

Cancel transaction (For SALE, PRE-AUTH, and PRE-AUTH COMP):

Normally, after the request is sent to the POS terminal, the SDK will wait for a response until it's timeout. You can also stop this waiting, and perform another transaction if you want. The example below works for any connectivity:

  // This will stop the SDK from waiting.
  _usbOTGConnector?.cancelWaitingPosTerminal();
  
  final cancelRequest = '{"CMD":"CANCEL","TIMESTAMP":"2021-05-06 16:00:35"}';
  final timeout = 60000 // 60 seconds. You can also extend this timeout if it's too fast.
  _usbOTGConnector?.sendTransaction(cancelRequest, timeout);

Releasing resources used by the SDK:

It's recommended to release the resources used by the SDK after you stop using it in dispose() method.

  @override
  void dispose() {
    _usbOTGConnector?.release();
    _usbOTGConnector = null;
    super.dispose();
  }

Getting logs from SDK:

You can also get the log from the SDK during your first initialization.

import 'package:aba_pos_sdk_flutter/pos_sdk_logger.dart';

class _AppState extends State<App> implements PosSdkLogger {

  // Implements PosSdkLogger and override another 2 methods.
  _usbOTGConnector = PosUsbOTGConnector(key, logger: this);
   
   
  @override
  void log(String message) {
    // Log me.
  }
  
  @override
  void logError(Exception exception) {
    final error = exception as PosConnectorException;
    // Log me.
  }

Exception Handling:

If you want to handle the error in specific cases, you can also check these error codes from the exception class 'PosConnectorException' below:

PosConnectorException's Error constant	Error Code	Description
openSerialPortError	1	The USB serial port can't be opened.
readSerialPortError	2	Unable to read data from the USB serial port.
writeSerialPortError	3	Unable to write data to the USB serial port.
openSocketError	4	SDK can't open a server socket to wait for a response from the POS terminal.
writeSocketError	5	SDK can't write data to the POS terminal via socket due to the connection was closed.
readSocketError	6	SDK can't read data from the POS terminal via socket due to the connection was closed.
invalidIpAddress	7	Invalid POS terminal's IP address.
invalidHash	8	The SDK and the POS terminal are using the wrong key, or the response is losing some data.
noDeviceFound	9	The POS terminal is not connected yet.
usbOtgNotSupported	10	The ECR or the billing system doesn't support USB OTG or the USB OTG isn't enabled.
unsupportedPlatform	11	The SDK doesn't support your target platform.
unknownError	1000	Unknown error.