Sign in on the web¶

Target Audience: Developers, Stakeholders

Introduced in Payway 4.10.

For web sites, Payway runs the whole provider sign-in as a redirect flow — you add a "Continue with Google / Microsoft" button and handle the return. You never run the provider handshake, hold provider secrets, or manage a web-view cookie. A returning user comes back signed in through your normal SSO2 Landing; a first-time user comes back to a short "complete your account" step.

This builds on SSO2 — read its Identify / Landing model first. Social sign-in is an alternative to the password Authenticate step; everything else (the session, the Landing token, the ticket exchange) is the SSO2 you already implement.

Prerequisites¶

An SSO2 API client, with its RedirectUri set to your Landing page (as for normal SSO2).
Serve two extra return paths at that same origin (see the flow): /social/broker/complete and /social/broker/link-required.
Ask Adeprimo to configure the provider(s) for your organisation — provider client ids + secrets stay with Payway.

Flow¶

Send the user to Payway, which runs the provider sign-in and redirects back to one of three places depending on whether the identity is already known.

1. Start¶

Redirect the browser (a link/button, no server call) to:

https://sso.worldoftulo.com/social/{provider}/start?client_id=<your SSO2 client>&r=<continue URL>

{provider} is google / microsoft. r is where the user should end up afterwards.

2. Payway returns to one of three places¶

Outcome	Payway redirects to	What you do
resolved	your Landing: `{RedirectUri}?t=<session token>&r=<continue>`	nothing new — your existing SSO2 Landing validates `t`, exchanges the ticket, signs the user in
new	`{your origin}/social/broker/complete?st=<signup token>&vt=<prefill>&r=<continue>`	show your complete-account form, then create (step 3)
link_required	`{your origin}/social/broker/link-required?provider=&email=`	an account with that email exists but isn't linked — send the user to your normal login; they can connect the provider afterwards

:resolved is the whole point — a returning social user lands signed in with zero extra code beyond the Landing you already have. Only :new needs the extra step below.

st — an opaque signup token; pass it to create. Required.
vt — a token signed with your client secret carrying the user's email / name, for prefilling your form (optional to use; identity for the actual account is taken from st, never from the form).

3. Complete the account (`:new`)¶

Show your branded form (terms + any profile fields), then call the Payway API with your access token (scope /external/social/native/w):

POST https://backend.worldoftulo.com/external/social/create

{ "signup_token": "<st>", "sid": "<your SSO2 session id>", "terms_accepted": true, "first_name": "…" }

sid is your current SSO2 session id (from Identify) — Payway logs that session in for the new account.
Payway redeems st (identity comes from it, sso-verified), creates the account, and responds:

{ "account_id": "…", "session_established": true, "session_token": "<Landing token>" }

Response	What you do
`session_established: true`	redirect the user to your Landing with `?t=<session_token>&r=<continue>` — the same path as `:resolved`, and they're signed in
`session_established: false`	the account was still created; just send the user through sign-in again (now returns `:resolved`)

Terms are your responsibility — terms_accepted is required; the account isn't created without it.

Notes¶

Providers: Google and Microsoft. Apple is coming.
Login and register are the same button — Payway decides resolved vs new from the identity, so a returning user who clicks "sign up" is just signed in, and a new user who clicks "log in" is onboarded.
The create call is identical to the native one; web just adds sid to get the session back in the same call.