PaymentTerminal (posapplib 1.10.0 API)

All Known Implementing Classes:

CarbonTerminal
```
public interface PaymentTerminal
```
The PaymentTerminal interface is the main interaction point with the payment terminal.
The POS application should perform these steps in order to use the payment terminal:
1. Get an instance of PaymentTerminal. This is done by creating an instance of CarbonTerminal and setting that up.
2. Initialise the payment terminal by calling initialise.
3. When the terminal is initialised, it is ready to receive transaction requests. The POS application should call doTransaction when it needs to perform a transaction.
The methods of PaymentTerminal works asynchronously. They return immediately, and the result of the operation is returned later in a callback that must be passed to the method.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`abortTransaction()` Aborts a transaction in progress.
`boolean`	`checkForUpdates(UpdateCheckResponseHandler response)` Checks for updates to the payment terminal.
`boolean`	`disableNavigationBar()` Makes the navigation bar disappear.
`boolean`	`doMaintenance(MaintenanceResponseHandler response)` Open the system menu in the payment terminal.
`boolean`	`doTransaction(TransactionRequest transaction, TransactionResponseHandler response, CardVerificationHandler cardCheck)` Performs a transaction.
`boolean`	`enableDataRoaming(boolean enable)` Enable/ Disable Data roaming.
`boolean`	`enableNavigationBar(NavigationBarButtons[] buttons)` Show the navigation bar with back and/or home buttons.
`boolean`	`getLastTransactionResult(TransactionResponseHandler response)` Gets the result of the last completed transaction.
`PrinterStatus`	`getPrinterStatus()`
`int`	`getSleepTime()` Gets the sleep time value.
`int`	`getSuspendTime()` Gets the suspend time value.
`boolean`	`getTerminalStatus(TerminalStatusResponseHandler response)`
`boolean`	`initialise(TerminalSettings settings, InitialisationResponseHandler response, NotificationHandler notification)` Initialises the payment terminal.
`boolean`	`openPaymentServiceMenu(MenuFeatures[] disabledMenuFeatures, MaintenanceResponseHandler response)` Open the system menu in the payment terminal.
`boolean`	`readCustomCard(CustomCardRequest request, CustomCardResponseHandler response)` Asks the payment application to read a custom card.
`boolean`	`reverseLastTransaction(ReversalResponseHandler response)` Reverses the previous transaction.
`boolean`	`setApn(ApnInfo apnInfo)` Set APN settings.
`boolean`	`setParameter(Parameter parameter, int value)` Set parameter.
`boolean`	`setScreenBrightness(int brightnessPercent)` Set screen brightness.
`boolean`	`setSleepTime(DisplayUtilities.SleepTime time)` Set the sleep time value.
`boolean`	`setSuspendTime(DisplayUtilities.SuspendTime time)` Set the suspend time value.
`boolean`	`setTransactionAmounts(TransactionAmounts transactionAmounts)` If a zero amount is provided in the transaction request, this call can be used to update the transaction with an amount.
`boolean`	`shutdown(boolean restart)` Shuts down the payment terminal.
`PrintJob`	`startPrintJob()` Starts a new printer job.
`boolean`	`validateMerchantPassword(java.lang.String password)` Validate the merchant password.

- Method Detail
  - initialise
```
boolean initialise(TerminalSettings settings,
                   InitialisationResponseHandler response,
                   NotificationHandler notification)
```
    Initialises the payment terminal. Before the payment terminal can be used to process transactions, it has to be initialised. The initialisation process includes contacting the payment processor and downloading the current terminal settings.
    This method returns immediately but the initialisation result is returned in the response callback. The initialisation takes a little time, from a few seconds to a couple of minutes, depending on network availability and if there are new settings or updates to process.
    The initialisation is done in the background. The payment application will not take over the screen during this time.
    
    Parameters:
    
    settings - The settings for the payment terminal.
    
    response - A callback that will be called with the result of the initialisation.
    
    notification - Optional. A callback that will be called for different events.
    
    Returns:
    
    true if the request was sent successfully, otherwise false. Note that this does not indicate the success or failure of the initialisation. If no InitialisationResponseHandler is provided the method will return false.
  - doTransaction
```
boolean doTransaction(TransactionRequest transaction,
                      TransactionResponseHandler response,
                      CardVerificationHandler cardCheck)
```
    Performs a transaction. A transaction request is passed to the payment application which will process the transaction. At the end of the transaction, regardless of outcome, the result is passed back to the POS application using the response callback.
    The payment application will take over the screen during the transaction. At the end of the transaction, when the response callback is called, the POS application has to start the appropriate activity to take the screen back.
    It is very important that the POS application remains inactive during a transaction. If the payment application loses focus during a transaction, the transaction will be aborted. The API will refuse to process new request while there is an active transaction.
    
    Parameters:
    
    transaction - The details of the transaction.
    
    response - A callback that will be called with the result of the transaction.
    
    cardCheck - Optional.
    
    Returns:
    
    true if the request was sent successfully, otherwise false.. Note that this does not indicate the success or failure of the transaction. If no TransactionResponseHandler is provided the method will return false.
  - readCustomCard
```
boolean readCustomCard(CustomCardRequest request,
                       CustomCardResponseHandler response)
```
    Asks the payment application to read a custom card.
    A custom card can be any card that is not a payment card. It is usually some sort of bonus card, or an employee id card.
    Custom cards can only be read outside of a transaction, and only after the payment application has been initialised.
    If a card is read that is identified as a known payment card, it will be rejected. If a card is read that looks like it could be a payment card (if it contains an expiry date for example), it will be rejected.
    
    Parameters:
    
    request - Contains parameters for the request. This is optional; set to null if no extra parameters are required.
    
    response - A callback that will be called with the result of the card read.
    
    Returns:
    
    true if the request was sent successfully, otherwise false.. Note that this does not indicate the success or failure of the action. If no CustomCardResponseHandler is provided the method will return false.
  - abortTransaction
```
void abortTransaction()
```
    Aborts a transaction in progress. An abort-transaction request is sent to the payment application. If there is no active transaction the request is ignored. If there is an active transaction the payment application will attempt to abort it.
    Note that this method does not provide a result. If the abortion is successful, it will be indicated in the response to doTransaction that the transaction was cancelled.
  - setTransactionAmounts
```
boolean setTransactionAmounts(TransactionAmounts transactionAmounts)
```
    If a zero amount is provided in the transaction request, this call can be used to update the transaction with an amount.
    
    Parameters:
    
    transactionAmounts -
    
    Returns:
    
    true if the set transaction amount was sent successfully, otherwise false..
  - reverseLastTransaction
```
boolean reverseLastTransaction(ReversalResponseHandler response)
```
    Reverses the previous transaction. A reversal request is sent to the payment application which will attempt to reverse the previous transaction. Note that this is not the same as aborting an active transaction. Reversing a transaction is done after the transaction has been completed. It is not possible to reverse a transaction while it is being processed.
    The payment application will take over the screen during the reversal. At the end of the transaction, when the response callback is called, the POS application has to start the appropriate activity to take the screen back.
    It is very important that the POS application remains inactive during a reversal. If the payment application loses focus during a reversal, the reversal will be aborted. The API will refuse to process new request while there is an active reversal.
    
    Parameters:
    
    response - A callback that will be called when the reversal is completed.
    
    Returns:
    
    true if the request was sent successfully, otherwise false.. Note that this does not indicate the success or failure of the reversal. If no ReversalResponseHandler is provided the method will return false.
  - getLastTransactionResult
```
boolean getLastTransactionResult(TransactionResponseHandler response)
```
    Gets the result of the last completed transaction. The response will contain the same data as the original response to doTransaction(TransactionRequest, TransactionResponseHandler, CardVerificationHandler).
    The response can be null if the result of the previous transaction is not available. This happens if there has not been a previous transaction, or if a new transaction has been started, but not completed.
    Note that this method cannot be called while a transaction is in progress. If it is called then, it will return false.
    This method requires Westpay Payment Application v2.0.11 or higher.
    
    Parameters:
    
    response - A callback that will be called with the results of the last completed transaction. This response contains the same data that is contained in the transaction response. If the callback is not given, the method returns false.
    
    Returns:
    
    true if the request was sent successfully, otherwise false.
  - doMaintenance
```
boolean doMaintenance(MaintenanceResponseHandler response)
```
    Open the system menu in the payment terminal. The payment terminal will take over the screen and show its System functions menu. When the user exits the menu, response callback is called and the POS application should start the appropriate activity to take over.
    
    Parameters:
    
    response - A callback that will be called when the maintenance is completed.
    
    Returns:
    
    true if the request was sent successfully, otherwise false.. Note that this does not indicate the success or failure of the maintenance. If no MaintenanceResponseHandler is provided the method will return false.
  - openPaymentServiceMenu
```
boolean openPaymentServiceMenu(MenuFeatures[] disabledMenuFeatures,
                               MaintenanceResponseHandler response)
```
    Open the system menu in the payment terminal. The payment terminal will take over the screen and show its System functions menu. When the user exits the menu, response callback is called and the POS application should start the appropriate activity to take over.
    
    Parameters:
    
    disabledMenuFeatures - An array of MenuFeatures that should not be visible in the payment service menu.
    
    response - A callback that will be called when the maintenance is completed.
    
    Returns:
    
    true if the request was sent successfully, otherwise false.. Note that this does not indicate the success or failure of the maintenance. If no MaintenanceResponseHandler is provided the method will return false.
  - startPrintJob
```
PrintJob startPrintJob()
```
    Starts a new printer job.
    
    Returns:
    
    A printer job instance, or null if a printer job cannot be started at this moment.
  - getPrinterStatus
```
PrinterStatus getPrinterStatus()
```
    Returns:
    
    The current printer status.
  - validateMerchantPassword
```
boolean validateMerchantPassword(java.lang.String password)
```
    Validate the merchant password.
    
    Parameters:
    
    password - The password in plain text.
    
    Returns:
    
    true if the validation was successfully, otherwise false..
  - checkForUpdates
```
boolean checkForUpdates(UpdateCheckResponseHandler response)
```
    Checks for updates to the payment terminal. Calling this method will start the Application Updater program. NOTE! The Application Updater will restart the terminal when it is finished so the POS application will not regain control after this method is called.
    
    Parameters:
    
    response - Not used, reserved for future use.
    
    Returns:
    
    true if the Application Updater was started, otherwise false.. If no UpdateCheckResponseHandler is provided the method will return false.
  - shutdown
```
boolean shutdown(boolean restart)
```
    Shuts down the payment terminal.
    
    Parameters:
    
    restart - If set to true, the terminal will restart after shut down.
    
    Returns:
    
    true if the request was sent successfully, otherwise false.. Note that this does not indicate the success or failure of the shutdown. If no TerminalStatusResponseHandler is provided the method will return false.
  - getTerminalStatus
```
boolean getTerminalStatus(TerminalStatusResponseHandler response)
```
  - enableNavigationBar
```
boolean enableNavigationBar(NavigationBarButtons[] buttons)
```
    Show the navigation bar with back and/or home buttons. This method will add the provided buttons to the navigation bar, that means that if the HOME button already been enabled by another activity and the provided button is BACK for this activity, both buttons will be shown. Hiding the navigation bar can be done by using the Android API method View.setSystemUiVisibility with the flags View.SYSTEM_UI_FLAG_HIDE_NAVIGATION and View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY int the application.
    
    Parameters:
    
    buttons - Buttons to be enabled on the navigation bar.
    
    Returns:
    
    true if operation was successful, otherwise false..
    
    See Also:
    
    setSystemUiVisibility NOTE: This method (enableNavigationBar) should not be used together with disableNavigationBar in the same activity, this will cause a RuntimeException.
  - disableNavigationBar
```
boolean disableNavigationBar()
```
    Makes the navigation bar disappear.
    NOTE: This method (disableNavigationBar) should not be used together with enableNavigationBar in the same activity, this will cause a RuntimeException.
    
    Returns:
    
    true if operation was successful, otherwise false..
  - setParameter
```
boolean setParameter(Parameter parameter,
                     int value)
```
    Set parameter.
    
    Parameters:
    
    parameter - Parameter type.
    
    value - Parameter value.
    
    Returns:
    
    true if the timeout was successfully set, otherwise false..
  - getSleepTime
```
int getSleepTime()
```
    Gets the sleep time value.
    
    Returns:
    
    the current sleep time value, in milliseconds. -1 means the value could not be read.
  - setSleepTime
```
boolean setSleepTime(DisplayUtilities.SleepTime time)
```
    Set the sleep time value.
    
    Parameters:
    
    time - SleepTime value.
    
    Returns:
    
    true if operation was successful, otherwise false..
  - getSuspendTime
```
int getSuspendTime()
```
    Gets the suspend time value.
    
    Returns:
    
    the current suspend time value, in milliseconds. -1 means the value could not be read.
  - setSuspendTime
```
boolean setSuspendTime(DisplayUtilities.SuspendTime time)
```
    Set the suspend time value.
    
    Parameters:
    
    time - SuspendTime value.
    
    Returns:
    
    true if operation was successful, otherwise false..
  - setScreenBrightness
```
boolean setScreenBrightness(int brightnessPercent)
```
    Set screen brightness.
    
    Parameters:
    
    brightnessPercent - Value for the brightness, valid values are 0 - 100 percent.
    
    Returns:
    
    boolean - True success, false otherwise.
  - setApn
```
boolean setApn(ApnInfo apnInfo)
```
    Set APN settings.
    
    Parameters:
    
    apnInfo - This object to set APN parameters.
    
    Returns:
    
    code>true if operation was successful, otherwise false..
  - enableDataRoaming
```
boolean enableDataRoaming(boolean enable)
```
    Enable/ Disable Data roaming.
    
    Parameters:
    
    enable - Enable/Disable flag (if value is true, then enable the data roaming. otherwise disable).
    
    Returns:
    
    code>true if operation was successful, otherwise false..

Interface PaymentTerminal

Method Summary

Method Detail

initialise

doTransaction

readCustomCard

abortTransaction

setTransactionAmounts

reverseLastTransaction

getLastTransactionResult

doMaintenance

openPaymentServiceMenu

startPrintJob

getPrinterStatus

validateMerchantPassword

checkForUpdates

shutdown

getTerminalStatus

enableNavigationBar

disableNavigationBar

setParameter

getSleepTime

setSleepTime

getSuspendTime

setSuspendTime

setScreenBrightness

setApn

enableDataRoaming