Class EpasClient

The EpasClient class provides the functionality required to operate a Westpay terminal.

Inheritance

System.Object

EpasClient

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Westpay.Epas

Assembly: EpasClientLibrary.dll

Syntax

public class EpasClient

Constructors

View Source

EpasClient(IClientApp)

Constructor

Declaration

public EpasClient(IClientApp app)

Parameters

Type	Name	Description
IClientApp	app	The client application

Fields

View Source

BusyStatus

Handler for busy status notifications

Declaration

public EpasClient.StatusNotification BusyStatus

Field Value

Type	Description
EpasClient.StatusNotification

Remarks

There are times when the terminal is going to be busy for an unknown time, normally when it is downloading new parameters. In these situations the terminal will notify its busy status by calling this callback with busy set to true. When the activity ends it will call this callback again with busy set to false.

Examples

...
mEpas.BusyStatus = HandleBusyState;
...

public void HandleBusyState(bool busy)
{
    if (InvokeRequired)
    {
        Invoke(new Action(() => HandleBusyState(busy)));
    }
    else
    {
        if (busy)
        {
            lblBusy.BackColor = Color.LightPink;
            lblBusy.ForeColor = Color.DarkRed;
            lblBusy.Text = "BUSY";
        }
        else
        {
            lblBusy.BackColor = Color.Transparent;
            lblBusy.ForeColor = Color.Gray;
            lblBusy.Text = "OK";
        }
    }
}

View Source

CardAccepted

The handler for card accepted notifications with MaskedCardNumber and CNA

Declaration

public EpasClient.CardAcceptedNotification CardAccepted

Field Value

Type	Description
EpasClient.CardAcceptedNotification

Remarks

The terminal�s configuration includes a list of card ranges that is used to identify valid card numbers. When a payment card is presented and is considered valid then this callback is used to notify the ECR of the masked card number and Card Number Alias (CNA). The masking means that only the first six digits and last four digits of the card number are shown. The rest are replaced with asterisk (*) characters.

Note that loyalty cards are handled separately, see LoyaltyCardPresented(String, out Boolean).

Examples

...
mEpas.CardAccepted = HandleCardAccepted;
...

public void HandleCardAccepted(CardAcceptedEventArgs args)
{
    if (InvokeRequired)
    {
        Invoke(new Action(() => HandleCardAccepted(args)));
    }
    else
    {
        string cardNumberAliasHexString = BufferTools.ByteArrayToHexString(args.CardNumberAlias);
        ttToolTips.SetToolTip(lblCardPresent, args.MaskedCardNumber + "\nCNA " + cardNumberAliasHexString);
        Log("Card accepted: " + args.MaskedCardNumber);
        Log("Card Number Alias: " + cardNumberAliasHexString);
    }
}

View Source

CardStatus

The handler for card insert and removal notifications

Declaration

public EpasClient.CardActionNotification CardStatus

Field Value

Type	Description
EpasClient.CardActionNotification

Remarks

This callback is used when the terminal recognises that a card has been inserted in, or removed from, the card reader. The ECR might use this status to prompt the cardholder to remove the card when the transaction is complete.

This notification only applies to the smart card reader. Cards that are tapped or swiped do not trigger this callback.

Note that if a card inserted while the card readers in the terminal are not enabled then this notification is used as soon as the readers are enabled.

Examples

...
mEpas.CardStatus = CardStatus;
...

public void CardStatus(bool inserted)
{
    if (InvokeRequired)
    {
        Invoke(new Action(() => CardStatus(inserted)));
    }
    else
    {
        if (inserted)
        {
            lblCardPresent.Text = "CARD INSERTED";
        }
        else
        {
            lblCardPresent.Text = "CARD TAKEN";
        }
    }
}

View Source

LinkStatus

Handler for link status notifications

Declaration

public EpasClient.StatusNotification LinkStatus

Field Value

Type	Description
EpasClient.StatusNotification

Remarks

This callback is called when the EPAS client library detects a change in the link status between the terminal and the ECR. When the linkUp parameter is true, the link is functioning. When the parameter is false then there has been a link failure and the ECR should take appropriate action.

Examples

...
mEpas.LinkStatus = HandleLinkState;
...

public void HandleLinkState(bool linkUp)
{
    if (InvokeRequired)
    {
        Invoke(new Action(() => HandleLinkState(linkUp)));
    }
    else
    {
        if (linkUp)
        {
            lblLink.BackColor = Color.PaleGreen;
            lblLink.ForeColor = Color.DarkGreen;
            lblLink.Text = "OK";
        }
        else
        {
            lblLink.BackColor = Color.LightPink;
            lblLink.ForeColor = Color.DarkRed;
            lblLink.Text = "DOWN";
        }
    }
}

View Source

RawMessageHandler

Handler for raw EPAS XML messages. This should only be used with a very good reason.

Declaration

public EpasClient.EpasMessageReceiver RawMessageHandler

Field Value

Type	Description
EpasClient.EpasMessageReceiver

Remarks

It may be useful or necessary for the ECR to be able to directly inspect EPAS XML messages that are received in the library. In these situations, the ECR can assign a handler to the RawMessageHandler callback.

This feature is only provided as a fallback way to deal with situations that the library does not handle. There is no clear usage for this, other than that it allows the ECR to directly handle EPAS messages to achieve some very specific objective that it cannot achieve via the library API.

In normal use the ECR should not need to provide a handler for this callback.

Examples

...
mEpas.RawMessageHandler = HandleIncomingXML;
...

private void HandleIncomingXML(string rawXml)
{
    Log(LogLevel.Debug, "Incoming XML:");
    Log(LogLevel.Debug, rawXml);
}

Properties

View Source

Options

Operating parameters for the library

Declaration

public OperatingParameters Options { get; }

Property Value

Type	Description
OperatingParameters

Methods

View Source

CashAdvance(Decimal, out TransactionResponse)

Performs a cash advance / withdrawal transaction.

Declaration

public ApiResult CashAdvance(decimal cashAmount, out TransactionResponse response)

Parameters

Type	Name	Description
System.Decimal	cashAmount	Amount of cash to withdraw
TransactionResponse	response	Transaction response

Returns

Type	Description
ApiResult	Standard ApiResult values

Examples

/// <summary>
/// Runs a cash advance transaction.
/// </summary>
/// <param name="amount">Cash amount</param>
/// sending the transaction result</param>
public void CashAdvance(decimal amount)
{
    Log($"Cash Advance of {amount:.00}");
    TransactionResponse response;
    ApiResult result = mEpas.CashAdvance(amount, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Cash Advance: " + response?.ToString());
}

View Source

Close()

Close the library

Declaration

public void Close()

View Source

ConnectNetwork(TerminalNetworkConnection, Boolean)

Attempts to create a network connection to the terminal

Declaration

public ApiResult ConnectNetwork(TerminalNetworkConnection connectionDetails, bool forceReconnect = false)

Parameters

Type	Name	Description
TerminalNetworkConnection	connectionDetails	Details of how to connect to the terminal via network
System.Boolean	forceReconnect	Set to `true` to close an existing connection and force a new connection to be made

Returns

Type	Description
ApiResult	A standard ApiResult value

Remarks

The ConnectNetwork method attempts to connect to the terminal over a TCP/IP network connection. The connectionDetails parameter contains the details needed for the connection.

If the forceReconnect parameter is true then if there is already a connection in place that connection will be closed and a new one will be created. Otherwise, if forceReconnect is false, if there is already a connection in place then this method will just return OK.

Examples

private void ConnectToTerminal()
{
    Log("Connecting...");
    bool dataOk = true;
    TerminalNetworkConnection tc = new TerminalNetworkConnection();
    try
    {
        tc.TerminalConnectionDetails = new
        IPEndPoint(IPAddress.Parse(txtTerminalAddress.Text), int.Parse(txtTerminalPort.Text));
    }
    catch (Exception)
    {
        dataOk = false;
        LogError("Unable to parse terminal address and / or port");
    }

    tc.UseKeepAlive = optKeepalive.Checked;
    if (dataOk)
    {
        ApiResult result = mEpas.ConnectNetwork(tc, optForceReconnect.Checked);
        LogApiResult(result, "Connect");
    }
}

View Source

ConnectUsb(String, Boolean)

USB/serial connections are no longer supported.

Declaration

[Obsolete]
public ApiResult ConnectUsb(string comPort, bool forceReconnect = false)

Parameters

Type	Name	Description
System.String	comPort
System.Boolean	forceReconnect

Returns

Type	Description
ApiResult

View Source

Disconnect()

Disconnect from the terminal

Declaration

public ApiResult Disconnect()

Returns

Type	Description
ApiResult	A standard ApiResult value

Remarks

The Disconnect method closes the connection to the terminal, whether it is network or USB.

Examples

private void btnDisconnect_Click()
{
    Log("Disconnecting");
    mEpas?.Disconnect();
}

View Source

EnableCardReaders(Boolean, EnableCardReaderOptions, out EnableReadersResponse)

Enables or disables the card readers on the terminal.

Declaration

public ApiResult EnableCardReaders(bool enable, EnableCardReaderOptions cardReaderOptions, out EnableReadersResponse response)

Parameters

Type	Name	Description
System.Boolean	enable	True to enable the card readers, false to disable them.
EnableCardReaderOptions	cardReaderOptions
EnableReadersResponse	response	Response from the terminal

Returns

Type	Description
ApiResult	Standard API result value

View Source

GetLastTransaction(String, out LastTransactionResponse)

Get Last Transaction Details.

Declaration

public ApiResult GetLastTransaction(string terminalId, out LastTransactionResponse response)

Parameters

Type	Name	Description
System.String	terminalId	Terminal Id
LastTransactionResponse	response	Transaction response

Returns

Type	Description
ApiResult	Standard ApiResult values

Examples

/// <summary>
/// Get last transaction details.
/// </summary>
/// <param name="terminalId">Terminal Id</param>
/// sending the transaction result</param>
public void LastTransaction(String terminalId)
 {

       LastTransactionResponse response;

       Log("API:  LastTransaction");
       ApiResult result = mEpas.GetLastTransaction(terminalId, out response);


       LogApiResult(result, "Last Transaction: " + response?.ToString());
 }

View Source

Login(TerminalEnvironment, out LoginResponse)

Sends a login request to the terminal. The login request provides essential information to the terminal and enables transactions to be run.

Declaration

public ApiResult Login(TerminalEnvironment environment, out LoginResponse response)

Parameters

Type	Name	Description
TerminalEnvironment	environment	Details of the terminal's operating environment and major parameters
LoginResponse	response	Response from the connect attempt

Returns

Type	Description
ApiResult	A standard ApiResult value

Remarks

The Login method carries details of the operating environment for the terminal.

If the method returns OK then the response parameter contains the terminal’s response to the login request.

Examples

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",
    StoreId       = "store_1",
    WorkstationId = 'workstation_1"
};

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

View Source

Logout(out LogoutResponse)

Sends a logout request to the terminal.

Declaration

public ApiResult Logout(out LogoutResponse response)

Parameters

Type	Name	Description
LogoutResponse	response	Response from the logout attempt

Returns

Type	Description
ApiResult	A standard ApiResult value

View Source

Purchase(Decimal, String, out TransactionResponse)

Starts a purchase transaction with only the purchase amount specified.

Declaration

public ApiResult Purchase(decimal purchaseAmount, string paymentMethod, out TransactionResponse response)

Parameters

Type	Name	Description
System.Decimal	purchaseAmount	Transaction value
System.String	paymentMethod	Name of alternative payment method to use
TransactionResponse	response	Transaction result

Returns

Type	Description
ApiResult	Standard API outcome value

Examples

/// <summary>
/// Runs a simple purchase transaction for the given amount using Swish, if available. 
/// There is no cashback or swipe-ahead in this transaction.
/// </summary>
/// <param name="amount">Transaction amount</param>
public void SimpleSwishPurchase(decimal amount)
{
    Log($"Simple Swish-purchase of {amount:.00}");
    TransactionResponse response;
    ApiResult result = mEpas.Purchase(amount, “Swish”, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Simple Swish-purchase: " + response?.ToString());
}

View Source

Purchase(Decimal, out TransactionResponse)

Starts a purchase transaction with only the purchase amount specified.

Declaration

public ApiResult Purchase(decimal purchaseAmount, out TransactionResponse response)

Parameters

Type	Name	Description
System.Decimal	purchaseAmount	Transaction value
TransactionResponse	response	Transaction result

Returns

Type	Description
ApiResult	Standard API outcome value

Examples

/// <summary>
/// Runs a simple purchase transaction for the given amount. There is no cashback
/// or swipe-ahead in this transaction.
/// </summary>
/// <param name="amount">Transaction amount</param>
public void SimplePurchase(decimal amount)
{
    Log($"Simple purchase of {amount:.00}");
    TransactionResponse response;
    ApiResult result = mEpas.Purchase(amount, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Simple purchase: " + response?.ToString());
}

View Source

Purchase(PurchaseRequest, out TransactionResponse)

Begins a purchase transaction. The method returns when the transaction is complete.

Declaration

public ApiResult Purchase(PurchaseRequest request, out TransactionResponse response)

Parameters

Type	Name	Description
PurchaseRequest	request	Transaction parameters
TransactionResponse	response	Transaction response

Returns

Type	Description
ApiResult	A standard ApiResult value

Examples

/// <summary>
/// Runs a full-featured purchase transaction
/// </summary>
/// <param name="amount">Purchase amount</param>
/// <param name="cashback">Cashback amount</param>
public void PurchaseWithCashback(decimal amount, decimal cashback)
{
    Log($"Purchase of {amount:.00} + {cashback:.00} cashback");
    TransactionResponse response;
    PurchaseRequest request = new PurchaseRequest
    {
        Amount = amount,
        CashbackAmount = cashback,
    };
    ApiResult result = mEpas.Purchase(request, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Purchase: " + response?.ToString());
}

View Source

Purchase(PurchaseTransactionAmounts, out TransactionResponse)

Begins a purchase transaction. The method returns when the transaction is complete.

Declaration

public ApiResult Purchase(PurchaseTransactionAmounts transactionAmounts, out TransactionResponse response)

Parameters

Type	Name	Description
PurchaseTransactionAmounts	transactionAmounts	Transaction amounts
TransactionResponse	response	Transaction response

Returns

Type	Description
ApiResult	A standard ApiResult value

Examples

/// <summary>
/// Runs a full-featured purchase transaction
/// </summary>
/// <param name="amount">Purchase amount</param>
/// <param name="cashback">Cashback amount</param>
public void PurchaseWithCashback(decimal amount, decimal cashback)
{
    Log($"Purchase of {amount:.00} + {cashback:.00} cashback");
    TransactionResponse response;
    PurchaseTransactionAmounts txnAmount = new PurchaseTransactionAmounts(amount, cashback);
    ApiResult result = mEpas.Purchase(txnAmount, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Purchase: " + response?.ToString());
}

View Source

PurchaseBeforeAmount(out TransactionResponse)

Starts a purchase transaction with no amount. The amount must be sent when available in order for the transaction to be completed.

Declaration

public ApiResult PurchaseBeforeAmount(out TransactionResponse response)

Parameters

Type	Name	Description
TransactionResponse	response	Transaction result

Returns

Type	Description
ApiResult	Standard API outcome value

Examples

/// <summary>
/// Runs a pre-amount purchase transaction, where the amount is supplied later.
/// Also known as swipe-ahead and pre-tap.
/// </summary>
public void PreAmountPurchase()
{
    Log("PreAmount purchase");
    TransactionResponse response;
    ApiResult result = mEpas.PurchaseBeforeAmount(out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "PreAmount purchase: " + response?.ToString());
}

Refund(Decimal, out TransactionResponse)

Begins a refund transaction. The method returns when the transaction is complete.

Declaration

public ApiResult Refund(decimal refundAmount, out TransactionResponse response)

Parameters

Type	Name	Description
System.Decimal	refundAmount	Amount to refund
TransactionResponse	response	Transaction response

Returns

Type	Description
ApiResult	A standard ApiResult value

Examples

/// <summary>
/// Runs a refund transaction
/// </summary>
/// <param name="amount">Refund amount</param>
/// sending the transaction result</param>
public void Refund(decimal amount)
{
    Log($"Refund of {amount:.00}");
    TransactionResponse response;
    ApiResult result = mEpas.Refund(amount, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Refund: " + response?.ToString());
}

View Source

Refund(AltMethodTransaction, out TransactionResponse)

Begins a refund transaction where the transaction being refunded was completed using an alternative payment method. Alternative payment methods are where a card was not used in the terminal. The method returns when the transaction is complete.

Declaration

public ApiResult Refund(AltMethodTransaction transactionDetails, out TransactionResponse response)

Parameters

Type	Name	Description
AltMethodTransaction	transactionDetails	Transaction details
TransactionResponse	response	Transaction response

Returns

Type	Description
ApiResult	A standard ApiResult value

View Source

Refund(RefundRequest, out TransactionResponse)

Begins a refund transaction. The method returns when the transaction is complete.

Declaration

public ApiResult Refund(RefundRequest request, out TransactionResponse response)

Parameters

Type	Name	Description
RefundRequest	request	Transaction parameters
TransactionResponse	response	Transaction response

Returns

Type	Description
ApiResult	A standard ApiResult value

Examples

/// <summary>
/// Runs a refund transaction
/// </summary>
/// <param name="amount">Refund amount</param>
/// sending the transaction result</param>
public void Refund(decimal amount)
{
    Log($"Refund of {amount:.00}");
    RefundRequest request = new RefundRequest { Amount = amount };
    TransactionResponse response;
    ApiResult result = mEpas.Refund(request, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Refund: " + response?.ToString());
}

View Source

RequestAdministrativeOperation(AdminOperation, out AdminResponse)

Sends an administrative request to the terminal.

Declaration

public ApiResult RequestAdministrativeOperation(AdminOperation operation, out AdminResponse response)

Parameters

Type	Name	Description
AdminOperation	operation	Administrative operation being requested
AdminResponse	response	Terminal response

Returns

Type	Description
ApiResult	Standard ApiResult value

View Source

RequestTransactionAbort()

Request that the current transaction should be aborted. The transaction may be at a stage where an abort is not possible, so the client must wait for the transaction result to be sent.

Declaration

public ApiResult RequestTransactionAbort()

Returns

Type	Description
ApiResult	A standard ApiResult value. This indicates only if the request was sent to the terminal. The transaction result will indicate if the request was successful or not.

View Source

ReverseLastTransaction(String, out TransactionResponse)

Requests that the last transaction should be reversed. Note that only approved transactions can be reversed, and that a reversal can only be applied to the most recent transaction that was performed. If an approved transaction is followed by a declined transaction then the approved transaction can no longer be reversed.

Declaration

public ApiResult ReverseLastTransaction(string transactionReference, out TransactionResponse response)

Parameters

Type	Name	Description
System.String	transactionReference	Reference number of the transaction to be reversed, provided in the TransactionResponse class.
TransactionResponse	response	The reversal response

Returns

Type	Description
ApiResult	A standard ApiResult value

Examples

/// <summary>
/// Reverse the last transaction
/// </summary>
public void Reversal()
{
    Log("Reversal");
    TransactionResponse response;
    ApiResult result = mEpas.ReverseLastTransaction(txnRef.Text, out response);
    if (result == ApiResult.OK)
    {
        HandleTxnResponse(response);
    }
    LogApiResult(result, "Reversal: " + response?.ToString());
}

View Source

SendPurchaseAmounts(PurchaseTransactionAmounts)

Sends the amounts for a Purchase before Amount transaction.

Declaration

public ApiResult SendPurchaseAmounts(PurchaseTransactionAmounts transactionAmount)

Parameters

Type	Name	Description
PurchaseTransactionAmounts	transactionAmount	Transaction amounts

Returns

Type	Description
ApiResult	Standard API outcome value

Remarks

A purchase transaction with zero amounts must have been started before this method can be called.

Examples

/// <summary>
/// Send the transaction amounts for a pre-amount purchase transaction.
/// </summary>
/// <param name="amount">Purchase amount</param>
/// <param name="cashback">Cashback amount</param>
public void SendAmounts(decimal amount, decimal cashback)
{
    Log($"Sending amounts: {amount:.00} + {cashback:.00} cashback");
    PurchaseTransactionAmounts txnAmount = new PurchaseTransactionAmounts(amount, cashback);
    LogApiResult(mEpas.SendPurchaseAmounts(txnAmount), "SendPurchaseAmounts");
}

SendRawXml(String)

Sends raw EPAS XML messages to the terminal.

Declaration

public ApiResult SendRawXml(string xml)

Parameters

Type	Name	Description
System.String	xml	EPAS XML message

Returns

Type	Description
ApiResult	Standard API result indicating the outcome of the send attempt