Interface IClientApp

Interface definition for an app that uses the EPAS Client Library

Namespace: Westpay.Epas

Assembly: EpasClientLibrary.dll

Syntax

public interface IClientApp

Methods

View Source

CheckDccOnOriginalTransaction(String, out Boolean)

Called during a refund transaction with a DCC-eligible card, to check if DCC was used in the original transaction. This will be clear from the original receipt.

Declaration

bool CheckDccOnOriginalTransaction(string displayText, out bool dccWasUsed)

Parameters

Type	Name	Description
System.String	displayText	Text to display.
System.Boolean	dccWasUsed	Set to `true` if DCC was used in the original purchase, or `false` if no DCC was used.

Returns

Type	Description
System.Boolean	`true` if the transaction should continue, `false` to abort the transaction.

Remarks

Dynamic Currency Conversion is a process where a cardholder from a different country can choose to pay for a transaction in their home currency rather than in the currency of the merchant.

This introduces a challenge for refunds, because if a refund transaction is to be done with a ‘foreign’ card then the refund should be made using the converted currency if the original purchase was made with a converted currency, even though the currency rates may have changed between purchase and refund.

The only way to know if DCC was used in the original purchase is to check the receipt. If this method is called, therefore, the cashier should check the original receipt to find out if DCC was used. If so, dccWasUsed should be set to true, otherwise it should be false if DCC was not used.

The displayText parameter contains a prompt for the cashier to check for DCC on the original purchase.

Normally the ECR should return true from this method, indicating that the setting of dccWasUsed is valid. If the ECR returns false then the library will abort the current transaction.

Examples

public bool CheckDccOnOriginalTransaction(string displayText, out bool dccWasUsed)
{
    Display(displayText);
    dccWasUsed = MessageBox.Show("Was DCC used in the original transaction?", "DCC", 
                 MessageBoxButtons.YesNo) == DialogResult.Yes;
    return true;
}

View Source

Display(String)

Called when the client app should display some text to the cashier.

Declaration

void Display(string text)

Parameters

Type	Name	Description
System.String	text	Text to be displayed

Remarks

The terminal will send messages intended for the cashier. These are localised into the cashier’s chosen language and are not always the same as the messages that appear on the terminal’s display.

Each line in the text is separated by a newline character (\n)

Examples

public void Display(string text)
{
    if (InvokeRequired)
    {
        Invoke(new Action(() => Display(text)));
    }
    else
    {
        txtCashierDisplay.Text = text.Replace("\n", Environment.NewLine);
    }
}

View Source

HandleVoiceReferral(String, out String)

Called when a voice referral should be done, which involves calling the card issuer to get an approval code verbally.

Declaration

bool HandleVoiceReferral(string displayText, out string approvalCode)

Parameters

Type	Name	Description
System.String	displayText	Text to display. This text includes the phone number, if needed.
System.String	approvalCode	The approval code provided by the issuer.

Returns

Type	Description
System.Boolean	`true` if the transaction should continue with the supplied approval code, `false` to abort the transaction.

Remarks

If a transaction cannot be authorised online due to communications problems then it may be suitable for voice referral. This is where the cashier contacts the authorisation centre directly by telephone and provides the transaction and card details verbally. If the transaction is approved then the cashier will be provided with an approval code.

When this method is called the text prompt for the cashier is provided in displayText, and this should contain the phone number to call.

The approval code should be provided in the approvalCode parameter. If the value in approvalCode is empty or null on return then the transaction will be aborted.

Normally the ECR should return true from this method, indicating that the setting of approvalCode is valid. If the ECR returns false then the library will abort the current transaction.

Examples

bool IClientApp.HandleVoiceReferral(string displayText, out string approvalCode)
{
    bool result = false;
    approvalCode = null;
    TextEntry vr = new TextEntry("Voice referral approval code", displayText);
    if (vr.ShowDialog() == DialogResult.OK)
    {
        approvalCode = vr.EnteredText;
        result = true;
    }
    return result;
}

View Source

Log(LogLevel, String)

Logs text with the client application.

Declaration

void Log(LogLevel level, string text)

Parameters

Type	Name	Description
LogLevel	level	Logging level
System.String	text	Text to log

Remarks

The EPAS Client Library will generate logging in various situations. When this happens, this method is called. This method is always called on a dedicated thread so that it can be called while another method or handler is executing. Only one call to Log will be made at a time, however – there will be no overlapping calls made.

The level parameter indicates that the log entry is one of error, status or debug logging. The text to be logged is in the text parameter.

If the ECR has a logging function then it is recommended that these texts are written to the ECR log. The ECR can, of course, filter the logging according to configuration. For example, it may not make sense to store debug level logging when in a production environment.

Examples

public void Log(LogLevel level, string text)
{
    try
    {
        LogTimestamp();
        RawLog(text);
    }
    catch (Exception)
    {
        // Logger exceptions are not logged.
    }
}

View Source

LoyaltyCardPresented(String, out Boolean)

Called when a loyalty card is presented to the terminal.

Declaration

bool LoyaltyCardPresented(string cardNumber, out bool cardAccepted)

Parameters

Type	Name	Description
System.String	cardNumber	The loyalty card number.
System.Boolean	cardAccepted	Set to true if the loyalty card is accepted and can be processed, or false to reject the loyalty card.

Returns

Type	Description
System.Boolean	`true` if the transaction should continue, `false` to abort the transaction.

Remarks

The terminal has a list of card ranges and some of those identify cards as loyalty / bonus cards. If one of those cards is presented to the terminal then this method is called. The loyalty card number is provided in the cardNumber parameter.

The ECR should decide if the loyalty card number is valid for the merchant. If the card is valid then the ECR should set cardAccepted to true, otherwise false will indicate that the loyalty card was not accepted. Neither of these affects the transaction in progress on the terminal.

Normally the ECR should return true from this method, indicating that the setting of cardAccepted is valid. If the ECR returns false then the library will abort the current transaction.

Examples

public bool LoyaltyCardPresented(string cardNumber, out bool cardAccepted)
{
    cardAccepted = MessageBox.Show("Accept loyalty card " + cardNumber, "Loyalty card", 
                   MessageBoxButtons.YesNo) == DialogResult.Yes;
    return true;
}

View Source

ParameterDownloadAvailable(String, out Boolean)

Called when a parameter download is available, and the ECR is permitted to choose whether to permit the download or delay it until later.

Declaration

void ParameterDownloadAvailable(string displayText, out bool permitDownload)

Parameters

Type	Name	Description
System.String	displayText	Text to display
System.Boolean	permitDownload	`true` to permit the download immediately, `false` to delay until later.

Remarks

From time to time the terminal will need parameter updates to be done. These are usually done at the beginning of the day after the ECR logs in to the terminal, but it is possible that the terminal will ask the ECR if the parameters can be downloaded immediately. The ECR can choose to respond with permitDownload set to false to delay the parameter download until later, though the same question will be asked repeatedly.

It should be noted that this functionality is very rarely used. The simplest approach is to simply set permitDownload to true to allow the download, but the ECR could implement a time-based response that sets permitDownload according to the time of day.

The displayText parameter contains a prompt to inform the cashier that a download is available.

There is no return value here. In the other methods of this type, the return value indicates if the response is valid or if the transaction should be cancelled. This method, however, is only ever called after the end of a transaction so there is nothing to abort.

Examples

public void ParameterDownloadAvailable(string displayText, out bool permitDownload)
{
    Display(displayText);
    permitDownload = MessageBox.Show("Download configuration?", "Configuration update", 
    MessageBoxButtons.YesNo) == DialogResult.Yes;
}

View Source

PaymentCodeRequired(String, out String)

Called when a card requires a payment code to be entered.

Declaration

bool PaymentCodeRequired(string displayText, out string paymentCode)

Parameters

Type	Name	Description
System.String	displayText	Text to display.
System.String	paymentCode	The payment code for the card / transaction.

Returns

Type	Description
System.Boolean	`true` if the transaction should continue with the supplied payment code, `false` to abort the transaction.

Remarks

Some cards can be configured such that they require a payment code to be entered. If this is the case then this method is called. The cardholder should know the payment code, and a text prompt for the cashier is provided in displayText.

The ECR should provide the payment code in the paymentCode parameter.

Normally the ECR should return true from this method, indicating that the setting of paymentCode is valid. If the ECR returns false then the library will abort the current transaction.

The payment application on the terminal will know what the expected payment code length will be. If the supplied code is not valid then the terminal may ask for the payment application to be re-entered.

Examples

public bool PaymentCodeRequired(string displayText, out string paymentCode)
{
    bool result = false;
    paymentCode = null;
    TextEntry pc = new TextEntry("Payment code", displayText);
    if (pc.ShowDialog() == DialogResult.OK)
    {
        paymentCode = pc.EnteredText;
        result = true;
    }
    return result;
}

View Source

PrintReceipt(ReceiptData)

Called when a receipt is to be handled. Customer and merchant receipts are handled separately, so this method may be called more than once in a transaction.

Declaration

void PrintReceipt(ReceiptData receipt)

Parameters

Type	Name	Description
ReceiptData	receipt	Receipt data

Remarks

Most transactions will require two receipts to be printed, one for the cardholder and one for the merchant. Each receipt is printed using a call to PrintReceipt and all the data required to produce the receipt is in the ReceiptData class instance that is passed as a parameter.

Some transaction will only involve a single receipt, e.g. transactions that are declined will only produce a cardholder receipt. It is also possible for receipts to be produced in other situations, e.g. if the terminal loses power during a transaction then it should attempt to print a receipt for the transaction that was in progress once connectivity has been restored.

Also, the receipts may not always be sent at the end of a transaction. If, for example, the transaction is being authorised by signature then one receipt, the one that is to be signed, will be produced earlier and the outcome of the transaction will then depend on whether that signature is correct or not.

Note: a receipt will only be printed after a card has been accepted. If a transaction is cancelled before a card is accepted then there will be no receipt.

Note: when PrintReceipt is called during a transaction then it is recommended to store the receipt data until the transaction is complete. The receipts can be printed when the method is called, the information in the receipt data will probably be useful for reporting once the transaction is complete.

Note: If a transaction is partly completed, e.g. at PIN entry, and the terminal loses power then when the terminal restarts PrintReceipt will be called after the ECR has logged in. The ECR must, therefore, be able to handle PrintReceipt outside of the context of an active transaction.

Examples

public void PrintReceipt(ReceiptData rcpt)
{
    Log(LogLevel.Status, "Receipt");
    LogFixedWidth(rcpt.GenerateSimpleReceipt(32));
}

View Source

PrintReport(String)

Called when a report is sent from the terminal

Declaration

void PrintReport(string report)

Parameters

Type	Name	Description
System.String	report	Text of the report

Remarks

The terminal can produce reports, e.g. transaction summaries or configuration details. These are presented as a single string where each line is separated by a newline character (\n).

The ECR can, of course, choose to save these reports to disk or show them on screen rather than print them.

Examples

public void PrintReport(string report)
{
    Log(LogLevel.Status, "Report");
    LogFixedWidth(report);
}

View Source

VatAmountRequired(String, out Decimal)

Called when a VAT amount is required.

Declaration

bool VatAmountRequired(string displayText, out decimal vatAmount)

Parameters

Type	Name	Description
System.String	displayText	Text to display.
System.Decimal	vatAmount	The VAT amount of the transaction.

Returns

Type	Description
System.Boolean	`true` if the transaction should continue with the supplied VAT amount, `false` to abort the transaction.

Remarks

Some cards can be configured such that they require a VAT / sales tax amount to be provided. If this is the case then this method is called.

A text prompt for the cashier is provided in displayText. The VAT amount of the transaction should be provided in the vatAmount parameter.

Normally the ECR should return true from this method, indicating that the setting of vatAmount is valid. If the ECR returns false then the library will abort the current transaction.

Examples

public bool VatAmountRequired(string displayText, out decimal vatAmount)
{
    bool result = false;
    vatAmount = 0;
    TextEntry vat = new TextEntry("VAT amount", displayText);
    if (vat.ShowDialog() == DialogResult.OK)
    {
        decimal.TryParse(vat.EnteredText, out vatAmount);
        result = true;
    }
    return result;
}

View Source

VerifySignature(String, out Boolean)

Called when the cardholder signature has to be verified.

Declaration

bool VerifySignature(string displayText, out bool signatureOk)

Parameters

Type	Name	Description
System.String	displayText	Text to display.
System.Boolean	signatureOk	Set to `true` if the signature is valid or `false` if the signature is not valid.

Returns

Type	Description
System.Boolean	`true` if the transaction should continue, `false` to abort the transaction.

Remarks

Cardholders may have the option to verify their identity using signature rather than by PIN entry. If signature verification is used then this method will be called. A text prompt for the cashier is provided in displayText.

If the signature is valid then the ECR should set signatureOk to true, otherwise signatureOk should be set to false.

Normally the ECR should return true from this method, indicating that the setting of signatureOk is valid. If the ECR returns false then the library will abort the current transaction.

The ECR can implement signature verification such that it always approves the signature (i.e. signatureOk is set to true and the method returns true) when this method is called, but then ensure that the signature is checked at the end of the transaction. The transaction can then be reversed if the signature is not valid.

Examples

public bool VerifySignature(string displayText, out bool signatureOk)
{
    Display(displayText);
    signatureOk = MessageBox.Show("Signature OK?", "Verify signature", 
    MessageBoxButtons.YesNo) == DialogResult.Yes;
    return true;
}