React

General
This document explains how to integrate the verification flow directly from your React application through our Javascript component to verify the identity of your users. This stage might be at the signup page of your application, or at a later point to enrich the profiles of your users. The guide assumes the preliminary steps have already been completed as explained in the initial setup section of the documentation.
We suggest you follow our best practice how to integrate Passbase in your wider system in the overview section.
You can either follow the integration guide below or also watch the video below that shows an integration. Please be aware that some property or function names might have slightly changed. Just compare to the latest code snippets here in the documentation.
​
1. Install the Package
Start by installing our component and its dependencies in your React project:
npm
yarn
1
$ npm i --save @passbase/button
Copied!
1
$ yarn add @passbase/button
Copied!
2. Render the Component
Import the React component from the newly installed npm package. 
The package supports UMD modules, the ES import method is presented below.
src/App.js
1
import VerifyButton from "@passbase/button/react";
Copied!
In order for the button to render correctly, you'll need to pass your previously generated apiKey as argument to the rendering function. Optionally you can also pass in handler functions like onFinish, onStart and onError to control the states of the button flow.
​
Property
Description
apiKey
The public API Key you obtained from the developer dashboard
onFinish: (identityAccessKey: string) => void
Method that is being called once a user clicks the "Finish" button
identityAccessKey: UUID of the completed verification. You can use this to query our API.
onSubmitted: (identityAccessKey: string) => void
Method that is being called once verification data is submitted to Passbase
identityAccessKey: UUID of the completed verification. You can use this to query our API.
onError: (errorCode: string, context: { step: StepID }) => void
errorCode:  The reason why the flow failed. Can be one of the following:
"CANCELLED_BY_USER" | "BIOMETRIC_AUTHENTICATION_FAILED" | "UNSUPPORTED_BROWSER"
context: Additional error context information (contains the step where the error occurred)
StepID: 
The step where the error occurred, can be one of the following
"START" | "CONSENT" | "EMAIL" | "COUNTRY" | "RESOURCE CHOICE" | "RESOURCE | "SUMMARY" | "FINISHED"
onStart: () => void
Method that is being called once a user starts the verification flow
hidden
A boolean value used to visually hide the verification button. Can be used in tandem with start() method to create a custom button UI.
src/App.js
1
function App() {
2
  return (
3
    <div className="App">
4
      <VerifyButton
5
        apiKey={"YOUR_API_KEY"}
6
        onSubmitted={(identityAccessKey) => {}}
7
        onFinish={(identityAccessKey) => {}}
8
        onError={(errorCode) => {}}
9
        onStart={() => {}}
10
      />;
11
    </div>
12
  );
13
}
Copied!
Make sure you're using the publishable API key for this client side integration
The button should now render as shown here:
Speed Up the Verification Flow
During the verification flow, your users will be asked to provide some information which you might already have in your application e.g. the user's email. In this case, you can use the prefillAttributes object to skip the email step. 
When the Biometric Authentication feature is enabled and the email is prefilled, Passbase will check if the user is already verified on our platform. If yes, the flow will enter the Biometric Authentication mode. If not, the user enters the normal verification flow and has to provide all required documents selected in your developer dashboard's customization section.
Property
Value
prefillAttributes
email:  Your user's email. This will enable skipping the email step.
​
country: An ISO-3166 compliant country code. This will set the default dropdown selection of the country selection screen.
1
<VerifyButton
2
  apiKey={"YOUR_API_KEY"}
3
  onFinish={(identityAccessKey) => {}}
4
  prefillAttributes={{
5
    email: "[email protected]",
6
    country: "de"
7
  }}
8
/>
Copied!
Identity Access Key as Reference
In order for your application to interoperate with Passbase, you will need to add a reference to your users once the Verification is completed.
For that, you will need to keep track of the identityAccessKey returned by the onFinish or onSubmitted callbacks and associate it in your backend with your end users' id. We recommend saving this key after the onSubmitted method from your user's completed verification, or listen for the incoming webhooks to make a call to the Passbase API linking back the email address of the user.
1
import React from 'react';
2
import VerifyButton from "@passbase/button/react";
3
​
4
function App() {
5
  const referenceUserWithKey = (key) => {
6
    console.log(key)
7
    // Make request to your backend/db and save the key to the user's profile
8
  }
9
​
10
  return (
11
    <div className="App">
12
      <VerifyButton
13
        apiKey={"YOUR_PUBLISHABLE_API_KEY"}
14
        onSubmitted={(identityAccessKey) => {
15
          referenceUserWithKey(identityAccessKey)
16
        }}
17
        onFinish={(identityAccessKey) => {}}
18
        onError={(errorCode) => {}}
19
        onStart={() => {}}
20
        prefillAttributes={{
21
          email: "[email protected]"
22
        }}
23
      />
24
    </div>
25
  );
26
}
27
​
28
export default App;
Copied!
MetaData for additional User References 
If you are tracking end users in your backend through an internal UUID, transaction number, stripe ID, etc., you can use the metaData object to securely pass encrypted end user information to identify completed verifications. 
The metaData object allows you to pass an encrypted JSON string via a private key encoded in base64 on the client-side, and then Passbase will use your public key to return the data on the Passbase API.
Add Encryption Key to your Project
Encryption should be completed on the server-side. Once you have completed the encryption, please enter the public encryption keys for each individual project within the developer dashboard. 
​Click here to view metaData encryption documentation.
Pass metaData Object
After adding the public encryption keys within the developer dashboard, you will need to pass the private key encoded in base64 to Passbase through the client-side.
​
Value
metaData
Encrypted JSON string via the private key encoded in base64
1
import React from 'react';
2
import VerifyButton from "@passbase/button/react";
3
​
4
function App() {
5
  const referenceUserWithKey = (key) => {
6
    console.log(key)
7
    // Make request to your backend/db and save the key to the user's profile
8
  }
9
​
10
  return (
11
    <div className="App">
12
      <VerifyButton
13
        apiKey={"YOUR_PUBLISHABLE_API_KEY"}
14
        onSubmitted={(identityAccessKey) => {
15
          referenceUserWithKey(identityAccessKey)
16
        }}
17
        onFinish={(identityAccessKey) => {
18
        // Open new window for end user to prevent duplicate verifications
19
          window.location.href =("https://passbase.com/")
20
        }}
21
        onError={(errorCode) => {}}
22
        onStart={() => {}}
23
        prefillAttributes={{
24
          email: "[email protected]"
25
        }}
26
        // Signed and Armored Metadata, which contain {internal_customer_id: "XYZ", "email": "[email protected]", "country": "de", ...}
27
        metaData={{
28
          "AJIZZDIZJADIOAJDOIZJAOIZJDOIAJIODZJIAJDIOZJAIOZDJALANLIKESJIZZOIZDJAOIZJDOZIAJDOIAZJDAZD"
29
        }}
30
      />
31
    </div>
32
  );
33
}
Copied!
Retrieve MetaData from Passbase API
After a user completes a verification and you receive the VERIFICATION_REVIEWED webhook event, it is time to call the Passbase Get Identity endpoint.  Using this API endpoint, you will see the new metaData object returned.
If the public encryption key is not added to the developer dashboard, you will not see the metaData information returned on the API.
1
{
2
   id: "1234-1234-1234-1234",
3
   resources: [...],
4
   metadata: { internal_customer_id: "XYZ" }
5
}
Copied!
Start Verification Flow Programmatically
If you wish to start the verification programmatically you can do so by invoking the start method with code.
1
import React, { useEffect } from "react";
2
import VerifyButton, { start } from "@passbase/button/react";
3
​
4
export default function App() {
5
  useEffect(() => {
6
    setTimeout(() => {
7
      start();
8
    }, 5000);
9
  }, []);
10
​
11
  return (
12
    <div className="App">
13
      <VerifyButton
14
        apiKey={"YOUR_PUBLISHABLE_API_KEY"}
15
        onSubmitted={(identityAccessKey) => {}}
16
        onFinish={(identityAccessKey) => {}}
17
        onError={(errorCode) => {}}
18
        onStart={() => {}}
19
      />
20
    </div>
21
  );
22
}
Copied!
3. UI Customizations
Appearance
Our component currently supports a set of customization options which will influence the appearance of the modal, once opened. The preferred way to customize this is via your developer dashboard's customization section.
Here you can choose amongst a variety of colors, fonts, accepted countries & much more.
Customization Section
The modal also supports a darkMode attribute, which supersedes the effects of any customization selected within the developer dashboard. This is especially useful if your App has a dark UI or you simply want to spare your users' eyes at night. You can activate the darkmode via the theme attribute.
Property
Value
theme
darkMode: A boolean value indicating whether or not to enable the dark theme
​
systemDarkMode: A boolean value indicating whether the dark mode setting of the users OS should be applied (see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
1
<VerifyButton
2
  apiKey={"YOUR_API_KEY"}
3
  onFinish={(identityAccessKey) => {}}
4
  theme={{
5
      darkMode: true,
6
      systemDarkMode: true
7
  }}
8
/>;
Copied!
Dark Mode
Language 
We support a variety of different languages for the verification flow. As of this writing more than 10 including (English, Spanish, German & many more). If one is missing and you want us to add support for it, please reach out to our customer support.
The Verification flow automatically detects the language of the user's browser settings. If we support the language, the verification flow will be set to it. Otherwise the default is English.
Custom UI Button
If you wish to customize the appearance of the Verification button you may do so by following the example:
1
import React from "react";
2
import VerifyButton, { start } from "@passbase/button/react";
3
​
4
export default function App() {
5
  return (
6
    <div>
7
      <button onClick={() => start()}>Custom Button</button>
8
      <div className="App">
9
        <VerifyButton
10
          apiKey={"YOUR_PUBLISHABLE_API_KEY"}
11
          onSubmitted={(identityAccessKey) => {}}
12
          onFinish={(identityAccessKey) => {}}
13
          onError={(errorCode) => {}}
14
          onStart={() => {}}
15
          hidden={true}
16
        />
17
      </div>
18
    </div>
19
  );
20
}
21
​
Copied!
Wrap-up & Example
If you've followed this integration guide, you have successfully integrated Passbase in your Website. You can also check out the code below that shows a working example and compare it with your own solution. To run the code press the Open Sandbox button in the lower right corner.
The demo needs to be in an window in order for the Javascript to work & render the Passbase verification flow. Hence open the Sandbox and then click the Open in New Window button in the top right corner to open the rendered page in a new tab.
You can also find a fully working React application in our Github repositories.​
You have successfully completed the Passbase React Integration! 🎉