With this integration guide, we’ve tried to make it as easy as possible to get up and running with Berbix. In this guide, you will:

1. Generate API Keys & Whitelist Domains
2. Create Template(s)
3. Configure Actions, Action Mappings & Review Queues
4. Create Transactions
5. Initialize the Berbix Verify Flow
6. Access Transaction Data
7. Test & Move to Production

Before getting started, let's review key Berbix Verify concepts and understand how a sample application works holistically.

Key Concepts

The following Berbix concepts will be referenced throughout this guide:

• Actions: Actions are a way to customize the business logic associated with Berbix transactions and can be thought of as the "business decision" after a verification such as accept, reject, or review. Actions are triggered by Verification Status Mapping and Flag Action Mapping. Actions are included in the returned Transaction data and can be mapped to a Review Queue.
• Templates: A template represents the configuration for a Berbix Verify flow including the types of verification you'd like to conduct (photo ID, selfie, etc.) and settings for the verification flow (number of attempts, timeouts, etc.).
• Themes: Themes can be used to customize the look-and-feel of your Berbix Verify experience. Themes are associated with a template.
• Transactions: Transactions are the core component of Berbix Verify and represent a user verification.
• Review Queues: Review Queues contain new transactions that may require additional manual verification.

Token Types

There are three token types associated with any given transaction within Berbix:

• access_token: short-lived (one hour) token that enables your backend to fetch data about a given transaction.
• client_token: short-lived (one hour) token that connects the Berbix frontend with a given transaction.
• refresh_token: long-lived token that may be used to regenerate the other two tokens.

End-to-End Application Workflow

Before integrating Berbix Verify, it's helpful to understand how all of the key integration concepts fit together. We recommend reading the Verify Flow Overview to also understand how the application workflow relates to the end-user experience.

The typical end-to-end application workflow is:

1. An end-user in your application flow needs to perform some form of identity verification. The identity verification desired is defined by your selected template.
2. Before initiating the verification flow, your application creates a new Berbix transaction associated with a customer_uid and template_key, which returns an associated access_token, refresh_token, and client_token.
3. Your application stores the refresh_token alongside your user record, which is used to generate a access_token and client_tokens in future requests.
4. Your application sends the generated client token for the transaction to your frontend to initialize the Berbix flow.
5. The end-user performs the selected form of identity verification and their details are sent directly to Berbix for validation.
6. Upon completion, the Berbix frontend SDK triggers a successful callback hook or an error if verification is unsuccessful.
7. Your application fetches the metadata for a successful verification using the transaction's access token.
8. Your backend sends the returned action the your client to determine the user experience.

Generating API Keys

You can generate your API keys by visiting the Berbix Dashboard settings and following these instructions. Please use Test API keys when integrating Berbix in a non-production environment.

Whitelist Domains

You'll need to next add the domains from which you expect to serve Berbix Verify. Please see our domains documentation for instructions.

Templates control the experience for your end-users and enable you to specify differing levels of verification required for different user account types. Templates include the types of verification you'd like to conduct (photo ID, selfie, etc.) and settings for the verification flow (number of attempts, timeouts, etc.).

To integrate Berbix, you'll need to create at least one template. Please see our templates documentation for instructions on how to create and configure a template. At a minimum, you should decide what types of IDs are allowed as well as if you need to require a selfie image and liveness check. For details on these features, please refer to the Verify Flow Overview.

You optionally may want to create a custom theme associated with your template(s). Themes configure the look-and-feel of your verification flow.

A Template Key is generated after template creation. You'll later use this key as a configuration option when invoking Berbix Verify to determine what experience your end user is presented.

Once you've defined what your users will need to complete, you'll need to determine how you process and respond to the data they provide. To do so, you'll:

• Utilize Actions to define possible decisions (accept, reject, review, etc.)
• Map ID Flags to define how actions are determined
• Configure Review Queues to manually process transactions based on the determined action (such as review).

These settings are highly dependent on your business logic and are custom to each integration. Let us know how we can help configure Berbix to meet your verification needs!

Actions

Actions are a way to customize the business logic associated with Berbix transactions and can be thought of as the "business decision" after a verification. When implementing Berbix, you'll need to determine the actions you want to take after a verification is completed. By default, Berbix provides three actions: reject, review, and accept.

Please refer to Actions to learn how to create and modify an action.

The determined action after a verification will be returned in the transaction metadata and exposed in the Berbix Dashboard for a given transaction.

Action Mappings

Actions themselves are determined based on their status and flag mappings. For Berbix to compute the appropriate action, you'll need these two mappings:

1. Verification Status Mapping
2. Flag Action Mappings

The verification status and flags will also be returned in the transaction metadata and exposed in the Berbix Dashboard for a given transaction.

Review Queues

Review Queues enable Berbix Dashboard users or agents to manually determine an action when the transaction data is not explicit enough to automatically make a business decision. Review Queues are populated by transactions based on their determined action.

For example, you may send all transactions with a review action to a manual review queue. You can learn how to create and configure Review Queues here.

Now that you've defined your business logic, you're now ready to integrate the Berbix Verify API into your backend to start creating transactions.

The Berbix Verify API can be called from any basic HTTP client. Berbix provides several Server-Side SDKs to simplify interactions with the API:

• Node
• PHP
• Python
• Ruby

Constructing the Berbix Client

Before creating a transaction, you'll first need to construct the Berbix API client.

If you're using one of our Server-Side SDKs, you can initialize the Berbix client by following the example code below for your selected SDK. You'll need to include your clientId and clientSecret.

var berbix = require('berbix');

var client = new berbix.Client({
  clientId: 'your_client_id_here',
  clientSecret: 'your_client_secret_here'
})

require_once('/path/to/berbix-php/init.php');

$client = new \Berbix\Client(
  "your_client_id_here",
  "your_client_secret_here");

import berbix

client = berbix.Client(
  client_id='your_client_id_here',
  client_secret='your_client_secret_here')

require 'berbix'

client = Berbix::Client.new(
  client_id: 'your_client_id_here',
  client_secret: 'your_client_secret_here'
)

Creating a Transaction

To create a transaction, you just need to send a customerUid and templateKey along in the API request. The customerUid should map to the primary key you use for your users in your internal systems and the templateKey should map to the Berbix template you want to use to verify your user.

var transactionTokens = client.createTransaction({
  customerUid: "interal_customer_uid", // ID for the user in internal database
  templateKey: "your_template_key", // Template key for this transaction
})

$transactionTokens = $client->createTransaction(array(
  'customerUid' => "interal_customer_uid", // ID for the user in internal database
  'templateKey' => "your_template_key", // Template key for this transaction
));

var transactionTokens = client.createTransaction({
  "customer_uid": "interal_customer_uid", // ID for the user in internal database
  "template_key": "your_template_key", // Template key for this transaction
})

transaction_tokens = client.create_transaction(
  customer_uid: 'internal_customer_uid', # ID for the user in client database
  template_key: 'your_template_key', # Template key for this transaction
)

A access_token, client_token, and refresh_token will be returned in the response as shown in the example below. Please refer the Create transaction reference documentation for a full request and response format specification.

{
"transaction_id":5689410907470336
"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1dsfsWQiOjU2NzYwNDE5MDc0NzAzMzYsImNpZCI6NTYzNDQ3MjU2OTQ3MDk3Niw"
"refresh_token":"x9iBVHQUVqx9sHGjRyTAEBOdsD23Wxld"
"expires_in":3600
"token_type":"Bearer"
"client_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ8dsdfsaWQiOjU2NzYwNDE5MDc0NzAzMzYsImNpZCI6NTYzNDQ3MjU2OTQ3MDk3Niw"
}

After successfully creating a transaction, you'll need to store the refresh_token in your application database associated with the respective customerUid. This refresh token is a long-lived token that may be used to regenerate an access_token or client_token in the future.

The returned client_token needs to be passed to your frontend and will be used in the subsequent step to initialize the frontend Berbix Verify user flow. The returned access_token will be used to fetch the metadata about the transaction after your end user completes the Berbix Verify flow.

There are several ways you can integrate Berbix Verify into your user-facing flows. At present, Berbix provides the following Client-Side SDKs:

• Basic JavaScript
• Angular
• Native iOS
• Native Android
• React
• React Native
• Vue

Basic JavaScript

When your page loads, you should create a handler via BerbixVerify.configure(). The verification flow can then be initialized by calling open() on the handler in response to any user events.

The simple example below initializes the Berbix flow in the #berbix-root element and when a user clicks the Verify Me button.

<button id="myButton">Verify Me</button>
<div id="berbix-root"></div>

<script src="https://sdk.berbix.com/latest/berbix-verify.js"></script>

<script>
  var handler = BerbixVerify.configure({
    clientId: 'your_client_id',
    onComplete: function() {
    },
  })

  document.getElementById('myButton').addEventListener('click', function(e) {
    handler.open({
      clientToken: 'your_client_token',
      root: 'berbix-root'
    });
  });
</script>

Upon completion of the verification flow, Berbix Verify will trigger the onComplete callback that can be used to advance the user through your application. If verification fails for any reason, Berbix Verify will invoke the onError callback.

Configuration

Required

• clientId: The client ID as generated in your API Key settings.
• clientToken: A token returned after creating a transaction that connects your frontend with the associated transaction meta. This allows a user to perform incremental verification in addition to any previously completed verifications. A client token can be regenerated using Create access token if necessary.
• onComplete: The callback invoked when Berbix Verify completes.
• root: The id of a <div> where Berbix Verify will render. If possible, keep the element visible on initial render (that is, don’t do display: none on the root).

Optional

• email: The email address of the verifying user, if it has already been collected prior to starting verification. If it is not provided or if it is malformed, Berbix Verify will collect it.
• phone: The phone number of the verifying user formatted as E.164, if it has already been collected prior to starting verification. If it is not provided or if it is malformed, Berbix Verify will collect it.
• onDisplay: The callback invoked when Berbix Verify is visible to the user. This is useful for removing loading states or hiding other elements.
• onError: The callback invoked when verification fails. It is passed any reason for failure as a parameter.

Once a verification completes, you'll need to consume the metadata about a transaction to determine next steps for your end-users.

Create Access Token from Refresh Token

To fetch metadata for a given transaction, you first need an access_token for the associated transaction. A short-lived access_token is returned in the transaction creation response but you'll often need to regenerate an access_token for later requests.

If you're using one of our Server-Side SDKs, you can utilize the example code below for your selected SDK. You'll need to load the transaction's refresh_token from your application database.

// Load refresh token from database
var transactionTokens = berbix.Tokens.fromRefresh(refreshToken)

$refreshToken = ''; // fetched from database
$transactionTokens = new \Berbix\Tokens::fromRefresh($refreshToken);

refresh_token = '' # fetched from database
transaction_tokens = Tokens.from_refresh(refresh_token)

refresh_token = '' # fetched from database
transaction_tokens = Berbix::Tokens.from_refresh(refresh_token)

If you're not using one of our Server-Side SDKs, you'll need to make a request including the refresh_token to the /tokens endpoint and the associated access_token will be included in the response. Complete documentation for the Berbix /token endpoint is available in our API reference.

Fetch Transaction Data

After generating the access_token, you'll then pass this to the /transactions endpoint to get all associated transaction data.

If you're using one of our Server-Side SDKs, you can reference the code samples below. Otherwise, please refer to our Get transaction verifications API spec.

var transactionData = await client.fetchTransaction(transactionTokens)

$transactionData = $client->fetchTransaction($transactionTokens);

transaction_data = client.fetch_transaction(transaction_tokens)

transaction_data = client.fetch_transaction(transaction_tokens)

All data for the given transaction will be returned in the response as shown in the example below. A complete list of properties returned is defined in our API Reference.

{
  "action": "reject",
  "addons": null,
  "created_at": "2019-07-02T21:18:43Z",
  "customer_uid": "123456789",
  "dashboard_url": "https://dashboardberbix.com/transaction?orgId=123456789&transactionId=123456789123",
  "duplicates": [...],
  "flags": [...],
  "fields": [...],
  "images": {...}
}

Most notably, you'll want to consume the action value (accept, reject, etc.) to determine next steps for your verified end-user.

You can likely rely on the action value for your business logic if you've properly configured your flag action mappings. In certain cases, you may need to reference the raw flags (id_fake_likely, id_under_18, etc.) or the fields data (address, date_of_birth, cropped_front_url, etc.).

Receive Actions via Webhooks

You may alternatively implement receive the transaction ID and the determined action via a webhook when verification is complete. Please see our webhook docs to implement.

Once you've integrated the transaction data into your application logic, you're now ready to complete and end-to-end test of your Berbix integration. Assuming all goes well, you can move your integration to production by simply replacing your Test API Keys with Live values.

Please don't hesitate to reach out if you have any questions!