Skip to main content
Correct cookie and WebView configuration is what keeps the SSO flow working without showing the authentication screen on every open.

​
Golden rule

All steps of the flow (pre-check, authentication, callback, opening) must run in the same WebView, with the same cookie jar.

​
A native WebView is required

The WebApp runs in a native WebView: WKWebView on iOS, WebView on Android, <webview> in Electron. The Consumer origin authenticates server-side, and the Paylead identity provider it redirects to serves its pages as a top-level document, which is what a native WebView provides. The Troubleshooting page covers the symptom an HTML <iframe> produces.

​
User-Agent identification (required)

The mobile app must keep the device’s default User-Agent and append a PayleadWebView suffix at the end.
Purpose: let Paylead reliably identify that the navigation comes from a WebView embedded in the mobile app
Example User-Agent
Do not replace the whole User-Agent. Replacing it breaks Paylead’s ability to identify the WebView and can lead to hard-to-diagnose support issues. Only append the PayleadWebView suffix.

​
Platform setup

Use the default (persistent) data store and reuse the same WebView instance.
Configuration
  • Reuse the same instance across opens.
  • Verify that the Paylead session cookies persist (Domain follows the environment, see server-side cookie attributes):
Cookie check
The Paylead session cookies are issued with the following attributes:
  • Domain = .paylead.eu in production, .sandbox.paylead.tech in sandbox (it follows the WebApp host, see Page URLs)
  • Path = /
  • HttpOnly = true
  • Secure = true
  • SameSite = None (required in a WebView)
Going further: the full list of cookies used by the WebApp (names, purpose, lifetimes) is documented on the Cookies page.

​
Opening URL parameters

The WebApp reads two optional URL parameters at startup, before the interface initialises. Pass them in the opening URL to control the display language and visual theme.

​
lang: Display language

Append ?lang=<code> to the opening URL. The WebApp selects a language using the following priority order:
  1. The lang URL parameter, if present.
  2. The language last saved in the user’s browser storage.
  3. The language detected from the browser’s Accept-Language header.
  4. French (fr) as the fallback.
The selected language is saved in the user’s browser. On subsequent opens without a lang parameter, the saved value applies.
Available languages depend on the theme configured for each client. An unsupported code falls back to French.

​
mode: Visual theme

Append ?mode=<value> to the opening URL. The parameter is applied on load and is not saved between sessions. Pass it on every open if the host app controls the visual theme.
Dark mode is only available for clients whose theme has been configured to support it. For other clients, the parameter is silently ignored and the WebApp displays in light mode.

​
Example

Production
Sandbox

​
What’s next

Cookies

The cookies the WebApp sets, their purpose, and scope.

Mobile Bridge

How the WebApp calls native capabilities from inside your WebView.