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.
To add wildcards to your domain name, use the * character.
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 four roles available with access to Live
and Test
mode data:
Admin
: can edit all settings and see analytics.Developer
: can edit all settings with the exception ofTeam
andBilling
settings.Agent
: can only edit manual review actions. This user only has access to allTransactions
, including those that have been completed, andReviews
. Agents cannot delete transactions, but can block them.Reviewer
: only has access toTransactions
that are enqueued for review, and they are able to take action on them (accept/reject/escalate/block). Once a transaction has been actioned upon, the reviewer can no longer access it. Reviewers cannot delete transactions.


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 status changed
: when the verification result status has been updated. This should be used to respond to action changes after manual review.Verification finished
: when the user completes a verification. This should only be utilized in unique circumstances as your application should typically respond to the client-side completion handler.
Webhooks are associated with Test
or Live
environments.
To test webhooks locally during development, you can set up a URL that redirects to localhost
using ngrok.


Verification status changed event
The Verification status changed
event hook can be used to update the verification action after a manual review in the Berbix dashboard.
The example below shows a sample verification finished webhook payload which includes:
id
: webhook event ID.transaction_id
: ID for associated transactioncustomer_uid
: customer UID associated with the transaction. This is omitted if not provided at transaction creation time.action
: actions associated with the transaction. This is the updated verification action post manual review.dashboard_link
: a URL to the corresponding transaction in the Berbix dashboard.
{
"id": 012346547912823,
"transaction_id": 123456789012,
"customer_uid": "abc1234567", // Omitted if not provided at transaction creation time
"action": "reject",
"dashboard_link": "https://dashboard.berbix.com/transaction?orgId=123456789&transactionId=123456789"
}
Verification finished event
The Verification finished
event hook can be used to notify your backend that a verification is complete and ready for data to be fetched via the API. This can be used in lieu of responding to the client-side completion handler in unique circumstances.
This is the recommended way to get notified on that a verification is complete for the Hosted Flow only. Please contact us if you are not using the Hosted Flow but believe that your integration requires consuming this webhook.
The example below shows a sample verification finished webhook payload which includes:
user_id
: deprecated field (please usetransaction_id
)transaction_id
: ID for associated transactioncode
: deprecated field used for fetching verification data (use the access token instead returned in transaction creation API response)customer_uid
: customer UID associated with the transaction. This is omitted if not provided at transaction creation time.action
: actions associated with the transaction. This is the updated verification action post manual review.dashboard_link
: a URL to the corresponding transaction in the Berbix dashboard.
{
"user_id": 123456789012, // Deprecated field (use transaction_id instead)
"transaction_id": 123456789012,
"code": "012345678990", // Deprecated field used for fetching verification data (use the access token instead)
"customer_uid": "abc1234567", // Omitted if not provided at transaction creation time
"action": "reject",
"dashboard_link": "https://dashboard.berbix.com/transaction?orgId=123456789&transactionId=123456789"
}
Webhook signatures
Within the webhook configurator, you can also find the Hook Secret
to be used for signature validation and Test
your endpoint by issuing a sample webhook. 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 theX-Berbix-Signature
header.
Editing Webooks
To edit the webhook Target URL
, click the Edit
button, change the Target URL
, then click Save
. You can edit both your test
URLs and your live
URLs at any time.
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 usetransaction_id
)transaction_id
: ID for associated transactioncode
: 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 yourauthorization_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