> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/kyc-mobile-sdk/integration-overview/android-sdk/integration.md).

# Integration

## **KYC Flow**

Follow these steps to integrate KYC into your Android application, from importing the class through releasing resources.

### **1. Import `VidaKyc`**

The first step is to import the `VidaKyc` class into your Activity or Fragment. This class is the entry point for all KYC operations — initialization, starting and stopping the verification process, and releasing resources.

Add this import to any component that will directly interact with the SDK.

```java
import id.vida.kyc.VidaKyc;
```

### **2. Create `VidaKyc` Instance**

Use the `VidaKycBuilder` class to create an instance of the `VidaKyc` class.\
You can specify the detection configurations, UI customization through the builder.

```java
VidaKyc vidaKyc = VidaKyc.VidaKycBuilder
        .newInstance(request, listener)
        .build();
```

<table><thead><tr><th width="132.82421875">Parameter</th><th width="210.28515625">Type</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td><code>VidaKycRequest</code></td><td>Contains the authentication tokens and flow type. See <code>VidaKycRequest</code>.</td></tr><tr><td>listener</td><td><code>VidaKycListener</code></td><td>Receives the lifecycle callbacks. See <code>VidaKycListener</code>.</td></tr></tbody></table>

Once built, the `VidaKyc` instance becomes your central interface for managing KYC operations.

### **3. Initialize `VidaKyc`**&#x20;

Call `initialize()` to prepare the SDK for the KYC flow. This method:

* Verifies the SDK configuration and network readiness.
* Establishes internal resources such as camera and backend connections.
* Triggers the `onInitialized()` callback once setup is complete.

{% code expandable="true" %}

```java
vidaKyc.initialize();
```

{% endcode %}

{% hint style="info" %}
You must call `initialize()` before any other KYC operation, and wait for `onInitialized()` before calling `startFlow()`. If initialization fails, the SDK notifies your application through the `onError()` callback.&#x20;
{% endhint %}

### 4. Start KYC Detection

Once the `vidaKyc` is initialized, you can start the KYC/OCR detection by calling the `startFlow()` API.

```java
vidaKyc.startFlow();
```

The startFlow() method begins the KYC capture and verification flow, launching the SDK camera interface and guiding users through:

* Document scanning (e.g., KTP, Passport, or ID).
* Face capture and matching (if required by the selected flow).

It handles frame processing, OCR extraction, liveness checks, and backend verification automatically.\
When the flow completes successfully, the SDK invokes onSuccess(VidaKycResponse) on the listener.

### 5. Stop KYC Detection

```java
vidaKyc.finishFlow();
```

This method allows the host app to manually stop the KYC process before it finishes, typically in cases where:

* The user cancels the process.
* An external condition (like network loss) requires halting detection.

The SDK gracefully stops all camera operations and releases partial resources.

### 6. Release Resources

Releasing resources is essential after completing or canceling the flow. It ensures all camera sessions, background threads, and temporary memory allocations used by the SDK are properly disposed of. Always invoke release() after a completed session to prevent memory leaks or background processing issues.

```java
vidaKyc.release();
```

### VidaKycListener Implementation

```java
public interface VidaKycListener {
    void onInitialized();
    void onSuccess(VidaKycResponse response);
    void onError(int errorCode, @NonNull String errorMessage, @Nullable VidaKycResponse response);
}
```

The VidaKycListener interface enables the host application to respond to SDK lifecycle events:

* onInitialized()\
  Called when the SDK is successfully initialized and ready to start KYC operations.\
  You should only call startFlow() after this callback.
* onSuccess(VidaKycResponse response)\
  Triggered upon successful completion of the KYC flow.\
  The VidaKycResponse contains results of all backend and OCR verifications, including scores and metadata.
* onError(int errorCode, String errorMessage, VidaKycResponse response)\
  Called when an error occurs during initialization or the KYC process.\
  The response object may include diagnostic data if available; otherwise, it may be null.

This listener pattern ensures asynchronous and event-driven control over SDK operations.

### 7. VidaKycRequest

The customer needs to create a VidaKycRequest class object and pass it while creating a VidaKyc instance.

```java
VidaKycRequest request = new VidaKycRequest();
request.setVidaFlow(VidaFlow.ID_VERIFICATION);// OR VidaFlow.KYC
request.setToken(token);
vidaKycRequest.setPartnerTransactionID("PARTNER_TRANSACTION_ID");
vidaKycRequest.setVidaSdkRegion(VidaSdkRegion.INDONESIA);
vidaKycRequest.setApiKey("API_KEY");
vidaKycRequest.setLicenseKey("LICENSE_KEY");
vidaKycRequest.setVidaIdFraudShieldClientId("CLIENT_ID");
```

The VidaKycRequest class defines the configuration and authentication parameters for the KYC process.

| Method                                   | Required                                                | Description                                                                                                                                                                                                                                                                    |
| ---------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| setVidaFlow (VidaFlow\.ID\_VERIFICATION) | Required                                                | Defines the type of verification flow (e.g., ID verification, KYC ).                                                                                                                                                                                                           |
| setToken (String token)                  | Required                                                | <p>The secure token provided by VIDA’s backend for authentication.<br>This token ensures the request is tied to your organization and user session.</p>                                                                                                                        |
| setPartnerTransactionID (String)         | Optional                                                | Your own reference for this KYC flow. If you do not set it, the SDK creates a UUID for you. The SDK adds the operation name and attempt number to your value, so the `partnerTrxId` in the SDK response will not be the same as the value you sent. See the SDK Response page. |
| setVidaSdkRegion()                       | Required                                                | Set the region of which ID card verification or KYC needs to be performed.                                                                                                                                                                                                     |
| setApiKey()                              | <p>Required for KYC<br>Optional for ID Verification</p> | API key provided by VIDA. Contact VIDA support to obtain it.                                                                                                                                                                                                                   |
| setLicenseKey()                          | <p>Required for KYC<br>Optional for ID Verification</p> | License key provided by VIDA. Contact VIDA support to obtain it.                                                                                                                                                                                                               |
| setVidaIdFraudShieldClientID             | Optional                                                | Enables ID Fraud Shield for the flow. If it is not set, the ID Fraud Shield SDK remains disabled.                                                                                                                                                                              |

Each request instance is used once per KYC flow to ensure a clean and traceable verification session.

### VidaKycResponse (id.vida.kyc.dtos)

```java
public final class VidaKycResponse {

    public VidaVerifyResponseDTO getVidaCardVerificationDetails() {...}
    public VidaVerifyResponseDTO getVidaFaceMatchDetails() {...}
}

```

```java
public enum VIDAKycOperation {
    FRONT_CARD_ID_VERIFICATION,
    BACK_CARD_ID_VERIFICATION,
    LIVENESS_VERIFICATION,
    FACE_VERIFICATION
}
```

The VidaKycResponse class encapsulates the results of the entire KYC verification process.\
It contains details of both document and face verification stages.

Accessor Methods

<table><thead><tr><th width="271.44921875">Method</th><th>Returns</th><th>Description</th></tr></thead><tbody><tr><td>getVidaCardVerificationDetails()</td><td>VidaVerifyResponseDTO</td><td>Document verification results, including OCR extraction data and any backend validation errors.</td></tr><tr><td>getVidaFaceMatchDetails()</td><td>VidaVerifyResponseDTO</td><td>Face matching results, including confidence scores, detected errors, and liveness evaluation outcomes.</td></tr><tr><td>getVidaLivenessResponse()</td><td>VidaLivenessResponseInternal</td><td>Liveness results, including liveness score, manipulation score, detected errors, and related details.</td></tr><tr><td>getVidaFailedOperation()</td><td>VIDAKycOperation</td><td>The last failed operation. See below.</td></tr></tbody></table>

{% hint style="info" %}
**Using `getVidaFailedOperation()` to troubleshoot error 72003**

Error code `72003` tells you an operation failed, but not which one. `getVidaFailedOperation()` returns the operation that was in progress, so you know where to look for the detailed error.

For example, if it returns `VIDAKycOperation.LIVENESS_VERIFICATION`, check the error details in `getVidaLivenessResponse()`.
{% endhint %}

* **Builder Inner Class**\
  The builder pattern ensures the response object is immutable and constructed only through controlled SDK operations.

The response serves as the final structured output from the VIDA SDK, passed via the onSuccess() or onError() callbacks in VidaKycListener.