Since app version 1.75.2 and AIDL library 1.28 it is possible to login/logout to the app directly from your system using the app2app API. It is also possible to unlock the terminal if it was already in use on another device.
Login to the app
Request
The input values are parameters that are contained as json in LoginEntity:
Mandatory attributes:
-
- username: email to log in to GP TOM
- password: password for the user to the GP TOM application
- terminalId: TID/ terminal id
Optional attributes:
- authCode: Authentication code that is used to release the occupied TID
void login(String username, String password, String terminalId)
LoginEntity(
/* username = */ username,
/* password = */ password,
/* terminalId = */ terminalId,
/* authCode = */ authCode
)
Response - states
The table below lists the statuses you may receive. A successful status is considered to be USER_LOGGED_IN or TID_ASSIGNED_AND_LOGGED_IN.
In case you receive a status code TID_RELEASE_REQUEST, you must call the login API again and this time fill in the parameter authCode, which is automatically sent to your email. The system then returns the status TID_ASSIGNED_AND_LOGGED_IN - the system assigns a TID to the user and logs them in.
The remaining states indicate the error condition and the reason for the error.
If the status is returned as part of the login PASSWORD_CHANGE_REQUIRED, this is the first login where you must first change your password.
Initial login to the application with password change
If you receive a status PASSWORD_CHANGE_REQUIRED, this is the first login of the user and a new password must be set. The new password is set in two steps.
void changePassword (String oldPass, String newPass, String authCode, boolean validationOnly)
In the first step, attributes are filled in the request:
- oldPass - initial user password
- newPass - new user password
- authCode - null
- validationOnly - true
This generates an authorization code that is sent to the email. As part of this step, the status is returned to you PASSWORD_PENDING_CONFIRMATION.
The authorization code must be used in the second step, where the attributes are filled in as follows:
- oldPass - initial user password
- newPass - new user password
- authCode - code sent to your email
- validationOnly - false
If the validation code is correct, the status is returned to you PASSWORD_CHANGED. At this point, the user's password has been changed and you can log them into the application.
Logging out of the app
Within the app2app API, it is also possible to unsubscribe a user from a selected TID via endpoint.
void logout()
After a successful logout, your status is returned to you USER_LOGGED_OUT. If the logout results in an error, the status is returned LOGOUT_FAILED.
Examples of use
Login
val intent = Intent(„com.globalpayments.atom.BIND_TO_LOGIN_SERVICE“) context.bindService(intent, connection, Context.BIND_AUTO_CREATE)
service?.registerCallback(callback)
val loginEntity = LoginEntity(
/* username = */ username,
/* password = */ password,
/* terminalId = */ terminalId,
/* authCode = */ authCode
)
service?.login(Gson().toJson(loginEntity))
Change password
// Step 1 - validation (request code)
val changePasswordValidationEntity = ChangePasswordEntity(
/* oldPass = */ currentPassword,
/* newPass = */ newPassword,
/* authCode = */ null,
/* validationOnly = */ true,
)
service?.changePassword(Gson().toJson(changePasswordValidationEntity))
// Step 2 - apply new password with code
val changePasswordEntity = ChangePasswordEntity(
/* oldPass = */ currentPassword,
/* newPass = */ newPassword,
/* authCode = */ authCode,
/* validationOnly = */ false,
)
service?.changePassword(Gson().toJson(changePasswordEntity))
Logout
service?.logout()
Status codes
EN: User successfully logged in.
EN: User successfully logged out.
EN: Login attempt failed.
EN: Logout attempt failed.
EN: Invalid username or password.
EN: Missing or invalid parameter.
EN: Terminal ID not linked to this user.
EN: Another TID/user is active on this device.
EN:Terminal successfully assigned and user logged in.
EN: Terminal ID not found.
EN: Terminal ID is inactive or disabled.
EN: No terminal selected for this session.
EN: If the Terminal ID is already occupied by someone else and no authorization Code is provided, the service will request an authorization code to release the TID.
EN: Wrong authCode for TID release was provided.
EN: User must change password before login.
EN: Confirmation code sent for password change.
EN: Password successfully changed.
EN: Password change attempt failed.