Skip to main content
The goal is a smooth SSO integration between your bank app and the Paylead WebApp, ensuring:
  • correct cookie and session handling between the WebView and the IdPs,
  • no spurious redirects to the authentication screen,
  • and silent re-authentication as long as the IdP sessions are valid.

​
Authentication flow architecture

​
Actors

Paylead WebApp

The end-user interface.

Paylead IdP

The Paylead Identity Provider. Manages the WebApp session (the Paylead session cookie).

Partner IdP

Authenticates the bank user. OIDC delegation flows from the Partner IdP to the Paylead IdP.
The Consumer URL for your Program (https://consumer-<reference_pm>.paylead.eu) is provided by your Paylead contact.

​
Flow at a glance

1

Open the WebApp

The user opens the WebApp from the partner app.
2

Query the Paylead IdP

The WebApp queries the Paylead IdP.
3

Delegate to the Partner IdP

The Paylead IdP redirects to the Partner IdP if needed.
4

Authenticate the user

The Partner IdP authenticates the user.
5

Create the Paylead session

The Paylead IdP creates a Paylead session and redirects back to the WebApp.
6

Open the authenticated WebApp

The WebApp opens for the user with an active session.

​
Session management

​
Session types

LevelIdPLifetimeImpact
Paylead SSOPaylead IdP30 min idle / 10h max (default)Manages the SSO authentication
Partner IdPPartnerVariableAuthenticates the bank user
  • Paylead IdP (configurable):
    • SSO Session Idle: 30 min
    • SSO Session Max: 10h
  • Partner IdP: must be ≥ the Paylead IdP session to avoid showing the authentication screen after a redirect to /authorize.
The idle session timer counts from the moment the session stops being active, not from the moment it was created.

​
Expected behaviour by session state

Paylead IdP sessionPartner IdP sessionResult
✅ Valid✅ ValidDirect access
⚙️ Expired✅ ValidSilent re-authentication
⚠️ Expired⚠️ ExpiredPartner IdP auth screen
⚠️ Valid⚠️ ExpiredPartner IdP auth screen
❌ Cookies lostn/aRedirect to /auth

​
Access check & re-authentication

​
Step 1: Pre-check before opening

Before opening the WebApp, perform a GET without automatically following redirects: 
GET https://consumer-<reference_pm>.paylead.eu
Expected handling:
  • If the response is 2xx → the session is considered valid, open the WebApp directly.
  • If the response is a 3xx redirect and the Location header points to /auth (the Paylead IdP auth route) → start the full SSO flow (Step 2).
The response of this GET is also useful for what follows, as it carries:
  • state: lets you send the user back to the page they originally requested.
  • nonce: lets you bind the session to the token we create.

​
Step 2: Web authentication

1

Follow every redirect

Follow all redirects present in the Location header.
2

Keep all cookies

Keep every cookie (Set-Cookie) received at each step.
3

Validate the final redirect

Check that the last redirect contains scope, state, nonce, client_id and redirect_uri. Otherwise, clear the cookies for the Paylead domain and retry once.
4

Generate the authorization code

Generate the authorization_code via the custom Paylead IdP plugin.
5

Build the callback URL

redirect_uri?code=<authorization_code>&state=<state>
6

Call the callback

Perform a GET on this callback, following redirects and storing cookies.
7

Open the WebApp

Open the WebApp with the updated cookies.

​
What’s next

WebView configuration

Cookie and WebView setup required for the flow above to work reliably.

Troubleshooting

Diagnose a recurring auth screen, lost cookies, or hard-to-trace behaviour.