UEMiddlewareInterface

onAlertUser()

void onAlertUser(java.lang.String message)

Called to alert the user to perform an action. This is generally implemented with an AlertDialog.

onConnected

void onConnected()

To connect to payment device call the connect() method. Once the connection to the payment terminal has completed successfully the onConnected() method will be fired. You can then proceed to startTransaction().

If the connection is not successful, the onError() method will be called.

onDeviceInfoReceived

void onDeviceInfoReceived(java.util.HashMap<java.lang.String,java.lang.String> allParams)

Called in response to getDeviceInfo(). "allParams" contains a HashMap of key value pairs describing the connected hardware.

Device Info Hash Map

Key Example Description
serialNum 0003130000123456 Serial number of device
vendorID 0005 ID of device manufacturer
productID MP200 Model of the device
hwVersion FFFFFFFF Hardware version
swVersion 16072141 Software version
batteryLevel d Current charge of the battery
deviceState Current device state (should always be blank)
DUKPT FFFF3D0100 KSN for debit encryption
DUKPT_MAC FFFFFFFFFFF MAC for debit encryption
DUKPT_DEFAULT FF991C0000 KSN for e2e encryption
SRED FFFF987654 KSN for e2e encryption (SRED)

onDisconnected

void onDisconnected()

Called when the middleware has disconnected from the device. See the disconnect() method.

onError

void onError(UE_ERROR error)

Called when there is a error. When processing a transaction you should rely on the result returned by onTransactionComplete. If the operation cannot proceed it will have been cancelled gracefully. No need to call cancel. Get text using UE_ERROR.text

UE_ERROR

Constant Description
ALREADY_STARTED
BAD_SWIPE MP200 received bad swipe, Transaction will be aborted, retry.
GATEWAY_401_UNAUTHORIZED
GATEWAY_CONNECTION_ERROR The connection to the gateway failed.
GENERAL_EXCEPTION_CAUGHT Exception from Exception class caught, stack trace printed, report this error.
HANDLED These errors go out to the user.
INVALID_AMOUNT The amount entered was invalid.
INVALID_MAG_STRIPE The transaction was terminated because of a bad mag swipe x3 retried.
INVALID_TERMINAL_CONFIG
INVALID_UPDATE_PARAMETER
LOW_BATTERY Low battery, plug in the MP200.
MP200_COMMAND_TIMEOUT Command to MP200 timed out, transaction will abort, retry.
NO_BT_DEVICE No BT Device was found, check BT settings.
NO_DEVICES_FOUND
NO_ERROR
NOT_CONNECTED The device is not in the connected state to execute this function.
NOT_ENOUGH_SPACE_FOR_UPDATE Free up memory in the app cache directory.
TIMEOUT_GATEWAY Timeout has occurred between gateway.
TRANSACTION_CANCEL_BUTTON The transaction was cancelled by pressing the cancel button.
TRANSACTION_CARD_ERROR
TRANSACTION_CARD_REMOVED
TRANSACTION_INVALID_PIN Transaction was terminated because of an invalid PIN.
TRANSACTION_REQUESTS_CHANGE_INTERFACE This will also fire a delegate to change interface.
UNHANDLED_ERROR Unhandled Error, please report this.
UNHANDLED_EXCEPTION
UNHANDLED_EXCEPTION_CAUGHT
UPDATE_COMPLETE
UPDATE_FAILED An error occurred during the update process caused it to fail.
USB_CONNECTION_CLOSED USB Connection has been closed, reconnect.
USER_INPUT_EXCEPTION

onProgressBarUpdateAvailable

void onProgressBarUpdateAvailable(java.lang.String title,
                                  java.lang.String message,
                                  float percent)

The middleware provides an optional hook for the developer to implement a progress bar for display during longer operations such as a terminal firmware update.

Parameters

Param Description
title The suggested title of the progress bar
message The suggested message
percent The percentage (decimal 0 < 1) of the progress. -1 means the dialog should be cancelled, and -2 means there is no percentage available

onPromptForPartialAuth

void    onPromptForPartialAuth(java.lang.String amountAuthorized, HashMap<String,String>  tranResults)

Called when the transaction is partially authorized. Please Note: By default, partial authorization is not enabled. You must pass in "enablePartialAuth" as "true" when calling startTransaction(). If not enabled, transactions where the full auth amount is not available will be declined with the error "Insufficient Funds".

Returns string containing the amount that was authorized. It is the developers responsibility to prompt the customer for another payment method for the remaining amount, or to void:release the transaction.

Example

Log.d(TAG, "onPromptForPartialAuth() transaction partially approved for "+ amountAuthorized + " RefNum: " + tranResults.get("UMrefNum"));

// Tell the middleware you want to keep the transaction (onTransactionComplete will then be called)
ueMiddleware.returnPartialAuthDecision(true);

// Tell the middleware that you do not want to keep the partially approved transaction.   It will be
// voided and the funds returned to the customer
//ueMiddleware.returnPartialAuthDecision(false);

onReceiptReceived()

void onReceiptReceived(java.lang.String receipt)

Called back when the receipt is returned from the API. See the getReceipt method

Returns either an HTML or text string with the rendered receipt, depending on the receipt format.

onSeePhoneNFC

void onSeePhoneNFC(java.util.HashMap<java.lang.String,java.lang.String> tagData)

onStatusChanged

void onStatusChanged(java.lang.String message)

Called when the status of a transaction changes. This method is only meant to give a realtime status of the transaction in progress. onTransactionComplete should be used when writing transaction result logic.

Possible Values

Approved
Declined
Need Castles Update!
Authorizing issuer data with card
Need Castles Update!
Need Middleware Update!
Error: xxx
Connecting MP200 with xxx
Connected
Transaction is starting
Transaction started, please complete payment on the MP200 reader
Transaction cancel was sent to the MP200
Disconnected

onTransactionComplete

void onTransactionComplete(UEMTransactionResult transResults)

Called when the transaction processing has completed (either successfully or unsuccessfully). Passes a UEMTransactionResult object containing transaction result details.

onUpdateCheckResultsReceived

void onUpdateCheckResultsReceived(MIDDLEWARE_STATUS statusCheck)

Called back after checkIfUpdateNeeded() is called.

MIDDLEWARE_STATUS enum

Constant Description
CASTLES_NEEDS_UPDATE The device needs to be updated to match the current SDK version.
CHECKING
MIDDLEWARE_NEEDS_UPDATE The software installed on the terminal is newer than the middleware library. Developer must update the middleware SDK before using the connected device.
NEEDS_UPDATE
OK Castles MP200 device and middleware are both up to date.

onWaitingForCardRemoval

void onWaitingForCardRemoval()

Called when the user should be prompted to remove the card. The transaction will not proceed until the card is physically removed from the terminal.