Pre-Fill Implementation Guide

The following endpoints apply to this flow:

Prerequisites

Access token — Obtain a bearer token using Prove OAuth (Authentication).
Server — Use a Prove server SDK or call POST /v3/start, POST /v3/validate, POST /v3/challenge, and POST /v3/complete directly. Use those reference pages for full request bodies, optional fields, and responses.
Client SDK — Install the Web, Android, or iOS Identity SDK for Initialize, Authenticate, and possession checks. For the browser flow, see Identity Web SDK.

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

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 app. Customers without a mobile number still have a path forward to continue with their app.

Create or update your first screen to prompt the customer to accept the terms and conditions to use Mobile Auth to verify a customer.

In order for Mobile Auth to succeed:

Disable VPN.
Disable Private Relay on iOS.

When testing, you can ignore any Chrome error messages that mention ERR_TUNNEL_CONNECTION_FAILED - this is due to the VPN, but the SDK fallbacks to OTP.

Summary

The following mobile network operators (MNO) have set requirements for accessing their data for relevant Prove services. Reference your Master Service Agreement for full details on submitting the appropriate forms.

Verizon
T-Mobile
AT&T

AT&T requires extra considerations. Talk to your sales representative for more info.

Prerequisites

Give the Production URLs where MNO Consent language lives once published in Production.
Give the estimated timeline of when consent language goes live. Language must be live for T-Mobile approval.
Give a mock-up of the page where the customer accepts these terms and conditions. The customer can proceed if you add terminology by clicking Continue you agree to our T&C or the customer checks the consent box.

Screenshot example of an MNO carrier consent page mockup

“You authorize your wireless carrier to use or share information about your account and your wireless device, if available, to Enterprise Customer Name or its service provider during your business relationship, to help identify you or your wireless device and to prevent fraud. See our Privacy Policy for how we treat your data.”

Required language placement

The MNOs require customers to accept carrier consent language in the customer flow before calling the endpoint in scope.Place the MNO Terms and Conditions on either the Landing Page or the Challenge Page. Speak to your Prove representative for more detail.If implementing Mobile Auth, place the MNO consent language on your Landing Page, referenced in Terms and Conditions.

Determine Type of Flow

Web SDK
Android SDK
iOS SDK

You can decide 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()

When using the Android SDK, set mobile as the flowType for the Start() function on the server.

When using the iOS SDK, set mobile as the flowType for the Start() function on the server.

Initialize the Flow

No Mobile Auth
Mobile Auth

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;
}

Java

  String initialize(String phoneNumber, String ssn, String flowType) {
      YourBackendClient backend = new YourBackendClient(); // Backend API client

      // TODO: Build your InitializeRequest object
      InitializeRequest initializeRequest = new InitializeRequest(phoneNumber, ssn, flowType);

      // Send an initialize request to your backend server to get authToken
      InitializeResponse response = backend.initialize(initializeRequest);

      // TODO: define your own InitializeResponse object to parse authToken string
      return response.getAuthToken();
  }

Swift

// The below example uses native iOS URLSession, but any other
// alternative networking approaches should also work
func initialize(phoneNumber: String, ssn: String, flowType: String, completion: @escaping (Result<String, Error>) -> Void) {
    guard let url = URL(string: "\(backendUrl)/initialize") else {
        completion(.failure(URLError(.badURL)))
        return
    }
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    // Set up the request body
    let body: [String: Any] = [
        "phoneNumber": phoneNumber,
        "flowType": flowType,
        "ssn": ssn
    ]
    do {
        request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
    } catch {
        completion(.failure(error))
        return
    }
    // Perform the request
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // Handle network or connection errors
        if let error = error {
            completion(.failure(error))
            return
        }
        // Check HTTP response status code
        if let httpResponse = response as? HTTPURLResponse,
            httpResponse.statusCode != 200 {
            let statusError = NSError(domain: "", code: httpResponse.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP error with status code: \(httpResponse.statusCode)"])
            completion(.failure(statusError))
            return
        }
        guard let data = data else {
            let noDataError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "No data received"])
            completion(.failure(noDataError))
            return
        }
        do {
            if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
                let authToken = json["authToken"] as? String {
                completion(.success(authToken))
            } else {
                let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to parse JSON or authToken is missing"])
                completion(.failure(parsingError))
            }
        } catch {
            completion(.failure(error))
        }
    }
    // Start the network call
    task.resume()
}

Send a request to your back end server with the flow type.

Web SDK
Android SDK
iOS SDK

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

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

  return authToken;
}

Java

  String initialize(String flowType) {
      YourBackendClient backend = new YourBackendClient(); // Backend API client

      // TODO: Build your InitializeRequest object
      InitializeRequest initializeRequest = new InitializeRequest(flowType);

      // Send an initialize request to your backend server to get authToken
      InitializeResponse response = backend.initialize(initializeRequest);

      // TODO: define your own InitializeResponse object to parse authToken string
      return response.getAuthToken();
  }

Swift

// The below example uses native iOS URLSession, but any other
// alternative networking approaches should also work
func initialize(flowType: String, completion: @escaping (Result<String, Error>) -> Void) {
    guard let url = URL(string: "\(backendUrl)/initialize") else {
        completion(.failure(URLError(.badURL)))
        return
    }
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    // Set up the request body
    let body: [String: Any] = [
        "flowType": flowType
    ]
    do {
        request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
    } catch {
        completion(.failure(error))
        return
    }
    // Perform the request
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // Handle network or connection errors
        if let error = error {
            completion(.failure(error))
            return
        }
        // Check HTTP response status code
        if let httpResponse = response as? HTTPURLResponse,
            httpResponse.statusCode != 200 {
            let statusError = NSError(domain: "", code: httpResponse.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP error with status code: \(httpResponse.statusCode)"])
            completion(.failure(statusError))
            return
        }
        guard let data = data else {
            let noDataError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "No data received"])
            completion(.failure(noDataError))
            return
        }
        do {
            if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
                let authToken = json["authToken"] as? String {
                completion(.success(authToken))
            } else {
                let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to parse JSON or authToken is missing"])
                completion(.failure(parsingError))
            }
        } catch {
            completion(.failure(error))
        }
    }
    // Start the network call
    task.resume()
}

Call the Start Endpoint

On the back end, start a Prove flow with Start() (POST /v3/start lists required fields such as flowType, optional finalTargetUrl for desktop Instant Link, optional ssn and dob for challenge data, allowOTPRetry, and the full response).

For OTP retries (allowOTPRetry), implement the 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)
}

// Send the start request.
rspStart, err := client.V3.V3StartRequest(context.TODO(), &components.V3StartRequest{
  FlowType:       "desktop",
  FinalTargetURL: provesdkservergo.String("https://www.example.com"),
  AllowOTPRetry: true,
})
if err != nil {
  return fmt.Errorf("error on Start: %w", err)
}

Return the authToken to the client for Authenticate(). Persist correlationId in the session and pass it to Validate(), Challenge(), and Complete() for this flow. See POST /v3/start for all response fields, JWT behavior, and session timing.

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

Use this section to configure SMS OTP fallback in the Web SDK: wire OtpStartStep and OtpFinishStep so the SDK can send the code, collect the PIN, and optionally support resend, OTP retry, or phone-number change.

Prerequisites

After Prove sends the SMS, the customer has about two minutes to enter the OTP before the session times out.
When building the authenticator, call withOtpFallback(startStep: OtpStartStep | OtpStartStepFn, finishStep: OtpFinishStep | OtpFinishStepFn) and implement both OtpStartStep and OtpFinishStep. Return the phone number from your start step as an object with a phoneNumber field passed to resolve(...); use reject('message') when collection fails. The Prove client SDK orchestrates when each step runs—do not duplicate that orchestration in app code (see Invalid OTP and step orchestration below).

Invalid OTP and step orchestrationWhen the customer enters an invalid OTP, the Prove client SDK detects it and may surface activity related to AuthFinishStep that looks unexpected. This behavior is expected.Do not add your own extra invocation of the OTP finish step to pass the error in otpError. The SDK runs your OtpFinishStep when retry or error UI is needed.Implement the required step functions, but let the Prove client SDK orchestrate when each step runs.

Configure the client

Implement start and finish for your use case

Open the tab that matches how the phone number is collected and which OTP options you need.

Default
Prompt for Phone Number
Resend
Retry OTP
Phone Number Change

Use this path when the server already has the phone number (for example from POST /v3/start or your server Start wrapper) and the browser must not prompt for it again.Call resolve(null) (or the equivalent in your snippet) so the SDK knows the customer agreed to receive the SMS. Follow the sample for the exact resolve shape your SDK version expects.

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

Call reject('some error message') if something prevents sending the SMS or completing the flow (for example the customer cancels or leaves the UI with the back button).In the finish step, return the OTP through resolve(result: OtpFinishResult) with the OnSuccess result type and the value wrapped in OtpFinishInput, as in the snippet below.

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');
    }
  });
}

Use this path when the page collects the phone number in the browser and you do not need SMS resend, dedicated OTP retry handling beyond defaults, or phone-number change. For those capabilities, use Resend, Retry OTP, or Phone Number Change.In the start step, call resolve(input) with an object that includes the collected phoneNumber.

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

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Implement the finish step:

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');
    }
  });
}

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

Allow a new OTP SMS to the same number (up to three send attempts including the first).Implement the start step:

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

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Then implement the finish step so the customer can request another SMS, for example:

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) {
      // If `Cancel`, then resend to the same phone number.
      resolve({
        resultType: 1, // OnResendOtp enum type = 1
      });

      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');
    }
  });
}

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

Allow the customer to re-enter the OTP after a wrong PIN (up to three attempts). On the server, pass allowOTPRetry=true on POST /v3/start (or your equivalent Start request).Implement the start step—no extra client changes beyond your normal prompt path:

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

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Implement the finish step—no extra client changes. If the OTP is invalid, the finish step drives retry UI until attempts are exhausted, then AuthFinish runs.

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');
    }
  });
}

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

Allow the customer to re-enter the phone number (up to three entries/send attempts).

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

Implement the start step:

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

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Then implement the finish step so the customer can supply a new number, for example:

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) {
      // If `Cancel`, then trigger the otpStartStep to re-prompt for
      // phone number.
      resolve({
        resultType: 2, // OnMobileNumberChange enum type = 2
      });

      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');
    }
  });
}

Verify the integration

In Sandbox, walk each shipped path (default, prompt, resend, retry if enabled, phone change if enabled). Confirm SMS delivery, OTP entry within the timeout, and that you never stack extra OtpFinishStep invocations on top of the SDK’s invalid-OTP handling—the SDK should remain the single orchestrator for retries and errors.

Configure Instant Link

Use this section to configure the Web SDK so Instant Link SMS can be sent from the browser flow and optional resend or phone-number change behaves as expected.

Instant Link for mobile web isn’t supported.

Custom or vanity Instant Links aren’t supported. You can’t substitute a custom link for the default Instant Link.

Prerequisites

Integrate on desktop (or other supported) web; see the callout above for mobile web.

When building the authenticator, use withInstantLinkFallback(startStep: InstantLinkStartStep | InstantLinkStartStepFn, retryStep?: InstantLinkRetryStep | InstantLinkRetryStepFn). Implement InstantLinkStartStep in every flow. Add InstantLinkRetryStep only if you support Resend or Phone Number Change (see those tabs). Return the phone number from your step as an object with a phoneNumber field passed to resolve(...); use reject('message') when collection fails.

Configure the client

Implement the Instant Link start and optional retry

Open the tab that matches how the phone number is collected and sent to Prove.

Default
Prompt for Phone Number
Resend
Phone Number Change

Use this path when the server already has the phone number (for example from POST /v3/start or your server Start wrapper) and the browser must not prompt again.Call resolve(null) (or the equivalent in your snippet) so the SDK knows the customer agreed to receive the SMS. Follow the sample for the exact resolve shape your SDK version expects.

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

Use this path when the page collects the number in the browser and you do not need resend or phone-number change. For resend or change, use the other tabs.Call resolve(input) with an object that includes the collected phoneNumber. Call reject('some error message') if collection fails, the customer cancels, or they leave the Instant Link start UI (for example with the back button).

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

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

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

Allow a new SMS to the same number (up to three send attempts including the first).Implement the start step:

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

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Then implement InstantLinkRetryStep so the customer can request another SMS, for example:

function instantLinkRetryStep() {
  return new Promise((resolve, reject) => {
    // There are multiple return options:
    // - resolve(0): request resend to the same phone number
    // - reject('user clicked cancel'): error out of the possession flow

    // Prompt the user for the phone number.
    // Typically, this is a page that is automatically closed or redirected
    // once the `AuthFinish` function is called. We are simplifying it by
    // requiring an input.
    var input = confirm('Did you receive a text message?');
    if (input) {
      // If `OK`, close the modal.
      return;
    }

    // Else `Cancel`, then resend to the same phone number.
    resolve(0);
  });
}

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

Allow the customer to re-enter the phone number (up to three entries/send attempts).

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

Implement the start step:

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

      return;
    }

    // If error message is found around phone number, handle it.
    // The `phoneValidationError` is ONLY available when `phoneNumberNeeded`
    // has a value.
    if (phoneValidationError) {
      // Set to a variable and display it in a field.
      // In this example, we don't do anything with the error.
      var someErrorMessage = phoneValidationError.message;
    }

    // Prompt the user for the phone number.
    var input = prompt('Enter phone number:');
    if (input) {
      // If the input is valid and the user clicked `OK`, return the phone
      // number.
      resolve({
        phoneNumber: input,
      });
    } else {
      // Else, exit the flow.
      reject('phone invalid or user cancelled');
    }
  });
}

Then implement InstantLinkRetryStep to collect a new number, for example:

function instantLinkRetryStep() {
  return new Promise((resolve, reject) => {
    // There are multiple return options:
    // - resolve(0): request resend to the same phone number
    // - resolve(1): request phone number change/re-prompt
    // - reject('user clicked cancel'): error out of the possession flow

    // Prompt the user for the phone number.
    // Typically, this is a page that is automatically closed or redirected
    // once the `AuthFinish` function is called. We are simplifying it by
    // requiring an input.
    var input = confirm('Did you receive a text message?');
    if (input) {
      // If `OK`, close the modal.
      return;
    }

    // Else `Cancel`, then trigger the instantLinkStartStep to re-prompt for
    // phone number.
    resolve(1);
  });
}

Verify the integration

In Sandbox, run through each path you ship (default, prompt, and any retry flows). Confirm the SMS sends, the customer can complete the link within the timeout window, and resolve / reject match the UX you expect when the customer cancels or retries.

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 app as an alternate method of verification.In the desktop flow, a WebSocket opens for 5 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 connect-src for wss://*.prove-auth.proveapis.com.

Java

// Object implementing AuthFinishStep interface
AuthFinishStep authFinishStep = new AuthFinishStep() {
   ...
};

// Objects implementing OtpStartStep/OtpFinishStep interfaces
OtpStartStep otpStartStep = new OtpStartStep() {
  ...
};

OtpFinishStep otpFinishStep = new OtpFinishStep() {
  ...
};

ProveAuth proveAuth = ProveAuth.builder()
    .withAuthFinishStep(authId -> verify(authId)) // verify(authId) call defined in #Validate the Mobile Phone section
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .build();

The mobile data connection can sometimes be unavailable during testing. The Builder class offers a withTestMode(boolean testMode) method, which permits simulated successful session results while connected to a Wi-Fi network only. Testing using a Wi-Fi connection is useful in the Sandbox environment.

Java

ProveAuth proveAuth = ProveAuth.builder()
    .withAuthFinishStep(authId -> verify(authId))
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .withTestMode(true) // Test mode flag
    .build();

The app employs an executor service with a minimum of two threads to manage threads due to the SDK’s ability to process concurrent blocking requests.

Java

public class MyAuthenticator {
    private final MyBackendClient backend = new MyBackendClient(); // Backend API client

    private final AuthFinishStep authFinishStep = new AuthFinishStep() {
        @Override
        void execute(String authId) {
            try {
                AuthFinishResponse response = backend.authFinish("My App", authId);
                ... // Check the authentication status returned in the response
            } catch (IOException e) {
                String failureCause = e.getCause() != null ? e.getCause().getMessage() : "Failed to request authentication results";
                // Authentication failed due to request failure
            }
        }
    };

    private ProveAuth proveAuth;

    public MyAuthenticator(Context context) {
        proveAuth = ProveAuth.builder()
          .withAuthFinishStep(authFinishStep)
          .withOtpFallback(otpStartStep, otpFinishStep)
          .withContext(context)
          .build();
    }

    public void authenticate() throws IOException, ProveAuthException {
        AuthStartResponse response = backend.authStart("My Prove Auth App");

        proveAuth.authenticate(response.getAuthToken());
    }
}

Configure OTP

Use this section to configure SMS OTP fallback on Android: wire OtpStartStep and OtpFinishStep so the SDK can send the code, collect the PIN, and optionally support resend, OTP retry, or phone-number change.

Prerequisites

After Prove sends the SMS, the customer has about two minutes to enter the OTP before the session times out.
When building the authenticator, call withOtpFallback(otpStart: OtpStartStep, otpFinish: OtpFinishStep) and implement both OtpStartStep and OtpFinishStep. The Prove client SDK orchestrates when each step runs—implement the interfaces, but do not duplicate that orchestration in app code (see Invalid OTP and step orchestration below).

Invalid OTP and step orchestrationWhen the customer enters an invalid OTP, the Prove client SDK detects it. Typical signs include a validation or reported error such as code 10001 with a message that the PIN doesn’t match. You may also see flow activity related to AuthFinishStep, such as ProveAuth.builder().withAuthFinishStep(…), that looks like an unexpected redirect.This behavior is expected. Do not add your own follow-up call to OtpFinishStep.execute to pass the error in otpException. The SDK invokes OtpFinishStep.execute when a retry or error UI is needed.Your app should implement the required step interfaces, but the Prove client SDK orchestrates when each step runs. Don’t duplicate that orchestration in application code.

Configure the client

Implement start and finish for your use case

Open the tab that matches how the phone number is collected and which OTP options you need.

Default
Prompt for Phone Number
Resend
Retry OTP
Phone Number Change

Use this path when the server already has the phone number (for example from POST /v3/start or your server Start wrapper) and the client must not prompt for it again.Call OtpStartStepCallback.onSuccess(OtpStartInput) with an OtpStartInput instance that reflects “number already known”—typically an empty string or null for the phone value, as in the snippet—so the SDK knows the customer agreed to receive the SMS.

Java

import com.prove.sdk.proveauth.OtpStartInput;
import com.prove.sdk.proveauth.OtpStartStep;
import com.prove.sdk.proveauth.OtpStartStepCallback;
import com.prove.sdk.proveauth.ProveAuthException;

public class NoPromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // No phone number needed, no need to ask end user for input.
        callback.onSuccess(new OtpStartInput(""));
    }

}

Call OtpStartStepCallback.onError() if something prevents sending the SMS (for example the customer cancels or leaves the flow with the back button).In the finish step, call OtpFinishStepCallback.onSuccess(OtpFinishInput) with the OTP the customer entered, wrapped in OtpFinishInput.

Java

import com.prove.sdk.proveauth.OtpFinishInput;
import com.prove.sdk.proveauth.OtpFinishStep;
import com.prove.sdk.proveauth.OtpFinishStepCallback;
import com.prove.sdk.proveauth.OtpValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class NoPromptFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

Use this path when the Android app collects the phone number in the client and you do not need SMS resend, dedicated OTP retry handling beyond defaults, or phone-number change. For those capabilities, use Resend, Retry OTP, or Phone Number Change.In the start step, call OtpStartStepCallback.onSuccess(OtpStartInput) with the collected number.

Java

import com.prove.sdk.proveauth.OtpStartInput;
import com.prove.sdk.proveauth.OtpStartStep;
import com.prove.sdk.proveauth.OtpStartStepCallback;
import com.prove.sdk.proveauth.PhoneNumberValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

Implement the finish step:

Java

import com.prove.sdk.proveauth.OtpFinishInput;
import com.prove.sdk.proveauth.OtpFinishStep;
import com.prove.sdk.proveauth.OtpFinishStepCallback;
import com.prove.sdk.proveauth.OtpValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class NoPromptFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

To use the Resend/Retry/Phone Change features, install the Android SDK version 6.5.0 or later.

Allow a new OTP SMS to the same number (up to three send attempts including the first).Implement the start step:

Java

import com.prove.sdk.proveauth.OtpStartInput;
import com.prove.sdk.proveauth.OtpStartStep;
import com.prove.sdk.proveauth.OtpStartStepCallback;
import com.prove.sdk.proveauth.PhoneNumberValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

Then implement the finish step so the customer can request another SMS, for example:

Java

import com.prove.sdk.proveauth.OtpFinishInput;
import com.prove.sdk.proveauth.OtpFinishStep;
import com.prove.sdk.proveauth.OtpFinishStepCallback;
import com.prove.sdk.proveauth.OtpValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class MultipleResendFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        // Prompt the user for whether they received the SMS.
        if (promptForResend("Didn't receive the SMS OTP? Click resend button for a new one!")) {
            // If the end user wants to send again to the same phone number call onOtpResend().
            otpFinishStepCallback.onOtpResend();
            return;
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

To use the Resend/Retry/Phone Change features, install the Android SDK version 6.5.0 or later.

Java

import com.prove.sdk.proveauth.OtpStartInput;
import com.prove.sdk.proveauth.OtpStartStep;
import com.prove.sdk.proveauth.OtpStartStepCallback;
import com.prove.sdk.proveauth.PhoneNumberValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

Implement the finish step—no extra client changes. If the OTP is invalid, the finish step drives retry UI until attempts are exhausted, then AuthFinish runs.

Java

import com.prove.sdk.proveauth.OtpFinishInput;
import com.prove.sdk.proveauth.OtpFinishStep;
import com.prove.sdk.proveauth.OtpFinishStepCallback;
import com.prove.sdk.proveauth.OtpValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class NoPromptFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

To use the Resend/Retry/Phone Change features, install the Android SDK version 6.5.0 or later.

Allow the customer to re-enter the phone number (up to three entries/send attempts).

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

Implement the start step:

Java

import com.prove.sdk.proveauth.OtpStartInput;
import com.prove.sdk.proveauth.OtpStartStep;
import com.prove.sdk.proveauth.OtpStartStepCallback;
import com.prove.sdk.proveauth.PhoneNumberValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class PromptStart implements OtpStartStep {
    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException otpException,
            OtpStartStepCallback callback) {
        // If phone number is needed, need to ask the end user for phone number input.
        if (phoneNumberNeeded) {
            // If error message is found around phone number, handle it.
            // The `PhoneNumberValidationException` is ONLY available when `phoneNumberNeeded`
            // has a value.
            if (otpException instanceof PhoneNumberValidationException) {
                // Set to a variable and display it in a field.
                // In this example, we don't do anything with the error.
                String errorMsg = otpException.getMessage();
            }

            try {
                // Prompt the user for phone number to receive OTP SMS. You can build UI to provide
                // best UX based on your application and business logic, here we simplify to a
                // generic function named promptForPhoneNumber which gives us the collected
                // phone number.
                String phoneNumber = promptForPhoneNumber();
                callback.onSuccess(new OtpStartInput(phoneNumber));
            } catch (Exception e) {
                // if any issue with the phone number collection from the end user or the user
                // wants to cancel then call onError to exit the flow.
                // In this example we simplify it as catching an exception.
                callback.onError();
            }
        } else {
            // No phone number needed, no need to ask end user for input.
            callback.onSuccess(new OtpStartInput(""));
        }
    }

}

Then implement the finish step so the customer can supply a new number, for example:

Java

import com.prove.sdk.proveauth.OtpFinishInput;
import com.prove.sdk.proveauth.OtpFinishStep;
import com.prove.sdk.proveauth.OtpFinishStepCallback;
import com.prove.sdk.proveauth.OtpValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

public class PhoneChangeFinish implements OtpFinishStep {
    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // If error message is found, handle it.
        if (otpException instanceof OtpValidationException) {
            // Set to a variable and display it in a field.
            // In this example, we don't do anything with the error.
            String errorMsg = otpException.getMessage();
        }

        // Prompt the user for whether they received the SMS.
        if (promptForPhoneNumberChange("Didn't receive the SMS OTP? Try a different phone number.")) {
            // If the end user wants to correct the phone number already in use, or changing to a
            // different phone number to receive the future SMS OTP, call onMobileNumberChange(), and
            // the otpStartStep will re-prompt for phone number input from the end user.
            otpFinishStepCallback.onMobileNumberChange();
            return;
        }

        try {
            // Prompt the user for OTP delivered by SMS. You can build UI to provide
            // best UX based on your application and business logic, here we simplify to a
            // generic function named promptForOtpCode which gives us the OTP code.
            String otpCode = promptForOtpCode();
            otpFinishStepCallback.onSuccess(new OtpFinishInput(otpCode));
        } catch (Exception e) {
            // if any issue with the OTP collection from the end user or the user wants to cancel
            // then call onError to exit the flow. In this example we simplify it as catching
            // an exception.
            otpFinishStepCallback.onError();
        }
    }

}

Verify the integration

In Sandbox, walk each shipped path (default, prompt, resend, retry if enabled, phone change if enabled). Confirm SMS delivery, OTP entry within the timeout, and that you never manually chain OtpFinishStep.execute on top of the SDK’s invalid-OTP handling—the SDK should remain the single orchestrator for retries and errors.

Swift

// Object implementing ProveAuthFinishStep protocols
let finishStep = FinishAuthStep()

// Objects implementing OtpStartStep/OtpFinishStep protocols
let otpStartStep = MobileOtpStartStep()
let otpFinishStep = MobileOtpFinishStep()

let proveAuthSdk: ProveAuth
proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
  .withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep)
  .build()

If a mobile data connection is unavailable during testing, use the Builder class. It permits simulated successful session results while connected to a Wi-Fi network. Testing using a Wi-Fi connection is useful in the Sandbox environment.

Swift

proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
  .withMobileAuthTestMode() // Test mode flag
  .build()

The app employs an executor service with a minimum of two threads to manage threads due to the SDK’s ability to process concurrent blocking requests.

Swift

// authToken retrieved from your server via StartAuthRequest
proveAuthSdk.authenticate(authToken) { error in
  DispatchQueue.main.async {
    self.messages.finalResultMessage = "ProveAuth.authenticate returned error: \(error.localizedDescription)"
    print(self.messages.finalResultMessage)
  }
}

Configure OTP

Use this section to configure SMS OTP fallback on iOS: wire OtpStartStep and OtpFinishStep so the SDK can send the code, collect the PIN, and optionally support resend, OTP retry, or phone-number change.

Prerequisites

After Prove sends the SMS, the customer has about two minutes to enter the OTP before the session times out.
When building the authenticator, call withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep) and implement both OtpStartStep and OtpFinishStep. The Prove client SDK orchestrates when each step runs—implement the protocols, but do not duplicate that orchestration in app code (see Invalid OTP and step orchestration below).

Invalid OTP and step orchestrationWhen the customer enters an invalid OTP, the Prove client SDK detects it (for example, a reported error such as code 10001 with a message that the PIN does not match). You may also see flow activity related to AuthFinishStep (the handler you pass to ProveAuth.builder(authFinish:)) that looks like an unexpected redirect.This behavior is expected. Do not add your own follow-up call to OtpFinishStep to pass the validation error in otpError. The SDK invokes OtpFinishStep.execute(otpError:callback:) when a retry or error UI is needed.Your app should implement the required step protocols, but the Prove client SDK orchestrates when each step runs. Do not duplicate that orchestration in application code.

Configure the client

Implement start and finish for your use case

Open the tab that matches how the phone number is collected and which OTP options you need.

Default
Prompt for Phone Number
Resend
Retry OTP
Phone Number Change

Swift

class OtpStartStepNoPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to handle phone number collection for SMS OTP,
    // or to obtain user confirmation for initiating an SMS message.
    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        // Since no phone number is needed, don't prompt the user.
        callback.onSuccess(input: nil)
    }
}

Call callback.onError() if something prevents sending the SMS (for example the customer cancels or leaves the flow with the back button).In the finish step, return the OTP the customer entered through your OtpFinishStep implementation, as in the snippet below.

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

Use this path when the iOS app collects the phone number in the client and you do not need SMS resend, dedicated OTP retry handling beyond defaults, or phone-number change. For those capabilities, use Resend, Retry OTP, or Phone Number Change.In the start step, call callback.onSuccess(input: otpStartInput) with the collected number.

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Implement the finish step:

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

To use the Resend/Retry/Phone Change features, install the iOS SDK version 6.5.1 or later.

Allow a new OTP SMS to the same number (up to three send attempts including the first).Implement the start step:

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Then implement the finish step so the customer can request another SMS, for example:

Swift

class OtpFinishStepMultipleResend: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered in the SMS message.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Update your UI to display the OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Update your UI to indicate that the provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Return the OTP value to the SDK
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Communicate to the SDK any issues when host app trys to obtain the OTP value
    // or when users cancel the OTP flow
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }

    // Call this method to request a new OTP code for the same mobile number.
    func sendNewOtp() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }
        callback.onOtpResend()
    }
}

To use the Resend/Retry/Phone Change features, install the iOS SDK version 6.5.1 or later.

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Implement the finish step—no extra client changes. If the OTP is invalid, the finish step drives retry UI until attempts are exhausted, then AuthFinish runs.

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

To use the Resend/Retry/Phone Change features, install the iOS SDK version 6.5.1 or later.

Allow the customer to re-enter the phone number (up to three entries/send attempts).

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

Implement the start step:

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Then implement the finish step so the customer can supply a new number, for example:

Swift

class OtpFinishStepWithPhoneChange: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Update your UI to display the OTP finish view.
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Update your UI to indicate that the provided OTP is invalid.
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Return the collected OTP value to the SDK.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // When callback.onMobileNumberChange() is evoked, OtpStartStep will be re-initiated
    // so that end-users can enter a different phone number via OtpStartStep.
    func handleMobileNumberChange() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set")
            return
        }
        callback.onMobileNumberChange()
    }
}

Verify the integration

In Sandbox, walk each shipped path (default, prompt, resend, retry if enabled, phone change if enabled). Confirm SMS delivery, OTP entry within the timeout, and that you never manually chain OtpFinishStep on top of the SDK’s invalid-OTP handling—the SDK should remain the single orchestrator for retries and errors.

Verify Mobile Number

In the AuthFinishStep, 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. If the user cancels the flow, 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 firstName = document.getElementById("firstNameInput");
  const lastName = document.getElementById("lastNameInput");

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

  return null;
}

Java

// Send a verify request to get return customer information.
void verify(String: authId) {
  YourBackendClient backend = new YourBackendClient(); // Backend API client

  // Build your VerifyRequest object
  VerifyRequest verifyRequest = new VerifyRequest(authId, ...);

  // Send a verify request to your backend server to get return customer information.
  VerifyResponse response = backend.verify(verifyRequest);

  // TODO: define your VerifyResponse object to parse customer information from the response
  String firstName = response.getFirstName();
  String lastName = response.getLastName();

  // Pre-fill customer information to your Android App UI, for example:
  firstNameEditText.setText(firstName);
  lastNameEditText.setText(lastName);
}

Swift

// Send a verify request to get return customer information.
// The below example uses native iOS URLSession, but any other
// alternative networking approaches should also work
func verify(authId: String, completion: @escaping (Error?) -> Void) {
    guard let url = URL(string: "\(backendUrl)/verify") else {
        completion(URLError(.badURL))
        return
    }
    // Create the request
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    // Set up the request body (empty JSON object) - authId is not needed so you can ignore.
    let body: [String: Any] = ["authId": authId]
    do {
        request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
    } catch {
        completion(error)
        return
    }
    // Perform the request
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            completion(error)
            return
        }
        // Check HTTP response status code
        if let httpResponse = response as? HTTPURLResponse,
            httpResponse.statusCode != 200 {
            let statusError = NSError(domain: "", code: httpResponse.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP error with status code: \(httpResponse.statusCode)"])
            completion(statusError)
            return
        }
        guard let data = data else {
            let noDataError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "No data received"])
            completion(noDataError)
            return
        }
        // Parse the response
        do {
            if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
                let firstName = json["firstName"] as? String,
                let lastName = json["lastName"] as? String {
                // Update the UI on the main thread
                DispatchQueue.main.async {
                    // Update your UI with the pre-fill customer information
                    // For example, assuming you have IBOutlet references for your text fields
                    // self.firstNameInput.text = firstName
                    // self.lastNameInput.text = lastName
                }
                completion(nil)
            } else {
                let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to parse JSON"])
                completion(parsingError)
            }
        } catch {
            completion(error)
        }
    }
    // Start the network call
    task.resume()
}

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.

You must complete the SDK possession check before calling /validate. If you call /validate immediately after /start without completing the Mobile Auth or OTP flow through the client-side SDK, you will receive error code 9100: Phone possession incomplete. The authToken returned from /start must be passed to the SDK’s authenticate() method, and the possession flow must complete before your backend calls /validate.

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.This function requires the Correlation ID that the Start() function returns.

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

When success is true, return the prefilled customer information to the front end. See POST /v3/challenge for the full response schema.

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 checkbox.“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;
}

Java

  // Send request to the backend to verify customer information.
  SendInfoResponse sendInfo(String firstName, String lastName) {
    YourBackendClient backend = new YourBackendClient(); // Backend API client

    // TODO: Build your SendInfoRequest object
    SendInfoRequest sendInfoRequest = new SendInfoRequest(firstName, lastName, ...);

    // Send a sendInfoRequest to your backend server to get return customer information.
    SendInfoResponse response = backend.verify(sendInfoRequest);

    // TODO: define your own SendInfoResponse object to parse the response
    return response;
  }

Swift

// Send request to the backend to verify customer information.
// The below example uses native iOS URLSession, but any other
// alternative networking approaches should also work
func sendInfo(firstName: String, lastName: String, completion: @escaping (Result<[String: Any], Error>) -> Void) {
    guard let url = URL(string: "\(backendUrl)/finish") else {
        completion(.failure(URLError(.badURL)))
        return
    }
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    // Set up the request body
    let body: [String: Any] = [
        "firstName": firstName,
        "lastName": lastName
    ]
    do {
        request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
    } catch {
        completion(.failure(error))
        return
    }
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // Handle network or connection errors
        if let error = error {
            completion(.failure(error))
            return
        }
        // Check HTTP response status code
        if let httpResponse = response as? HTTPURLResponse,
            httpResponse.statusCode != 200 {
            let statusError = NSError(domain: "", code: httpResponse.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP error with status code: \(httpResponse.statusCode)"])
            completion(.failure(statusError))
            return
        }
        guard let data = data else {
            let noDataError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "No data received"])
            completion(.failure(noDataError))
            return
        }
        do {
            if let results = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] {
                completion(.success(results))
            } else {
                let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to parse JSON"])
                completion(.failure(parsingError))
            }
        } catch {
            completion(.failure(error))
        }
    }
    // Start the network call
    task.resume()
}

Call the Complete Endpoint

This is the final server call that verifies customer information against the possession-validated phone. Call Complete() with the correlation ID from Start() and your individual payload (POST /v3/complete).

For the KYC add-on, include the attributes needed to return KYC and CIP (for example name, DOB, SSN or address). Reason codes, example responses, and field definitions are documented on POST /v3/complete.

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)
}

Return the verification outcome to your front end. See POST /v3/complete for success, next, and related fields.

Get Started

Welcome

Resources

Pre-Fill Implementation Guide

Prerequisites

Implement Prove Pre-Fill

Summary

Prerequisites

Required language placement

Configure OTP

Prerequisites

Configure the client

Configure Instant Link

Prerequisites

Configure the client

OTP

Page summary

Instant Link

Page summary

Alternate path for customers

Configure OTP

Prerequisites

Configure the client

Configure OTP

Prerequisites

Configure the client

Page summary requirements

Data entry prompt requirements

Opt out

Display fields and requirements

Get Started

Welcome

Resources

Documentation Index

​Prerequisites

​Implement Prove Pre-Fill

​Summary

​Prerequisites

​Required consent language

​Required language placement

​Configure OTP

​Prerequisites

​Configure the client

​Configure Instant Link

​Prerequisites

​Configure the client

​OTP

​Page summary

​Instant Link

​Page summary

​Alternate path for customers

​Configure OTP

​Prerequisites

​Configure the client

​Configure OTP

​Prerequisites

​Configure the client

​Page summary requirements

​Data entry prompt requirements

​Opt out

​Display fields and requirements

Prerequisites

Implement Prove Pre-Fill

Summary

Prerequisites

Required consent language

Required language placement

Configure OTP

Prerequisites

Configure the client

Configure Instant Link

Prerequisites

Configure the client

OTP

Page summary

Instant Link

Page summary

Alternate path for customers

Configure OTP

Prerequisites

Configure the client

Configure OTP

Prerequisites

Configure the client

Page summary requirements

Data entry prompt requirements

Opt out

Display fields and requirements