> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/psdk-latest/reference-material/code-labs/login-a-terminal.md). # Login a terminal {% columns %} {% column width="41.66666666666667%" %} :clock: 7 minutes reading time\ :calendar: Last updated: 23rd November, 2023 {% endcolumn %} {% column width="24.999999999999986%" %} {% endcolumn %} {% column %} ✅ Login ✅ PSDK DeviceInformation ✅ VHQ updates during Logged in ✅ Logout ✅ Recommendations for Login ✅ Exception handling {% endcolumn %} {% endcolumns %} {% stepper %} {% step %} ### Introduction This code lab describes steps for logging in to the terminal while developing PSDK based POS application. #### What you should already know * Setting up the device and development environment for developing PSDK application * Connecting to payment application #### What you'll need * Any Verifone device with necessary software loaded. * Internet connectivity {% endstep %} {% step %} ### Login After initialization is complete, the transaction manager can be retrieved. Once the transaction manager is obtained and bound, it’s time to login. * The PaymentSdk must be initialized to login and the CommerceListenerAdapter should be provided in the initialize APIs. * Please check the [TransactionManagerState](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanagerstate) before invoking Login API. * [Login API](https://docs.verifone.com/psdk-api-latest/android-java/index/transactionmanager#loginwithcredentials-logincredentials) can be used only when the TransactionManagerState is NOT\_LOGGED\_IN. * Use below API's to login to terminal // Check the statuscode appropriate for login request was accepted or rejected by PSDK Status statuscode = PaymentSdk.getTransactionManager().loginWithCredentials(null); // Configuration parameters can be enabled to handle password inputs at the POS side during login request for AGPA solutions. // Please refer below code snippet ```java HashMap config = new HashMap(); config.put(TransactionManager.PASSWORD_AT_POS_CAPABILITY, "1"); config.put(TransactionManager.INPUT_CONFIRMATION_CAPABILITY, "1"); //setCapabilities during login request to terminal. paymentSdk.getTransactionManager().setCapabilities(config); paymentSdk.getTransactionManager().loginWithCredentials(null); ``` * Handle the status of login and other error codes in the CommerceListenerAdapter ```java private final CommerceListenerAdapter mCommerceListenerAdapter = new CommerceListenerAdapter() { @Override public void handleTransactionEvent(TransactionEvent event) { if (TransactionEvent.LOGIN_COMPLETED.equals(event.getType())) { if (event.getStatus() == StatusCode.SUCCESS) { // Login success } else { // Handle failure by examining the status code and message. } } } } ``` #### Login with PIN Pairing(SCA) * PIN pairing feature is available only for terminals which are using SCA as payment solution. * During Login a dynamically generated PIN will be used to pair POS/ECR with the payment device/terminal. * Pairing with PIN registers POS/ECR to the device's list of trusted clients and establishes the data to be passed with each request that is necessary to determine if transactions originating from the POS are authentic * The code must be entered on the payment device/terminal in order to register the associated POS to the device. * Use below snippet to Display 4 digit code and login to terminal // Check the statuscode appropriatey for login request was accepted or rejected by PSDK ``` Status statuscode = paymentSdk.getTransactionManager().loginWithCredentials(null); ``` * Handle the status of login and other error codes in the CommerceListenerAdapter ```java private final CommerceListenerAdapter mCommerceListenerAdapter = new CommerceListenerAdapter() { @Override public void handleTransactionEvent(TransactionEvent event) { // Below snippet can be used to display the four digit code on the POS/ECR // which is received through transactionEvent if (TransactionEvent.TRANSACTION_NOTIFICATION.equals(event.getType())) { String message = event.getMessage(); // Display "message" on the ECR or POS so that User can know the code to enter on the terminal. } if (TransactionEvent.LOGIN_COMPLETED.equals(event.getType())) { if (event.getStatus() == StatusCode.SUCCESS) { // Login success } else { // Handle failure by examining the status code and message. } } } } ``` #### Multi Merchant Login **Overview** The Multi-Merchant function allows more than one merchants accept payments using the same terminal.This feature is commonly used in places like a dental office, doctors office or gyms, where there can be multiple operators practising in the same dwelling. For example you may have multiple doctors operating independently in the same office. At the point when the patient pays for the visit the receptionist will have the ability on the terminal to select which doctor the patient saw. The transaction process will be then be initiated and funds credited to the doctor that was selected on the terminal,reporting of the transactions performed will be displayed individually for each doctor. Merchants can be with any acquirer(i.e. merchants can bank with the any acquirer). This is available only with AGPA solutions **Login with multiple Merchants** * After initialization is complete, the transaction manager can be retrieved. * ECR/POS displays the list of merchants available to Login. * Only one Merchant should be choosen from the list for Login. * By default primary merchant will be highlighted for Login. * If you have to choose another merchant, you need to logout of the current merchant who is logged inn. * Code snippet below shows login to terminal with selected merchant from the merchant List. ```java // 1. Retrieve merchant list for selection ArrayList merchantConfig = null; private String record_id = null; private Merchant merchant = null; merchantConfig = paymentSdk.getDeviceInformation().getMerchantConfig(); for(Merchant merchant : merchantConfig) { // This is the reference ID which needs to be passed as part of the Login API to Login with this specific merchant String record_id = merchant.getRecordId(); // This is the name of the merchant which can be used for Display/selection in ECR/POS String name = merchant.getMerchantName(); } // 2. Perform merchant selection // 3. Once merchant is selected provide the record_id LoginCredentials Credentials = LoginCredentials.createWith2(null, null, null, record_id); // Check the status code appropriately for login request was accepted or rejected by PSDK Status statuscode = paymentSdk.getTransactionManager().loginWithCredentials(mCredentials); ``` * Handle the status of login and other error codes in the CommerceListenerAdapter ```java private final CommerceListenerAdapter mCommerceListenerAdapter = new CommerceListenerAdapter() { @Override public void handleTransactionEvent(TransactionEvent event) { if (TransactionEvent.LOGIN_COMPLETED.equals(event.getType())) { if (event.getStatus() == StatusCode.SUCCESS) { // Login success } else { // Handle failure by examining the status code and message. } } } }; ``` {% endstep %} {% step %} ### PSDK Device Information User-displayable information about the connected device and PSDK. The information provided through PSDKDeviceInformation class can be used to create a About screen in an POS application. About screen can contain details about the payment application version, PSDK version, Device Logical ID, Device Serial number etc. Code example below displays required details. ```java public void displayDeviceInformation(PaymentSdk paymentSdk) { PsdkDeviceInformation device = paymentSdk.getDeviceInformation(); StringBuilder info = null; if(device == null) return; info.append("IP Address : " + device.getAddress() + '\n' + "PaymentAppName : " + device.getPaymentAppName() + '\n' + "PaymentAppVersion : " + device.getPaymentAppVersion() + '\n' + "Device Serial Number : " + device.getSerialNumber() + '\n' + "Device State : " + device.getState() + '\n' + "Logical deviceID: " + device.getLogicalDeviceId()) ; } ``` {% endstep %} {% step %} ### VHQ updates during login VHQ updates happen to upgrade the terminal with the required parameters or to upgrade terminal to latest software version. VHQ Updates has to be handled in the POS application in the listener callback handleNotificationEvent based on the events triggered BEGIN\_MAINTENANCE and END\_MAINTENANCE by the terminal. These maintenance events are applicable ony for AGPA solution. Please refer below code snippet for handling the events ```java public void handleNotificationEvent(NotificationEvent event) { if(event.getNotificationType().equals("BEGIN_MAINTENANCE")) { // VHQ update started, Display alert message to user // PSDK will be logged out automatically. } else if(event.getNotificationType().equals("END_MAINTENANCE")) { // VHQ update Ended // Request for PSDK Login again as PSDK is logged out } } ``` {% endstep %} {% step %} ### Logout If the merchant or cashier wants to log out call TransactionManager.logout(). This makes Payment SDK to logout of the payment terminal. * Before calling Logout,the paymentSdk must be initialized and should be logged in already * The listener provided during initialize will receive the event for logout ```java //Check the statuscode appropriatey for login request was accepted or rejected by PSDK Status statuscode = paymentSdk.getTransactionManager().logout(); private final CommerceListenerAdapter mCommerceListenerAdapter = new CommerceListenerAdapter() { @Override public TransactionEventResponse handleTransactionEvent(TransactionEvent event) { if (TransactionEvent.LOGOUT_COMPLETED.equals(event.getType())) { if (event.getStatus() == StatusCode.SUCCESS) { // Logout success } else { // Handle failure by examining the status code and message. } } } } ``` {% endstep %} {% step %} ### Recommendation for Login #### For single merchant scenario * We recommend initialization followed by a one time Login on application bootup until application shut down to speed up the flow. * Login is required per instance of PSDK and not per transaction. * Prefer One time login with one time logout and teardown at the end when required to close the ECR/POS application. * During VHQ update begin maintenance and end maintenance events will be sent accordingly. * PSDK logs out automatically when maintenance begins, after maintenance ends PSDK should be logged in again. {% endstep %} {% step %} ### Exception handling #### StatusCode.COMMAND\_TIMED\_OUT (-25) * This occurs when a response was not received from the terminal in time. **Solution** * Try teardown, init and login again * If the issue persists restart the terminal * Please contact helpdesk if the issue is not solved with restart of the terminal. #### StatusCode.DEVICE\_ERROR (-8) Device out of order * General Error **Solution** * Please reboot the terminal and if reboot doesn't help please contact verifone help desk. #### StatusCode.DEVICE\_CONNECTION\_LOST (-5) * This occurs when Connection to the payment terminal is lost. **Solution** * Please refer initialization code labs to handle this exception condition programatically. (OR) * Please reboot the terminal to recover the state of PSDK and Payment application. {% endstep %} {% endstepper %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verifone.com/psdk-latest/reference-material/code-labs/login-a-terminal.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.