SCA Widget
Learn how to use stepped up authentication in your journey.
Overview
Embed the SCA Widget
The widget is embedded onto your site using an iFrame. When two-step authentication is required for a customer to complete an Order Processing journey, the SCA widget can be used to confirm their identity and help them move forward in their journey.
Below is an example of how to add the widget to your website:
Javascript
1 <iframe src="https://id.newdaytechnology.com/<brand>/identity?redirect_uri=https://mywebsite.com&scaToken=<scaToken>"></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. | |
redirect_uri (required) | Specifies where the user is redirected in some scenarios (more details below), you choose the page the user is redirected to. | |
scaToken (required) | An encrypted JWT token is recieved from the Order Processing Initiate endpoint that contains all the information needed by the SCA widget to initilaise and complete the authentication. |
After the user has successfully confirmed their identity, 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"])
The src of the iFrame, including the scaToken
, will be in the payload of the response from Order Processing on the first authentication attempt.
Widget Responses
Whether a user has successfully authenticated, or something went wrong, the widget will post back data to the redirect_uri
provided in the query string. From that point onwards, you can decide how to handle each scenario.
Here it is a list of possible scenarios and respective payloads that the widget can send back:
Successful authentication
Code Sample
Node + Request
1{
2 scaToken: '<scaToken>',
3 success: true,
4 status: 'authenticated',
5 message: 'User successfully authenticated',
6}
Token expired
Code Sample
Node + Request
1{
2 scaToken: '<scaToken>',
3 success: false,
4 status: 'accessTokenInvalid',
5 errorMessage: 'Access token expired.',
6}
Token invalid
Code Sample
Node + Request
1{
2 scaToken: '<scaToken>',
3 success: false,
4 status: 'SCATokenInvalid',
5 errorMessage: 'SCA Token is invalid.',
6}
Not my number
The "That's not my number" button is clicked by the user to indicate that the mobile number to which the SCA OTP will be sent is incorrect.
Code Sample
Node + Request
1{
2 scaToken: '<scaToken>',
3 status: 'notMyNumber',
4 errorMessage: 'User number incorrect.',
5}
Account locked
When an invalid otp code is provided for 5 times, the user account is locked. The account can be unlocked by resetting the passcode.
Code Sample
Node + Request
1{
2 scaToken: '<scaToken>',
3 success: false,
4 status: 'authenticationFailed',
5 errorMessage: 'User account locked.',
6}
Account blocked
The SCA user account is blocked if SCA fails or incorrect credentials are entered during unlock or reset passcode journeys.
Code Sample
Node + Request
1{
2 scaToken: '<scaToken>',
3 success: false,
4 status: 'userBlocked',
5 errorMessage: 'Account blocked.',
6}
Technical error
If the API call returns an unexpected response, the widget will display an error page where the user can either try again or exit the journey. In the latter case the below payload will be sent to the redirect_uri
.
Code Sample
Node + Request
1{
2 scaToken: '<scaToken>',
3 status: '500',
4 errorMessage: 'Technical Error.',
5}
Customisation options
The following elements can be configured by NewDay to match your site:
Category | Configurable Options |
---|---|
Fonts & colours | Fonts, font size, font colour, background colours |
Page titles | Can either be displayed or hidden |
Fields | Input fields border width, radius and colour |
Buttons | Text and background colour, copy, border-radius, border, border width, border-colour |
Getting Started with NewDay
Quick start guides for how you can start working with NewDay as a partner and learn about the end to end processes of integrating with APIs.
Was this page helpful?