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

Installation

First, add the Berbix Maven repository to your Gradle repositories in your project's build.gradle file.

allprojects {
    repositories {
        // Existing repositories, like google() and mavenCentral()
        maven {
            url "https://storage.googleapis.com/berbix-mobile-releases/repo"
        }
    }
}

Next, add the Berbix Android SDK to your module dependencies.

dependencies {
  // Insert line below to include our client library as a dependency.
  implementation 'com.berbix:berbixverify:2.1.0'
}

A gradle sync of the project in Android Studio might be required to download the library and allow Android Studio to find it.

Usage

To initialize the Berbix Verify flow, refer to the code sample below and replace your client_token for your_token_here. Please see our Integration Guide for more details on initializing the Berbix Verify flow and integrating Berbix APIs.

Start Flow

Start the Berbix Verify flow from an Activity. The flow can also be started from a Fragment via the sdk.startFlow(fragment, config) method.

class VerifyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
        super.onCreate(savedInstanceState, persistentState)

        setContentView(R.layout.verify_activity)

        findViewById<Button>(R.id.startFlowButton).setOnClickListener {
          startBerbix()
        }
    }

    fun startBerbix() {
        val token = "your_token_here" // Fetch client token from the backend

        val sdk = BerbixSDK()
        val config = BerbixConfigurationBuilder().
                setClientToken(token).
                build()
        sdk.startFlow(this, config)
    }
}
public class VerifyActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
      
        setContentView(R.layout.verify_activity);

        startBerbix();
    }

    private void startBerbix() {
        BerbixSDK sdk = new BerbixSDK();
        final BerbixConfiguration config = new BerbixConfigurationBuilder()
                .setClientToken("your_token_here")
                .build();
        sdk.startFlow(this, config);
    }
}

Handle Result

Handle the Berbix result in the onActivityResult method of the Activity or Fragment that started the Berbix Verify flow.

Using handleResult helper

In 2.0.0 a helper method was introduced to assist in handling the response statuses.

onComplete:

The Berbix verification was successfully completed. Check the verification status on backend via the getTransaction API or a webhook if configured. A complete verification does not contain any information abut whether the transaction is accepted or rejected and requires confirmation on backend to verify.

onFailure:

The Berbix verification was not successfully completed. Some errors are non-recoverable and some may allow retrying the Berbix flow. On Failure will return an error String message that can be used for logging to identify the cause of the error.

USER_EXIT:
The user has canceled and quit the Berbix verification. This error can be retried and the user can either restart or resume their verification.

NO_CAMERA_PERMISSIONS:
The user has denied camera permissions. Suggest to the user that they need to enable camera permissions in settings to be able to complete a Berbix verification.
NOTE: In new templates with a 2.0+ SDK, this error will not occur and the Verify flow will handle permission failure and fallback to file uploads.

UNABLE_TO_LAUNCH_CAMERA:
The camera was unable to be started in the Berbix verify flow. This will likely occur if there is an exception when starting the camera due to Android OS internals or hardware issues. This error is fatal but the user can attempt to retry. If this error is received multiple times the user will likely be unable to complete a verification on the device.

BERBIX_ERROR:
The Berbix flow failed due to an internal error. This is most likely due to an issue on the Berbix backend. This error should be retry-able, and should be reported to Berbix support if it happens continuously.

UNKNOWN_ERROR:
The Berbix flow failed due to an unknown error. This is likely similar to the BERBIX_ERROR and can be retried.

class VerifyActivity : AppCompatActivity() {
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == BerbixConstants.REQUEST_CODE_BERBIX_FLOW) {
      BerbixResultStatus.handleResult(resultCode, data, object : BerbixResultListener {

        override fun onComplete() {
          Toast.makeText([email protected], "flow completed", Toast.LENGTH_LONG).show()
        }

        override fun onFailure(status: BerbixErrorReason, errorReason: String) {
          when (status) {
            BerbixErrorReason.USER_EXIT -> Toast.makeText(this, "user exited flow", Toast.LENGTH_LONG).show()
            BerbixErrorReason.NO_CAMERA_PERMISSIONS -> Toast.makeText(this, "no camera permission", Toast.LENGTH_LONG).show()
            BerbixErrorReason.UNABLE_TO_LAUNCH_CAMERA -> Toast.makeText(this, "could not launch camera", Toast.LENGTH_LONG).show()
            BerbixErrorReason.BERBIX_ERROR -> Toast.makeText(this, "Berbix error occurred", Toast.LENGTH_LONG).show()
            BerbixErrorReason.UNKNOWN_ERROR -> Toast.makeText(this, "unknown error received", Toast.LENGTH_LONG).show()
            else -> Toast.makeText(this, "unknown error received", Toast.LENGTH_LONG).show()
          }
        }
      })
    }
}
public class VerifyActivity extends AppCompatActivity {
  @Override
  protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    super.onActivityResult(requestCode, resultCode, data);

    if (requestCode == BerbixConstants.REQUEST_CODE_BERBIX_FLOW) {
      BerbixResultStatus.handleResult(resultCode, new BerbixResultListener() {
        @Override
        public void onComplete() {
          Toast.makeText(VerifyActivity.this, "flow completed", Toast.LENGTH_LONG).show();
        }

        @Override
        public void onFailure(@NotNull BerbixErrorReason status) {
          switch (status) {
            case UNKNOWN_ERROR:
              Toast.makeText(VerifyActivity.this, "unknown error", Toast.LENGTH_LONG).show();
              break;
            case BERBIX_ERROR:
              Toast.makeText(VerifyActivity.this, "berbix internal error", Toast.LENGTH_LONG).show();
              break;
            case NO_CAMERA_PERMISSIONS:
              Toast.makeText(VerifyActivity.this, "camera permissions denied", Toast.LENGTH_LONG).show();
              break;
            case USER_EXIT:
              Toast.makeText(VerifyActivity.this, "user exited flow", Toast.LENGTH_LONG).show();
              break;
            case UNABLE_TO_LAUNCH_CAMERA:
              Toast.makeText(VerifyActivity.this, "unable to launch camera error", Toast.LENGTH_LONG).show();
              break;
          }
        }
      });
    }
  }
}

Legacy method of looking at statuses directly.

SUCCESS:
The Berbix verification was successfully completed. Check the verification status on backend via the getTransaction API or a webhook if configured. A complete verification does not contain any information abut whether the transaction is accepted or rejected and requires confirmation on backend to verify.

USER_EXIT:
The User has canceled and quit the Berbix verification. This error can be retried and the user can either restart or resume their verification.

NO_CAMERA_PERMISSIONS:
The user has denied camera permissions. Suggest to the user that they need to enable camera permissions in settings to be able to complete a Berbix verification.
NOTE: In new templates with a 2.0+ SDK, this error will not occur and the Verify flow will handle permission failure and fallback to file uploads.

UNABLE_TO_LAUNCH_CAMERA:
The camera was unable to be started in the Berbix verify flow. This will likely occur if there is an exception when starting the camera due to Android OS internals or hardware issues. This error is fatal but the user can attempt to retry. If this error is received multiple times the user will likely be unable to complete a verification on the device.

ERROR:
The Berbix flow failed due to an internal error. This is most likely due to an issue on the Berbix backend. This error should be retry-able, and should be reported to Berbix support if it happens continuously.

UNKNOWN_ERROR:
The Berbix flow failed due to an unknown error. This is likely similar to the BERBIX_ERROR and can be retried.

class VerifyActivity : AppCompatActivity() {
        override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)

        if (requestCode == BerbixConstants.REQUEST_CODE_BERBIX_FLOW) {
          val errorReason = data?.getStringExtra(BerbixConstants.ERROR_REASON)
            when (BerbixResultStatus.getStatus(resultCode)) {
                BerbixResultStatus.SUCCESS -> {
                    Log.e("berbix-result", "success!")
                }
                BerbixResultStatus.ERROR -> {
                    Log.e("berbix-result", "error thrown")
                }
                BerbixResultStatus.NO_CAMERA_PERMISSIONS -> {
                    Log.e("berbix-result", "no camera permissions")
                }
                BerbixResultStatus.USER_EXIT -> {
                    Log.e("berbix-result", "user exited")
                }
                BerbixResultStatus.UNABLE_TO_LAUNCH_CAMERA -> {
                    Log.e("berbix-result", "could not launch the camera")
                }
                BerbixResultStatus.UNEXPECTED_RESULT_STATUS -> {
                    Log.e("berbix-verify", "unexpected response code received");
                }
            }
        }
    }
}
public class VerifyActivity extends AppCompatActivity {     
        @Override
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        super.onActivityResult(requestCode, resultCode, data);

        if (requestCode == BerbixConstants.REQUEST_CODE_BERBIX_FLOW) {
            switch (BerbixResultStatus.getStatus(resultCode)) {
                case SUCCESS:
                    Log.e("berbix-verify", "flow completed");
                    break;
                case USER_EXIT:
                    Log.e("berbix-verify", "user exited flow");
                    break;
                case NO_CAMERA_PERMISSIONS:
                    Log.e("berbix-verify", "no camera permission");
                    break;
                case UNABLE_TO_LAUNCH_CAMERA:
                    Log.e("berbix-verify", "could not launch camera");
                    break;
                case ERROR:
                    Log.e("berbix-verify", "error occurred");
                    break;
                case UNEXPECTED_RESULT_STATUS:
                    Log.e("berbix-verify", "unexpected response code received");
                    break;
            }
        }
    }
}

ProGuard Rules

If you're using ProGuard in your Android application, you'll need to include the following rules to initialize the Berbix SDK:

-keep class com.berbix.berbixverify.request.** { *; }
-keep class sun.misc.Unsafe { *; }

Demo App Source Code

A demo app source code is available here and can help with integration or environment setup.

Reference

BerbixSDK Methods

constructor()

Constructs a Berbix SDK client. This can be used subsequently to invoke the Berbix flow within your app.

void startFlow(Activity activity, BerbixConfiguration configuration)

void startFlow(Fragment fragment, BerbixConfiguration configuration)

Starts the Berbix flow and immediately takes control of the user interface. This is the most basic invocation of the flow. Upon completion of the flow, the user interface control will be returned to the app and the onActivityResult will be called with the appropriate request and result codes.

BerbixSDKConfigurationBuilder Methods

constructor()

Creates a new options builder with the default initial state.

BerbixConfigurationBuilder setClientToken(String clientToken)

Sets the client token for the session. This value is fetched from the Berbix API upon creation of a transaction.

Updated about a month ago

Android


Suggested Edits are limited on API Reference Pages

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