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:
- Create Test Transactions
- Initialize the Berbix Verify Flow
- Fetch Transaction Data
- Customize Berbix
- 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:
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: 'secret_[mode]_*',
})
require_once('/path/to/berbix-php/init.php');
$client = new \Berbix\Client(
"secret_[mode]_*");
import berbix
client = berbix.Client(
api_secret='secret_[mode]_*')
require 'berbix'
client = Berbix::Client.new(
api_secret: 'secret_[mode]_*',
environment: :production,
)
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: "tpk_*", // Template key for this transaction
})
$transactionTokens = $client->createTransaction(array(
'customerUid' => "interal_customer_uid", // ID for the user in internal database
'templateKey' => "tpk_*", // Template key for this transaction
));
transaction_tokens = client.create_transaction(
customer_uid="interal_customer_uid", # ID for the user in internal database
template_key="tpk_*", # Template key for this transaction
)
transaction_tokens = client.create_transaction(
customer_uid: 'internal_customer_uid', # ID for the user in client database
template_key: 'tpk_*', # 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:
access tokens
- used for fetching transaction verification metadata. These expire after 1 hour.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.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.
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:
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 totrue
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 theroot
attribute to specify the ID of the rootdiv
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)
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)
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!
Updated about a month ago