Using the EPAS client library

Connecting to the terminal

After initialisation, the first step for the ECR is to connect to the terminal.

Use the ConnectNetwork method to connect.

void ConnectToTerminal()
{
    TerminalNetworkConnection tc = new TerminalNetworkConnection();
    tc.TerminalConnectionDetails = new IPEndPoint(IPAddress.Parse(txtTerminalAddress.Text),
                                                                  int.Parse(txtTerminalPort.Text));
    tc.UseKeepAlive = optKeepalive.Checked;

    ApiResult result = mEpas.ConnectNetwork(tc, optForceReconnect.Checked);
    LogApiResult(result, "Connect");
}

There is a Disconnect method that can be used to disconnect from the terminal, but it is not required. The terminal will automatically detect if the connection has been lost.

When the client library loses connection with a terminal the LinkStatus callback will be called if it has been defined.

Note: The client library does not support automatic reconnection.

The library has no way of knowing if the disconnection was intentional or not, or if is something that will be resolved quickly or not, so it has no way to know if automatic reconnection is a good idea. If the ECR wishes to handle a disconnection, therefore, it should handle the LinkStatus callback.

If the link goes down then the terminal will do two things:

  • Abort any transaction that is ongoing, and
  • Perform an automatic log out.

When the ECR wishes to reconnect, therefore, it should:

  • Call the appropriate connection method (see above).
  • Call the Login method.

Logging in

The ECR must log in to the terminal before it can run any transactions. The login includes necessary details about the terminal. See Login.

void LoginToTerminal()
{
    TerminalEnvironment te = new TerminalEnvironment()
    {
        AuthorisationServer = new IPEndPoint(IPAddress.Parse("185.27.171.42"), 55144),
        ConfigurationServer = new IPEndPoint(IPAddress.Parse("185.27.171.42"), 55133),
        ISO639_1_LanguageCode = TerminalEnvironment.LangSwedish,
        OperatorId = "cashier_1",
        TerminalId = "80000082"
    };

    if (epas.Login(te, out LoginResponse lr) == ApiResult.OK)
    {
        if (lr.LoggedIn)
        {
            ...
        }
    }
}

Note: The ECR only needs to log in once. There is no need to log in for every transaction.

The ECR can log out as well, but there is rarely any need to do so, unless the ECR needs to change some of the terminal options, like the terminal ID. See Logout.

Note: If the terminal is disconnected, it is automatically logged out.

Transactions

When the library is connected and logged in, it is ready to perform transactions with the terminal.

The EPAS client library offers several transaction methods, of which the most basic is Purchase, which can be used like this:

public void SimplePurchase(decimal amount)
{
    Log("Simple purchase of " + string.Format("{0:.00}", amount));
    TransactionResponse response;
    ApiResult result = mEpas.Purchase(amount, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Simple purchase: " + response?.ToString());
}

Each transaction is synchronous, so the method will return when the transaction is complete. This can take some time, since it involves waiting for a card to be presented, waiting for PIN entry, etc.

Some of the methods in IClientApp will be called while the transaction is in progress. Similarly some of the optional handler methods will be called, if defined. All these methods will be called from a different thread to the one that is executing the transaction so there is no risk of deadlock in the callback mechanism.

Transaction types

See the transactions page for more details on how to perform different types of transactions.

The examples page contains examples of different transactions.

Configuration

There are some configuration options in the client library. These are defined in the library’s Options property, which is an instance of the OperatingParameters class.

Notes on the API

Calling API methods

API calls into the library are always synchronous. When a purchase transaction is called, for example, the method does not return until the transaction has ended. In general, therefore, it is best for the ECR software to avoid calling API methods from the user interface thread

Return values

Most library methods return an ApiResult value. These are related to the operation of the library, the communications link, and the protocols involved. They are not directly related to transactions or other high-level operations.

Note: a return value of ApiResult.OK only indicates that the low level communications and messaging was successful. It does not, for example, indicate that a transaction was approved.