SSO Widgets
Learn how to use authentication in your journey.
Overview
Embed the SSO Widget
The SSO widget can be embedded onto your site using an iFrame. It alllows users to create credentials and to log into their customer credit account. The widget can be used along different customer journeys.
Below is an example of how to add the widget to your website:
Javascript
1<iframe src="https://id.newdaytechnology.com/<brand>/<endpoint>?token=<token>&redirect_uri=<redirect_uri>&sessionId=<sessionId>&context=<context>&user_name=<user_name>"></iframe>The widget accepts the following parameters in the iFrame source url:
| Parameter | Description |
|---|---|
brand(required) | A string in lowercased format that represents your brand name. |
endpoint(required) | Either "credentials" or "login" depending on the journey you wish to display. |
token(required for credentials creation) | A JWT token returned from the Create Application endpoint, once the user has successfully completed an eligibility check. The token is valid for 10 minutes from creation. |
context(optional) | Identifies the journey type as either "checkout" or "nocheckout" (further details in the next sections). Defaults to "checkout" if not provided. |
redirect_uri(required) | Specifies where you want the user to be redirected in some scenarios (further details in the next sections). |
sessionId(required) | A unique identifier mapping a session to a user. |
user_name(optional) | The username input field default value in the create credentials journey. |
When the user successfully creates credentials or logs in, the widget posts serialized data back to the redirect_uri provided in the query string. The data returned by the widget must be deserialized before usage.
Data deserialisation example
Code Sample
C#
1var payload = JsonConvert.DeserializeObject<Object>(formData["payload"])You must provide NewDay with a list of URLs where you intend to embed the widget, as well as the redirect URIs you will wish to use for redirect purposes. These will be added in our CORS policy whitelist.
Create Credentials
A user can create credentials during a purchase checkout journey or in any other scenario (hereby referred as a non-checkout journey). The context parameter specified in the iFrame query string defines whether the user is either in one or the other journey types.
By default, the user is in a purchase checkout journey unless nocheckout is specified.
There are differences in the user experience between the two journey types:
- Purchase checkout journey:
Page titles are displayed;
If the user tries to create an account with a username that is already taken, an alert message will be displayed, with a link to be redirected to the log in page; - Non-checkout journey:
Page titles are not displayed;
If the user tries to create an account with a username that is already taken, an alert message will be displayed but no link to be redirected to the log in page will be provided;
Copy and paste the below code into your website where you want to display the create credentials journey.
Code Sample
Javascript
1<iframe src="https://id.newdaytechnology.com/<brand>/credentials?sessionId=<sessionId>&redirect_uri=<redirect_uri>&token=<token>"></iframe>Successful response
When credentials are successfully created, the widget posts back the following data to the redirect_uri provided in the query string:
Code Sample
Node + Request
1{
2 "data": {
3 "idToken": "{{id_token}}"
4 },
5 "isSuccessful": true,
6 "message": null,
7 "errorMessages": {
8 "status": null,
9 "errors": []
10 }
11}Unsuccessful response - Token expired
The widget does not handle errors related to invalid tokens. Instead, it posts back the below data and redirect the user to the redirect_uri present in the query string. A refreshed token can be retrieved from the Refresh Token endpoint.
The widget can then be re-called by passing the new token in the URL parameters.
Code Sample
Node + Request
1{
2 "status": 401,
3 "errorMessage": "Token expired"
4}}Log in
Copy and paste the code below code into your website where you want the log in journey to be displayed.
Javascript
1 <iframe src="https://id.newdaytechnology.com/<brand>/login?sessionId=<sessionId>&redirect_uri=<redirect_uri>"></iframe>Successful response
When a user successfully logs in, the widget posts the below data back to the redirect_uri provided in the query string:
Code Sample
Node + Request
1{
2 "hashedUserId": "{{hashed_user_id}}",
3 "identityToken": “",
4 "expiresIn": 600,
5 "tokenType": "Bearer",
6 "refreshToken": "{{refresh_token}}",
7 "correlationId": "string",
8 "isAccountLocked": false,
9 "remainingAttempts": null,
10 "success": true
11}Unsuccessful response - Account locked
Users can attempt to log in with incorrect credentials up to 5 times before their account is locked. The widget does not handle this scenario. Instead, it can optionally post back the below data and redirect the user to the redirect_uri provided in the query string:
Code Sample
Node + Request
1{
2 "status": 403,
3 "errorMessage": "User account locked."
4}Customisation
Our widget is built to integrate naturally with your website and brand, providing a consistent user experience.
- Fonts: type, size, text and background colours
- Page titles: Can either be displayed or hidden
- Fields: input fields border width, border radius and border colour
- Buttons: text and background colour, border width, border radius, border colour
- Validation messages
- Page titles copy (e.g. 'Username', 'Passcode', etc.)
- Input fields hints and placeholder text (e.g. ‘This is your username you use to log in’)
- Error messages based on API responses (e.g. 'Unauthorised user')
- Help copy (e.g. 'Do you already have NewPay?')
- Retrieval copy (e.g. 'Trouble logging in?')
Note: Further details can be discussed with your account manager.