Introduction

With this integration guide, we’ve made it as easy as possible to quickly get up and running with an end-to-end embedded Berbix integration. Please see our Hosted Flow if you're only looking to create unique links to share with your customers.

In this guide, you will:

1. Create Test Transactions
2. Initialize the Berbix Verify Flow
3. Fetch Transaction Data
4. Customize Berbix
5. Move to Production

We recommend reading our Platform Overview for a look at key concepts and a diagram of an end-to-end integration. A sample open-source Ruby integration is available for review on our GitHub.

Create Test Transactions

To begin, you'll integrate the Berbix Verify API into your backend to start creating test 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
• Go
• Java

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 test API Secret.

You can find your API secret by visiting the Berbix Dashboard settings and following these instructions. Please use Test API secret when integrating Berbix in a non-production environment. Your account will have one Test API secret by default.

var berbix = require('berbix');

var client = new berbix.Client({
  apiSecret: '<<user>>',
})

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

$client = new \Berbix\Client(
  "<<user>>");

import berbix

client = berbix.Client(
  api_secret='<<user>>')

require 'berbix'

client = Berbix::Client.new(
  api_secret: '<<user>>',
)

BerbixClient berbixClient = Berbix.create(
    new Berbix.BerbixOptions.Builder()
        .apiSecret("<<user>>")
        .build());

import "github.com/berbix/berbix-go"

client := NewClient("<<user>>", &ClientOptions{})

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. You will have a Default template for web integrations configured for a front & back ID check in your account by default. Please create a new template for native mobile integrations.

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

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

transaction_tokens = client.create_transaction(
  customer_uid="interal_customer_uid", # ID for the user in internal database
  template_key="<<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: '<<template_key>>', # Template key for this transaction
)

CreateTransactionRequest request = new CreateTransactionRequest();
request.customerUid = "interal_customer_uid"; // ID for the user in internal database
request.templateKey = "<<template_key>>"; // Template key for this transaction

CreateTransactionResponse response = berbixClient.createTransaction(request);

tokens, err := client.CreateTransaction(&CreateTransactionOptions{
    CustomerUID: "internal_customer_uid", // ID for the user in client database
    TemplateKey: "<<template_key>>", // Template key for this transaction,
})

An 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"
}

In general, interacting with the Berbix API involves 3 types of tokens:

1. access tokens - used for fetching transaction verification metadata. These expire after 1 hour.
2. client tokens - intended to be rendered in the frontend user facing part of the flow (i.e. used by Javascript in the browser or similar). These expire after 1 hour.
3. refresh tokens - long lived tokens used to fetch an access token. These remain valid until a transaction is deleted (either manually in the dashboard, programmatically via the API or automatically via retention policy).

After successfully creating a transaction, store the refresh_token in your application database associated with the respective customerUid. This refresh token is a long-lived token that should be used to regenerate an access_token in the future for fetching, updating or deleting transaction data. See below section Create Access Token From Refresh Token for more on using refresh_tokens.

Please note that every time the create_transaction endpoint is called, a new transaction is created (even if it is called with the same customer_uid since we allow for multiple transactions for a given customer_uid). It is often helpful to include a check when creating a transaction to see if a refresh_token exists for a given user before calling create_transaction in order to re-open the pending transaction. Without checking for a pending transaction, a user could inadvertently create multiple transactions (e.x. by refreshing the page that renders the Berbix flow if that page triggers a call to create_transaction). While we charge based on completed transactions, it is best to minimize the number of incomplete transactions in order to keep things tidy.

The returned short-lived client_token needs to be passed to your frontend and is used to initialize the frontend Berbix Verify user flow. The returned short-lived access_token will be used to fetch the metadata about the transaction after your end user completes the Berbix Verify flow.

Creating hosted transactions

In order to create a hosted transaction, you'll need to include the hosted_options parameter in your Create transaction request. This parameter can be an empty object (hosted_options={}) if you don't require additional configuration. When provided, Berbix will return a hosted verification link that is unique to each transaction in the hosted_url response field.

Initialize the Berbix Verify Flow

There are several ways you can integrate Berbix Verify Flow Berbix Verify into your application. In addition to Basic JavaScript, Berbix provides the following Client-Side SDKs across web and mobile:

• Angular
• Cordova
• 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 when a user clicks the Verify Me button.

Upon completion of the verification flow, Berbix will trigger the onComplete callback that can be used to advance the user through your application. Berbix will invoke the onError callback if the verification fails for any reason and the onExit when someone closes the Berbix modal.

<button id="myButton">Verify Me</button>

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

<script>
  var handler = BerbixVerify.configure({
    onComplete: function() {
    },
    onExit: function() {
    }
  });

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

Configuration

Required

• clientToken: A token returned after creating a transaction that connects your frontend with the associated transaction metadata. 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.
• modal: This value should be set to true unless you intend to use Berbix in an embedded element on the page rather than a modal invoked after button click. To use Berbix in an embedded element on the page, use the root attribute to specify the ID of the root div in which Berbix should be embedded.
• onComplete: The callback invoked when Berbix Verify completes.
• onExit: The callback invoked when a user exits or closes the Berbix Verify modal. Required when using the modal experience.

Optional

• 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.

🚧

Allowlist domains serving Berbix

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

Fetch Transaction Data

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.

refreshToken = ''; // fetched from database
// Load refresh token from database into a Token object
const transactionTokens = berbix.Tokens.fromRefresh(refreshToken);

// Call Berbix API to exchange refreshToken for fresh tokens. 
// This is typically not needed to be called explicitly as it will be called 
// by the higher-level SDK methods, but can be used to get fresh client or 
// access tokens.
const refreshedTokens = client.refreshTokens(transactionTokens);

$refreshToken = ''; // fetched from database
// Load refresh token from database into a Token object
$transactionTokens = new \Berbix\Tokens::fromRefresh($refreshToken);

// Call Berbix API to exchange refreshToken for fresh tokens. 
// This is typically not needed to be called explicitly as it will be called 
// by the higher-level SDK methods, but can be used to get fresh client or 
// access tokens.
$refreshedTokens = $client->refreshTokens($transactionTokens)

refresh_token = '' # fetched from database
# Load refresh token from database into a Token object
transaction_tokens = Tokens.from_refresh(refresh_token)

# Call Berbix API to exchange refreshToken for fresh tokens. 
# This is typically not needed to be called explicitly as it will be called 
# by the higher-level SDK methods, but can be used to get fresh client or 
# access tokens.
refreshed_tokens = client.refresh_tokens(transaction_tokens)

refresh_token = '' # fetched from database
# Load refresh token from database into a Token object
transaction_tokens = Berbix::Tokens.from_refresh(refresh_token)

# Call Berbix API to exchange refreshToken for fresh tokens. 
# This is typically not needed to be called explicitly as it will be called 
# by the higher-level SDK methods, but can be used to get fresh client or 
# access tokens.
refreshed_tokens = client.refresh_tokens(transaction_tokens)

refreshToken := "" // fetched from database
// Load refresh token from database into a Token object
transactionTokens := TokensFromRefresh(refreshToken)

// Call Berbix API to exchange refreshToken for fresh tokens. 
// This is typically not needed to be called explicitly as it will be called 
// by the higher-level SDK methods, but can be used to get fresh client or 
// access tokens.
refreshedTokens, err := client.RefreshTokens(transactionTokens)

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 API Libraries , 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)

transactionData, err := client.FetchTransaction(transactionTokens)

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 importantly, 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 action mapping. 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

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

Customize Berbix

You've now built a fully functional end-to-end Berbix integration! Before moving to production, you'll want to customize the required verification steps, the look-and-feel, and the business logic behind your integration.

Custom Template

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

Custom Theme

You optionally may want to create a custom theme associated with your template(s). Themes configure the look-and-feel of your verification flow. Theme customization is currently only supported for web templates.

Custom 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. Review Queues are populated by review actions.

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.

Move to Production

At this point, you'll be able to test a fully customized Berbix flow in your own application. Please refer to our Testing Guide for instructions on how to best test Berbix end-to-end. Assuming all goes well, you can move your integration to production by simply replacing your Test API Secret with a corresponding Live value.

You'll need to accept our terms and subscribe to Berbix before gaining access to live mode. Please don't hesitate to contact us if you have any questions!