Implement Prove Pre-Fill

Prompt Customer

No Mobile Auth
Mobile Auth

Create or update your first screen to prompt for phone number and challenge data.

Page Summary Language: Let’s Begin by Finding Your Information
Page Summary Description: We can prefill some of this request like your name, address, and contact info for you.

Challenge Page phone number entry example

When prompting for the phone number, follow the image.The table outlines your options for prompting the challenge data.

Contracted Solution	Customer Prompt Language Requirements	Required Challenge Data
Prove Pre-Fill	Customer can choose one from the following prompts: “Last 4 SSN/ITIN” “SSN/ITIN” “MM/DD/YYYY” “MM/YYYY” “MM/DD”	Last 4 SSN/ITIN Full SSN* Full DOB DOB - Month and Year DOB - Month and Day *If the customer is applying to open a demand deposit account (DDA), the customer must enter their full social security number (SSN) for the challenge
Prove Pre-Fill with KYC	”Full SSN/ITIN”	Full SSN
If the customer doesn’t have a mobile number, exit the Prove flow and present a manual application. Customers without a mobile number still have a path forward to continue with their application.

Determine Type of Flow

Web SDK
Android SDK
iOS SDK

You can determine if the customer is on a mobile or desktop browser using this example. If the isMobile is true, set mobile as the flowType for the Start() function on the server, otherwise you can set desktop:

// Check if the customer is on a mobile or desktop browser.
const authCheck = new proveAuth.AuthenticatorBuilder().build();
let isMobile = authCheck.isMobileWeb()

Initialize the Flow

No Mobile Auth
Mobile Auth

You need to send a request to your back end server with the phone number, flow type, and an optional challenge to start the flow. This can either be the date of birth or last four digits of the social security number.

Web SDK
Android SDK
iOS SDK

async function initialize(phoneNumber, ssn, flowType) {
  const response = await fetch(backendUrl + "/initialize", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumber: phoneNumber,
      "Content-Type": "application/json",
      ssn: ssn
    }),
  });

  const rsp = await response.json();
  const authToken = rsp.authToken;

  return authToken;
}

Call the Start Endpoint

On the back end, you’ll start a Prove flow with a call to the Start() function. This function takes these required parameters:

flowType: either desktop or mobile to describe which type of device the customer is starting their flow on.
finalTargetURL: required when flowType=desktop. This should be a URL you maintain. Once the customer clicks the Instant Link, they will be redirected to this URL. It should instruct the customer to continue the workflow. Maximum length is 128 characters.

These parameters are optional:

ssn: full or last four digits of the customer’s social security number. You can pass it into Start() or Challenge().
dob: date of birth in one of these formats: YYYY-MM-DD, YYYY-MM, MM-DD. You can pass it into Start() or Challenge().
allowOTPRetry: set to true to allow the customer to re-enter the OTP up to three times. Defaults to false.
For OTP retries, make sure to implement client SDK changes in the next step.

No Mobile Auth
Mobile Auth

ctx := context.TODO()

rspStart, err := client.V3.V3StartRequest(ctx, &components.V3StartRequest{
	FlowType:       "desktop",
	FinalTargetURL: provesdkservergo.String("https://prove.com"),
	PhoneNumber:    provesdkservergo.String("2001001686"),
	Ssn:            provesdkservergo.String("8370"),
})
if err != nil {
	t.Fatal(err)
}

The function returns the following fields:

authToken: send this to your client-side code through the Authenticate() function - it’s a JSON Web Token (JWT) tied to the current flow and used for the possession checks. It expires after 15 minutes.
correlationId: save this in your current session, then pass it in to each of the Validate(), Challenge(), and Complete() function calls of the same flow. The correlation ID ties together different system calls for the same Prove flow. It can aids in troubleshooting. The session expires in 15 minutes from when the correlation ID returns from the Start() call.
next: map of the next API call you need to make.

Return the authToken in a response to the front end.

Authenticate

Once you have the authToken, build the authenticator for both the mobile and desktop flows.

Web SDK
Android SDK
iOS SDK

async function authenticate(isMobileWeb, authToken) {
  // Set up the authenticator for either mobile or desktop flow.
  let builder = new proveAuth.AuthenticatorBuilder();

  if (isMobileWeb) {
    // Set up Mobile Auth and OTP.
    builder = builder
      .withAuthFinishStep((input) => verify(input.authId))
      .withMobileAuthImplementation("fetch")
      .withOtpFallback(otpStart, otpFinish);
  } else {
    // Set up Instant Link.
    builder = builder
      .withAuthFinishStep((input) => verify(input.authId))
      .withInstantLinkFallback(instantLink)
      .withRole("secondary");
  }

  const authenticator = builder.build();

  // Authenticate with the authToken.
  return authenticator.authenticate(authToken);
}

Configure OTP

To use the Resend/Retry/Phone Change features, you need to install the Web SDK version 2.15.1 or later.

To set the One-Time Password (OTP) handler, withOtpFallback(startStep: OtpStartStep | OtpStartStepFn, finishStep: OtpFinishStep | OtpFinishStepFn), requires implementing the OtpStartStep and OtpFinishStep. When returning the phone number in the functions, ensure you return an object with the field phoneNumber to the resolve() function.The OTP session has a two minute timeout from when it’s sent through Short Message Service (SMS) to when the customer can enter in the OTP.

Default
Prompt for Phone Number
Resend
Retry OTP
Phone Number Change

Follow these instructions if you are implementing OTP and you are passing in the phone number on the /v3/start endpoint. In this case, you’ve already prompted for a phone number so you don’t need to prompt for it in the client SDK.Since you passed the phone number in the Start() function, call resolve(null) to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an object to resolve() function.

function otpStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // Since no phone number is needed, don't prompt the user.
    resolve(null);
  });
}

Call the reject('some error message') method to communicate to the SDK any issues while trying to obtain the phone number or the OTP. Report an error if the customer cancels the SMS transaction or presses the back button to leave the screen.In the finish step, call the resolve(result: OtpFinishResult) method to return the collected OTP value in which result variable has OnSuccess value for OtpFinishResultType and the OTP value wrapped in OtpFinishInput.

function otpFinishStep(otpError) {
  return new Promise((resolve, reject) => {
    // If error message is found, handle it.
    if (otpError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = otpError.message;
    }

    // Prompt the user for whether they received the SMS.
    // Typically, this is a page that shows the OTP already. We are simplifying
    // it by requiring an input.
    var input = confirm('Did you receive a text message?');
    if (!input) {
      // Close the modal if a text message was not received.
      return;
    }

    // Prompt the user for the OTP.
    var otp = prompt('Enter OTP code:');
    if (otp) {
      // If the input is valid and the user clicked `OK`, return the OTP.
      resolve({
        input: { otp }, // OTP value
        resultType: 0, // OnSuccess enum type = 0
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Configure Instant Link

To use the Resend/Retry/Phone Change features, you need to install the Web SDK version 2.15.1 or later.

To set the Instant Link handler,

withInstantLinkFallback(startStep: InstantLinkStartStep | InstantLinkStartStepFn, retryStep?: InstantLinkRetryStep | InstantLinkRetryStepFn)

requires implementing the InstantLinkStartStep interface and optionally the InstantLinkRetryStep interface if you wish for advanced capabilities. When returning the phone number in the functions, ensure you return an object with the field phoneNumber to the resolve() function.The Instant Link session has a three minute timeout from when it’s sent through Short Message Service (SMS) to when the customer can click the received link.

Default
Prompt for Phone Number
Resend
Phone Number Change

Follow these instructions if you are implementing Instant Link and you are passing in the phone number on the /v3/start endpoint. In this case, you’ve already prompted for a phone number so you don’t need to prompt for it in the client SDK.Since you passed the phone number in the Start() function, call resolve(null) to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an object to resolve() function.

function instantLinkStartStep(phoneNumberNeeded, phoneValidationError) {
  return new Promise((resolve, reject) => {
    // Since no phone number is needed, don't prompt the user.
    resolve(null);
  });
}

OTP

Page Summary

Flow	Page Summary Language
Mobile	Enter verification code. Please enter the code we just sent to (XXX) XXX-XXXX.

Instant Link

Page Summary

Flow	Page Summary Language
Desktop	Check your Phone. A text message with a link was just sent to the phone ending in XXXX (last 4 digits of mobile number).

Alternate path for customers

If the customer can’t authenticate through Instant Link or SMS one-time password (OTP), customer exits the Prove flow. Present a manual application as an alternate method of verification.Reference the Quick Start Guide to get started.In the desktop flow, a WebSocket opens for three minutes on the desktop browser while waiting for the customer to select the link in the text message. Once clicked, the WebSocket closes and the AuthFinishStep function finishes.

If you’re using Content Security Policy headers, ensure you allow wss: device.uat.prove-auth.proveapis.com and wss: device.prove-auth.proveapis.com.

Verify Mobile Number

In the AuthFinishStep, you’ll specify a function to call once the possession checks complete on the mobile phone. This endpoint on your back end server calls the Validate() function to validate the phone number. If it was successful, the server returns the results from the Challenge() function including customer information. Refer to the following example fields that return and then prefill on a form for the customer to verify. The AuthFinishStep then completes. In the event of cancellation, the server makes a call to the Validate() function and returns success=false.

Web SDK
Android SDK
iOS SDK

// Send a verify request to get return customer information.
async function verify() {
  const response = await fetch(backendUrl + "/verify", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  });

  const results = await response.json();
  const rsp = JSON.stringify(results);

  const firstName = document.getElementById("firstNameInput");
  const lastName = document.getElementById("lastNameInput");

  firstName.value = rsp.firstName;
  lastName.value = rsp.lastName;

  return null;
}

Validate Mobile Phone

Once the possession checks finish on the mobile device, the finish handler on the client-side SDK executes. You then make a request to your server such as POST /verify to make the next call in the flow to the Validate() function.

Mobile Number Collection Page screenshot

Page Summary Requirements

Page Summary Language: Let’s Get Started
Page Summary Description: Please enter your phone number to begin the account creation process.

Data entry prompt requirements

Prompt for the mobile number within the input field.

Opt out

Allow customers to select “I don’t have a mobile number” which sends the customer to a manual form to allow customers without mobile numbers to still apply.Reference the Quick Start Guide to get started.This function requires the Correlation ID which is returned by the Start() function.

rspValidate, err := client.V3.V3ValidateRequest(context.TODO(), &components.V3ValidateRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
})
if err != nil {
    return fmt.Errorf("error on Validate(): %w", err)
}

The function returns the following fields:

success: true if customer info returned.
individual: customer information in a map.
next: map of the next API you need to call you need to make.

If success=true, return the customer information in a response to the front end to prefill the form.

Verify the Customer Information

Example display of required fields and masking for personal information

Display fields and requirements

Pre-Fill

Required Display Field	Display Requirements	Editable Field
First Name	Yes - unmasked	Yes
Last Name	Yes - unmasked	Yes
Address	Yes - unmasked	Yes
Extended Address	Yes - unmasked	Yes
City	Yes - unmasked	Yes
State	Yes - unmasked	Yes
Postal Code	Yes - unmasked	Yes
Phone Number	Yes - unmasked	No
Social Security Number (SSN)	Mask first five, display last four	Yes*
Date of Birth	Yes - MM/DD/YYYY	Yes**
* Upon edit, clear data and require customer to enter full SSN.
**Upon edit, clear the data and require customer to enter the full date of birth.

Pre-Fill with KYC

Required Display Field	Display Requirements	Editable Field
First Name	Yes - unmasked	Yes
Last Name	Yes - unmasked	Yes
Address	Yes - unmasked	Yes
Extended Address	Yes - unmasked	Yes
City	Yes - unmasked	Yes
State	Yes - unmasked	Yes
Postal Code	Yes - unmasked	Yes
Phone Number	Yes - unmasked	No
Social Security Number	Mask first five, display last four	No, full SSN entered at beginning of process.
Date of Birth	Yes - MM/DD/YYYY	Yes*
* Upon edit, clear the data and require customer to enter the full date of birth.

Know Your Customer (KYC) Required Customer ConfirmationInclude this statement before the submit button. You can include an optional check box.“I have reviewed the information provided and confirm it’s accurate.”

Once the customer has made any edits to their prefill information, submit that information to the back end server so the Complete() call can then verify the customer information.

Web SDK
Android SDK
iOS SDK

// Send request to the backend to verify customer information.
async function sendInfo(firstName, lastName) {
  const response = await fetch(backendUrl + "/finish", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      firstName: firstName,
      lastName: lastName,
    }),
  });
  const results = await response.json();
  const rsp = JSON.stringify(results);

  return rsp;
}

Call the Complete Endpoint

This function is the final call in the flow that verifies the customer information.This function takes these required parameters:

Correlation ID: this is the ID returned by the Start() function.
Individual: customer information in a map.

When implementing the KYC add-on, you need to pass in first name, last name, DOB, and SSN (or address) to ensure you receive back the KYC and CIP fields. If applicable, the following reason codes will return in Production:

DI - this identity is associated with a death indicator.
CF - The address matches the address of a U.S. correctional facility.
PO - The address was classified as a PO Box.

Refer to the Complete API reference and select “Response with KYC - 0 hits” for an example response.

rspComplete, err := client.V3.V3CompleteRequest(context.TODO(), &components.V3CompleteRequest{
	CorrelationID: rspStart.V3StartResponse.CorrelationID,
	Individual: components.Individual{
		FirstName: provesdkservergo.String("Tod"),
		LastName:  provesdkservergo.String("Weedall"),
		Addresses: []components.AddressEntry{
			{
				Address:    provesdkservergo.String("39 South Trail"),
				City:       provesdkservergo.String("San Antonio"),
				Region:     provesdkservergo.String("TX"),
				PostalCode: provesdkservergo.String("78285"),
			},
		},
		Ssn: provesdkservergo.String("565228370"),
		Dob: provesdkservergo.String("1984-12-10"),
		EmailAddresses: []string{
			"[email protected]",
		},
	},
})
if err != nil {
	return fmt.Errorf("error on Complete(): %w", err)
}

The function returns the following fields:

Success: true if customer information returned.
Next: map of the next API call you need to make, in this case, Done.

You can then respond to the front end with the results of the customer verification.

Test your Prove implementation

Next, reference the Sandbox test scenarios to test users and simulate different behaviors encountered in production.

Production LaunchTo launch in Production, please contact your Prove representative.

Get Started

Welcome

Know

Grow

Pre-Fill

Identity

Resources

Implement Prove Pre-Fill