Berbix

Berbix Docs

Welcome to the Berbix docs! Here you’ll find comprehensive information for integrating Berbix Verify and its associated APIs as well as an overview of Berbix Dashboard functionality.

The fastest way to integrate Berbix Verify is to follow our Integration Guide, which walks through your entire Berbix integration step-by-step. You’ll integrate Berbix Verify into your site or app and then use one of our SDKs to retrieve the data you need from our API. You'll also be guided through the configuration of verification workflow rules to map to your existing business logic.

You can see the full Berbix Verify API specification in our API Reference Docs and find functional documentation for the Berbix Dashboard here.

If you have any questions, please don't hesitate to reach out to us at [email protected] or via your organization's shared Slack channel.

Docs & Guides    API Reference

Settings

API Keys

You can generate your API keys by visiting the Berbix Dashboard and navigating to your settings by clicking the gear icon in the top navigation.

Within Settings > API Keys you can create a new API Secret by clicking Add Key. Live API Secrets should be used in production environments and Test API Secrets should be used in testing environments. API secrets are prefixed in the following format: secret_[mode]_ where mode is either live or test.

Never include your API secret(s) in client-side code

Your API secret(s) are required for requests to create transactions or fetch verification data. They should never be shared in client-side and only used for server-side API requests.

Domains

To prevent misuse of your API credentials, the Allowed Domains list whitelists a specified set of domains from which you expect to serve Berbix Verify. In the event that we see a request for verification from an unspecified domain, we’ll return an API error when opening the verification flow.

To add a domain, simply click Add Domain, provide your domain name and click Submit. Domains are associated with Test or Live environments.

HTTPS Required in Live Mode

Your domain and the pages hosting Berbix Verify must be being served over HTTPS in live mode. Test mode supports HTTP pages.

Team

Team settings presents the list of all Team Members that have access to the Berbix Dashboard and their respective roles. You can also Invite new team members from this view as an Admin.

There are three roles available with access to Live and Test mode data:

  1. Admin: can edit all settings.
  2. Developer: can edit all settings with the exception of Team and Billing settings.
  3. Agent: can only edit manual review actions. This user only has access to view Transactions and Reviews.

You additionally create a Test mode only Agent role who only has access to Test mode Transactions and Reviews.

Webhooks

Webhooks fire to a specified endpoint when a transaction event occurs. There are two types of transaction events:

  • Verification finished: when the user completes a verification.
  • Verification status changed: when the verification status changes.

The action associated with the event will be included in the webhook payload. Webhooks are associated with Test or Live environments.

Within the webhook configurator, you can also find the Hook Secret to be used for signtaure validation (see below) and Test your endpoint by issuing a sample webhook.

The example below shows a sample notification webhook payload which includes:

  • id: webhook event ID.
  • user_id: deprecated field (please use transaction_id)
  • transaction_id: ID for associated transaction
  • customer_uid: customer UID associated with the transaction
  • action: actions associated with the transaction.
{
  "id": 012346547912823
  "user_id": 123456789012 // Deprecated field (use transaction_id instead)
  "transaction_id": 123456789012
  "customer_uid": "abc1234567"
  "action": "reject"
}

Webhooks can be validated using the validateSignature method available in Berbix Server-Side SDKs. This method requires the following parameters:

  • secret - This is the secret associated with that webhook available in the webhook settings page.
  • body - The full request body from the webhook. This should take the raw request body prior to parsing.
  • header - The value in the X-Berbix-Signature header.

Test IDs

Test IDs allow you to specify the list of IDs you intend to use in test mode by providing the Last Name for the IDs used in test mode. Berbix will return sample data for test verifications whose documents are not included in the list of Test IDs. Please read Live & Test Mode for more information on how Berbix handles test mode verifications.

Notifications

Notifications let you configure what Queues should trigger notifications when transactions are added to them. They should be used to notify individuals to visit the Berbix Dashboard to manually review a transaction in a review queue.

There are two notification types:

  • Email: sends an email notification to a given email address.
  • Webhook: delivers a webhook to a given endpoint.

Notifications are associated with Test or Live environments.

In the example below, Berbix will notify [email protected] via email for new transactions add to the Rejections queue and deliver a webhook to http://example.com/api/berbix for new transactions added to the Accepted queue.

The example below shows a sample notification webhook payload which includes:

  • user_id: deprecated field (please use transaction_id)
  • transaction_id: ID for associated transaction
  • code: an authorization code that can be used to create new access tokens for the transaction. Please see Create access token for details on how to pass your authorization_code to the /tokens endpoint.
  • dashboard_link: Berbix dashboard URL for transaction. Please see Transactions to review all the data that is shown on the transaction page.
{
  "user_id": 1234123412341234 // Deprecated field (use transaction_id instead)
  "transaction_id": 1234123412341234
  "code": 1234123412341234
  "dashboard_link": "https://dashboard.berbix.com/transaction?orgId=5634472569470976&transactionId=5260092142256128"
}

Updated 2 months ago

Settings

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.