C# Library

The information within this section of the developer documents is related to implementing the POS Buddy application using the C3 Library.

The below list highlights the headings you will find within this section.

Installation
API Functions
Appendix A: Data types
Appendix B: Example implementation.

Before you get started with your implementation, there are some installation steps you need to follow in order to effectively implement the POS Buddy App using the C# library.

These steps are as follows:

Installation

Before you get started you will need to:

Install-Package PosBuddy -Source "Path on disk to nupkg file provided by Ecentric"
The Nuget install should automatically add its dependent Nuget packages, which needs to be installed from the public Nuget feed nuget.org

📘
Note_:
The above can also be installed from a private feed, provided that the package and dependent packages is present on the private Nuget feed.
The Nuget feed is configured to have a source lookup to nuget.org and it should include dependencies automatically.

Once your installation has been completed successfully, the next section to look at is API functions..

It is important to understand the API functions that are present in the POS Buddy Application so that your implementation can go as smoothly as possible. A list of the API functions can be found below:

API Functions

📘
What is an API function?
An API functions with the goal of allowing different systems, applications and devices to share information with each other. APIs work by translating a user's input into data, which helps a system send back the right response

PbResultConnect(string deviceId, Action callback)
Connects to posbuddy device using a websocket connection.
Parameters
- deviceId: The device Identifier string.
- callback: The status callback which will propagate the status of the websocket connection.

PbResult Disconnect()
Disconnects from the posbuddy device.

PbResult ClearItems()
Clear the items on the line display of the terminal.

PbResult DisplayItems(string totalCost, IEnumerable items)
Display items on the terminal: Quantity, cost, description and total Cost.
Parameters
- totalCost: Total cost to display on terminal screen in cents.
- items: List of items to display on terminal screen

PbResult DoPosAuth(string secretKey, string accessKey, Action<Dictionary<string, object>> callback)
Do a pos auth. We Authenticate the POS once which allows it to forward the authkey to the transacting terminal.
Parameters
- secretKey: The provided secret key.
- accessKey: The provided access key.
- callback: The auth callback action which will receive the authentication response payload.

👍
Remarks
On success, the authentication key will be stored inside the authenticationKey in the callback. The software needs to send this authentication key to the device using setAuthenticationKey() before a transaction can be initiated. The POS id must be set before calling this function - see the SetPosId function.

Please refer to the API reference section or click the link below to find information pertaining to:

Appendix A: Data Types
Appendix B: Example implementation

Appendix A - Data types

In the code sample below you will find all the data types along with a description that are necessary for your POS Buddy implementation

/// Status of the websocket connection
public enum PbStatus
{
    /// The status when the websocket connection is connected.
    Connected = 1,
    /// The status when the websocket connection gets disconnected.
    Disconnected = 2,
    /// The status when errors happen with the websocket connection.
    Error = 3
}

/// Provides a definition for the different types of log messages the client can forward via the log callback.
public enum PbLogType
{
    /// The log type for info messages.
    Info = 1,
    /// The log type for warning messages.
    Warning = 2,
    /// The log type message for when we transmit data.
    TransmitData = 3,
    /// The log type message for when we receive data.
    ReceiveData = 4,
    /// The log type for any errors which occur.
    Error = 5   
}

/// Return values for POS Buddy functions
public enum PbResult
{
    /// Result went everything is OK
    RESULT_OK = 0,
    /// Result for any unsupported actions or parameters
    NOT_SUPPORTED = -1000,
    /// Result for any missing required parameters
    MISSING_PARAMETERS = -1001,
    /// Result for any errors parsing the JSON
    PARSE_JSON_ERROR = -1002,
    /// Result when no response was received
    NO_RESPONSE = -1003,
    /// Result when there is a comms error
    COMMS_ERROR = -1004,
    /// Result when an invalid response is received
    INVALID_RESPONSE = -1005,
    /// Result when authentication has not been performed or authentication key is not populated
    AUTH_ERROR = -1006,
    /// Result When calling do sale but an existing sale is still in progress
    SALE_IN_PROGRESS = -1007,
    /// Result when there is a comms issue on the server
    SERVER_COMMS_ERROR = -1008,
    /// Result when comms has not been initialised
    COMMS_NOT_INITIALISED = -2000,
    /// Result when there is an error opening the websocket
    ERROR_OPENING_WEBSOCKET = -2002
}

/// Status of the POS Buddy device
public enum PbDeviceStatus
{
    /// The device is available for use
    Available = 1,
    /// The device is currently connected to a POS and needs to be disconnected before it becomes available
    Connected = 2,
}

Appendix B: Example Implementation

using Ecentric.PosBuddyClient;
using Ecentric.PosBuddyClient.Enums;
using Ecentric.PosBuddyClient.DTOs;

namespace PosBuddyExampleClient
{
    internal class Program
    {
        static PosBuddy PosBuddyClient;
        static bool IsPosBuddyConnected = false;
        static bool IsPosBuddyAuthenticated = false;

        static void Main()
        {
            PosBuddyClient = new PosBuddy((logType, message) =>
            {
                Console.WriteLine($"LogCallback {logType}, Message: {message}");
            });

            PosBuddyClient.SetMerchantId("000000123456");
            PosBuddyClient.SetPosId("0001");

            // Connect to PosBuddy device before interacting with it
            PosBuddyClient.Connect("111222", (status) =>
            {
                // Callback to process Connect result

                switch (status)
                {
                    case PbStatus.Connected:
                        Console.WriteLine($"Status Callback: Connection success.");
                        IsPosBuddyConnected = true;
                        break;
                    case PbStatus.Disconnected:
                        Console.WriteLine($"Status Callback: Connection Disconnected.");
                        IsPosBuddyConnected = false;
                        break;
                    case PbStatus.Error:
                        Console.WriteLine($"Status Callback: Connection Error.");
                        IsPosBuddyConnected = false;
                        break;
                }
            });

            if (IsPosBuddyConnected)
            {
                string? authResult = null;

                // Use provided secret and access keys for DoPosAuth
                PosBuddyClient.DoPosAuth("secretKey", "accessKey", (result) =>
                {
                    // Callback to process DoPosAuth result

                    // Set received authKey before transacting
                    authResult = result["resultDescription"] as string;
                    if (authResult == "COMPLETED" || authResult == "SUCCESS")
                    {
                        var authKey = result["authenticationKey"] as string;
                        PosBuddyClient.SetAuthenticationKey(authKey!);
                        IsPosBuddyAuthenticated = true;
                    }
                });

                // Wait for DoPosAuth to complete before proceeding
                while (authResult == null) ;                

                // PosBuddy device needs to be authenticated before DoSale call
                if (IsPosBuddyAuthenticated)
                {
                    // Do a sale for R10.00
                    PosBuddyClient.DoSale(1000, new Dictionary<string, string>(), (result) =>
                    {
                        Console.WriteLine($"DoSale callback called. Result: {result}");
                    });
                }
            }
        }
    }    
}

C# Library

Installation

📘
Note_:

API Functions

📘
What is an API function?

👍
Remarks

Appendix A - Data types

Appendix B: Example Implementation

Installation

📘Note_:

API Functions

📘What is an API function?

👍Remarks

Appendix A - Data types

Appendix B: Example Implementation

📘
Note_:

📘
What is an API function?

👍
Remarks