Submission (NZ brands)

Overview

This page describes the Sign Up submission process to create a new client account on the NZ brands, which are currently TabNZ and Betcha.

Branding

The main difference between brands is that the id verification leverage flow is a betcha specific feature, hence it's expected that the id-verification-reuse-native will always be off for TabNZ and that TabNZ customers will always progress through the standard idv flow.

The other notable difference is that the pin field only exists on TabNZ, thus it will never get sent with the create client request in Betcha.

Integrations

Feature Flags

id-verification-reuse-native

• If on then the app will perform checks to determine if the customer is eligible for id verification reuse. If the user is eligible, they will be navigated to the leverage flow post submission.
• By default, this flag is off for TabNZ and on for Betcha.

Inputs

User Input: Client Details

The client details entered by the user in the sign up form.

Navigation Params: email address and mobile

• Both of these are collected on the Landing Screen, sent to the join form and submitted to the create client endpoint.

REST: POST /client/client-v2/CheckIDVLeverageEligibility

• Used to check if the newly created user is eligible for the IDV leverage flow.
• A user is eligible for the leverage flow if their personal details match those of an existing, verified TabNZ customer, see Leveraging TAB IDV for Betcha for more details.

Websocket Method: customerMatchCompleted

• An unauthenticated websocket used to inform the app that the customer matching process is complete and that the backend is ready to give a response to the above endpoint.

method: "customerMatchCompleted"
handler: "client"
topics: {"id": clientId } // the clientId of the newly created user

Outputs

REST: POST /client/Create

• This is the endpoint to which the user's details are sent to create a new account.

Parameters:

• first_name, middle_name, last_name, username, password, email, bonus_code, pin and and address fields: string values as entered into form.
• address_locality: this value is the 'town/city' entered by the user in the manual address
• address_sub_locality: this value mirrors address_suburb.
• phone_number_type_id: hardcoded to "06ae915f-905e-4be7-abc7-bc9c1b9a6021" to represent a mobile phone.
• phone_number: mobile phone number without country code e.g. 0221234567.
• date_of_birth: date in string format yyyy-MM-dd e.g. 1980-01-31.
• deposit_limit: decimal value representing the deposit limit.
• deposit_limit_period: string value concatenating the prefix "DAYS_" with the duration e.g. DAYS_7
• address_place_id: Harmony address ID or null for manual entry

Json Request

{
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string",
  "date_of_birth": "string",        // In yyyy-MM-dd format
  "email": "string",
  "phone_number": "string",
  "phone_number_type_id": "string", // hardcoded to mobile id: 06ae915f-905e-4be7-abc7-bc9c1b9a6021
  "username": "string"
  "password": "string",
  "deposit_limit": number,
  "deposit_limit_period": "string", // e.g. DAYS_7
  "accepts_marketing": boolean,
  "bonus_code": "string",
  "address_place_id": "string",     // Populated with Harmony address ID or null for manual entry
  "address_unit_number": "string",
  "address_street_number": "string",
  "address_street": "string",
  "address_post_code": "string",
  "address_suburb": "string",
  "address_locality": "string",     // corresponds to the 'town/city' entered by the user
  "address_state": "string",
  "address_country_code": "string",
  "address_premise": "string",
  "address_sub_locality": "string", // corresponds to the 'suburb' entered by the user
  "currency_code": "string",        // hardcoded to "NZD"
  "pin": "string"                   // only applicable to TabNZ
  "nature_and_purpose_responses": [
    {"question_id": "string", "answer_id": "string"}
  ]
}

Create Client UI Mapping

The following scenarios are the result of the process of creating a new client account:

Successful client creation

A successful response from the create client API, results in a new account being created. The auto_login_token value in the response enables authenticating the user with the auth web url without the user entering their credentials again. For more information on authentication, refer to the Login feature, the Android authentication or iOS authentication docs, or the Authentication Bridge. Onward navigation is determined based on the below logic.

User already exists

The backend returns this error when it determines that the user already has an account. While the username, email address and phone number are checked before submission to make sure they don't exist in the database, it is still possible to receive this error when for example, the first name, lastname and date of birth combination already exists. In this case, a system error is presented to the user to let them know that an account already exists and gives the user the option to go to the Login screen.

Self excluded

This error is returned by the backend when the user has been added to the Self exclusion list. In this case the user is navigated to the sign up self exclusion page.

Generic or Unknown errors

This scenario can happen when:

• There is an issue creating or sending the create client request
• The backend returns an error that is not one of the mentioned scenarios above, and for which there is no specific scenario.

In this case, a system error is displayed to the user letting them know that something went wrong and inviting them to try again or contact Customer Support. The "Contact Us" button dimisses the sign up flow and navigates the user to the contact us page.

Onward Navigation

As briefly mentioned above, after a new account is successfully created, automatic authentication is attempted. If this process fails, then the user is navigated to the login screen so they can manually login on Android. On iOS, the sign-up flow is dismissed, and the user ends up on the home screen. If the token exchange is successful then more checks are required to see if the user is eligible for the IDV Leverage flow:

• The IDV reuse feature flag is checked
  • If this flag is off then the user is navigated to the standard id verification flow
• The users' eligibility for the leverage flow is then checked
  • If the user is eligible then they are navigated to the id verification leverage flow
  • If they're not eligible then they are navigated to the standard verification flow

IDV Leverage Eligibility

To be eligible for id verification leverage, a user must be creating an account on Betcha that matches the personal details of an existing, verified TabNZ account. To determine if the newly created user is eligible, firstly a subscribe call is made to the customerMatchCompleted websocket method described under inputs. If this websocket returns a clientId matching the one provided in the subscribe call, this indicates that the user matching process is complete and that it's safe to call the check eligibility rest endpoint (also described under inputs).

Once the matching process is complete, or if the websocket doesn't return a matching id in 5 seconds, then the rest endpoint is called. The existence of a client id in the response of that call indicates that the new Betcha customer is eligible for the idv leverage flow.

Resources

• Epic - Jira
• Leveraging TAB IDV for Betcha.

Role	Contact
PM	Laura Baggio
Android Lead	Anthony Librio
iOS Lead	Nicholas Vella