Every App2App session begins with a login, and a session can be invalidated by events outside your control. Getting this lifecycle right is the difference between an integration that "works on my machine" and one that survives real terminal usage — restarts, updates, and dropped connections. This guide explains when a session exists, what invalidates it, and how to keep one alive.
Why login comes first
Until you receive a successful login response, the payment application treats every request you send as unauthorized and silently ignores it. There is no error, no exception — your payment, status, or admin request simply produces no response. A developer who skips login spends hours wondering why nothing comes back.
So the rule is absolute: a successful RetailerLoginResponse opens the session, and nothing else works until it does.
viewModelScope.launch {
clientSDK.sendLoginRequest()
}
// Wait for SuccessRetailerLoginResponse in your interceptor before
// sending any other request.
What invalidates a session
A session is not permanent. Any of these events ends it, and your next request will be ignored until you log in again:
- The payment application is updated — a new version of the payment app resets the session.
- The payment application restarts — for any reason, including a device reboot.
- Your application restarts — your process being killed and recreated loses the session.
- The connection between the two apps is lost — the IPC binding dropped.
- You sent a logout request — an explicit
sendLogoutRequest()ends the session deliberately.
The unifying idea: a session ties together two specific running app instances. If either app restarts, or the link between them breaks, the session they shared no longer exists — even though your code is still holding an SDK object that looks ready to use.
When and how to re-login
You cannot reliably predict these events, so don't try to. Instead, structure your app so re-login is cheap and automatic:
Log in at startup. Trigger sendLoginRequest() when your application starts. This covers the "your app restarted" case for free.
Re-login when responses stop arriving. If you send a request and the expected response never comes (you can detect this with a timeout, e.g. via blocking mode), treat it as a possible lost session and re-login before retrying. A successful login response confirms the session is live again.
Re-login is idempotent in practice. Calling login when a session is already open is safe — you simply get another successful login response. So "log in whenever in doubt" is a valid strategy; you will not damage anything by logging in more often than strictly necessary.
A common, robust pattern: wrap your send logic so that if an operation times out, you automatically send a login, wait for success, then retry the original operation once. This recovers transparently from the most common invalidation cases without the user ever seeing a failure.
Logout is optional
You do not have to log out. A session persists until one of the invalidation events above occurs, so most integrations never call sendLogoutRequest() at all — they just let the session live.
Log out only when you specifically want to end the session deliberately — for example, when switching operators on a shared terminal, or to force a clean re-login. Logging out and back in is also a valid way to reset a session you suspect is in a bad state.
Related
- Quickstart — where login first appears, in context.
- How the message model works — why the login result arrives in the interceptor rather than from the call.
- Troubleshooting: requests are ignored / no response — the symptom a missing or lost login produces.
- Troubleshooting: login returns BUSY — the one login error that means "retry," not "fix your request."