TransactionManager

public class TransactionManager

The service handle for performing transactions. Generally, only the static getTransactionManager methods should be used to obtain an instance of this class, ensuring that the proper service and binder are wrapped by this class.

Fields

DEBUG_DELAY_IN_MS_KEY

public static final String DEBUG_DELAY_IN_MS_KEY

The debug parameters key to set how long the service should arbitrarily delay the response. This is particularly helpful when testing in STUB mode for some use cases.

DEBUG_FAIL_EVENT_TYPES_KEY

public static final String DEBUG_FAIL_EVENT_TYPES_KEY

The debug parameters key to set which types of events should be arbitrarily returned as failed. This is particularly helpful when testing in STUB mode for some use cases.

DEBUG_MODE_KEY

public static final String DEBUG_MODE_KEY

Configures the debug mode of the device. Must be one of com.verifone.commerce.CommerceConstants.MODE_DEVICE, com.verifone.commerce.CommerceConstants.MODE_SIMULATOR, com.verifone.commerce.CommerceConstants.MODE_STUBS_DEBUG, or 0 to remove any preference.

DEBUG_MODE_STUB_EVENT_KEY

public static final String DEBUG_MODE_STUB_EVENT_KEY

Configure the debug mode to return stub events for testing purposes.

DELAYED_CHARGE_CAPABILITY

public static final String DELAYED_CHARGE_CAPABILITY

If capable, the terminal can do delayed charge transactions.

DEVICE_APPLICATION_CERTIFICATION_CODE_KEY

public static final String DEVICE_APPLICATION_CERTIFICATION_CODE_KEY

Allows the calling POS application to provide a certification code, sometimes used for certification or to meet other requirements.

DEVICE_APPLICATION_MANUFACTURER_ID_KEY

public static final String DEVICE_APPLICATION_MANUFACTURER_ID_KEY

Allows the calling POS application to provide a manufacturer ID, sometimes used for certification or to meet other requirements.

DEVICE_APPLICATION_NAME_KEY

public static final String DEVICE_APPLICATION_NAME_KEY

Allows the calling POS application to provide an application name, sometimes used for certification or to meet other requirements.

DEVICE_APPLICATION_VERSION_KEY

public static final String DEVICE_APPLICATION_VERSION_KEY

Allows the calling POS application to provide an application version, sometimes used for certification or to meet other requirements.

DEVICE_ENCRYPTION_KEY

public static final String DEVICE_ENCRYPTION_KEY

The device parameters key to use encryption on messages. Set this to the #ENABLED_VALUE to enable. This defaults to no fallback to non-encrypted mode if encryption fails. Set to #ENABLED_FALLBACK_VALUE to enable with fallback to non-encrypted mode. Please note that this only applies to SCI terminals.

DEVICE_HOST_AUTHENTICATION_ENABLED

public static final String DEVICE_HOST_AUTHENTICATION_ENABLED

This indicates that the terminal is expected to send authentication request events

DEVICE_HOST_AUTHENTICATION_KEY

public static final String DEVICE_HOST_AUTHENTICATION_KEY

Informs the payment terminal that the POS application should or should not perform the host authentication. Terminal must be configured for this or initialization will fail.

DEVICE_LISTEN_KEY

public static final String DEVICE_LISTEN_KEY

The device parameters key to require the POS to listen for connections from the payment terminal. The default is to connect outwards towards the terminal. Set this to the #ENABLED_VALUE to enable.

DEVICE_LOGIN_TIMEOUT_KEY

public static final String DEVICE_LOGIN_TIMEOUT_KEY

The device parameters key to set a login timeout for the device. Please note that this does not apply to SCI terminals.

DEVICE_PORT_KEY

public static final String DEVICE_PORT_KEY

The device parameters key to set which port to use when connecting to the payment application on the payment terminal. This is useful if integrating with a payment application that uses a non-standard port for the messages, and should only be set in specific regions.

DEVICE_PROTOCOL_CRS

public static final String DEVICE_PROTOCOL_CRS

The protocol value for CRS.

DEVICE_PROTOCOL_EPAS

public static final String DEVICE_PROTOCOL_EPAS

The protocol value when communicating using EPAS, supported for multiple regions.

DEVICE_PROTOCOL_IL

public static final String DEVICE_PROTOCOL_IL

The protocol value for Israel.

DEVICE_PROTOCOL_KEY

public static final String DEVICE_PROTOCOL_KEY

The device parameters key to set if specifying a specific protocol to use when communicating with the payment application. This is generally discovered, though some regions may require this parameter to be set explicitly.

DEVICE_PROTOCOL_LOCAL

public static final String DEVICE_PROTOCOL_LOCAL

The protocol value for the CM5 Payment App when running locally.

DEVICE_PROTOCOL_NEXO

public static final String DEVICE_PROTOCOL_NEXO

The protocol value when communicating using NEXO, supported for multiple regions. EPAS changed its name to NEXO when moving to version 3.0.

DEVICE_PROTOCOL_SCI

public static final String DEVICE_PROTOCOL_SCI

The protocol value when communicating using the general SCI protocol, without region-specific modifications.

DEVICE_PROTOCOL_SDI

public static final String DEVICE_PROTOCOL_SDI

The protocol value for SDI.

DEVICE_SUPPORTED_CP_TRIGGERS_KEY

public static final String DEVICE_SUPPORTED_CP_TRIGGERS_KEY

Allows the calling POS application to define which CP Triggers it can support. When passed, this expects an array of the corresponding event types, e.g., if Amount Adjustment is supported, include the value from AmountAdjustedEvent.TYPE in the array. Refer to enableCpTriggerHandling() for more information.

DEVICE_TRAINING_MODE_KEY

public static final String DEVICE_TRAINING_MODE_KEY

The device parameters key to set training mode for the device. This should generally be left unset, unless testing in the simulator or some other environment. Set this to the #ENABLED_VALUE to enable.

ENABLED_FALLBACK_VALUE

public static final String ENABLED_FALLBACK_VALUE

The value used when enabling an extended mode of operation but allowing fallback to the default mode of operation if the extended mode fails, example is #DEVICE_ENCRYPTION_KEY.

ENABLED_VALUE

public static final String ENABLED_VALUE

The value used when enabling a specific key. Generally disabling that value can be performed by leaving it unset or setting it to an empty value.

GRATUITY_ADJUSTMENT_CAPABILITY

public static final String GRATUITY_ADJUSTMENT_CAPABILITY

If capable, the terminal can adjust the gratuity amount of a payment which is already captured / completed.

INPUT_CONFIRMATION_CAPABILITY

public static final String INPUT_CONFIRMATION_CAPABILITY

If capable, the POS will support input confirmation

PASSWORD_AT_POS_CAPABILITY

public static final String PASSWORD_AT_POS_CAPABILITY

If capable, the POS will support password at POS

SESSION_CLOSED

public static final int SESSION_CLOSED

Please use STATE_NOT_LOGGED_IN.

SESSION_OPEN

public static final int SESSION_OPEN

Please use STATE_LOGGED_IN.

SESSION_SERVICE_CONNECTING

public static final int SESSION_SERVICE_CONNECTING

Please use STATE_LOGGING_IN.

TRANSACTION_PROCESSING

public static final int TRANSACTION_PROCESSING

Please use STATE_SESSION_OPEN.

VHQ_DEVICE_ID_KEY

public static final String VHQ_DEVICE_ID_KEY

Forces setup of device ID during SCA protocol negotiation

Methods

abort

public Status abort()

Aborts the most recent command, but does not reset the session unless aborting the startSession call. If a new invoice ID is needed, or a new cart, end the session or purge the basket, respectively.

Return:

A status object indicating if the command was issued properly. Events regarding the effect of the command are sent to the registered listener(s).

abort2

public Status abort2(DisplayOutput message)

Abort with a message to the Customer

Parameters:

  • message – com.verifone.commerce.entities.DisplayOutput

Return:

A status object indicating if the command was issued properly. Events regarding the effect of the command are sent to the registered listener(s).

activateStoredValueCard

public Status activateStoredValueCard(Payment payment)

Activates a stored value card. Fires a StoredValueCardEvent to the listeners.

Parameters:

addGeneralListener

public boolean addGeneralListener(CommerceListener listener)

Adds a listener for events that occur without an active session. For example, a com.verifone.commerce.payment.reports.ReconciliationEvent is sent outside of a session, as the reconciliation commands are not issued within the context of a session. Returns success if the listener was added or is already registered, and false if the listener was not registered. Deprecated on 2020-06-01.

addSessionListener

public boolean addSessionListener(CommerceListener listener)

Allows adding new listeners for session events.

Parameters:

  • listener – A listener for session events. There may be more listeners added, but there must always be at least one registered.

Return:

True if the listener was not already registered. Deprecated on 2020-06-01.

deactivateStoredValueCard

public Status deactivateStoredValueCard(Payment payment)

Deactivate the stored value card. Refer to activateStoredValueCard(Payment).

Parameters:

  • payment – If this is null or Payment.getRequestedPaymentAmount() is not set,

enableReader

public void enableReader(ReaderParameters parameters)

Activates the Contact, Contactless, and Mag-stripe readers on the device. The listener receives a CardInformationReceivedEvent if the customer presents something.

endSession

public boolean endSession()

Ends a session. This releases the terminal reservation for this application, allowing other applications to open sessions. This sends a stop message to the terminal to exit the terminal application if launched by this app. The internal service may send this on behalf of this POS application if this application crashes or exits without closing the session. This method should be called prior to the release of the final reference to the Commerce Manager. Once the session is ended, references to any registered listeners are removed once the Session End event is properly reported.

Return:

True if the session end message was submitted successfully. The listener will receive the end event if the session is ended properly, or will receive the appropriate message if the session is not able to be ended.

getBasketManager

public BasketManager getBasketManager()

The method to get an appropriate concrete implementation of the Basket Manager.

Return:

A concrete implementation of the basket manager.

getDeviceInformation

public Status getDeviceInformation()

Deprecated on 2020-06-15. Please use PaymentSdk.getDeviceInformation() instead.

getListeners

public ArrayList<CommerceListener> getListeners()

Get the set of currently registered listeners.

Return:

The set of ICommerceListeners that are currently registered. This set is independent of the internal set, and should only used as a reference for the current listeners, and not be expected to update with the addition or removal of listeners. Deprecated on 2020-06-01.

getReportManager

public ReportManager getReportManager()

The method to get an appropriate concrete implementation of the Report Manager.

Return:

A concrete implementation of the report manager.

getState

public TransactionManagerState getState()

Immediately returns the current state of the communication between the POS device and the payment terminal. This may change based on messages already sent but not yet handled.

getStoredValueCardBalance

public Status getStoredValueCardBalance(StoredValueCardInformation cardInformation)

Retrieves the current balance for a stored value card. Fires a StoredValueCardEvent to the listeners.

Parameters:

  • cardInformation – Optionally pass card information to use when fetching the balance. If optional parameter is not supplied the balance request will not be restricted to particular card type. Use StoredValueCardInformation.setType(String) to define the type of card for which we are checking the balance. Use StoredValueCardInformation.setCardPan(String) or StoredValueCardInformation.setCardToken(String) to pass in the information about the card to be checked.

getTransaction

public Transaction getTransaction()

Gets the most recent transaction. This transaction may still be in progress, and should be treated accordingly.

Return:

The most recent transaction.

hasCollectedCardData

public boolean hasCollectedCardData()

Checks if PSDK has a card acquisition reference saved Returns true if saved, or false if not.

isCapable

public boolean isCapable(String capability)

Checks if the current terminal implementation allows handling of a specific command, as listed in the constants above. Returns true if the interface can handle the command, or false if not.

loadStoredValueCard

public Status loadStoredValueCard(Payment payment)

Loads an amount on to an existing stored value card. Refer to activateStoredValueCard(Payment).

login

public Status login(CommerceListener listener, String userId, String password, String shiftNumber)

Logs in through the payment terminal, possibly synchronizing information from the host to the terminal and performing other similar setup/configuration steps. Also used for following transactions, allowing them to be tracked by user and/or according to the shift. Notifies all general listeners with a TransactionEvent of type TransactionEvent.LOGIN_COMPLETED. Use the status from this event to determine the success or failure of the request, using any of the constant error codes to determine the nature of the failure if not successful.

Parameters:

  • listener – Optional. A commerce listener that is attached to the general events.

  • userId – Optional. The username / operator ID of the cashier, used by the payment terminal or the host to group transactions together. If the host requires login by a specific known cashier/user, then this field is required, but normally this field is optional and only used for reporting and transaction queries.

  • password – Optional. Only required when the host must authenticate the current operator, otherwise this should be unset.

  • shiftNumber: – Optional. The current shift ID, sometimes used by the payment terminal or the host to group transactions together. This can be used later to query the transactions performed during this shift.

Return:

A status code. Returns success or failure of sending the request to the terminal. The actual result will be sent using the notification described earlier. Deprecated on 2020-06-01. Please use loginWithCredentials.

loginWithCredentials

public Status loginWithCredentials(LoginCredentials credentials)

Logs in through the payment terminal, possibly synchronizing information from the host to the terminal and performing other similar setup/configuration steps. Also used for following transactions, allowing them to be tracked by user and/or according to the shift. Notifies all general listeners with a TransactionEvent of type TransactionEvent.LOGIN_COMPLETED. Use the status from this event to determine the success or failure of the request, using any of the constant error codes to determine the nature of the failure if not successful.

Parameters:

  • LoginCredentials. –

Return:

A status code. Returns success or failure of sending the request to the terminal. The actual result will be sent using the notification described earlier.

logout

public Status logout()

Logs out through the payment terminal. This must always be used in conjunction with the login(CommerceListener,String,String,String) method. Returns the success or failure of sending the request to the terminal. The actual result will be sent to the general listeners with a TransactionEvent of type TransactionEvent.LOGOUT_COMPLETED. Use the status from this event to determine the success or failure of the request, using any of the constant error codes to determine the nature of the failure if not successful.

performDeviceManagement

public Status performDeviceManagement(DeviceManagementAction deviceManagementAction)

Perform device management action

performDeviceManagementCommand

public Status performDeviceManagementCommand(DeviceManagementCommand deviceManagementCommand)

Perform device management action with parameters

performEncryption

public Status performEncryption(EncryptionRequest encryptionToPerform)

Encrypt an item. See EncryptionRequest for more information.

performPin

public Status performPin(PinRequest pinRequest)

Perform PIN processing action

presentCustomerContent

public Status presentCustomerContent(String content, ContentType contentType, int minimumDisplayTime)

Presents either HTML or Text content to the customer using the customer-facing display. The content will be displayed until some other request is sent to display different content, or something on the device controlling the display decides that it must be updated, depending on the minimum display time.

Parameters:

  • content – The actual content to be presented.

  • contentType – The type of content to be presented, either ContentType.HTML or ContentType.TEXT

  • minimumDisplayTime – The minimum amount of time to display this content before the customer display can update itself to different content. Any following request, such as starting a payment or presenting additional content, will override the current displayed content regardless of this time, but the device controlling the display will not update it without a specific command before this time is expired. Defaults to 0. Values less than 0 are undefined.

Return:

The status of the request to the terminal. There is no other event returned to the caller.

presentCustomerContent2

public Status presentCustomerContent2(String content, ContentType contentType, int minimumDisplayTime, DisplayType displayType)

See presentCustomerContent with new parameter displayType.

Parameters:

presentUserOptions

public Status presentUserOptions(String header, ArrayList<String> buttonLabels)

Presents button options to the user and relaying the selected option back to the listener. This does not automatically include a back/exit/cancel option. EPAS reference 4.5.3 Input, 4.5.3.1 Processing Overview. For #1 Reading Confirmation (“GetAnyKey”), pass a header with a null or empty array of button labels. For #2 Asks a Question (“GetConfirmation”, “SiteManager”), pass two buttons with the appropriate values. For #4 Select an item in a Menu (“GetMenuEntry”), pass any number of buttons. SCA reference Customer Buttons. Automatically breaks the header into the appropriate maximum lengths using word wrapping. Supports up to 6 header lines followed by 6 buttons.

Parameters:

  • header – The message to be displayed to the user, preferably providing context for the user to select the correct option. This is optional.

  • buttonLabels – An array of button labels presented to the user. The corresponding event returns the index of the button selected based on this array. This is required.

Return:

The status of the request to the payment terminal. The selected option is returned in the appropriate UserInputEvent.Values.getSelectedIndices().

print

public Status print(String document, ContentType contentType, ReceiptType receiptType, DeliveryMethod receiptDeliveryMethod, String deliveryAddress)

Based on DeliveryMethod settings and terminal capabilities, print the document on the terminal or send through SMS/Email.

Parameters:

  • document – The document to be printed on the terminal.

  • contentType – ContentType.

  • receiptType – optional. ReceiptType.

  • receiptDeliveryMethod – optional. DeliveryMethod.

  • deliveryAddress – optional.

Return:

The status of the print request to the terminal.

processRefund

public Status processRefund(Payment payment)

Attempts to refund the specific payment. If multiple payments were accepted in a transaction, this method will need to be called individually for each payment, allowing the listener(s) to better respond to the related events.

Parameters:

  • payment – The payment to refund.

Return:

The status object indicating if the refund command was issued properly. Events regarding the refund itself are sent to the registered listener(s).

processVoid

public Status processVoid(Payment payment)

Attempts to void the transaction.

Parameters:

  • payment – The payment to void.

Return:

A status object indicating if the void command was issued properly. Events regarding the void itself are sent to the registered listener(s).

removeGeneralListener

public boolean removeGeneralListener(CommerceListener listener)

Removes a listener for events that occur without an active session. Refer to addGeneralListener(CommerceListener) for more information. Returns success if the listener was removed or is not registered, and false if the listener was not able to be removed. Deprecated on 2020-06-01.

removeSessionListener

public boolean removeSessionListener(CommerceListener listener)

Removes a session listener. The last session listener cannot be removed through this method, as there must always be a listener until the session ends.

Parameters:

  • listener – A registered listener for the session events.

Return:

True if the listener exists. Deprecated on 2020-06-01.

reprintReceipt

public Status reprintReceipt(Payment payment, ReceiptType receiptType, DeliveryMethod receiptDeliveryMethod, String deliveryAddress)

Convenient method to reprint the customer receipt using com.verifone.commerce.entities.Receipt.DELIVERY_METHOD_PRINT.

requestCardData

public Status requestCardData(String message, ArrayList<PresentationMethod> presentationMethodNames)

Request information about card data from terminal

Parameters:

  • message – The message to be displayed in terminal

  • inputMethods – array of com.verifone.commerce.entities.CardInformation.PresentationMethod, optional

Return:

The status of the request to the terminal.

requestCardData2

public Status requestCardData2(CardAcquisitionRequest cardAcquisitionRequest)

Request information about card data from terminal

Parameters:

  • cardAcquisitionRequest – com.verifone.commerce.entities.CardAcquisitionRequest

requestCardDataWithAids

public Status requestCardDataWithAids(String message, ArrayList<PresentationMethod> presentationMethodNames, ArrayList<String> aidList)

Request information about card data from terminal

Parameters:

  • message – The message to be displayed in terminal

  • inputMethods – array of com.verifone.commerce.entities.CardInformation.PresentationMethod,

  • list – of AID(Application ID) strings.

Return:

The status of the request to the terminal.

requestCardToken

public Status requestCardToken()

Asks the terminal to collect card information from the user and return a token for the information. In some regions, this can also be called after the payment has started to generate a token for the card that is currently being used for payment, instead of requiring a separate card entry action.

Return:

The status of the request to the terminal.

requestDeviceVitals

public Status requestDeviceVitals()

Request device vitals. DeviceVitals.

requestUserInput

public Status requestUserInput(InputType inputType, String message, String defaultValue)

Presents the user with a screen to collect information, specially formatting the keyboard and display based on the input type.

Parameters:

  • inputType – The type of input requested from the user. This is required.

  • message – The message to display to the user to provide context for the input. This is optional.

  • defaultValue – The default value for the input field. This is optional.

Return:

The status of the request to the payment terminal. The input value is returned in the appropriate UserInputEvent.

requestUserInput2

public Status requestUserInput2(RequestParameters params)

Presents the user with a screen to collect information, customizing the process based on RequestParameters

Parameters:

respondToHostAuthorization

public Status respondToHostAuthorization(String authorizationCode, HostDecisionType hostDecision, HashMap<String, String> emvTags, Decimal authAmount)

Sends back the response to a host authorization request.

Parameters:

  • authorizationCode – The Authorization code sent from the host.

  • hostDecision – Enum representing the Hosts decision for the request see HostDecisionType.

  • emvTags – EMV Tags to be sent to the POI deviceAuthAmount.

  • authAmount – The amount which has been authorized, including, if applicable, the approved cashback amount. Optional. Note: When this parameter is omitted but the transaction has been authorized, the result will be an partial authorization with a zero amount.

respondToHostFinalizeTransaction

public Status respondToHostFinalizeTransaction(String authorizationCode, HostDecisionType hostDecision, HashMap<String, String> emvTags, Decimal authAmount)

Sends back the response to a finalize transaction request

Parameters:

  • authorizationCode – The Authorization code sent from the host.

  • hostDecision – Enum representing the Hosts decision for the request see HostDecisionType.

  • emvTags – EMV Tags to be sent to the POI deviceAuthAmount.

  • authAmount – The amount which has been authorized, including, if applicable, the approved cashback amount. Optional. Note: When this parameter is omitted but the transaction has been authorized, the result will be an partial authorization with a zero amount.

resumeSession

public boolean resumeSession(CommerceListener listener, String sessionId)

Not currently supported. Attempts to resume a session in the case of a Session Closed event or an application crash. If it is not possible to resume, this may return immediately or may send a Session Resume Failed event to the listener.

Parameters:

  • listener – The first listener for the session events. There may be more listeners added, but there must always be at least one registered. @return True if the session opening message was submitted successfully. The listener will receive the start event if the session is created, or will receive the appropriate message if the session is not able to be created. Deprecated on 2020-06-01.

sendEventResponse

public Status sendEventResponse(CommerceResponse response)

Sends back the response to a specific event, allowing the POS to asynchronously respond to received events.

sendHostResponse

public Status sendHostResponse(HostResponse hostResponse)

Sends back the response to either a host authorization request or a finalize transaction request. See HostResponse

sendInputResponse

public Status sendInputResponse(UserInputEventResponse userInputEventResponse)

Returns the information requested from the terminal, such as updating configuration options or performing similar administrative tasks.

setCapabilities

public void setCapabilities(HashMap<String, String> config)

Set optional capabilities that the POS will support

setDebugMode

public void setDebugMode(int mode)

Allows the service to be set to a different mode, allowing automated testing and other similar tasks.

Parameters:

  • mode – One of the debug modes from the CommerceConstants.

startPayment

public Status startPayment(Payment payment)

Starts a payment for the current transaction.

Parameters:

startSession

public boolean startSession(CommerceListener listener, Transaction transaction)

Deprecated on 2020-06-01. Please use startSession2.

startSession2

public boolean startSession2(Transaction transaction)

Starts a session. This reserves the terminal for this application, preventing conflicts with other apps. A listener of CommerceListener2 should be added before calling this API.

Parameters:

  • transaction – The transaction for this session. Please note that this parameter may be null if a transaction is not required for the session.

Return:

True if the session opening message was submitted successfully. The SessionListener will receive the start event if the session is created, or will receive the appropriate message if the session is not able to be created.

unloadStoredValueCard

public Status unloadStoredValueCard(Payment payment)

Removes the requested amount from the stored value card. Refer to activateStoredValueCard(Payment).

Parameters:

  • payment – If this is null or Payment.getRequestedPaymentAmount() is not set, The entire available balance will be removed from the card, sometimes requiring a balance inquiry before performing the unload. If Payment.getRequestedPaymentAmount() is set to an amount, attempts to remove that amount from the card.