Aba.PayWay.Sdk.Pos 1.0.3

ABA POS SDK for .NET

ABA POS SDK for .NET developed by ABA Bank (Advanced Bank of Asia Ltd.). This package allows you to connect with the ABA POS terminal from these supported platforms: Windows (x64), macOS (x64), and Linux (x64).

Driver Installation

The driver might already come with Windows Update if you use Windows 10 or 11. To verify if you have the driver installed, you need to:

• Connect ABA POS to your POS system via a USB cable.

• On Windows, open Device Manager > Ports (COM & LPT). Check the listed devices:

  • Prolific USB-to-Serial Comm Port
  • Prolific PL2303GT USB Serial COM Port
  • Prolific PL2303GC USB Serial COM Port
  • Or something similar. If you cannot find the USB device after you plug in the ABA POS USB cable, you can get the latest official USB driver from the Prolific website here. https://www.prolific.com.tw/US/ShowProduct.aspx?p_id=223&pcid=126

• On macOS, you need to install the official driver from AppStore here: https://apps.apple.com/us/app/pl2303-serial/id1624835354

• On Linux, please contact our ABA Terminal Integration Team via any channel (Telegram, Email, etc)

Install the SDK

Using .NET CLI

• You can find the latest version from NuGet Package Manager here: NuGet Website
• Add the package with this command: dotnet add package Aba.PayWay.Sdk.Pos --version x.x.x

Using Visual Studio

• Go to Tools > NuGet Package Manager > Manages NuGet Package for Solution...
• Search for: Aba.PayWay.Sdk.Pos and install the package

Define a method to handle an error

private void OnSdkError(Exception ex)
{
    if (ex is AbaPosSdkException sdkError)
    {
        // You can handle the specific error code and message.
        int errorCode = sdkError.ErrorCode;
        string errorMessage = sdkError.Message;

        // Or just get the formatted error message.
        string formattedMessage = sdkError.ToString();
        Console.WriteLine(formattedMessage);
    }
    else
    {
        Console.WriteLine($"Something went wrong: {ex.Message}");
    }
}

Using USB Serial Port:

You need to connect ABA POS terminal to your POS system (PC, ECR, Kiosk, etc) and follow the sample code below.

Note: 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.

// Make sure you use the correct namespace.
using Aba.PayWay.Sdk.Pos;


try
{
    // A new key will be provided by ABA Bank to use with the production POS terminal.
    string key = "001116A775D266AE67DF1F6CA9C7F071";
    AbaPosSdk.InitUsbConnection(key);
    
    string invoiceId = $"MY_INVOICE_ID_{DateTime.Now:yyyyMMddHHmmss}";
    string timestamp = AbaPosSdk.GenerateTimestamp();
    string data = $"{{\"CMD\":\"SALE\",\"TYPE\":\"ALL\",\"QRTYPE\":\"ALL\",\"AMT\":\"0.01\",\"CURRCODE\":\"USD\",\"TIMESTAMP\":\"{timestamp}\",\"ECRREF\":\"{invoiceId}\"}}";

    // The timeout in milliseconds. You can increase the timeout if it's too fast.
    int timeoutMs = 60000;

    Console.WriteLine($"Sending data to ABA POS: {data}");
    string response = AbaPosSdk.SendDataByUsb(data, timeoutMs);

    // Or use AbaPosSdk.SendDataByUsbAsync(data, timeoutMs, (response) => {}, (error) => {});
    
    if (!string.IsNullOrEmpty(response))
    {
        Console.WriteLine($"Response received: {response}");
    }
    else
    {
        // Response can be empty when the SDK got timeout, or you have called AbaPosSdk.cancelWaitingPosTerminal()
        Console.WriteLine($"No response from ABA POS.");
    }
}
catch (Exception e)
{
    OnSdkError(e);
}

Using Wi-Fi (IP Address):

To use Wi-Fi (IP Address) connectivity, your POS system (PC, ECR, Kiosk, etc) and the ABA POS terminal must be connected to the same Wi-Fi router/hotspot.

• On macOS, during the development, you also need to sign your app. Otherwise, your app will be blocked by the Firewall, and it cannot send or receive the response.
  sudo codesign --force --deep --sign - MyApp

// Make sure you use the correct namespace.
using Aba.PayWay.Sdk.Pos;


try
{
    // A new key will be provided by ABA Bank to use with the production POS terminal.
    string key = "001116A775D266AE67DF1F6CA9C7F071";

    // You can see the IP address on ABA POS App.    
    string ipAddress = "192.168.0.1";
    AbaPosSdk.InitIpConnection(ipAddress, key);
    
    string invoiceId = $"MY_INVOICE_ID_{DateTime.Now:yyyyMMddHHmmss}";
    string timestamp = AbaPosSdk.GenerateTimestamp();
    string data = $"{{\"CMD\":\"SALE\",\"TYPE\":\"ALL\",\"QRTYPE\":\"ALL\",\"AMT\":\"0.01\",\"CURRCODE\":\"USD\",\"TIMESTAMP\":\"{timestamp}\",\"ECRREF\":\"{invoiceId}\"}}";

    // The timeout in milliseconds. You can increase the timeout if it's too fast.
    int timeoutMs = 60000;

    Console.WriteLine($"Sending data to ABA POS: {data}");
    string response = AbaPosSdk.SendDataByIp(data, timeoutMs);

    // Or use AbaPosSdk.SendDataByIpAsync(data, timeoutMs, (response) => {}, (error) => {});

    if (!string.IsNullOrEmpty(response))
    {
        Console.WriteLine($"Response received: {response}");
    }
    else
    {
        // Response can be empty when the SDK got timeout, or you have called AbaPosSdk.cancelWaitingPosTerminal()
        Console.WriteLine($"No response from ABA POS.");
    }
}
catch (Exception e)
{
    OnSdkError(e);
}

Cancel Waiting for ABA POS Terminal:

Normally, after the request is sent to the ABA POS terminal, the SDK will wait for a response until it times out. You can also stop this waiting and perform another transaction if you want.

• Note: this command only works for CMD: "SALE", "PRE-AUTH", and "PRE-AUTH COMP"

The example below works for any connectivity:

try
{
    Console.WriteLine("Cancel waiting POS terminal...");
    // This will stop the SDK from waiting.
    AbaPosSdk.CancelWaitingPosTerminal();

    string data = $"{{\"CMD\":\"CANCEL\",\"TIMESTAMP\":\"{AbaPosSdk.GenerateTimestamp()}\"}}";
    // If you are using USB serial port, please use this method.
    AbaPosSdk.SendDataByUsb(data, 10000);

    // Or if you are using Wi-Fi (IP Address), please use this method.
    AbaPosSdk.sendDataByIp(data, 10000);
}
catch (Exception ex)
{
    OnSdkError(ex);
}

Getting the Logs From the SDK:

You can also get the log from the SDK by following the sample code below:

// Make sure you call the init method first:
AbaPosSdk.InitUsbConnection(...) or AbaPosSdk.InitIpConnection(...)

// Set the directory where you want the SDK to keep all the log files.
// Here, it'll generate a directory 'ABA_Logs' inside the current directory.
AbaPosSdk.SetLogDirectoryPath("ABA_Logs");

Releasing resources used by the SDK:

It's recommended to release the resources used by the SDK after you stop using it.

• If you are using a USB serial port:
  AbaPosSdk.releaseUsbConnection();

• Or if you are using Wi-Fi (IP Address):
  AbaPosSdk.releaseIpConnection();

// Here is an example for an application using WinForm:
private void Form1_Closing(object sender, System.ComponentModel.CancelEventArgs e)
{
   // Release all the resources used by the SDK. 
   AbaPosSdk.releaseUsbConnection();
   AbaPosSdk.releaseIpConnection();
}

Exception Handling:

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

try 
{
  // Calling any method from AbaPosSdk
}
catch (Exception ex)
{
  if (ex is AbaPosSdkException sdkError)
  {
      // You can handle the specific error code and message.
      int errorCode = sdkError.ErrorCode;
      string errorMessage = sdkError.Message;

      // Or just get the formatted error message.
      string formattedMessage = sdkError.ToString();
      Console.WriteLine(formattedMessage);
  }
  else
  {
      Console.WriteLine($"Something went wrong: {ex.Message}");
  }
}

Other Available Functionalities

To learn about other functionalities offered by ABA POS and more details about the request and response, please see the document ABA POS Integration Specification.pdf provided by the ABA Team. Please do not hesitate to contact us if you have any questions.