# eKYB (Electronic Know Your Business)

The eKYB module verifies a business entity's identity data, such as business name, address, and tax ID. The fields that are collected and how the checks are evaluated depend on your Incode Flow or Workflow configuration.

For an overview of the module and how it works, see [eKYB (electronic Know Your Business)](https://developer.incode.com/docs/ekyb).

How you use this module depends on your integration pattern. When the app defines the steps in code, you add the module to an `IncdOnboardingFlowConfiguration` as shown below; when the flow is defined in Dashboard, you reference it by session token and let the back end drive the steps. See [Integration Approaches](https://developer.incode.com/docs/ios-flow-configuration).

**Availability:** All variants.

**UI:** v1 (data-entry for the business attributes being verified, followed by a processing/status screen).

## Add eKYB

Add the module with `addEKYB(configuration:)`, passing an `ExternalVerificationEkybConfiguration`. Every parameter of the initializer is optional, so you configure only the checks you need.

```swift
flowConfig.addEKYB(
    configuration: ExternalVerificationEkybConfiguration(checkBusinessName: true)
)
```

### Example

The example below builds an `ExternalVerificationEkybConfiguration` that verifies all three attributes, adds the module to the flow, and reads the outcome from the `onExternalValidationEkybCompleted(_:)` delegate callback.

```swift
// Build the eKYB configuration
let ekybConfiguration = ExternalVerificationEkybConfiguration(
    checkBusinessName: true,
    checkAddress: true,
    checkTaxId: true
)

// Add the module to the flow configuration
flowConfig.addEKYB(configuration: ekybConfiguration)
```

```swift
// Receive the result on your IncdOnboardingDelegate
extension MyOnboardingHandler: IncdOnboardingDelegate {
    func onExternalValidationEkybCompleted(_ result: EkybResult) {
        // eKYB verification completed.
        // Inspect result.externalVerification for the per-check results.
    }
}
```

## Configuration Options

`ExternalVerificationEkybConfiguration` controls which attributes are verified and where each value is sourced from. Every field is optional and defaults to `nil`.

| Option               | Type      | Description                                                                   |
| -------------------- | --------- | ----------------------------------------------------------------------------- |
| `checkBusinessName`  | `Bool?`   | Whether to verify the business name.                                          |
| `businessNameSource` | `String?` | The source for the business name value.                                       |
| `checkAddress`       | `Bool?`   | Whether to verify the business address.                                       |
| `address`            | `String?` | The business address value to verify.                                         |
| `checkTaxId`         | `Bool?`   | Whether to verify the tax ID. See [Tax ID Validation](#tax-id-validation).    |
| `taxIdSource`        | `String?` | The source for the tax ID value. See [Tax ID Validation](#tax-id-validation). |

The attributes that are actually collected and how each check is evaluated ultimately depend on your Incode Flow or Workflow configuration.

## Result

eKYB delivers an `EkybResult` to the `onExternalValidationEkybCompleted(_:)` method on your `IncdOnboardingDelegate`.

```swift
func onExternalValidationEkybCompleted(_ result: EkybResult)
```

`EkybResult` fields:

- `externalVerification: [EkybVerificationStep]?`: The list of individual eKYB check results.
- `error: IncdError?`: Populated only when the module fails to produce a result at all; for example, a network or configuration failure. This is separate from individual check outcomes, which are reported via each `EkybVerificationStep.status` (see below).

Each `EkybVerificationStep` contains:

- `stepName: String?`: The identifier of the check performed; for example, `name`, `address_verification`, `address_deliverability`, or `address_property_type`.
- `status: String?`: The outcome of the check: `success`, `warning`, or `failure`.
- `additionalInfo: String?`: A secondary label describing the check.

## Tax ID Validation

Tax ID Validation is **not a standalone module** on iOS: there is no `addTaxIdValidation` builder, no `TaxIdValidationModule` type, and no `TaxIdValidationListener` or `onTaxIdValidationCompleted` callback. On iOS, tax ID checking is performed as part of the eKYB module: you enable it through fields on `ExternalVerificationEkybConfiguration`, and the outcome is delivered with the rest of the eKYB result.

**Availability:** all SDK build variants. The eKYB path (and therefore tax ID checking) is not gated behind a specific SDK build variant; `addEKYB` and `handleEKYBModule` perform no variant inclusion check.

### Add Tax ID Validation

Enable Tax ID Validation by setting the tax ID fields on `ExternalVerificationEkybConfiguration` when you add eKYB to the flow:

```swift
flowConfig.addEKYB(
    configuration: ExternalVerificationEkybConfiguration(
        checkTaxId: true,          // Bool? — run tax ID verification as part of eKYB
        taxIdSource: "<TAX_ID>"    // String? — the tax ID value to verify
    )
)
```

There is no dedicated tax ID builder to call and no tax-ID-specific step to add on its own; the check runs inside eKYB.

### Configuration Options

The tax ID fields live on `ExternalVerificationEkybConfiguration`:

| Option        | Type      | Description                      |
| ------------- | --------- | -------------------------------- |
| `checkTaxId`  | `Bool?`   | Whether to verify the tax ID.    |
| `taxIdSource` | `String?` | The source for the tax ID value. |

### Result

There is no tax-ID-specific result payload or callback. The tax ID outcome is delivered as part of the eKYB result, through the eKYB completion callback:

```swift
func onExternalValidationEkybCompleted(_ result: EkybResult)   // EkybResult carries the eKYB verification steps
```

Failures surface through standard error handling; there is no tax-ID-specific exception type.